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