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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2881 - (hide annotations)
Thu Jan 28 02:03:15 2010 UTC (9 years, 10 months ago) by jfenwick
File MIME type: text/plain
File size: 16396 byte(s)
Don't panic.
Updating copyright stamps

1 jgs 121
2 ksteube 1312 /*******************************************************
3 ksteube 1811 *
4 jfenwick 2881 * Copyright (c) 2003-2010 by University of Queensland
5 ksteube 1811 * Earth Systems Science Computational Center (ESSCC)
6     * http://www.uq.edu.au/esscc
7     *
8     * Primary Business: Queensland, Australia
9     * Licensed under the Open Software License version 3.0
10     * http://www.opensource.org/licenses/osl-3.0.php
11     *
12     *******************************************************/
13 ksteube 1312
14 ksteube 1811
15 jgs 82 #if !defined escript_DataTagged_20040615_H
16     #define escript_DataTagged_20040615_H
17 woo409 757 #include "system_dep.h"
18 jgs 82
19 jfenwick 2005 #include "DataReady.h"
20 jfenwick 1796 #include "DataTypes.h"
21 jgs 82
22     #include <vector>
23     #include <map>
24    
25     namespace escript {
26    
27     class DataConstant;
28    
29     /**
30     \brief
31 jgs 496 Simulates a full dataset accessible via sampleNo and dataPointNo.
32 jgs 82
33     Description:
34 jgs 496 Each data-point has an associated tag number, and a given tag can represent a
35     range of dataPointNo and sampleNo. Each tag indexes only a single data-point.
36 jgs 82 Thus only a single data-point needs to be stored for a range of sampleNo and
37     dataPointNo values.
38     */
39    
40 jfenwick 2005 class DataTagged : public DataReady {
41     typedef DataReady parent;
42 jgs 82 public:
43    
44 jgs 119 //
45 jgs 496 // Types for the lists of tags and values.
46 jgs 121 typedef std::vector<int> TagListType;
47 jfenwick 1796 // typedef std::vector<DataArrayView> ValueListType;
48     typedef DataTypes::ValueType ValueType;
49     typedef std::vector<ValueType::ElementType> ValueBatchType;
50 jgs 82
51     //
52 jgs 496 // Map from a tag to an offset into the data array.
53 jgs 82 typedef std::map<int, int> DataMapType;
54    
55     /**
56     \brief
57     Default constructor for DataTagged.
58    
59     Description:
60     Default constructor for DataTagged. Creates a DataTagged object for which
61 jgs 509 the default data-point is a scalar data-point with value 0.0, and no other
62     tag values are stored.
63 jgs 507 T
64 jgs 82 */
65 woo409 757 ESCRIPT_DLL_API
66 jgs 82 DataTagged();
67    
68     /**
69     \brief
70 jgs 496 Alternative Constructor for DataTagged.
71 jgs 119
72     Description:
73 jgs 496 Alternative Constructor for DataTagged.
74 jgs 119 \param what - Input - A description of what this data object represents.
75 jgs 496 \param shape - Input - The shape of each data-point.
76 jfenwick 1796 \param tags - Input - An array of tags, one for each sample number (starts at tag[1]).
77 jgs 496 \param data - The data values for each tag.
78 jgs 535 NB: no unit testing yet
79 jgs 119 */
80 woo409 757 ESCRIPT_DLL_API
81 jgs 119 DataTagged(const FunctionSpace& what,
82 jfenwick 1796 const DataTypes::ShapeType &shape,
83 jgs 119 const int tags[],
84 jgs 500 const ValueType& data);
85 jgs 119
86 jfenwick 1796 /**
87 jgs 119 \brief
88 woo409 757 Alternative Constructor for DataTagged.
89    
90     Description:
91     Alternative Constructor for DataTagged.
92     \param what - Input - A description of what this data object represents.
93     \param shape - Input - The shape of each data-point.
94     \param tags - Input - An vector of tags, one for each sample number.
95     \param data - The data values for each tag.
96 jfenwick 1796 TODO Make sure to document the relationship between tags and data, ie: data also contains the default value
97     */
98 woo409 757 ESCRIPT_DLL_API
99     DataTagged(const FunctionSpace& what,
100 jfenwick 1796 const DataTypes::ShapeType &shape,
101 woo409 757 const TagListType& tags,
102     const ValueType& data);
103    
104     /**
105     \brief
106 jgs 496 Copy Constructor for DataTagged.
107 jgs 82 Performs a deep copy from the given DataTagged object.
108 jgs 507 T
109 jgs 82 */
110 woo409 757 ESCRIPT_DLL_API
111 jgs 82 DataTagged(const DataTagged& other);
112    
113     /**
114     \brief
115 jgs 496 Copy Constructor for DataTagged.
116 jgs 509 Construct a DataTagged object from a DataConstant object.
117     The default value will be the value of the DataConstant object.
118 jgs 507 T
119 jgs 82 */
120 woo409 757 ESCRIPT_DLL_API
121 jgs 82 DataTagged(const DataConstant& other);
122    
123     /**
124     \brief
125 jfenwick 1796 Copies the tags from a DataTagged into a new Data Tagged and assigns them the default value. ** Not unit tested **
126    
127     This is different from a deep copy because we are not copying shape or other information, just tags.
128     \param what - Input - FunctionSpace for the new DataTagged
129     \param shape - Input - Shape for points in the new DataTagged
130     \param defaultvalue - Input - Default value for new DataTagged
131     \param tagsource - Input - A DataTagged object which supplies the tags.
132     */
133     ESCRIPT_DLL_API
134     DataTagged(const FunctionSpace& what,
135     const DataTypes::ShapeType& shape,
136     const DataTypes::ValueType& defaultvalue,
137     const DataTagged* tagsource=0);
138    
139     /**
140     \brief
141 phornby 1628 Destructor
142     */
143     ESCRIPT_DLL_API
144     inline virtual
145     ~DataTagged() {};
146    
147 jfenwick 2005 ESCRIPT_DLL_API
148     bool
149     isTagged() const
150     {
151     return true;
152     };
153    
154 jfenwick 2766 /**
155     \brief Return true if any one of the datapoints contains a NaN.
156     */
157     ESCRIPT_DLL_API
158     bool
159     hasNaN() const;
160 jfenwick 2005
161 phornby 1628 /**
162 jfenwick 1799 \brief Return a deep copy of the current object.
163     */
164     ESCRIPT_DLL_API
165     virtual
166     DataAbstract*
167     deepCopy();
168    
169    
170     /**
171 phornby 1628 \brief
172 jgs 82 getSampleDataByTag
173    
174     Description:
175 jgs 496 Return the data-point for the given tag. All of the data for the
176     sample will be visible via the returned pointer.
177    
178     ** This provides an interface into the data suitable for legacy C code.
179 jgs 507 ** NB: need to do array bounds checking when accessing returned value!
180     T
181 jgs 82 */
182 woo409 757 ESCRIPT_DLL_API
183 jgs 82 virtual
184     double*
185     getSampleDataByTag(int tag);
186    
187     /**
188     \brief
189     Write the data as a string.
190     Writes out each tag, including the default, and the data-point which is
191     associated with each tag.
192 jgs 507 T
193 jgs 82 */
194 woo409 757 ESCRIPT_DLL_API
195 jgs 82 virtual
196     std::string
197     toString() const;
198 gross 950 /**
199     \brief
200     dumps the object into a netCDF file
201     */
202     ESCRIPT_DLL_API
203     virtual
204     void
205     dump(const std::string fileName) const;
206 jgs 82
207 jfenwick 2742 /**
208     \brief invert square matricies
209     \param out - Where to store the results
210 jfenwick 2792 \return errorcode (0 indicates success)
211 jfenwick 2742 */
212     ESCRIPT_DLL_API
213 jfenwick 2792 virtual int
214 jfenwick 2742 matrixInverse(DataAbstract* out) const;
215    
216 gross 1118 /**
217     \brief
218     sets all values to zero
219     */
220     ESCRIPT_DLL_API
221     virtual
222     void
223     setToZero();
224    
225 jgs 82 /**
226     \brief
227 jgs 496 Return the tag number associated with the given data-point number
228     according to the associated function space.
229 jgs 507 T
230 jgs 149 */
231 woo409 757 ESCRIPT_DLL_API
232 jgs 149 virtual
233     int
234     getTagNumber(int dpno);
235    
236     /**
237     \brief
238 jgs 82 getPointOffset
239    
240     Description:
241 jgs 496 Return the offset to the given data-point value in the underlying
242     data vector.
243 jgs 82
244     \param sampleNo - Input - sample number.
245     \param dataPointNo - Input - data-point number.
246 jgs 507 T
247     */
248 woo409 757 ESCRIPT_DLL_API
249 jgs 82 virtual
250 jgs 121 ValueType::size_type
251 jgs 82 getPointOffset(int sampleNo,
252     int dataPointNo) const;
253    
254 jfenwick 2005 ESCRIPT_DLL_API
255     virtual
256     ValueType::size_type
257     getPointOffset(int sampleNo,
258     int dataPointNo);
259 jfenwick 1796
260     /**
261 jgs 82 \brief
262     addTaggedValues
263    
264     Description:
265 jgs 509 Add the given tags and values to this DataTagged object.
266 jgs 507 \param tagKeys - Input - A vector of integer tags.
267 jfenwick 1796 \param values - Input - A vector of doubles. If this is empty, the default value for
268     this DataTagged will be used for all tags.
269     If it contains one value all tag values will be assigned
270 jgs 509 this value. Otherwise consecutive tags will be assigned
271     consecutive values. If there is a mismatch between the
272     number of keys and the number of values an exception
273     will be generated.
274 jfenwick 1796 \param vShape - shape of the datapoints in "values"
275 jgs 507 T
276 jfenwick 1796 */
277     ESCRIPT_DLL_API
278     void
279     addTaggedValues(const TagListType& tagKeys,
280     const ValueBatchType& values,
281     const ShapeType& vShape);
282    
283    
284     /**
285     Description:
286     Add the given tags and values to this DataTagged object.
287     \param tagKeys - Input - A vector of integer tags.
288     \param values - Input - A DataVector containing the datapoints.
289     If this is empty, the default value for
290     this DataTagged will be used for all tags.
291     If it contains one value all tag values will be assigned
292     this value. Otherwise consecutive tags will be assigned
293     consecutive values. If there is a mismatch between the
294     number of keys and the number of values an exception
295     will be generated.
296     \param vShape - shape of the datapoints in "values"
297    
298     TODO Makesure this is properly unit tested
299 jgs 82 */
300 woo409 757 ESCRIPT_DLL_API
301 jgs 82 void
302     addTaggedValues(const TagListType& tagKeys,
303 jfenwick 1796 const ValueType& values,
304     const ShapeType& vShape);
305 jgs 82
306 jfenwick 1796
307    
308    
309 jgs 82 /**
310     \brief
311     addTaggedValue
312    
313     Description:
314 jgs 121 Add a single tag and value to this DataTagged object. If this tag already has
315     a value associated with it, setTaggedValue will be used to update this value.
316 jgs 509 \param tagKey - Input - Integer tag.
317 jfenwick 1796 \param pointshape - Shape of the value parameter
318     \param value - Input - Single DataArrayView value to be assigned to the tag.
319     \param dataOffset - Input - Offset of the beginning of the point in the value parameter
320 jgs 82 */
321 woo409 757 ESCRIPT_DLL_API
322 jgs 82 void
323     addTaggedValue(int tagKey,
324 jfenwick 1796 const DataTypes::ShapeType& pointshape,
325     const ValueType& value,
326     int dataOffset=0);
327 jgs 82
328     /**
329     \brief
330 jfenwick 1796 addTag - does not modify the default value for this object. ** Not unit tested **
331 jgs 82
332     Description:
333 jfenwick 1796 Add a single tag. The default value for this DataTagged will be associated with the tag.
334     If this tag already has a value associated with it, then no change will be made.
335     \param tagKey - Input - Integer tag.
336     TODO: Make sure this is unit tested
337 jgs 82 */
338 woo409 757 ESCRIPT_DLL_API
339 jgs 82 void
340 jfenwick 1796 addTag(int tagKey);
341 jgs 82
342     /**
343     \brief
344     setTaggedValue
345    
346     Description:
347 jgs 509 Assign the given value to the given tag.
348     \param tagKey - Input - Integer tag.
349 jfenwick 1796 \param pointshape - the shape of the value parameter
350     \param value - Input - Vector storing the datapoint to be assigned to the tag.
351     \param dataOffset - beginning of the datapoint within "value".
352 jgs 507 T
353 jgs 82 */
354 woo409 757 ESCRIPT_DLL_API
355 jgs 82 void
356     setTaggedValue(int tagKey,
357 jfenwick 1796 const DataTypes::ShapeType& pointshape,
358     const ValueType& value,
359     int dataOffset=0);
360 jgs 82
361     /**
362     \brief
363 jfenwick 1796 getDataByTag
364 jgs 82
365 jfenwick 1796 Return a pointer to the beginning of the datapoint with the specified tag.
366     TODO Eventually these should be inlined.
367 jgs 82 \param tag - Input - Integer key.
368 jfenwick 1796 \param i - position in the underlying datastructure
369 jgs 82 */
370    
371 jfenwick 1796 ESCRIPT_DLL_API
372     DataTypes::ValueType::reference
373 jfenwick 2271 getDataByTagRW(int tag, DataTypes::ValueType::size_type i);
374 jfenwick 1796
375 jfenwick 2271 ESCRIPT_DLL_API
376     DataTypes::ValueType::const_reference
377     getDataByTagRO(int tag, DataTypes::ValueType::size_type i) const;
378 jfenwick 1796
379 jfenwick 2271
380    
381 jgs 82 /**
382 jfenwick 1796 \brief
383     getOffsetForTag
384 jgs 82
385 jfenwick 1796 \param tag
386     \return the offset of the beginning of the datapoint corresponding to tag.
387    
388     Note: If the tag is not valid, the offset of the default value is returned instead.
389 jgs 82 */
390 woo409 757 ESCRIPT_DLL_API
391 jfenwick 1796 DataTypes::ValueType::size_type
392     getOffsetForTag(int tag) const;
393 jgs 82
394 jfenwick 1796
395 jgs 82 /**
396 gross 983 \brief
397 jfenwick 1796 Return a reference to the underlying DataVector.
398     */
399    
400     ESCRIPT_DLL_API
401     DataTypes::ValueType&
402 jfenwick 2271 getVectorRW();
403 jfenwick 1796
404     ESCRIPT_DLL_API
405     const DataTypes::ValueType&
406 jfenwick 2271 getVectorRO() const;
407 jfenwick 1796
408    
409    
410     /**
411 jgs 82 \brief
412     getTagLookup
413    
414     Description:
415     Return a reference to the tag offset lookup table.
416 jgs 507 T
417 jgs 82 */
418 woo409 757 ESCRIPT_DLL_API
419 jgs 82 const DataMapType&
420     getTagLookup() const;
421    
422     /**
423     \brief
424     isCurrentTag
425    
426     Description:
427 jgs 496 Return true if the given tag exists within the DataTagged tag map.
428    
429 jgs 509 *** NB: The DataTagged tag map does not necessarily coincide with the tag
430 jgs 496 keys in the associated function space.
431 jgs 507 T
432     */
433 woo409 757 ESCRIPT_DLL_API
434 jgs 82 bool
435     isCurrentTag(int tag) const;
436    
437     /**
438     \brief
439     getDefaultValue
440    
441     Description:
442     Return the default value. This value is associated with any tag which
443 jgs 496 is not explicitly recorded in this DataTagged object's tag map.
444 jfenwick 1796 \param i - position in the underlying datastructure
445 jgs 82 */
446 woo409 757 ESCRIPT_DLL_API
447 jfenwick 1796 DataTypes::ValueType::reference
448 jfenwick 2271 getDefaultValueRW(DataTypes::ValueType::size_type i);
449 jgs 82
450 woo409 757 ESCRIPT_DLL_API
451 jfenwick 1796 DataTypes::ValueType::const_reference
452 jfenwick 2271 getDefaultValueRO(DataTypes::ValueType::size_type i) const;
453 jgs 82
454 jfenwick 1796
455    
456    
457 jfenwick 2271
458 jgs 82 /**
459     \brief
460     getLength
461    
462     Description:
463 jgs 509 Return the total number of doubles stored for this DataTagged object.
464 jgs 507 T
465 jgs 82 */
466 woo409 757 ESCRIPT_DLL_API
467 jgs 82 virtual
468     ValueType::size_type
469     getLength() const;
470    
471     /**
472     \brief
473     getSlice
474    
475     Description:
476 jgs 513 Factory method that returns a newly created DataTagged object generated
477     by taking the specified slice from this DataTagged object.
478     The caller is reponsible for managing the returned object.
479 jgs 535 T
480 jgs 82 */
481 woo409 757 ESCRIPT_DLL_API
482 jgs 82 virtual
483     DataAbstract*
484 jfenwick 1796 getSlice(const DataTypes::RegionType& region) const;
485 jgs 82
486     /**
487     \brief
488 jgs 513 Slice Constructor for DataTagged.
489 jgs 82
490     Description:
491 jgs 513 Creates a DataTagged object which is the specified slice
492 jgs 519 from the given DataTagged object.
493     \param other - Input - DataTagged object to slice from.
494     \param region - Input - Region to slice.
495 jgs 535 T
496 jgs 82 */
497 woo409 757 ESCRIPT_DLL_API
498 jgs 513 DataTagged(const DataTagged& other,
499 jfenwick 1796 const DataTypes::RegionType& region);
500 jgs 513
501     /**
502     \brief
503     setSlice
504    
505     Description:
506 jgs 519 Copy the given Data object into the specified region in this object.
507 jgs 513 \param other - Input - Data object to copy from.
508 jgs 519 \param region - Input - Region to copy into (NB: must have same shape as other!).
509 jgs 535 T
510 jgs 513 */
511 woo409 757 ESCRIPT_DLL_API
512 jgs 82 virtual
513     void
514 jgs 513 setSlice(const DataAbstract* other,
515 jfenwick 1796 const DataTypes::RegionType& region);
516 jgs 82
517 jgs 123
518     /**
519 jgs 509 \brief
520 ksteube 775 Computes a symmetric matrix (A + AT) / 2
521    
522     \param ev - Output - symmetric matrix
523    
524     */
525 gross 800 ESCRIPT_DLL_API
526 ksteube 775 virtual void
527     symmetric(DataAbstract* ev);
528    
529     /**
530     \brief
531     Computes a nonsymmetric matrix (A - AT) / 2
532    
533     \param ev - Output - nonsymmetric matrix
534    
535     */
536 gross 800 ESCRIPT_DLL_API
537 ksteube 775 virtual void
538     nonsymmetric(DataAbstract* ev);
539    
540     /**
541     \brief
542     Computes the trace of a matrix
543    
544     \param ev - Output - the trace of a matrix
545 jfenwick 2519 \param axis_offset
546 ksteube 775 */
547 gross 800 ESCRIPT_DLL_API
548 ksteube 775 virtual void
549 gross 800 trace(DataAbstract* ev, int axis_offset);
550 ksteube 775
551     /**
552     \brief
553 gross 804 swaps components axis0 and axis1
554 gross 800
555     \param ev - Output - swapped components
556 jfenwick 2519 \param axis0
557     \param axis1
558 gross 800 */
559     ESCRIPT_DLL_API
560     virtual void
561 gross 804 swapaxes(DataAbstract* ev, int axis0, int axis1);
562 gross 800
563     /**
564     \brief
565 ksteube 775 Transpose each data point of this Data object around the given axis.
566    
567     \param ev - Output - the transpose of a matrix
568 jfenwick 2519 \param axis_offset
569 ksteube 775 */
570 gross 800 ESCRIPT_DLL_API
571 ksteube 775 virtual void
572     transpose(DataAbstract* ev, int axis_offset);
573    
574     /**
575     \brief
576 gross 580 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
577    
578     \param ev - Output - eigenvalues in increasing order at each data point
579    
580     */
581 woo409 757 ESCRIPT_DLL_API
582 gross 580 virtual void
583     eigenvalues(DataAbstract* ev);
584    
585     /**
586     \brief
587     solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
588    
589     \param ev - Output - eigenvalues in increasing order at each data point
590     \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
591     and the first nonzero component is positive.
592     \param tol - Input - eigenvalue with relative distance tol are treated as equal.
593    
594     */
595    
596 woo409 757 ESCRIPT_DLL_API
597 gross 580 virtual void
598     eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
599    
600    
601 jfenwick 1796 /**
602     \brief Returns the offset in the structure which stores the default value
603     */
604     ESCRIPT_DLL_API
605     DataTypes::ValueType::size_type
606     getDefaultOffset() const;
607    
608 jgs 82 protected:
609    
610     private:
611    
612     //
613     // The offset lookup table
614     DataMapType m_offsetLookup;
615    
616     //
617 jgs 496 // the offset to the default value
618 jgs 119 static const int m_defaultValueOffset = 0;
619    
620     //
621 jgs 82 // The actual data
622 jgs 121 ValueType m_data;
623 jgs 82
624     };
625    
626     inline
627     bool
628     DataTagged::isCurrentTag(int tag) const
629     {
630     DataMapType::const_iterator pos(m_offsetLookup.find(tag));
631     return (pos!=m_offsetLookup.end());
632     }
633    
634 jfenwick 1796 inline
635     DataTypes::ValueType::size_type
636     DataTagged::getDefaultOffset() const
637 jgs 82 {
638 jfenwick 1796 return m_defaultValueOffset;
639 jgs 82 }
640    
641     inline
642 jfenwick 1796 DataTypes::ValueType::reference
643 jfenwick 2271 DataTagged::getDefaultValueRW(DataTypes::ValueType::size_type i)
644     {
645     return getVectorRW()[i]; // getVectorRW has exclusive write checks
646 jgs 82 }
647    
648 jgs 496 inline
649 jfenwick 1796 DataTypes::ValueType::const_reference
650 jfenwick 2271 DataTagged::getDefaultValueRO(DataTypes::ValueType::size_type i) const
651 gross 983 {
652 jfenwick 2271 return getVectorRO()[i];
653 gross 983 }
654    
655     inline
656 jgs 496 const DataTagged::DataMapType&
657     DataTagged::getTagLookup() const
658     {
659     return m_offsetLookup;
660     }
661    
662     inline
663 jfenwick 1796 DataTypes::ValueType::size_type
664 jgs 496 DataTagged::getLength() const
665     {
666     return m_data.size();
667     }
668    
669 jgs 82 } // end of namespace
670    
671     #endif

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26