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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2271 - (hide annotations)
Mon Feb 16 05:08:29 2009 UTC (10 years, 9 months ago) by jfenwick
File MIME type: text/plain
File size: 15986 byte(s)
Merging version 2269 to trunk

1 jgs 121
2 ksteube 1312 /*******************************************************
3 ksteube 1811 *
4     * Copyright (c) 2003-2008 by University of Queensland
5     * 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    
155 phornby 1628 /**
156 jfenwick 1799 \brief Return a deep copy of the current object.
157     */
158     ESCRIPT_DLL_API
159     virtual
160     DataAbstract*
161     deepCopy();
162    
163    
164     /**
165 phornby 1628 \brief
166 jgs 82 getSampleDataByTag
167    
168     Description:
169 jgs 496 Return the data-point for the given tag. All of the data for the
170     sample will be visible via the returned pointer.
171    
172     ** This provides an interface into the data suitable for legacy C code.
173 jgs 507 ** NB: need to do array bounds checking when accessing returned value!
174     T
175 jgs 82 */
176 woo409 757 ESCRIPT_DLL_API
177 jgs 82 virtual
178     double*
179     getSampleDataByTag(int tag);
180    
181     /**
182     \brief
183     Write the data as a string.
184     Writes out each tag, including the default, and the data-point which is
185     associated with each tag.
186 jgs 507 T
187 jgs 82 */
188 woo409 757 ESCRIPT_DLL_API
189 jgs 82 virtual
190     std::string
191     toString() const;
192 gross 950 /**
193     \brief
194     dumps the object into a netCDF file
195     */
196     ESCRIPT_DLL_API
197     virtual
198     void
199     dump(const std::string fileName) const;
200 jgs 82
201 gross 1118 /**
202     \brief
203     sets all values to zero
204     */
205     ESCRIPT_DLL_API
206     virtual
207     void
208     setToZero();
209    
210 jgs 82 /**
211     \brief
212 jgs 496 Return the tag number associated with the given data-point number
213     according to the associated function space.
214 jgs 507 T
215 jgs 149 */
216 woo409 757 ESCRIPT_DLL_API
217 jgs 149 virtual
218     int
219     getTagNumber(int dpno);
220    
221     /**
222     \brief
223 jgs 82 getPointOffset
224    
225     Description:
226 jgs 496 Return the offset to the given data-point value in the underlying
227     data vector.
228 jgs 82
229     \param sampleNo - Input - sample number.
230     \param dataPointNo - Input - data-point number.
231 jgs 507 T
232     */
233 woo409 757 ESCRIPT_DLL_API
234 jgs 82 virtual
235 jgs 121 ValueType::size_type
236 jgs 82 getPointOffset(int sampleNo,
237     int dataPointNo) const;
238    
239 jfenwick 2005 ESCRIPT_DLL_API
240     virtual
241     ValueType::size_type
242     getPointOffset(int sampleNo,
243     int dataPointNo);
244 jfenwick 1796
245     /**
246 jgs 82 \brief
247     addTaggedValues
248    
249     Description:
250 jgs 509 Add the given tags and values to this DataTagged object.
251 jgs 507 \param tagKeys - Input - A vector of integer tags.
252 jfenwick 1796 \param values - Input - A vector of doubles. If this is empty, the default value for
253     this DataTagged will be used for all tags.
254     If it contains one value all tag values will be assigned
255 jgs 509 this value. Otherwise consecutive tags will be assigned
256     consecutive values. If there is a mismatch between the
257     number of keys and the number of values an exception
258     will be generated.
259 jfenwick 1796 \param vShape - shape of the datapoints in "values"
260 jgs 507 T
261 jfenwick 1796 */
262     ESCRIPT_DLL_API
263     void
264     addTaggedValues(const TagListType& tagKeys,
265     const ValueBatchType& values,
266     const ShapeType& vShape);
267    
268    
269     /**
270     Description:
271     Add the given tags and values to this DataTagged object.
272     \param tagKeys - Input - A vector of integer tags.
273     \param values - Input - A DataVector containing the datapoints.
274     If this is empty, the default value for
275     this DataTagged will be used for all tags.
276     If it contains one value all tag values will be assigned
277     this value. Otherwise consecutive tags will be assigned
278     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     \param vShape - shape of the datapoints in "values"
282    
283     TODO Makesure this is properly unit tested
284 jgs 82 */
285 woo409 757 ESCRIPT_DLL_API
286 jgs 82 void
287     addTaggedValues(const TagListType& tagKeys,
288 jfenwick 1796 const ValueType& values,
289     const ShapeType& vShape);
290 jgs 82
291 jfenwick 1796
292    
293    
294 jgs 82 /**
295     \brief
296     addTaggedValue
297    
298     Description:
299 jgs 121 Add a single tag and value to this DataTagged object. If this tag already has
300     a value associated with it, setTaggedValue will be used to update this value.
301 jgs 509 \param tagKey - Input - Integer tag.
302 jfenwick 1796 \param pointshape - Shape of the value parameter
303     \param value - Input - Single DataArrayView value to be assigned to the tag.
304     \param dataOffset - Input - Offset of the beginning of the point in the value parameter
305 jgs 82 */
306 woo409 757 ESCRIPT_DLL_API
307 jgs 82 void
308     addTaggedValue(int tagKey,
309 jfenwick 1796 const DataTypes::ShapeType& pointshape,
310     const ValueType& value,
311     int dataOffset=0);
312 jgs 82
313     /**
314     \brief
315 jfenwick 1796 addTag - does not modify the default value for this object. ** Not unit tested **
316 jgs 82
317     Description:
318 jfenwick 1796 Add a single tag. The default value for this DataTagged will be associated with the tag.
319     If this tag already has a value associated with it, then no change will be made.
320     \param tagKey - Input - Integer tag.
321     TODO: Make sure this is unit tested
322 jgs 82 */
323 woo409 757 ESCRIPT_DLL_API
324 jgs 82 void
325 jfenwick 1796 addTag(int tagKey);
326 jgs 82
327     /**
328     \brief
329     setTaggedValue
330    
331     Description:
332 jgs 509 Assign the given value to the given tag.
333     \param tagKey - Input - Integer tag.
334 jfenwick 1796 \param pointshape - the shape of the value parameter
335     \param value - Input - Vector storing the datapoint to be assigned to the tag.
336     \param dataOffset - beginning of the datapoint within "value".
337 jgs 507 T
338 jgs 82 */
339 woo409 757 ESCRIPT_DLL_API
340 jgs 82 void
341     setTaggedValue(int tagKey,
342 jfenwick 1796 const DataTypes::ShapeType& pointshape,
343     const ValueType& value,
344     int dataOffset=0);
345 jgs 82
346     /**
347     \brief
348 jfenwick 1796 getDataByTag
349 jgs 82
350 jfenwick 1796 Return a pointer to the beginning of the datapoint with the specified tag.
351     TODO Eventually these should be inlined.
352 jgs 82 \param tag - Input - Integer key.
353 jfenwick 1796 \param i - position in the underlying datastructure
354 jgs 82 */
355    
356 jfenwick 1796 ESCRIPT_DLL_API
357     DataTypes::ValueType::reference
358 jfenwick 2271 getDataByTagRW(int tag, DataTypes::ValueType::size_type i);
359 jfenwick 1796
360 jfenwick 2271 ESCRIPT_DLL_API
361     DataTypes::ValueType::const_reference
362     getDataByTagRO(int tag, DataTypes::ValueType::size_type i) const;
363 jfenwick 1796
364 jfenwick 2271
365    
366 jgs 82 /**
367 jfenwick 1796 \brief
368     getOffsetForTag
369 jgs 82
370 jfenwick 1796 \param tag
371     \return the offset of the beginning of the datapoint corresponding to tag.
372    
373     Note: If the tag is not valid, the offset of the default value is returned instead.
374 jgs 82 */
375 woo409 757 ESCRIPT_DLL_API
376 jfenwick 1796 DataTypes::ValueType::size_type
377     getOffsetForTag(int tag) const;
378 jgs 82
379 jfenwick 1796
380 jgs 82 /**
381 gross 983 \brief
382 jfenwick 1796 Return a reference to the underlying DataVector.
383     */
384    
385     ESCRIPT_DLL_API
386     DataTypes::ValueType&
387 jfenwick 2271 getVectorRW();
388 jfenwick 1796
389     ESCRIPT_DLL_API
390     const DataTypes::ValueType&
391 jfenwick 2271 getVectorRO() const;
392 jfenwick 1796
393    
394    
395     /**
396 jgs 82 \brief
397     getTagLookup
398    
399     Description:
400     Return a reference to the tag offset lookup table.
401 jgs 507 T
402 jgs 82 */
403 woo409 757 ESCRIPT_DLL_API
404 jgs 82 const DataMapType&
405     getTagLookup() const;
406    
407     /**
408     \brief
409     isCurrentTag
410    
411     Description:
412 jgs 496 Return true if the given tag exists within the DataTagged tag map.
413    
414 jgs 509 *** NB: The DataTagged tag map does not necessarily coincide with the tag
415 jgs 496 keys in the associated function space.
416 jgs 507 T
417     */
418 woo409 757 ESCRIPT_DLL_API
419 jgs 82 bool
420     isCurrentTag(int tag) const;
421    
422     /**
423     \brief
424     getDefaultValue
425    
426     Description:
427     Return the default value. This value is associated with any tag which
428 jgs 496 is not explicitly recorded in this DataTagged object's tag map.
429 jfenwick 1796 \param i - position in the underlying datastructure
430 jgs 82 */
431 woo409 757 ESCRIPT_DLL_API
432 jfenwick 1796 DataTypes::ValueType::reference
433 jfenwick 2271 getDefaultValueRW(DataTypes::ValueType::size_type i);
434 jgs 82
435 woo409 757 ESCRIPT_DLL_API
436 jfenwick 1796 DataTypes::ValueType::const_reference
437 jfenwick 2271 getDefaultValueRO(DataTypes::ValueType::size_type i) const;
438 jgs 82
439 jfenwick 1796
440    
441    
442 jfenwick 2271
443 jgs 82 /**
444     \brief
445     getLength
446    
447     Description:
448 jgs 509 Return the total number of doubles stored for this DataTagged object.
449 jgs 507 T
450 jgs 82 */
451 woo409 757 ESCRIPT_DLL_API
452 jgs 82 virtual
453     ValueType::size_type
454     getLength() const;
455    
456     /**
457     \brief
458     getSlice
459    
460     Description:
461 jgs 513 Factory method that returns a newly created DataTagged object generated
462     by taking the specified slice from this DataTagged object.
463     The caller is reponsible for managing the returned object.
464 jgs 535 T
465 jgs 82 */
466 woo409 757 ESCRIPT_DLL_API
467 jgs 82 virtual
468     DataAbstract*
469 jfenwick 1796 getSlice(const DataTypes::RegionType& region) const;
470 jgs 82
471     /**
472     \brief
473 jgs 513 Slice Constructor for DataTagged.
474 jgs 82
475     Description:
476 jgs 513 Creates a DataTagged object which is the specified slice
477 jgs 519 from the given DataTagged object.
478     \param other - Input - DataTagged object to slice from.
479     \param region - Input - Region to slice.
480 jgs 535 T
481 jgs 82 */
482 woo409 757 ESCRIPT_DLL_API
483 jgs 513 DataTagged(const DataTagged& other,
484 jfenwick 1796 const DataTypes::RegionType& region);
485 jgs 513
486     /**
487     \brief
488     setSlice
489    
490     Description:
491 jgs 519 Copy the given Data object into the specified region in this object.
492 jgs 513 \param other - Input - Data object to copy from.
493 jgs 519 \param region - Input - Region to copy into (NB: must have same shape as other!).
494 jgs 535 T
495 jgs 513 */
496 woo409 757 ESCRIPT_DLL_API
497 jgs 82 virtual
498     void
499 jgs 513 setSlice(const DataAbstract* other,
500 jfenwick 1796 const DataTypes::RegionType& region);
501 jgs 82
502 jgs 123
503     /**
504 jgs 509 \brief
505 ksteube 775 Computes a symmetric matrix (A + AT) / 2
506    
507     \param ev - Output - symmetric matrix
508    
509     */
510 gross 800 ESCRIPT_DLL_API
511 ksteube 775 virtual void
512     symmetric(DataAbstract* ev);
513    
514     /**
515     \brief
516     Computes a nonsymmetric matrix (A - AT) / 2
517    
518     \param ev - Output - nonsymmetric matrix
519    
520     */
521 gross 800 ESCRIPT_DLL_API
522 ksteube 775 virtual void
523     nonsymmetric(DataAbstract* ev);
524    
525     /**
526     \brief
527     Computes the trace of a matrix
528    
529     \param ev - Output - the trace of a matrix
530    
531     */
532 gross 800 ESCRIPT_DLL_API
533 ksteube 775 virtual void
534 gross 800 trace(DataAbstract* ev, int axis_offset);
535 ksteube 775
536     /**
537     \brief
538 gross 804 swaps components axis0 and axis1
539 gross 800
540     \param ev - Output - swapped components
541    
542     */
543     ESCRIPT_DLL_API
544     virtual void
545 gross 804 swapaxes(DataAbstract* ev, int axis0, int axis1);
546 gross 800
547     /**
548     \brief
549 ksteube 775 Transpose each data point of this Data object around the given axis.
550    
551     \param ev - Output - the transpose of a matrix
552    
553     */
554 gross 800 ESCRIPT_DLL_API
555 ksteube 775 virtual void
556     transpose(DataAbstract* ev, int axis_offset);
557    
558     /**
559     \brief
560 gross 580 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
561    
562     \param ev - Output - eigenvalues in increasing order at each data point
563    
564     */
565 woo409 757 ESCRIPT_DLL_API
566 gross 580 virtual void
567     eigenvalues(DataAbstract* ev);
568    
569     /**
570     \brief
571     solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
572    
573     \param ev - Output - eigenvalues in increasing order at each data point
574     \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
575     and the first nonzero component is positive.
576     \param tol - Input - eigenvalue with relative distance tol are treated as equal.
577    
578     */
579    
580 woo409 757 ESCRIPT_DLL_API
581 gross 580 virtual void
582     eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
583    
584    
585 jfenwick 1796 /**
586     \brief Returns the offset in the structure which stores the default value
587     */
588     ESCRIPT_DLL_API
589     DataTypes::ValueType::size_type
590     getDefaultOffset() const;
591    
592 jgs 82 protected:
593    
594     private:
595    
596     //
597     // The offset lookup table
598     DataMapType m_offsetLookup;
599    
600     //
601 jgs 496 // the offset to the default value
602 jgs 119 static const int m_defaultValueOffset = 0;
603    
604     //
605 jgs 82 // The actual data
606 jgs 121 ValueType m_data;
607 jgs 82
608     };
609    
610     inline
611     bool
612     DataTagged::isCurrentTag(int tag) const
613     {
614     DataMapType::const_iterator pos(m_offsetLookup.find(tag));
615     return (pos!=m_offsetLookup.end());
616     }
617    
618 jfenwick 1796 inline
619     DataTypes::ValueType::size_type
620     DataTagged::getDefaultOffset() const
621 jgs 82 {
622 jfenwick 1796 return m_defaultValueOffset;
623 jgs 82 }
624    
625     inline
626 jfenwick 1796 DataTypes::ValueType::reference
627 jfenwick 2271 DataTagged::getDefaultValueRW(DataTypes::ValueType::size_type i)
628     {
629     return getVectorRW()[i]; // getVectorRW has exclusive write checks
630 jgs 82 }
631    
632 jgs 496 inline
633 jfenwick 1796 DataTypes::ValueType::const_reference
634 jfenwick 2271 DataTagged::getDefaultValueRO(DataTypes::ValueType::size_type i) const
635 gross 983 {
636 jfenwick 2271 return getVectorRO()[i];
637 gross 983 }
638    
639     inline
640 jgs 496 const DataTagged::DataMapType&
641     DataTagged::getTagLookup() const
642     {
643     return m_offsetLookup;
644     }
645    
646     inline
647 jfenwick 1796 DataTypes::ValueType::size_type
648 jgs 496 DataTagged::getLength() const
649     {
650     return m_data.size();
651     }
652    
653 jgs 82 } // end of namespace
654    
655     #endif

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26