/[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 1628 by phornby, Fri Jul 11 13:12:46 2008 UTC
# Line 1  Line 1 
 // $Id$  
1    
2  /*  /* $Id$ */
3   ******************************************************************************  
4   *                                                                            *  /*******************************************************
5   *       COPYRIGHT  ACcESS 2004 -  All Rights Reserved                        *   *
6   *                                                                            *   *           Copyright 2003-2007 by ACceSS MNRF
7   * This software is the property of ACcESS. No part of this code              *   *       Copyright 2007 by University of Queensland
8   * may be copied in any form or by any means without the expressed written    *   *
9   * consent of ACcESS.  Copying, use or modification of this software          *   *                http://esscc.uq.edu.au
10   * by any unauthorised person is illegal unless that person has a software    *   *        Primary Business: Queensland, Australia
11   * license agreement with ACcESS.                                             *   *  Licensed under the Open Software License version 3.0
12   *                                                                            *   *     http://www.opensource.org/licenses/osl-3.0.php
13   ******************************************************************************   *
14  */   *******************************************************/
15    
16  #if !defined escript_DataTagged_20040615_H  #if !defined escript_DataTagged_20040615_H
17  #define escript_DataTagged_20040615_H  #define escript_DataTagged_20040615_H
18    #include "system_dep.h"
19    
20  #include "DataAbstract.h"  #include "DataAbstract.h"
21  #include "DataArrayView.h"  #include "DataArrayView.h"
# Line 58  class DataTagged : public DataAbstract { Line 58  class DataTagged : public DataAbstract {
58    
59       Description:       Description:
60       Default constructor for DataTagged. Creates a DataTagged object for which       Default constructor for DataTagged. Creates a DataTagged object for which
61       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
62       will map to this single data-point.       tag values are stored.
63        T
64    */    */
65      ESCRIPT_DLL_API
66    DataTagged();    DataTagged();
67    
68    /**    /**
# Line 69  class DataTagged : public DataAbstract { Line 71  class DataTagged : public DataAbstract {
71    
72       Description:       Description:
73       Constructor for DataTagged.       Constructor for DataTagged.
74       \param tagKeys - Input - A vector of integer keys.       \param tagKeys - Input - A vector of integer tags.
75       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
76                       all tag values will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
77                       it contains one value all tag values will be assigned the                       0. If it contains one value all tag values will be assigned
78               same value. Otherwise if there is a mismatch between               this value. Otherwise consecutive tags will be assigned
79               the number of keys and the number of values an exception                       consecutive values.  If there is a mismatch between  the
80                 number of keys and the number of values an exception
81               will be generated.               will be generated.
82       \param defaultValue - Input - Value returned if a requested tag doesn't exist.       \param defaultValue - Input - Value returned if a requested tag doesn't exist.
83       \param what - Input - A description of what this data represents.       \param what - Input - A description of what this data represents.
84        T
85    */    */
86      ESCRIPT_DLL_API
87    DataTagged(const TagListType& tagKeys,    DataTagged(const TagListType& tagKeys,
88               const ValueListType& values,               const ValueListType& values,
89           const DataArrayView& defaultValue,           const DataArrayView& defaultValue,
# Line 94  class DataTagged : public DataAbstract { Line 99  class DataTagged : public DataAbstract {
99       \param shape - Input - The shape of each data-point.       \param shape - Input - The shape of each data-point.
100       \param tags - Input - An array of tags, one for each sample number.       \param tags - Input - An array of tags, one for each sample number.
101       \param data - The data values for each tag.       \param data - The data values for each tag.
102        NB: no unit testing yet
103    */    */
104      ESCRIPT_DLL_API
105    DataTagged(const FunctionSpace& what,    DataTagged(const FunctionSpace& what,
106               const DataArrayView::ShapeType &shape,               const DataArrayView::ShapeType &shape,
107               const int tags[],               const int tags[],
108               const ValueType &data);               const ValueType& data);
109    
110    /**    /**
111       \brief       \brief
112       Slice Constructor for DataTagged.       Alternative Constructor for DataTagged.
113    
114       Description:       Description:
115       Slice Constructor for DataTagged.       Alternative Constructor for DataTagged.
116       Copies a slice from another DataTagged object.       \param what - Input - A description of what this data object represents.
117       \param other - Input - DataTagged object to copy from.       \param shape - Input - The shape of each data-point.
118       \param region - Input - Region to copy.       \param tags - Input - An vector of tags, one for each sample number.
119         \param data - The data values for each tag.
120        NB: no unit testing yet
121    */    */
122    DataTagged(const DataTagged& other,    ESCRIPT_DLL_API
123           const DataArrayView::RegionType& region);    DataTagged(const FunctionSpace& what,
124                 const DataArrayView::ShapeType &shape,
125                 const TagListType& tags,
126                 const ValueType& data);
127    
128    /**    /**
129       \brief       \brief
130       Copy Constructor for DataTagged.       Copy Constructor for DataTagged.
131       Performs a deep copy from the given DataTagged object.       Performs a deep copy from the given DataTagged object.
132        T
133    */    */
134      ESCRIPT_DLL_API
135    DataTagged(const DataTagged& other);    DataTagged(const DataTagged& other);
136    
137    /**    /**
138       \brief       \brief
139       Copy Constructor for DataTagged.       Copy Constructor for DataTagged.
140       Construct a tagged data from a DataConstant object.       Construct a DataTagged object from a DataConstant object.
141       The default value will be that held by the DataConstant object.       The default value will be the value of the DataConstant object.
142        T
143    */    */
144      ESCRIPT_DLL_API
145    DataTagged(const DataConstant& other);    DataTagged(const DataConstant& other);
146    
147    /**    /**
148       \brief       \brief
149         Destructor
150      */
151      ESCRIPT_DLL_API
152      inline virtual
153      ~DataTagged() {};
154    
155      /**
156         \brief
157       getSampleDataByTag       getSampleDataByTag
158    
159       Description:       Description:
# Line 137  class DataTagged : public DataAbstract { Line 161  class DataTagged : public DataAbstract {
161       sample will be visible via the returned pointer.       sample will be visible via the returned pointer.
162    
163       ** This provides an interface into the data suitable for legacy C code.       ** This provides an interface into the data suitable for legacy C code.
164         ** NB: need to do array bounds checking when accessing returned value!
165        T
166    */    */
167      ESCRIPT_DLL_API
168    virtual    virtual
169    double*    double*
170    getSampleDataByTag(int tag);    getSampleDataByTag(int tag);
# Line 147  class DataTagged : public DataAbstract { Line 174  class DataTagged : public DataAbstract {
174       Write the data as a string.       Write the data as a string.
175       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
176       associated with each tag.       associated with each tag.
177        T
178    */    */
179      ESCRIPT_DLL_API
180    virtual    virtual
181    std::string    std::string
182    toString() const;    toString() const;
183     /**
184         \brief
185         dumps the object into a netCDF file
186      */
187      ESCRIPT_DLL_API
188      virtual
189      void
190      dump(const std::string fileName) const;
191    
192     /**
193         \brief
194        sets all values to zero
195      */
196      ESCRIPT_DLL_API
197      virtual
198      void
199      setToZero();
200    
201    /**    /**
202       \brief       \brief
203       Return the tag number associated with the given data-point number       Return the tag number associated with the given data-point number
204       according to the associated function space.       according to the associated function space.
205        T
206    */    */
207      ESCRIPT_DLL_API
208    virtual    virtual
209    int    int
210    getTagNumber(int dpno);    getTagNumber(int dpno);
# Line 171  class DataTagged : public DataAbstract { Line 219  class DataTagged : public DataAbstract {
219    
220       \param sampleNo - Input - sample number.       \param sampleNo - Input - sample number.
221       \param dataPointNo - Input - data-point number.       \param dataPointNo - Input - data-point number.
222     */      T
223      */
224      ESCRIPT_DLL_API
225    virtual    virtual
226    ValueType::size_type    ValueType::size_type
227    getPointOffset(int sampleNo,    getPointOffset(int sampleNo,
# Line 182  class DataTagged : public DataAbstract { Line 232  class DataTagged : public DataAbstract {
232       addTaggedValues       addTaggedValues
233    
234       Description:       Description:
235       Add the given tags and values to this DataTagged object, by repeatedly       Add the given tags and values to this DataTagged object.
236       using addTaggedValue for each given tag/value pair.       \param tagKeys - Input - A vector of integer tags.
      \param tagKeys - Input - A vector of integer keys.  
237       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
238                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
239                        it contains one value all tags will be assigned the same value.                       0. If it contains one value all tag values will be assigned
240                        Otherwise if there is a mismatch between the number of tags and               this value. Otherwise consecutive tags will be assigned
241                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
242                 number of keys and the number of values an exception
243                 will be generated.
244        T
245    */    */
246      ESCRIPT_DLL_API
247    void    void
248    addTaggedValues(const TagListType& tagKeys,    addTaggedValues(const TagListType& tagKeys,
249                    const ValueListType& values);                      const ValueListType& values);  
# Line 202  class DataTagged : public DataAbstract { Line 255  class DataTagged : public DataAbstract {
255       Description:       Description:
256       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
257       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.
258       \param tagKey - Input - Integer key.       \param tagKey - Input - Integer tag.
259       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
260        T
261    */    */
262      ESCRIPT_DLL_API
263    void    void
264    addTaggedValue(int tagKey,    addTaggedValue(int tagKey,
265                   const DataArrayView& value);                   const DataArrayView& value);
# Line 214  class DataTagged : public DataAbstract { Line 269  class DataTagged : public DataAbstract {
269       setTaggedValues       setTaggedValues
270    
271       Description:       Description:
272       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.
273       using setTaggedValue for each given tag/value pair.       \param tagKeys - Input - A vector of integer tag.
      \param tagKeys - Input - A vector of integer keys.  
274       \param values - Input - A vector of DataArrayViews. If this is empty       \param values - Input - A vector of DataArrayViews. If this is empty
275                        then all given tags will be assigned a value of zero. If                       all tag values will be assigned a scalar data-point of value
276                        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
277                        Otherwise if there is a mismatch between the number of keys and               this value. Otherwise consecutive tags will be assigned
278                        the number of values an exception will be generated.                       consecutive values.  If there is a mismatch between  the
279                 number of keys and the number of values an exception
280                 will be generated.
281        T
282    */    */
283      ESCRIPT_DLL_API
284    void    void
285    setTaggedValues(const TagListType& tagKeys,    setTaggedValues(const TagListType& tagKeys,
286                    const ValueListType& values);                    const ValueListType& values);
# Line 232  class DataTagged : public DataAbstract { Line 290  class DataTagged : public DataAbstract {
290       setTaggedValue       setTaggedValue
291    
292       Description:       Description:
293       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.
294       associated with it, addTaggedValue will be used to add this tag/value pair.       \param tagKey - Input - Integer tag.
      \param tagKey - Input - Integer key.  
295       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
296        T
297    */    */
298      ESCRIPT_DLL_API
299    virtual    virtual
300    void    void
301    setTaggedValue(int tagKey,    setTaggedValue(int tagKey,
# Line 247  class DataTagged : public DataAbstract { Line 306  class DataTagged : public DataAbstract {
306       getDataPointByTag       getDataPointByTag
307    
308       Description:       Description:
309       Return a view into the data-point associated with the given tag.       Return data-point associated with the given tag as a DataArrayView.
310       \param tag - Input - Integer key.       \param tag - Input - Integer key.
311        T
312    */    */
313      ESCRIPT_DLL_API
314    DataArrayView    DataArrayView
315    getDataPointByTag(int tag) const;    getDataPointByTag(int tag) const;
316    
# Line 258  class DataTagged : public DataAbstract { Line 319  class DataTagged : public DataAbstract {
319       getDataPoint       getDataPoint
320    
321       Description:       Description:
322       Return a view into the data-point specified by the given sample       Return the data-point specified by the given sample and data-point
323       and data-point numbers.       numbers as a DataArrayView.
324       \param sampleNo - Input.       \param sampleNo - Input.
325       \param dataPointNo - Input.       \param dataPointNo - Input.
326        T
327    */    */
328      ESCRIPT_DLL_API
329    virtual    virtual
330    DataArrayView    DataArrayView
331    getDataPoint(int sampleNo,    getDataPoint(int sampleNo,
332                 int dataPointNo);                 int dataPointNo);
333    
334    /**    /**
335         \brief
336         getData
337    
338         Description:
339         Return pointer to the data
340        T
341      */
342      ESCRIPT_DLL_API
343      const DataArrayView::ValueType::ElementType*
344      getData() const;
345    
346      /**
347       \brief       \brief
348       getTagLookup       getTagLookup
349    
350       Description:       Description:
351       Return a reference to the tag offset lookup table.       Return a reference to the tag offset lookup table.
352        T
353    */    */
354      ESCRIPT_DLL_API
355    const DataMapType&    const DataMapType&
356    getTagLookup() const;    getTagLookup() const;
357    
# Line 285  class DataTagged : public DataAbstract { Line 362  class DataTagged : public DataAbstract {
362       Description:       Description:
363       Return true if the given tag exists within the DataTagged tag map.       Return true if the given tag exists within the DataTagged tag map.
364    
365       NOTE: The DataTagged tag map does not necessarily coincide with the tag       *** NB: The DataTagged tag map does not necessarily coincide with the tag
366       keys in the associated function space.       keys in the associated function space.
367     */      T
368      */
369      ESCRIPT_DLL_API
370    bool    bool
371    isCurrentTag(int tag) const;    isCurrentTag(int tag) const;
372    
# Line 298  class DataTagged : public DataAbstract { Line 377  class DataTagged : public DataAbstract {
377       Description:       Description:
378       Return the default value. This value is associated with any tag which       Return the default value. This value is associated with any tag which
379       is not explicitly recorded in this DataTagged object's tag map.       is not explicitly recorded in this DataTagged object's tag map.
380        T
381    */    */
382      ESCRIPT_DLL_API
383    DataArrayView&    DataArrayView&
384    getDefaultValue();    getDefaultValue();
385    
386      ESCRIPT_DLL_API
387    const DataArrayView&    const DataArrayView&
388    getDefaultValue() const;    getDefaultValue() const;
389    
# Line 310  class DataTagged : public DataAbstract { Line 392  class DataTagged : public DataAbstract {
392       getLength       getLength
393    
394       Description:       Description:
395       Return the number of doubles stored for the Data.       Return the total number of doubles stored for this DataTagged object.
396        T
397    */    */
398      ESCRIPT_DLL_API
399    virtual    virtual
400    ValueType::size_type    ValueType::size_type
401    getLength() const;    getLength() const;
# Line 321  class DataTagged : public DataAbstract { Line 405  class DataTagged : public DataAbstract {
405       getSlice       getSlice
406    
407       Description:       Description:
408       Factory method that returns a newly created DataTagged object.       Factory method that returns a newly created DataTagged object generated
409       The caller is reponsible for managing the object created.       by taking the specified slice from this DataTagged object.
410         The caller is reponsible for managing the returned object.
411        T
412    */    */
413      ESCRIPT_DLL_API
414    virtual    virtual
415    DataAbstract*    DataAbstract*
416    getSlice(const DataArrayView::RegionType& region) const;    getSlice(const DataArrayView::RegionType& region) const;
417    
418    /**    /**
419       \brief       \brief
420       setSlice       Slice Constructor for DataTagged.
421    
422       Description:       Description:
423       Copy the specified region from the given value into this object.       Creates a DataTagged object which is the specified slice
424       \param value - Input - Data to copy from.       from the given DataTagged object.
425       \param region - Input - Region to copy.       \param other - Input - DataTagged object to slice from.
426         \param region - Input - Region to slice.
427        T
428    */    */
429    virtual    ESCRIPT_DLL_API
430    void    DataTagged(const DataTagged& other,
431    setSlice(const DataAbstract* value,           const DataArrayView::RegionType& region);
            const DataArrayView::RegionType& region);  
432    
433    /**    /**
434       \brief       \brief
435       reshapeDataPoint       setSlice
436    
437       Description:       Description:
438       Reshape the data point only if the data-point is currently rank 0.       Copy the given Data object into the specified region in this object.
439       An exception is thrown if the data-point has rank other than 0.       \param other - Input - Data object to copy from.
440       The original data point value is used for all values of the new       \param region - Input - Region to copy into (NB: must have same shape as other!).
441       data point.      T
442    */    */
443      ESCRIPT_DLL_API
444      virtual
445    void    void
446    reshapeDataPoint(const DataArrayView::ShapeType& shape);    setSlice(const DataAbstract* other,
447               const DataArrayView::RegionType& region);
448    
449    /**    /**
450      \brief       \brief
451      Archive the underlying data values to the file referenced       Archive the underlying data values to the file referenced
452      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
453      is provided as a cross-check.       is provided as a cross-check.
454    
455      The return value indicates success (0) or otherwise (1).       The return value indicates success (0) or otherwise (1).
456    */    */
457      ESCRIPT_DLL_API
458    int    int
459    archiveData(std::ofstream& archiveFile,    archiveData(std::ofstream& archiveFile,
460                const DataArrayView::ValueType::size_type noValues) const;                const DataArrayView::ValueType::size_type noValues) const;
461    
462    /**    /**
463      \brief       \brief
464      Extract the number of values specified by noValues from the file       Extract the number of values specified by noValues from the file
465      referenced by ifstream to the underlying data structure.       referenced by ifstream to the underlying data structure.
466    
467      The return value indicates success (0) or otherwise (1).       The return value indicates success (0) or otherwise (1).
468    */    */
469      ESCRIPT_DLL_API
470    int    int
471    extractData(std::ifstream& archiveFile,    extractData(std::ifstream& archiveFile,
472                const DataArrayView::ValueType::size_type noValues);                const DataArrayView::ValueType::size_type noValues);
473    
474      /**
475         \brief
476         Computes a symmetric matrix (A + AT) / 2
477    
478         \param ev - Output - symmetric matrix
479    
480      */
481      ESCRIPT_DLL_API
482      virtual void
483      symmetric(DataAbstract* ev);
484    
485      /**
486         \brief
487         Computes a nonsymmetric matrix (A - AT) / 2
488    
489         \param ev - Output - nonsymmetric matrix
490    
491      */
492      ESCRIPT_DLL_API
493      virtual void
494      nonsymmetric(DataAbstract* ev);
495    
496      /**
497         \brief
498         Computes the trace of a matrix
499    
500         \param ev - Output - the trace of a matrix
501    
502      */
503      ESCRIPT_DLL_API
504      virtual void
505      trace(DataAbstract* ev, int axis_offset);
506    
507      /**
508         \brief
509         swaps components axis0 and axis1
510    
511         \param ev - Output - swapped components
512    
513      */
514      ESCRIPT_DLL_API
515      virtual void
516      swapaxes(DataAbstract* ev, int axis0, int axis1);
517    
518      /**
519         \brief
520         Transpose each data point of this Data object around the given axis.
521    
522         \param ev - Output - the transpose of a matrix
523    
524      */
525      ESCRIPT_DLL_API
526      virtual void
527      transpose(DataAbstract* ev, int axis_offset);
528    
529      /**
530         \brief
531         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
532    
533         \param ev - Output - eigenvalues in increasing order at each data point
534    
535      */
536      ESCRIPT_DLL_API
537      virtual void
538      eigenvalues(DataAbstract* ev);
539    
540      /**
541         \brief
542         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
543    
544         \param ev - Output - eigenvalues in increasing order at each data point
545         \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
546                             and the first nonzero component is positive.
547         \param tol - Input - eigenvalue with relative distance tol are treated as equal.
548    
549      */
550    
551      ESCRIPT_DLL_API
552      virtual void
553      eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
554    
555    
556   protected:   protected:
557    
558   private:   private:
# Line 421  DataTagged::getDefaultValue() const Line 596  DataTagged::getDefaultValue() const
596  }  }
597    
598  inline  inline
599    const DataArrayView::ValueType::ElementType*
600    DataTagged::getData() const
601    {
602       return &(m_data[0]);
603    }
604    
605    inline
606  const DataTagged::DataMapType&  const DataTagged::DataMapType&
607  DataTagged::getTagLookup() const  DataTagged::getTagLookup() const
608  {  {

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

  ViewVC Help
Powered by ViewVC 1.1.26