/[escript]/branches/arrayview_from_1695_trunk/escript/src/DataTagged.h
ViewVC logotype

Diff of /branches/arrayview_from_1695_trunk/escript/src/DataTagged.h

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

trunk/esys2/escript/src/Data/DataTagged.h revision 102 by jgs, Wed Dec 15 07:08:39 2004 UTC trunk/escript/src/DataTagged.h revision 950 by gross, Tue Feb 6 07:01:11 2007 UTC
# Line 1  Line 1 
1  // $Id$  // $Id$
2  /*  
3   ******************************************************************************  /*
4   *                                                                            *   ************************************************************
5   *       COPYRIGHT  ACcESS 2004 -  All Rights Reserved                        *   *          Copyright 2006 by ACcESS MNRF                   *
6   *                                                                            *   *                                                          *
7   * This software is the property of ACcESS. No part of this code              *   *              http://www.access.edu.au                    *
8   * may be copied in any form or by any means without the expressed written    *   *       Primary Business: Queensland, Australia            *
9   * consent of ACcESS.  Copying, use or modification of this software          *   *  Licensed under the Open Software License version 3.0    *
10   * by any unauthorised person is illegal unless that person has a software    *   *     http://www.opensource.org/licenses/osl-3.0.php       *
11   * license agreement with ACcESS.                                             *   *                                                          *
12   *                                                                            *   ************************************************************
  ******************************************************************************  
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    #include "system_dep.h"
18    
19  #include "escript/Data/DataAbstract.h"  #include "DataAbstract.h"
20  #include "escript/Data/DataArray.h"  #include "DataArrayView.h"
 #include "escript/Data/DataArrayView.h"  
21    
22  #include <vector>  #include <vector>
23  #include <map>  #include <map>
# Line 29  class DataConstant; Line 28  class DataConstant;
28    
29  /**  /**
30     \brief     \brief
31     Creates the illusion of a full dataset accessible via sampleNo and dataPointNo.     Simulates a full dataset accessible via sampleNo and dataPointNo.
32    
33     Description:     Description:
34     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
35     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.  
36     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
37     dataPointNo values.     dataPointNo values.
38  */  */
# Line 44  class DataTagged : public DataAbstract { Line 41  class DataTagged : public DataAbstract {
41    
42   public:   public:
43    
44    typedef std::vector<int> TagListType;    //
45      // Types for the lists of tags and values.
46      typedef std::vector<int>           TagListType;
47    typedef std::vector<DataArrayView> ValueListType;    typedef std::vector<DataArrayView> ValueListType;
48      typedef DataArrayView::ValueType   ValueType;
49    
50    //    //
51    // Map type, maps the key to an array offset.    // Map from a tag to an offset into the data array.
52    typedef std::map<int, int> DataMapType;    typedef std::map<int, int> DataMapType;
53    
54    /**    /**
# Line 57  class DataTagged : public DataAbstract { Line 57  class DataTagged : public DataAbstract {
57    
58       Description:       Description:
59       Default constructor for DataTagged. Creates a DataTagged object for which       Default constructor for DataTagged. Creates a DataTagged object for which
60       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
61       will map to this data-point.       tag values are stored.
62        T
63    */    */
64      ESCRIPT_DLL_API
65    DataTagged();    DataTagged();
66    
67    /**    /**
# Line 68  class DataTagged : public DataAbstract { Line 70  class DataTagged : public DataAbstract {
70    
71       Description:       Description:
72       Constructor for DataTagged.       Constructor for DataTagged.
73       \param tagKeys - Input - A vector of integer keys.       \param tagKeys - Input - A vector of integer tags.
74       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
75                     all tag values will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
76                     it contains one value all tag values will be assigned the                       0. If it contains one value all tag values will be assigned
77             same value. Otherwise if there is a mismatch between               this value. Otherwise consecutive tags will be assigned
78             the number of keys and the number of values an exception                       consecutive values.  If there is a mismatch between  the
79             will be generated.               number of keys and the number of values an exception
80                 will be generated.
81       \param defaultValue - Input - Value returned if a requested tag doesn't exist.       \param defaultValue - Input - Value returned if a requested tag doesn't exist.
82       \param what - Input - A description of what this data represents.       \param what - Input - A description of what this data represents.
83        T
84    */    */
85      ESCRIPT_DLL_API
86    DataTagged(const TagListType& tagKeys,    DataTagged(const TagListType& tagKeys,
87               const ValueListType& values,               const ValueListType& values,
88           const DataArrayView& defaultValue,           const DataArrayView& defaultValue,
# Line 85  class DataTagged : public DataAbstract { Line 90  class DataTagged : public DataAbstract {
90    
91    /**    /**
92       \brief       \brief
93       Slice constructor for DataTagged.       Alternative Constructor for DataTagged.
94    
95       Description:       Description:
96       Slice constructor for DataTagged.       Alternative Constructor for DataTagged.
97       Copies a slice from another DataTagged object.       \param what - Input - A description of what this data object represents.
98       \param other - Input - DataTagged object to copy from.       \param shape - Input - The shape of each data-point.
99       \param region - Input - region to copy.       \param tags - Input - An array of tags, one for each sample number.
100         \param data - The data values for each tag.
101        NB: no unit testing yet
102    */    */
103    DataTagged(const DataTagged& other,    ESCRIPT_DLL_API
104           const DataArrayView::RegionType& region);    DataTagged(const FunctionSpace& what,
105                 const DataArrayView::ShapeType &shape,
106                 const int tags[],
107                 const ValueType& data);
108    
109      /**
110         \brief
111         Alternative Constructor for DataTagged.
112    
113         Description:
114         Alternative Constructor for DataTagged.
115         \param what - Input - A description of what this data object represents.
116         \param shape - Input - The shape of each data-point.
117         \param tags - Input - An vector of tags, one for each sample number.
118         \param data - The data values for each tag.
119        NB: no unit testing yet
120      */
121      ESCRIPT_DLL_API
122      DataTagged(const FunctionSpace& what,
123                 const DataArrayView::ShapeType &shape,
124                 const TagListType& tags,
125                 const ValueType& data);
126    
127    /**    /**
128       \brief       \brief
129       Copy constructorfor DataTagged.       Copy Constructor for DataTagged.
130       Performs a deep copy from the given DataTagged object.       Performs a deep copy from the given DataTagged object.
131        T
132    */    */
133      ESCRIPT_DLL_API
134    DataTagged(const DataTagged& other);    DataTagged(const DataTagged& other);
135    
136    /**    /**
137       \brief       \brief
138       Construct a tagged data from a DataConstant object.       Copy Constructor for DataTagged.
139       The default data-point will be that held by the DataConstant object.       Construct a DataTagged object from a DataConstant object.
140         The default value will be the value of the DataConstant object.
141        T
142    */    */
143      ESCRIPT_DLL_API
144    DataTagged(const DataConstant& other);    DataTagged(const DataConstant& other);
145    
146    /**    /**
# Line 115  class DataTagged : public DataAbstract { Line 148  class DataTagged : public DataAbstract {
148       getSampleDataByTag       getSampleDataByTag
149    
150       Description:       Description:
151       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
152       sample should be visable via the returned pointer. This provides an       sample will be visible via the returned pointer.
153       interface into the data suitable for legacy C code.  
154         ** This provides an interface into the data suitable for legacy C code.
155         ** NB: need to do array bounds checking when accessing returned value!
156        T
157    */    */
158      ESCRIPT_DLL_API
159    virtual    virtual
160    double*    double*
161    getSampleDataByTag(int tag);    getSampleDataByTag(int tag);
# Line 128  class DataTagged : public DataAbstract { Line 165  class DataTagged : public DataAbstract {
165       Write the data as a string.       Write the data as a string.
166       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
167       associated with each tag.       associated with each tag.
168        T
169    */    */
170      ESCRIPT_DLL_API
171    virtual    virtual
172    std::string    std::string
173    toString() const;    toString() const;
174     /**
175         \brief
176         dumps the object into a netCDF file
177      */
178      ESCRIPT_DLL_API
179      virtual
180      void
181      dump(const std::string fileName) const;
182    
183      /**
184         \brief
185         Return the tag number associated with the given data-point number
186         according to the associated function space.
187        T
188      */
189      ESCRIPT_DLL_API
190      virtual
191      int
192      getTagNumber(int dpno);
193    
194    /**    /**
195       \brief       \brief
196       getPointOffset       getPointOffset
197    
198       Description:       Description:
199       Return the offset to the given data-point. This is somewhat artificial,       Return the offset to the given data-point value in the underlying
200       but returns the offset for the given point in the DataTagged object.       data vector.
      Only really necessary to avoid many DataArrayView objects.  
201    
202       \param sampleNo - Input - sample number.       \param sampleNo - Input - sample number.
203       \param dataPointNo - Input - data-point number.       \param dataPointNo - Input - data-point number.
204     */      T
205      */
206      ESCRIPT_DLL_API
207    virtual    virtual
208    DataArrayView::ValueType::size_type    ValueType::size_type
209    getPointOffset(int sampleNo,    getPointOffset(int sampleNo,
210                   int dataPointNo) const;                   int dataPointNo) const;
211    
# Line 155  class DataTagged : public DataAbstract { Line 214  class DataTagged : public DataAbstract {
214       addTaggedValues       addTaggedValues
215    
216       Description:       Description:
217       Add the given tags and values to this DataTagged object.       Add the given tags and values to this DataTagged object.
218       \param tagKeys - Input - A vector of integer keys.       \param tagKeys - Input - A vector of integer tags.
219       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
220                     then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
221                     it contains one value all tags will be assigned the same value.                       0. If it contains one value all tag values will be assigned
222                     Otherwise if there is a mismatch between the number of tags and               this value. Otherwise consecutive tags will be assigned
223                     the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
224       NB: If a tag given here already exists in this object, this attempt to add the given               number of keys and the number of values an exception
225       value will have no effect. setTaggedValues is more versatile and should be               will be generated.
226       used in most cases in preference to addTaggedValues.      T
227    */    */
228      ESCRIPT_DLL_API
229    void    void
230    addTaggedValues(const TagListType& tagKeys,    addTaggedValues(const TagListType& tagKeys,
231                    const ValueListType& values);                      const ValueListType& values);  
# Line 175  class DataTagged : public DataAbstract { Line 235  class DataTagged : public DataAbstract {
235       addTaggedValue       addTaggedValue
236    
237       Description:       Description:
238       Add a single tag and value to this DataTagged object.       Add a single tag and value to this DataTagged object. If this tag already has
239       \param tagKey - Input - Integer key.       a value associated with it, setTaggedValue will be used to update this value.
240       \param value - Input - DataArrayView.       \param tagKey - Input - Integer tag.
241       NB: If this tag already exists in this object, this attempt to add the given       \param value - Input - Single DataArrayView value to be assigned to the tag.
242       value will have no effect. setTaggedValue is more versatile and should be      T
      used in most cases in preference to addTaggedValue.  
243    */    */
244      ESCRIPT_DLL_API
245    void    void
246    addTaggedValue(int tagKey,    addTaggedValue(int tagKey,
247                   const DataArrayView& value);                   const DataArrayView& value);
# Line 191  class DataTagged : public DataAbstract { Line 251  class DataTagged : public DataAbstract {
251       setTaggedValues       setTaggedValues
252    
253       Description:       Description:
254       Assign the given values to the tags listed.       Set the given tags to the given values in this DataTagged object.
255       \param tagKeys - Input - A vector of integer keys.       \param tagKeys - Input - A vector of integer tag.
256       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
257                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
258                        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
259                        Otherwise if there is a mismatch between the number of keys and               this value. Otherwise consecutive tags will be assigned
260                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
261       NB: If a given tag does not yet exist in this DataTagged object, it will be added.               number of keys and the number of values an exception
262                 will be generated.
263        T
264    */    */
265      ESCRIPT_DLL_API
266    void    void
267    setTaggedValues(const TagListType& tagKeys,    setTaggedValues(const TagListType& tagKeys,
268                    const ValueListType& values);                    const ValueListType& values);
# Line 210  class DataTagged : public DataAbstract { Line 273  class DataTagged : public DataAbstract {
273    
274       Description:       Description:
275       Assign the given value to the given tag.       Assign the given value to the given tag.
276       \param tagKey - Input - Integer key.       \param tagKey - Input - Integer tag.
277       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
278       NB: If the given tag does not yet exist in this DataTagged object, it will be added.      T
279    */    */
280      ESCRIPT_DLL_API
281    virtual    virtual
282    void    void
283    setTaggedValue(int tagKey,    setTaggedValue(int tagKey,
# Line 224  class DataTagged : public DataAbstract { Line 288  class DataTagged : public DataAbstract {
288       getDataPointByTag       getDataPointByTag
289    
290       Description:       Description:
291       Return a view into the data-point associated with the given tag.       Return data-point associated with the given tag as a DataArrayView.
292       \param tag - Input - Integer key.       \param tag - Input - Integer key.
293        T
294    */    */
295      ESCRIPT_DLL_API
296    DataArrayView    DataArrayView
297    getDataPointByTag(int tag) const;    getDataPointByTag(int tag) const;
298    
# Line 235  class DataTagged : public DataAbstract { Line 301  class DataTagged : public DataAbstract {
301       getDataPoint       getDataPoint
302    
303       Description:       Description:
304       Return a view into the data-point specified by the given sample       Return the data-point specified by the given sample and data-point
305       and data-point numbers.       numbers as a DataArrayView.
      NOTE: Construction of the DataArrayView is a relatively expensive  
      operation.  
306       \param sampleNo - Input.       \param sampleNo - Input.
307       \param dataPointNo - Input.       \param dataPointNo - Input.
308        T
309    */    */
310      ESCRIPT_DLL_API
311    virtual    virtual
312    DataArrayView    DataArrayView
313    getDataPoint(int sampleNo,    getDataPoint(int sampleNo,
# Line 253  class DataTagged : public DataAbstract { Line 319  class DataTagged : public DataAbstract {
319    
320       Description:       Description:
321       Return a reference to the tag offset lookup table.       Return a reference to the tag offset lookup table.
322        T
323    */    */
324      ESCRIPT_DLL_API
325    const DataMapType&    const DataMapType&
326    getTagLookup() const;    getTagLookup() const;
327    
# Line 262  class DataTagged : public DataAbstract { Line 330  class DataTagged : public DataAbstract {
330       isCurrentTag       isCurrentTag
331    
332       Description:       Description:
333       Return true if the given tag exists within the DataTagged tag keys.       Return true if the given tag exists within the DataTagged tag map.
334       NOTE: The DataTagged keys do not necessarily coincide with the tag  
335       keys for the function space.       *** NB: The DataTagged tag map does not necessarily coincide with the tag
336     */       keys in the associated function space.
337        T
338      */
339      ESCRIPT_DLL_API
340    bool    bool
341    isCurrentTag(int tag) const;    isCurrentTag(int tag) const;
342    
# Line 275  class DataTagged : public DataAbstract { Line 346  class DataTagged : public DataAbstract {
346    
347       Description:       Description:
348       Return the default value. This value is associated with any tag which       Return the default value. This value is associated with any tag which
349       is not explicitly recorded in this DataTagged object.       is not explicitly recorded in this DataTagged object's tag map.
350        T
351    */    */
352      ESCRIPT_DLL_API
353    DataArrayView&    DataArrayView&
354    getDefaultValue();    getDefaultValue();
355    
356    /**    ESCRIPT_DLL_API
      \brief  
      getDefaultValue  
   
      Description:  
      Return the default value, const version.  
   */  
357    const DataArrayView&    const DataArrayView&
358    getDefaultValue() const;    getDefaultValue() const;
359    
# Line 295  class DataTagged : public DataAbstract { Line 362  class DataTagged : public DataAbstract {
362       getLength       getLength
363    
364       Description:       Description:
365       Return the number of doubles stored for the Data.       Return the total number of doubles stored for this DataTagged object.
366        T
367    */    */
368      ESCRIPT_DLL_API
369    virtual    virtual
370    ValueType::size_type    ValueType::size_type
371    getLength() const;    getLength() const;
# Line 306  class DataTagged : public DataAbstract { Line 375  class DataTagged : public DataAbstract {
375       getSlice       getSlice
376    
377       Description:       Description:
378       Factory method that returns a newly created DataTagged object.       Factory method that returns a newly created DataTagged object generated
379       The caller is reponsible for managing the object created.       by taking the specified slice from this DataTagged object.
380         The caller is reponsible for managing the returned object.
381        T
382    */    */
383      ESCRIPT_DLL_API
384    virtual    virtual
385    DataAbstract*    DataAbstract*
386    getSlice(const DataArrayView::RegionType& region) const;    getSlice(const DataArrayView::RegionType& region) const;
387    
388    /**    /**
389       \brief       \brief
390         Slice Constructor for DataTagged.
391    
392         Description:
393         Creates a DataTagged object which is the specified slice
394         from the given DataTagged object.
395         \param other - Input - DataTagged object to slice from.
396         \param region - Input - Region to slice.
397        T
398      */
399      ESCRIPT_DLL_API
400      DataTagged(const DataTagged& other,
401             const DataArrayView::RegionType& region);
402    
403      /**
404         \brief
405       setSlice       setSlice
406    
407       Description:       Description:
408       Copy the specified region from the given value into this object.       Copy the given Data object into the specified region in this object.
409       \param value - Input - Data to copy from.       \param other - Input - Data object to copy from.
410       \param region - Input - Region to copy.       \param region - Input - Region to copy into (NB: must have same shape as other!).
411        T
412    */    */
413      ESCRIPT_DLL_API
414    virtual    virtual
415    void    void
416    setSlice(const DataAbstract* value,    setSlice(const DataAbstract* other,
417             const DataArrayView::RegionType& region);             const DataArrayView::RegionType& region);
418    
419    /**    /**
420       \brief       \brief
421       reshapeDataPoint       Archive the underlying data values to the file referenced
422         by ofstream. A count of the number of values expected to be written
423         is provided as a cross-check.
424    
425       Description:       The return value indicates success (0) or otherwise (1).
      Reshape the data point only if the data-point is currently rank 0.  
      An exception is thrown if the data-point has rank other than 0.  
      The original data point value is used for all values of the new  
      data point.  
426    */    */
427    void    ESCRIPT_DLL_API
428    reshapeDataPoint(const DataArrayView::ShapeType& shape);    int
429      archiveData(std::ofstream& archiveFile,
430                  const DataArrayView::ValueType::size_type noValues) const;
431    
432      /**
433         \brief
434         Extract the number of values specified by noValues from the file
435         referenced by ifstream to the underlying data structure.
436    
437         The return value indicates success (0) or otherwise (1).
438      */
439      ESCRIPT_DLL_API
440      int
441      extractData(std::ifstream& archiveFile,
442                  const DataArrayView::ValueType::size_type noValues);
443    
444      /**
445         \brief
446         Computes a symmetric matrix (A + AT) / 2
447    
448         \param ev - Output - symmetric matrix
449    
450      */
451      ESCRIPT_DLL_API
452      virtual void
453      symmetric(DataAbstract* ev);
454    
455      /**
456         \brief
457         Computes a nonsymmetric matrix (A - AT) / 2
458    
459         \param ev - Output - nonsymmetric matrix
460    
461      */
462      ESCRIPT_DLL_API
463      virtual void
464      nonsymmetric(DataAbstract* ev);
465    
466      /**
467         \brief
468         Computes the trace of a matrix
469    
470         \param ev - Output - the trace of a matrix
471    
472      */
473      ESCRIPT_DLL_API
474      virtual void
475      trace(DataAbstract* ev, int axis_offset);
476    
477      /**
478         \brief
479         swaps components axis0 and axis1
480    
481         \param ev - Output - swapped components
482    
483      */
484      ESCRIPT_DLL_API
485      virtual void
486      swapaxes(DataAbstract* ev, int axis0, int axis1);
487    
488      /**
489         \brief
490         Transpose each data point of this Data object around the given axis.
491    
492         \param ev - Output - the transpose of a matrix
493    
494      */
495      ESCRIPT_DLL_API
496      virtual void
497      transpose(DataAbstract* ev, int axis_offset);
498    
499      /**
500         \brief
501         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
502    
503         \param ev - Output - eigenvalues in increasing order at each data point
504    
505      */
506      ESCRIPT_DLL_API
507      virtual void
508      eigenvalues(DataAbstract* ev);
509    
510      /**
511         \brief
512         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
513    
514         \param ev - Output - eigenvalues in increasing order at each data point
515         \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
516                             and the first nonzero component is positive.
517         \param tol - Input - eigenvalue with relative distance tol are treated as equal.
518    
519      */
520    
521      ESCRIPT_DLL_API
522      virtual void
523      eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
524    
525    
526   protected:   protected:
527    
# Line 349  class DataTagged : public DataAbstract { Line 532  class DataTagged : public DataAbstract {
532    DataMapType m_offsetLookup;    DataMapType m_offsetLookup;
533    
534    //    //
535    // The actual data    // the offset to the default value
536    DataArrayView::ValueType m_data;    static const int m_defaultValueOffset = 0;
537    
538    //    //
539    // the default value offset    // The actual data
540    static const int m_defaultValueOffset = 0;    ValueType m_data;
541    
542  };  };
543    
# Line 370  inline Line 553  inline
553  DataArrayView&  DataArrayView&
554  DataTagged::getDefaultValue()  DataTagged::getDefaultValue()
555  {  {
   //  
556    // The default value is always the first value.    // The default value is always the first value.
557    return getPointDataView();    return getPointDataView();
558  }  }
# Line 379  inline Line 561  inline
561  const DataArrayView&  const DataArrayView&
562  DataTagged::getDefaultValue() const  DataTagged::getDefaultValue() const
563  {  {
   //  
564    // The default value is always the first value.    // The default value is always the first value.
565    return getPointDataView();    return getPointDataView();
566  }  }
567    
568    inline
569    const DataTagged::DataMapType&
570    DataTagged::getTagLookup() const
571    {
572      return m_offsetLookup;
573    }
574    
575    inline
576    DataArrayView::ValueType::size_type
577    DataTagged::getLength() const
578    {
579      return m_data.size();
580    }
581    
582  } // end of namespace  } // end of namespace
583    
584  #endif  #endif

Legend:
Removed from v.102  
changed lines
  Added in v.950

  ViewVC Help
Powered by ViewVC 1.1.26