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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26