/[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

revision 496 by jgs, Tue Feb 7 01:27:14 2006 UTC revision 757 by woo409, Mon Jun 26 13:12:56 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    #include "system_dep.h"
18    
19  #include "DataAbstract.h"  #include "DataAbstract.h"
20  #include "DataArrayView.h"  #include "DataArrayView.h"
# Line 58  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 only data-point is a scalar data-point with value 0.0. All tags       the default data-point is a scalar data-point with value 0.0, and no other
61       will map to this single data-point.       tag values are stored.
62        T
63    */    */
64      ESCRIPT_DLL_API
65    DataTagged();    DataTagged();
66    
67    /**    /**
# Line 69  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                 number of keys and the number of values an exception
80               will be generated.               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 94  class DataTagged : public DataAbstract { Line 98  class DataTagged : public DataAbstract {
98       \param shape - Input - The shape of each data-point.       \param shape - Input - The shape of each data-point.
99       \param tags - Input - An array of tags, one for each sample number.       \param tags - Input - An array of tags, one for each sample number.
100       \param data - The data values for each tag.       \param data - The data values for each tag.
101        NB: no unit testing yet
102    */    */
103      ESCRIPT_DLL_API
104    DataTagged(const FunctionSpace& what,    DataTagged(const FunctionSpace& what,
105               const DataArrayView::ShapeType &shape,               const DataArrayView::ShapeType &shape,
106               const int tags[],               const int tags[],
107               const ValueType &data);               const ValueType& data);
108    
109    /**    /**
110       \brief       \brief
111       Slice Constructor for DataTagged.       Alternative Constructor for DataTagged.
112    
113       Description:       Description:
114       Slice Constructor for DataTagged.       Alternative Constructor for DataTagged.
115       Copies a slice from another DataTagged object.       \param what - Input - A description of what this data object represents.
116       \param other - Input - DataTagged object to copy from.       \param shape - Input - The shape of each data-point.
117       \param region - Input - Region to copy.       \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    DataTagged(const DataTagged& other,    ESCRIPT_DLL_API
122           const DataArrayView::RegionType& region);    DataTagged(const FunctionSpace& what,
123                 const DataArrayView::ShapeType &shape,
124                 const TagListType& tags,
125                 const ValueType& data);
126    
127    /**    /**
128       \brief       \brief
129       Copy Constructor for 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       Copy Constructor for DataTagged.       Copy Constructor for DataTagged.
139       Construct a tagged data from a DataConstant object.       Construct a DataTagged object from a DataConstant object.
140       The default value will be that held by the DataConstant object.       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 137  class DataTagged : public DataAbstract { Line 152  class DataTagged : public DataAbstract {
152       sample will be visible via the returned pointer.       sample will be visible via the returned pointer.
153    
154       ** This provides an interface into the data suitable for legacy C code.       ** 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 147  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;
# Line 156  class DataTagged : public DataAbstract { Line 176  class DataTagged : public DataAbstract {
176       \brief       \brief
177       Return the tag number associated with the given data-point number       Return the tag number associated with the given data-point number
178       according to the associated function space.       according to the associated function space.
179        T
180    */    */
181      ESCRIPT_DLL_API
182    virtual    virtual
183    int    int
184    getTagNumber(int dpno);    getTagNumber(int dpno);
# Line 171  class DataTagged : public DataAbstract { Line 193  class DataTagged : public DataAbstract {
193    
194       \param sampleNo - Input - sample number.       \param sampleNo - Input - sample number.
195       \param dataPointNo - Input - data-point number.       \param dataPointNo - Input - data-point number.
196     */      T
197      */
198      ESCRIPT_DLL_API
199    virtual    virtual
200    ValueType::size_type    ValueType::size_type
201    getPointOffset(int sampleNo,    getPointOffset(int sampleNo,
# Line 182  class DataTagged : public DataAbstract { Line 206  class DataTagged : public DataAbstract {
206       addTaggedValues       addTaggedValues
207    
208       Description:       Description:
209       Add the given tags and values to this DataTagged object, by repeatedly       Add the given tags and values to this DataTagged object.
210       using addTaggedValue for each given tag/value pair.       \param tagKeys - Input - A vector of integer tags.
      \param tagKeys - Input - A vector of integer keys.  
211       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
212                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
213                        it contains one value all tags will be assigned the same value.                       0. If it contains one value all tag values will be assigned
214                        Otherwise if there is a mismatch between the number of tags and               this value. Otherwise consecutive tags will be assigned
215                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
216                 number of keys and the number of values an exception
217                 will be generated.
218        T
219    */    */
220      ESCRIPT_DLL_API
221    void    void
222    addTaggedValues(const TagListType& tagKeys,    addTaggedValues(const TagListType& tagKeys,
223                    const ValueListType& values);                      const ValueListType& values);  
# Line 202  class DataTagged : public DataAbstract { Line 229  class DataTagged : public DataAbstract {
229       Description:       Description:
230       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
231       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.
232       \param tagKey - Input - Integer key.       \param tagKey - Input - Integer tag.
233       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
234        T
235    */    */
236      ESCRIPT_DLL_API
237    void    void
238    addTaggedValue(int tagKey,    addTaggedValue(int tagKey,
239                   const DataArrayView& value);                   const DataArrayView& value);
# Line 214  class DataTagged : public DataAbstract { Line 243  class DataTagged : public DataAbstract {
243       setTaggedValues       setTaggedValues
244    
245       Description:       Description:
246       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.
247       using setTaggedValue for each given tag/value pair.       \param tagKeys - Input - A vector of integer tag.
      \param tagKeys - Input - A vector of integer keys.  
248       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
249                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
250                        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
251                        Otherwise if there is a mismatch between the number of keys and               this value. Otherwise consecutive tags will be assigned
252                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
253                 number of keys and the number of values an exception
254                 will be generated.
255        T
256    */    */
257      ESCRIPT_DLL_API
258    void    void
259    setTaggedValues(const TagListType& tagKeys,    setTaggedValues(const TagListType& tagKeys,
260                    const ValueListType& values);                    const ValueListType& values);
# Line 232  class DataTagged : public DataAbstract { Line 264  class DataTagged : public DataAbstract {
264       setTaggedValue       setTaggedValue
265    
266       Description:       Description:
267       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.
268       associated with it, addTaggedValue will be used to add this tag/value pair.       \param tagKey - Input - Integer tag.
      \param tagKey - Input - Integer key.  
269       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
270        T
271    */    */
272      ESCRIPT_DLL_API
273    virtual    virtual
274    void    void
275    setTaggedValue(int tagKey,    setTaggedValue(int tagKey,
# Line 247  class DataTagged : public DataAbstract { Line 280  class DataTagged : public DataAbstract {
280       getDataPointByTag       getDataPointByTag
281    
282       Description:       Description:
283       Return a view into the data-point associated with the given tag.       Return data-point associated with the given tag as a DataArrayView.
284       \param tag - Input - Integer key.       \param tag - Input - Integer key.
285        T
286    */    */
287      ESCRIPT_DLL_API
288    DataArrayView    DataArrayView
289    getDataPointByTag(int tag) const;    getDataPointByTag(int tag) const;
290    
# Line 258  class DataTagged : public DataAbstract { Line 293  class DataTagged : public DataAbstract {
293       getDataPoint       getDataPoint
294    
295       Description:       Description:
296       Return a view into the data-point specified by the given sample       Return the data-point specified by the given sample and data-point
297       and data-point numbers.       numbers as a DataArrayView.
298       \param sampleNo - Input.       \param sampleNo - Input.
299       \param dataPointNo - Input.       \param dataPointNo - Input.
300        T
301    */    */
302      ESCRIPT_DLL_API
303    virtual    virtual
304    DataArrayView    DataArrayView
305    getDataPoint(int sampleNo,    getDataPoint(int sampleNo,
# Line 274  class DataTagged : public DataAbstract { Line 311  class DataTagged : public DataAbstract {
311    
312       Description:       Description:
313       Return a reference to the tag offset lookup table.       Return a reference to the tag offset lookup table.
314        T
315    */    */
316      ESCRIPT_DLL_API
317    const DataMapType&    const DataMapType&
318    getTagLookup() const;    getTagLookup() const;
319    
# Line 285  class DataTagged : public DataAbstract { Line 324  class DataTagged : public DataAbstract {
324       Description:       Description:
325       Return true if the given tag exists within the DataTagged tag map.       Return true if the given tag exists within the DataTagged tag map.
326    
327       NOTE: The DataTagged tag map does not necessarily coincide with the tag       *** NB: The DataTagged tag map does not necessarily coincide with the tag
328       keys in the associated function space.       keys in the associated function space.
329     */      T
330      */
331      ESCRIPT_DLL_API
332    bool    bool
333    isCurrentTag(int tag) const;    isCurrentTag(int tag) const;
334    
# Line 298  class DataTagged : public DataAbstract { Line 339  class DataTagged : public DataAbstract {
339       Description:       Description:
340       Return the default value. This value is associated with any tag which       Return the default value. This value is associated with any tag which
341       is not explicitly recorded in this DataTagged object's tag map.       is not explicitly recorded in this DataTagged object's tag map.
342        T
343    */    */
344      ESCRIPT_DLL_API
345    DataArrayView&    DataArrayView&
346    getDefaultValue();    getDefaultValue();
347    
348      ESCRIPT_DLL_API
349    const DataArrayView&    const DataArrayView&
350    getDefaultValue() const;    getDefaultValue() const;
351    
# Line 310  class DataTagged : public DataAbstract { Line 354  class DataTagged : public DataAbstract {
354       getLength       getLength
355    
356       Description:       Description:
357       Return the number of doubles stored for the Data.       Return the total number of doubles stored for this DataTagged object.
358        T
359    */    */
360      ESCRIPT_DLL_API
361    virtual    virtual
362    ValueType::size_type    ValueType::size_type
363    getLength() const;    getLength() const;
# Line 321  class DataTagged : public DataAbstract { Line 367  class DataTagged : public DataAbstract {
367       getSlice       getSlice
368    
369       Description:       Description:
370       Factory method that returns a newly created DataTagged object.       Factory method that returns a newly created DataTagged object generated
371       The caller is reponsible for managing the object created.       by taking the specified slice from this DataTagged object.
372         The caller is reponsible for managing the returned object.
373        T
374    */    */
375      ESCRIPT_DLL_API
376    virtual    virtual
377    DataAbstract*    DataAbstract*
378    getSlice(const DataArrayView::RegionType& region) const;    getSlice(const DataArrayView::RegionType& region) const;
379    
380    /**    /**
381       \brief       \brief
382         Slice Constructor for DataTagged.
383    
384         Description:
385         Creates a DataTagged object which is the specified slice
386         from the given DataTagged object.
387         \param other - Input - DataTagged object to slice from.
388         \param region - Input - Region to slice.
389        T
390      */
391      ESCRIPT_DLL_API
392      DataTagged(const DataTagged& other,
393             const DataArrayView::RegionType& region);
394    
395      /**
396         \brief
397       setSlice       setSlice
398    
399       Description:       Description:
400       Copy the specified region from the given value into this object.       Copy the given Data object into the specified region in this object.
401       \param value - Input - Data to copy from.       \param other - Input - Data object to copy from.
402       \param region - Input - Region to copy.       \param region - Input - Region to copy into (NB: must have same shape as other!).
403        T
404    */    */
405      ESCRIPT_DLL_API
406    virtual    virtual
407    void    void
408    setSlice(const DataAbstract* value,    setSlice(const DataAbstract* other,
409             const DataArrayView::RegionType& region);             const DataArrayView::RegionType& region);
410    
411    /**    /**
# Line 347  class DataTagged : public DataAbstract { Line 413  class DataTagged : public DataAbstract {
413       reshapeDataPoint       reshapeDataPoint
414    
415       Description:       Description:
416       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
417       An exception is thrown if the data-point has rank other than 0.       if current data-points are scalars. An exception is thrown if
418       The original data point value is used for all values of the new       the current data-points have rank other than 0.
419       data point.       The original values of the data-points are used for all values
420         of the new data-points.
421        T
422    */    */
423      ESCRIPT_DLL_API
424    void    void
425    reshapeDataPoint(const DataArrayView::ShapeType& shape);    reshapeDataPoint(const DataArrayView::ShapeType& shape);
426    
427    /**    /**
428      \brief       \brief
429      Archive the underlying data values to the file referenced       Archive the underlying data values to the file referenced
430      by ofstream. A count of the number of values expected to be written       by ofstream. A count of the number of values expected to be written
431      is provided as a cross-check.       is provided as a cross-check.
432    
433      The return value indicates success (0) or otherwise (1).       The return value indicates success (0) or otherwise (1).
434    */    */
435      ESCRIPT_DLL_API
436    int    int
437    archiveData(std::ofstream& archiveFile,    archiveData(std::ofstream& archiveFile,
438                const DataArrayView::ValueType::size_type noValues) const;                const DataArrayView::ValueType::size_type noValues) const;
439    
440    /**    /**
441      \brief       \brief
442      Extract the number of values specified by noValues from the file       Extract the number of values specified by noValues from the file
443      referenced by ifstream to the underlying data structure.       referenced by ifstream to the underlying data structure.
444    
445      The return value indicates success (0) or otherwise (1).       The return value indicates success (0) or otherwise (1).
446    */    */
447      ESCRIPT_DLL_API
448    int    int
449    extractData(std::ifstream& archiveFile,    extractData(std::ifstream& archiveFile,
450                const DataArrayView::ValueType::size_type noValues);                const DataArrayView::ValueType::size_type noValues);
451    
452      /**
453         \brief
454         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
455    
456         \param ev - Output - eigenvalues in increasing order at each data point
457    
458      */
459      ESCRIPT_DLL_API
460      virtual void
461      eigenvalues(DataAbstract* ev);
462    
463      /**
464         \brief
465         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
466    
467         \param ev - Output - eigenvalues in increasing order at each data point
468         \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
469                             and the first nonzero component is positive.
470         \param tol - Input - eigenvalue with relative distance tol are treated as equal.
471    
472      */
473    
474      ESCRIPT_DLL_API
475      virtual void
476      eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
477    
478    
479   protected:   protected:
480    
481   private:   private:

Legend:
Removed from v.496  
changed lines
  Added in v.757

  ViewVC Help
Powered by ViewVC 1.1.26