/[escript]/branches/arrexp_2137_win/escript/src/DataTagged.h
ViewVC logotype

Contents of /branches/arrexp_2137_win/escript/src/DataTagged.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2212 - (show annotations)
Wed Jan 14 00:15:00 2009 UTC (11 years, 5 months ago) by jfenwick
File MIME type: text/plain
File size: 16487 byte(s)
Executive summary:

This commit adds copy on write checks to operations involving shared data. 

Changes:

new #defines:
~~~~~~~~~~~~~
Data.cpp has ASSIGNMENT_MEANS_DEEPCOPY (defaults to undefined).
Defining this will put the data = operator back to making deep copies instead
of sharing data (now the default.)

Data:
~~~~~
. Added exclusiveWrite method to copy the underlying data if it is shared.
. Some operators which took python objects now call the c++ versions intead of duplicating code.

DataAbstract and offspring:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
. Added method to determine whether the data is currently shared.
. Added getVectorRO to children of DataReady.
. Added getTagRO.

. Operations which modify values in place (or return modifiable pointers) now use
a macro to check for sharing. In the case where a modification attempt is detected, it throws an exception. In the future, I will enable this only for debugging.

. This shold not really have been required but the compiler was not choosing the use the const version as I would have liked. Besides, this makes things explict.

. Moved (and de-inlined) getVector in DataConstant (It was virtual in a parent class).

Unit tests:
~~~~~~~~~~~
Added both python and c++ unit tests to check known cases of sharing and "inplace"
modification operations.

General:
~~~~~~~~
Removed some commented out code.

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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26