/[escript]/trunk/escript/src/DataTagged.h
ViewVC logotype

Diff of /trunk/escript/src/DataTagged.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

trunk/esys2/escript/src/Data/DataTagged.h revision 121 by jgs, Fri May 6 04:26:16 2005 UTC trunk/escript/src/DataTagged.h revision 615 by elspeth, Wed Mar 22 02:12:00 2006 UTC
# Line 1  Line 1 
1  // $Id$  // $Id$
2    
3  /*  /*
4   ******************************************************************************   ************************************************************
5   *                                                                            *   *          Copyright 2006 by ACcESS MNRF                   *
6   *       COPYRIGHT  ACcESS 2004 -  All Rights Reserved                        *   *                                                          *
7   *                                                                            *   *              http://www.access.edu.au                    *
8   * This software is the property of ACcESS. No part of this code              *   *       Primary Business: Queensland, Australia            *
9   * may be copied in any form or by any means without the expressed written    *   *  Licensed under the Open Software License version 3.0    *
10   * consent of ACcESS.  Copying, use or modification of this software          *   *     http://www.opensource.org/licenses/osl-3.0.php       *
11   * by any unauthorised person is illegal unless that person has a software    *   *                                                          *
12   * license agreement with ACcESS.                                             *   ************************************************************
  *                                                                            *  
  ******************************************************************************  
13  */  */
14    
15  #if !defined escript_DataTagged_20040615_H  #if !defined escript_DataTagged_20040615_H
16  #define escript_DataTagged_20040615_H  #define escript_DataTagged_20040615_H
17    
18  #include "escript/Data/DataAbstract.h"  #include "DataAbstract.h"
19  #include "escript/Data/DataArray.h"  #include "DataArrayView.h"
 #include "escript/Data/DataArrayView.h"  
20    
21  #include <vector>  #include <vector>
22  #include <map>  #include <map>
# Line 30  class DataConstant; Line 27  class DataConstant;
27    
28  /**  /**
29     \brief     \brief
30     Creates the illusion of a full dataset accessible via sampleNo and dataPointNo.     Simulates a full dataset accessible via sampleNo and dataPointNo.
31    
32     Description:     Description:
33     Creates the illusion of a full dataset accessible via sampleNo and     Each data-point has an associated tag number, and a given tag can represent a
34     dataPointNo. In reality a much smaller number of data-points is stored.     range of dataPointNo and sampleNo. Each tag indexes only a single data-point.
    Each data-point has an associated key, thus a given key represents a specific  
    range of dataPointNo and sampleNo. Each key indexes a single data-point.  
35     Thus only a single data-point needs to be stored for a range of sampleNo and     Thus only a single data-point needs to be stored for a range of sampleNo and
36     dataPointNo values.     dataPointNo values.
37  */  */
# Line 46  class DataTagged : public DataAbstract { Line 41  class DataTagged : public DataAbstract {
41   public:   public:
42    
43    //    //
44    // Types for the lists of tags and values    // Types for the lists of tags and values.
45    typedef std::vector<int>           TagListType;    typedef std::vector<int>           TagListType;
46    typedef std::vector<DataArrayView> ValueListType;    typedef std::vector<DataArrayView> ValueListType;
47    typedef DataArrayView::ValueType   ValueType;    typedef DataArrayView::ValueType   ValueType;
48    
49    //    //
50    // Map from the tag to an offset the the data array.    // Map from a tag to an offset into the data array.
51    typedef std::map<int, int> DataMapType;    typedef std::map<int, int> DataMapType;
52    
53    /**    /**
# Line 61  class DataTagged : public DataAbstract { Line 56  class DataTagged : public DataAbstract {
56    
57       Description:       Description:
58       Default constructor for DataTagged. Creates a DataTagged object for which       Default constructor for DataTagged. Creates a DataTagged object for which
59       the default data-point is a scalar data-point with value 0.0. Any given tag       the default data-point is a scalar data-point with value 0.0, and no other
60       will map to this data-point.       tag values are stored.
61        T
62    */    */
63    DataTagged();    DataTagged();
64    
# Line 72  class DataTagged : public DataAbstract { Line 68  class DataTagged : public DataAbstract {
68    
69       Description:       Description:
70       Constructor for DataTagged.       Constructor for DataTagged.
71       \param tagKeys - Input - A vector of integer keys.       \param tagKeys - Input - A vector of integer tags.
72       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
73                     all tag values will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
74                     it contains one value all tag values will be assigned the                       0. If it contains one value all tag values will be assigned
75             same value. Otherwise if there is a mismatch between               this value. Otherwise consecutive tags will be assigned
76             the number of keys and the number of values an exception                       consecutive values.  If there is a mismatch between  the
77             will be generated.               number of keys and the number of values an exception
78                 will be generated.
79       \param defaultValue - Input - Value returned if a requested tag doesn't exist.       \param defaultValue - Input - Value returned if a requested tag doesn't exist.
80       \param what - Input - A description of what this data represents.       \param what - Input - A description of what this data represents.
81        T
82    */    */
83    DataTagged(const TagListType& tagKeys,    DataTagged(const TagListType& tagKeys,
84               const ValueListType& values,               const ValueListType& values,
# Line 89  class DataTagged : public DataAbstract { Line 87  class DataTagged : public DataAbstract {
87    
88    /**    /**
89       \brief       \brief
90       Alternative constructor for DataTagged objects.       Alternative Constructor for DataTagged.
91    
92       Description:       Description:
93       Alternative Constructor for DataTagged objects.       Alternative Constructor for DataTagged.
94       \param what - Input - A description of what this data object represents.       \param what - Input - A description of what this data object represents.
95       \param shape - Input - the shape of each data-point.       \param shape - Input - The shape of each data-point.
96       \param tags - Input - array of tags, one for each sample number       \param tags - Input - An array of tags, one for each sample number.
97       \param data - the data values for each data-point.       \param data - The data values for each tag.
98        NB: no unit testing yet
99    */    */
100    DataTagged(const FunctionSpace& what,    DataTagged(const FunctionSpace& what,
101               const DataArrayView::ShapeType &shape,               const DataArrayView::ShapeType &shape,
102               const int tags[],               const int tags[],
103               const ValueType &data);               const ValueType& data);
104    
105    /**    /**
106       \brief       \brief
107       Slice constructor for DataTagged.       Copy Constructor for DataTagged.
   
      Description:  
      Slice constructor for DataTagged.  
      Copies a slice from another DataTagged object.  
      \param other - Input - DataTagged object to copy from.  
      \param region - Input - region to copy.  
   */  
   DataTagged(const DataTagged& other,  
          const DataArrayView::RegionType& region);  
   
   /**  
      \brief  
      Copy constructorfor DataTagged.  
108       Performs a deep copy from the given DataTagged object.       Performs a deep copy from the given DataTagged object.
109        T
110    */    */
111    DataTagged(const DataTagged& other);    DataTagged(const DataTagged& other);
112    
113    /**    /**
114       \brief       \brief
115       Construct a tagged data from a DataConstant object.       Copy Constructor for DataTagged.
116       The default data-point will be that held by the DataConstant object.       Construct a DataTagged object from a DataConstant object.
117         The default value will be the value of the DataConstant object.
118        T
119    */    */
120    DataTagged(const DataConstant& other);    DataTagged(const DataConstant& other);
121    
# Line 135  class DataTagged : public DataAbstract { Line 124  class DataTagged : public DataAbstract {
124       getSampleDataByTag       getSampleDataByTag
125    
126       Description:       Description:
127       Return the data-point for the given tag. All of the data for the entire       Return the data-point for the given tag. All of the data for the
128       sample should be visable via the returned pointer. This provides an       sample will be visible via the returned pointer.
129       interface into the data suitable for legacy C code.  
130         ** This provides an interface into the data suitable for legacy C code.
131         ** NB: need to do array bounds checking when accessing returned value!
132        T
133    */    */
134    virtual    virtual
135    double*    double*
# Line 148  class DataTagged : public DataAbstract { Line 140  class DataTagged : public DataAbstract {
140       Write the data as a string.       Write the data as a string.
141       Writes out each tag, including the default, and the data-point which is       Writes out each tag, including the default, and the data-point which is
142       associated with each tag.       associated with each tag.
143        T
144    */    */
145    virtual    virtual
146    std::string    std::string
# Line 155  class DataTagged : public DataAbstract { Line 148  class DataTagged : public DataAbstract {
148    
149    /**    /**
150       \brief       \brief
151         Return the tag number associated with the given data-point number
152         according to the associated function space.
153        T
154      */
155      virtual
156      int
157      getTagNumber(int dpno);
158    
159      /**
160         \brief
161       getPointOffset       getPointOffset
162    
163       Description:       Description:
164       Return the offset to the given data-point. This is somewhat artificial,       Return the offset to the given data-point value in the underlying
165       but returns the offset for the given point in the DataTagged object.       data vector.
      Only really necessary to avoid many DataArrayView objects.  
166    
167       \param sampleNo - Input - sample number.       \param sampleNo - Input - sample number.
168       \param dataPointNo - Input - data-point number.       \param dataPointNo - Input - data-point number.
169     */      T
170      */
171    virtual    virtual
172    ValueType::size_type    ValueType::size_type
173    getPointOffset(int sampleNo,    getPointOffset(int sampleNo,
# Line 175  class DataTagged : public DataAbstract { Line 178  class DataTagged : public DataAbstract {
178       addTaggedValues       addTaggedValues
179    
180       Description:       Description:
181       Add the given tags and values to this DataTagged object, by repeatedly       Add the given tags and values to this DataTagged object.
182       using addTaggedValue for each given tag/value pair.       \param tagKeys - Input - A vector of integer tags.
      \param tagKeys - Input - A vector of integer keys.  
183       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
184                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
185                        it contains one value all tags will be assigned the same value.                       0. If it contains one value all tag values will be assigned
186                        Otherwise if there is a mismatch between the number of tags and               this value. Otherwise consecutive tags will be assigned
187                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
188                 number of keys and the number of values an exception
189                 will be generated.
190        T
191    */    */
192    void    void
193    addTaggedValues(const TagListType& tagKeys,    addTaggedValues(const TagListType& tagKeys,
# Line 195  class DataTagged : public DataAbstract { Line 200  class DataTagged : public DataAbstract {
200       Description:       Description:
201       Add a single tag and value to this DataTagged object. If this tag already has       Add a single tag and value to this DataTagged object. If this tag already has
202       a value associated with it, setTaggedValue will be used to update this value.       a value associated with it, setTaggedValue will be used to update this value.
203       \param tagKey - Input - Integer key.       \param tagKey - Input - Integer tag.
204       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
205        T
206    */    */
207    void    void
208    addTaggedValue(int tagKey,    addTaggedValue(int tagKey,
# Line 207  class DataTagged : public DataAbstract { Line 213  class DataTagged : public DataAbstract {
213       setTaggedValues       setTaggedValues
214    
215       Description:       Description:
216       Set the given tags to the given values in this DataTagged object, by repeatedly       Set the given tags to the given values in this DataTagged object.
217       using setTaggedValue for each given tag/value pair.       \param tagKeys - Input - A vector of integer tag.
      \param tagKeys - Input - A vector of integer keys.  
218       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
219                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
220                        it contains one value all tag values will be assigned the same value.                       0. If it contains one value all tag values will be assigned
221                        Otherwise if there is a mismatch between the number of keys and               this value. Otherwise consecutive tags will be assigned
222                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
223                 number of keys and the number of values an exception
224                 will be generated.
225        T
226    */    */
227    void    void
228    setTaggedValues(const TagListType& tagKeys,    setTaggedValues(const TagListType& tagKeys,
# Line 225  class DataTagged : public DataAbstract { Line 233  class DataTagged : public DataAbstract {
233       setTaggedValue       setTaggedValue
234    
235       Description:       Description:
236       Assign the given value to the given tag. If this tag does not already have a value       Assign the given value to the given tag.
237       associated with it, addTaggedValue will be used to add this tag/value pair.       \param tagKey - Input - Integer tag.
      \param tagKey - Input - Integer key.  
238       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
239        T
240    */    */
241    virtual    virtual
242    void    void
# Line 240  class DataTagged : public DataAbstract { Line 248  class DataTagged : public DataAbstract {
248       getDataPointByTag       getDataPointByTag
249    
250       Description:       Description:
251       Return a view into the data-point associated with the given tag.       Return data-point associated with the given tag as a DataArrayView.
252       \param tag - Input - Integer key.       \param tag - Input - Integer key.
253        T
254    */    */
255    DataArrayView    DataArrayView
256    getDataPointByTag(int tag) const;    getDataPointByTag(int tag) const;
# Line 251  class DataTagged : public DataAbstract { Line 260  class DataTagged : public DataAbstract {
260       getDataPoint       getDataPoint
261    
262       Description:       Description:
263       Return a view into the data-point specified by the given sample       Return the data-point specified by the given sample and data-point
264       and data-point numbers.       numbers as a DataArrayView.
      NOTE: Construction of the DataArrayView is a relatively expensive  
      operation.  
265       \param sampleNo - Input.       \param sampleNo - Input.
266       \param dataPointNo - Input.       \param dataPointNo - Input.
267        T
268    */    */
269    virtual    virtual
270    DataArrayView    DataArrayView
# Line 269  class DataTagged : public DataAbstract { Line 277  class DataTagged : public DataAbstract {
277    
278       Description:       Description:
279       Return a reference to the tag offset lookup table.       Return a reference to the tag offset lookup table.
280        T
281    */    */
282    const DataMapType&    const DataMapType&
283    getTagLookup() const;    getTagLookup() const;
# Line 278  class DataTagged : public DataAbstract { Line 287  class DataTagged : public DataAbstract {
287       isCurrentTag       isCurrentTag
288    
289       Description:       Description:
290       Return true if the given tag exists within the DataTagged tag keys.       Return true if the given tag exists within the DataTagged tag map.
291       NOTE: The DataTagged keys do not necessarily coincide with the tag  
292       keys for the function space.       *** NB: The DataTagged tag map does not necessarily coincide with the tag
293     */       keys in the associated function space.
294        T
295      */
296    bool    bool
297    isCurrentTag(int tag) const;    isCurrentTag(int tag) const;
298    
# Line 291  class DataTagged : public DataAbstract { Line 302  class DataTagged : public DataAbstract {
302    
303       Description:       Description:
304       Return the default value. This value is associated with any tag which       Return the default value. This value is associated with any tag which
305       is not explicitly recorded in this DataTagged object.       is not explicitly recorded in this DataTagged object's tag map.
306        T
307    */    */
308    DataArrayView&    DataArrayView&
309    getDefaultValue();    getDefaultValue();
# Line 304  class DataTagged : public DataAbstract { Line 316  class DataTagged : public DataAbstract {
316       getLength       getLength
317    
318       Description:       Description:
319       Return the number of doubles stored for the Data.       Return the total number of doubles stored for this DataTagged object.
320        T
321    */    */
322    virtual    virtual
323    ValueType::size_type    ValueType::size_type
# Line 315  class DataTagged : public DataAbstract { Line 328  class DataTagged : public DataAbstract {
328       getSlice       getSlice
329    
330       Description:       Description:
331       Factory method that returns a newly created DataTagged object.       Factory method that returns a newly created DataTagged object generated
332       The caller is reponsible for managing the object created.       by taking the specified slice from this DataTagged object.
333         The caller is reponsible for managing the returned object.
334        T
335    */    */
336    virtual    virtual
337    DataAbstract*    DataAbstract*
# Line 324  class DataTagged : public DataAbstract { Line 339  class DataTagged : public DataAbstract {
339    
340    /**    /**
341       \brief       \brief
342         Slice Constructor for DataTagged.
343    
344         Description:
345         Creates a DataTagged object which is the specified slice
346         from the given DataTagged object.
347         \param other - Input - DataTagged object to slice from.
348         \param region - Input - Region to slice.
349        T
350      */
351      DataTagged(const DataTagged& other,
352             const DataArrayView::RegionType& region);
353    
354      /**
355         \brief
356       setSlice       setSlice
357    
358       Description:       Description:
359       Copy the specified region from the given value into this object.       Copy the given Data object into the specified region in this object.
360       \param value - Input - Data to copy from.       \param other - Input - Data object to copy from.
361       \param region - Input - Region to copy.       \param region - Input - Region to copy into (NB: must have same shape as other!).
362        T
363    */    */
364    virtual    virtual
365    void    void
366    setSlice(const DataAbstract* value,    setSlice(const DataAbstract* other,
367             const DataArrayView::RegionType& region);             const DataArrayView::RegionType& region);
368    
369    /**    /**
# Line 341  class DataTagged : public DataAbstract { Line 371  class DataTagged : public DataAbstract {
371       reshapeDataPoint       reshapeDataPoint
372    
373       Description:       Description:
374       Reshape the data point only if the data-point is currently rank 0.       Reshape each data-point in this object to the given shape, only
375       An exception is thrown if the data-point has rank other than 0.       if current data-points are scalars. An exception is thrown if
376       The original data point value is used for all values of the new       the current data-points have rank other than 0.
377       data point.       The original values of the data-points are used for all values
378         of the new data-points.
379        T
380    */    */
381    void    void
382    reshapeDataPoint(const DataArrayView::ShapeType& shape);    reshapeDataPoint(const DataArrayView::ShapeType& shape);
383    
384      /**
385         \brief
386         Archive the underlying data values to the file referenced
387         by ofstream. A count of the number of values expected to be written
388         is provided as a cross-check.
389    
390         The return value indicates success (0) or otherwise (1).
391      */
392      int
393      archiveData(std::ofstream& archiveFile,
394                  const DataArrayView::ValueType::size_type noValues) const;
395    
396      /**
397         \brief
398         Extract the number of values specified by noValues from the file
399         referenced by ifstream to the underlying data structure.
400    
401         The return value indicates success (0) or otherwise (1).
402      */
403      int
404      extractData(std::ifstream& archiveFile,
405                  const DataArrayView::ValueType::size_type noValues);
406    
407      /**
408         \brief
409         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
410    
411         \param ev - Output - eigenvalues in increasing order at each data point
412    
413      */
414      virtual void
415      eigenvalues(DataAbstract* ev);
416    
417      /**
418         \brief
419         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
420    
421         \param ev - Output - eigenvalues in increasing order at each data point
422         \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
423                             and the first nonzero component is positive.
424         \param tol - Input - eigenvalue with relative distance tol are treated as equal.
425    
426      */
427    
428      virtual void
429      eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
430    
431    
432   protected:   protected:
433    
434   private:   private:
# Line 358  class DataTagged : public DataAbstract { Line 438  class DataTagged : public DataAbstract {
438    DataMapType m_offsetLookup;    DataMapType m_offsetLookup;
439    
440    //    //
441    // the default value offset    // the offset to the default value
442    static const int m_defaultValueOffset = 0;    static const int m_defaultValueOffset = 0;
443    
444    //    //
# Line 391  DataTagged::getDefaultValue() const Line 471  DataTagged::getDefaultValue() const
471    return getPointDataView();    return getPointDataView();
472  }  }
473    
474    inline
475    const DataTagged::DataMapType&
476    DataTagged::getTagLookup() const
477    {
478      return m_offsetLookup;
479    }
480    
481    inline
482    DataArrayView::ValueType::size_type
483    DataTagged::getLength() const
484    {
485      return m_data.size();
486    }
487    
488  } // end of namespace  } // end of namespace
489    
490  #endif  #endif

Legend:
Removed from v.121  
changed lines
  Added in v.615

  ViewVC Help
Powered by ViewVC 1.1.26