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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2881 - (show 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
2 /*******************************************************
3 *
4 * Copyright (c) 2003-2010 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
14
15 #if !defined escript_DataTagged_20040615_H
16 #define escript_DataTagged_20040615_H
17 #include "system_dep.h"
18
19 #include "DataReady.h"
20 #include "DataTypes.h"
21
22 #include <vector>
23 #include <map>
24
25 namespace escript {
26
27 class DataConstant;
28
29 /**
30 \brief
31 Simulates a full dataset accessible via sampleNo and dataPointNo.
32
33 Description:
34 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 Thus only a single data-point needs to be stored for a range of sampleNo and
37 dataPointNo values.
38 */
39
40 class DataTagged : public DataReady {
41 typedef DataReady parent;
42 public:
43
44 //
45 // Types for the lists of tags and values.
46 typedef std::vector<int> TagListType;
47 // typedef std::vector<DataArrayView> ValueListType;
48 typedef DataTypes::ValueType ValueType;
49 typedef std::vector<ValueType::ElementType> ValueBatchType;
50
51 //
52 // Map from a tag to an offset into the data array.
53 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 the default data-point is a scalar data-point with value 0.0, and no other
62 tag values are stored.
63 T
64 */
65 ESCRIPT_DLL_API
66 DataTagged();
67
68 /**
69 \brief
70 Alternative Constructor for DataTagged.
71
72 Description:
73 Alternative Constructor for DataTagged.
74 \param what - Input - A description of what this data object represents.
75 \param shape - Input - The shape of each data-point.
76 \param tags - Input - An array of tags, one for each sample number (starts at tag[1]).
77 \param data - The data values for each tag.
78 NB: no unit testing yet
79 */
80 ESCRIPT_DLL_API
81 DataTagged(const FunctionSpace& what,
82 const DataTypes::ShapeType &shape,
83 const int tags[],
84 const ValueType& data);
85
86 /**
87 \brief
88 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 TODO Make sure to document the relationship between tags and data, ie: data also contains the default value
97 */
98 ESCRIPT_DLL_API
99 DataTagged(const FunctionSpace& what,
100 const DataTypes::ShapeType &shape,
101 const TagListType& tags,
102 const ValueType& data);
103
104 /**
105 \brief
106 Copy Constructor for DataTagged.
107 Performs a deep copy from the given DataTagged object.
108 T
109 */
110 ESCRIPT_DLL_API
111 DataTagged(const DataTagged& other);
112
113 /**
114 \brief
115 Copy Constructor for DataTagged.
116 Construct a DataTagged object from a DataConstant object.
117 The default value will be the value of the DataConstant object.
118 T
119 */
120 ESCRIPT_DLL_API
121 DataTagged(const DataConstant& other);
122
123 /**
124 \brief
125 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 Destructor
142 */
143 ESCRIPT_DLL_API
144 inline virtual
145 ~DataTagged() {};
146
147 ESCRIPT_DLL_API
148 bool
149 isTagged() const
150 {
151 return true;
152 };
153
154 /**
155 \brief Return true if any one of the datapoints contains a NaN.
156 */
157 ESCRIPT_DLL_API
158 bool
159 hasNaN() const;
160
161 /**
162 \brief Return a deep copy of the current object.
163 */
164 ESCRIPT_DLL_API
165 virtual
166 DataAbstract*
167 deepCopy();
168
169
170 /**
171 \brief
172 getSampleDataByTag
173
174 Description:
175 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 ** NB: need to do array bounds checking when accessing returned value!
180 T
181 */
182 ESCRIPT_DLL_API
183 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 T
193 */
194 ESCRIPT_DLL_API
195 virtual
196 std::string
197 toString() const;
198 /**
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
207 /**
208 \brief invert square matricies
209 \param out - Where to store the results
210 \return errorcode (0 indicates success)
211 */
212 ESCRIPT_DLL_API
213 virtual int
214 matrixInverse(DataAbstract* out) const;
215
216 /**
217 \brief
218 sets all values to zero
219 */
220 ESCRIPT_DLL_API
221 virtual
222 void
223 setToZero();
224
225 /**
226 \brief
227 Return the tag number associated with the given data-point number
228 according to the associated function space.
229 T
230 */
231 ESCRIPT_DLL_API
232 virtual
233 int
234 getTagNumber(int dpno);
235
236 /**
237 \brief
238 getPointOffset
239
240 Description:
241 Return the offset to the given data-point value in the underlying
242 data vector.
243
244 \param sampleNo - Input - sample number.
245 \param dataPointNo - Input - data-point number.
246 T
247 */
248 ESCRIPT_DLL_API
249 virtual
250 ValueType::size_type
251 getPointOffset(int sampleNo,
252 int dataPointNo) const;
253
254 ESCRIPT_DLL_API
255 virtual
256 ValueType::size_type
257 getPointOffset(int sampleNo,
258 int dataPointNo);
259
260 /**
261 \brief
262 addTaggedValues
263
264 Description:
265 Add the given tags and values to this DataTagged object.
266 \param tagKeys - Input - A vector of integer tags.
267 \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 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 \param vShape - shape of the datapoints in "values"
275 T
276 */
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 */
300 ESCRIPT_DLL_API
301 void
302 addTaggedValues(const TagListType& tagKeys,
303 const ValueType& values,
304 const ShapeType& vShape);
305
306
307
308
309 /**
310 \brief
311 addTaggedValue
312
313 Description:
314 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 \param tagKey - Input - Integer tag.
317 \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 */
321 ESCRIPT_DLL_API
322 void
323 addTaggedValue(int tagKey,
324 const DataTypes::ShapeType& pointshape,
325 const ValueType& value,
326 int dataOffset=0);
327
328 /**
329 \brief
330 addTag - does not modify the default value for this object. ** Not unit tested **
331
332 Description:
333 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 */
338 ESCRIPT_DLL_API
339 void
340 addTag(int tagKey);
341
342 /**
343 \brief
344 setTaggedValue
345
346 Description:
347 Assign the given value to the given tag.
348 \param tagKey - Input - Integer tag.
349 \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 T
353 */
354 ESCRIPT_DLL_API
355 void
356 setTaggedValue(int tagKey,
357 const DataTypes::ShapeType& pointshape,
358 const ValueType& value,
359 int dataOffset=0);
360
361 /**
362 \brief
363 getDataByTag
364
365 Return a pointer to the beginning of the datapoint with the specified tag.
366 TODO Eventually these should be inlined.
367 \param tag - Input - Integer key.
368 \param i - position in the underlying datastructure
369 */
370
371 ESCRIPT_DLL_API
372 DataTypes::ValueType::reference
373 getDataByTagRW(int tag, DataTypes::ValueType::size_type i);
374
375 ESCRIPT_DLL_API
376 DataTypes::ValueType::const_reference
377 getDataByTagRO(int tag, DataTypes::ValueType::size_type i) const;
378
379
380
381 /**
382 \brief
383 getOffsetForTag
384
385 \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 */
390 ESCRIPT_DLL_API
391 DataTypes::ValueType::size_type
392 getOffsetForTag(int tag) const;
393
394
395 /**
396 \brief
397 Return a reference to the underlying DataVector.
398 */
399
400 ESCRIPT_DLL_API
401 DataTypes::ValueType&
402 getVectorRW();
403
404 ESCRIPT_DLL_API
405 const DataTypes::ValueType&
406 getVectorRO() const;
407
408
409
410 /**
411 \brief
412 getTagLookup
413
414 Description:
415 Return a reference to the tag offset lookup table.
416 T
417 */
418 ESCRIPT_DLL_API
419 const DataMapType&
420 getTagLookup() const;
421
422 /**
423 \brief
424 isCurrentTag
425
426 Description:
427 Return true if the given tag exists within the DataTagged tag map.
428
429 *** NB: The DataTagged tag map does not necessarily coincide with the tag
430 keys in the associated function space.
431 T
432 */
433 ESCRIPT_DLL_API
434 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 is not explicitly recorded in this DataTagged object's tag map.
444 \param i - position in the underlying datastructure
445 */
446 ESCRIPT_DLL_API
447 DataTypes::ValueType::reference
448 getDefaultValueRW(DataTypes::ValueType::size_type i);
449
450 ESCRIPT_DLL_API
451 DataTypes::ValueType::const_reference
452 getDefaultValueRO(DataTypes::ValueType::size_type i) const;
453
454
455
456
457
458 /**
459 \brief
460 getLength
461
462 Description:
463 Return the total number of doubles stored for this DataTagged object.
464 T
465 */
466 ESCRIPT_DLL_API
467 virtual
468 ValueType::size_type
469 getLength() const;
470
471 /**
472 \brief
473 getSlice
474
475 Description:
476 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 T
480 */
481 ESCRIPT_DLL_API
482 virtual
483 DataAbstract*
484 getSlice(const DataTypes::RegionType& region) const;
485
486 /**
487 \brief
488 Slice Constructor for DataTagged.
489
490 Description:
491 Creates a DataTagged object which is the specified slice
492 from the given DataTagged object.
493 \param other - Input - DataTagged object to slice from.
494 \param region - Input - Region to slice.
495 T
496 */
497 ESCRIPT_DLL_API
498 DataTagged(const DataTagged& other,
499 const DataTypes::RegionType& region);
500
501 /**
502 \brief
503 setSlice
504
505 Description:
506 Copy the given Data object into the specified region in this object.
507 \param other - Input - Data object to copy from.
508 \param region - Input - Region to copy into (NB: must have same shape as other!).
509 T
510 */
511 ESCRIPT_DLL_API
512 virtual
513 void
514 setSlice(const DataAbstract* other,
515 const DataTypes::RegionType& region);
516
517
518 /**
519 \brief
520 Computes a symmetric matrix (A + AT) / 2
521
522 \param ev - Output - symmetric matrix
523
524 */
525 ESCRIPT_DLL_API
526 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 ESCRIPT_DLL_API
537 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 \param axis_offset
546 */
547 ESCRIPT_DLL_API
548 virtual void
549 trace(DataAbstract* ev, int axis_offset);
550
551 /**
552 \brief
553 swaps components axis0 and axis1
554
555 \param ev - Output - swapped components
556 \param axis0
557 \param axis1
558 */
559 ESCRIPT_DLL_API
560 virtual void
561 swapaxes(DataAbstract* ev, int axis0, int axis1);
562
563 /**
564 \brief
565 Transpose each data point of this Data object around the given axis.
566
567 \param ev - Output - the transpose of a matrix
568 \param axis_offset
569 */
570 ESCRIPT_DLL_API
571 virtual void
572 transpose(DataAbstract* ev, int axis_offset);
573
574 /**
575 \brief
576 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 ESCRIPT_DLL_API
582 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 ESCRIPT_DLL_API
597 virtual void
598 eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
599
600
601 /**
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 protected:
609
610 private:
611
612 //
613 // The offset lookup table
614 DataMapType m_offsetLookup;
615
616 //
617 // the offset to the default value
618 static const int m_defaultValueOffset = 0;
619
620 //
621 // The actual data
622 ValueType m_data;
623
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 inline
635 DataTypes::ValueType::size_type
636 DataTagged::getDefaultOffset() const
637 {
638 return m_defaultValueOffset;
639 }
640
641 inline
642 DataTypes::ValueType::reference
643 DataTagged::getDefaultValueRW(DataTypes::ValueType::size_type i)
644 {
645 return getVectorRW()[i]; // getVectorRW has exclusive write checks
646 }
647
648 inline
649 DataTypes::ValueType::const_reference
650 DataTagged::getDefaultValueRO(DataTypes::ValueType::size_type i) const
651 {
652 return getVectorRO()[i];
653 }
654
655 inline
656 const DataTagged::DataMapType&
657 DataTagged::getTagLookup() const
658 {
659 return m_offsetLookup;
660 }
661
662 inline
663 DataTypes::ValueType::size_type
664 DataTagged::getLength() const
665 {
666 return m_data.size();
667 }
668
669 } // 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