/[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 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
# Line 58  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 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
60       will map to this single data-point.       tag values are stored.
61        T
62    */    */
63    DataTagged();    DataTagged();
64    
# Line 69  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                 number of keys and the number of values an exception
78               will be generated.               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 94  class DataTagged : public DataAbstract { Line 95  class DataTagged : public DataAbstract {
95       \param shape - Input - The shape of each data-point.       \param shape - Input - The shape of each data-point.
96       \param tags - Input - An 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 tag.       \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);
   
   /**  
      \brief  
      Slice 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);  
104    
105    /**    /**
106       \brief       \brief
107       Copy Constructor for DataTagged.       Copy Constructor for 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       Copy Constructor for DataTagged.       Copy Constructor for DataTagged.
116       Construct a tagged data from a DataConstant object.       Construct a DataTagged object from a DataConstant object.
117       The default value will be that held by the DataConstant object.       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 137  class DataTagged : public DataAbstract { Line 128  class DataTagged : public DataAbstract {
128       sample will be visible via the returned pointer.       sample will be visible via the returned pointer.
129    
130       ** This provides an interface into the data suitable for legacy C code.       ** 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 147  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 156  class DataTagged : public DataAbstract { Line 150  class DataTagged : public DataAbstract {
150       \brief       \brief
151       Return the tag number associated with the given data-point number       Return the tag number associated with the given data-point number
152       according to the associated function space.       according to the associated function space.
153        T
154    */    */
155    virtual    virtual
156    int    int
# Line 171  class DataTagged : public DataAbstract { Line 166  class DataTagged : public DataAbstract {
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 182  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 202  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 214  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 232  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 247  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 258  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.
265       \param sampleNo - Input.       \param sampleNo - Input.
266       \param dataPointNo - Input.       \param dataPointNo - Input.
267        T
268    */    */
269    virtual    virtual
270    DataArrayView    DataArrayView
# Line 274  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 285  class DataTagged : public DataAbstract { Line 289  class DataTagged : public DataAbstract {
289       Description:       Description:
290       Return true if the given tag exists within the DataTagged tag map.       Return true if the given tag exists within the DataTagged tag map.
291    
292       NOTE: The DataTagged tag map does not necessarily coincide with the tag       *** NB: The DataTagged tag map does not necessarily coincide with the tag
293       keys in the associated function space.       keys in the associated function space.
294     */      T
295      */
296    bool    bool
297    isCurrentTag(int tag) const;    isCurrentTag(int tag) const;
298    
# Line 298  class DataTagged : public DataAbstract { Line 303  class DataTagged : public DataAbstract {
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's tag map.       is not explicitly recorded in this DataTagged object's tag map.
306        T
307    */    */
308    DataArrayView&    DataArrayView&
309    getDefaultValue();    getDefaultValue();
# Line 310  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 321  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 330  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 347  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       \brief
386      Archive the underlying data values to the file referenced       Archive the underlying data values to the file referenced
387      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
388      is provided as a cross-check.       is provided as a cross-check.
389    
390      The return value indicates success (0) or otherwise (1).       The return value indicates success (0) or otherwise (1).
391    */    */
392    int    int
393    archiveData(std::ofstream& archiveFile,    archiveData(std::ofstream& archiveFile,
394                const DataArrayView::ValueType::size_type noValues) const;                const DataArrayView::ValueType::size_type noValues) const;
395    
396    /**    /**
397      \brief       \brief
398      Extract the number of values specified by noValues from the file       Extract the number of values specified by noValues from the file
399      referenced by ifstream to the underlying data structure.       referenced by ifstream to the underlying data structure.
400    
401      The return value indicates success (0) or otherwise (1).       The return value indicates success (0) or otherwise (1).
402    */    */
403    int    int
404    extractData(std::ifstream& archiveFile,    extractData(std::ifstream& archiveFile,
405                const DataArrayView::ValueType::size_type noValues);                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:

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

  ViewVC Help
Powered by ViewVC 1.1.26