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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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_DataAbstract_20040315_H
16 #define escript_DataAbstract_20040315_H
17 #include "system_dep.h"
18
19 #include "DataTypes.h"
20 #include "FunctionSpace.h"
21
22 #include <boost/scoped_ptr.hpp>
23 #include <boost/python/numeric.hpp>
24
25 #include "DataException.h"
26
27 #include <string>
28 #include <fstream>
29 #include <vector>
30
31 #include "Pointers.h"
32
33 namespace escript {
34
35 /**
36 \brief
37 DataAbstract provides an abstract interface for the class of containers
38 which hold ESyS data.
39
40 Description:
41 DataAbstract provides an abstract interface for the class of containers
42 which hold ESyS data. The container may be thought of as a 2 dimensional
43 array of data points where one dimension corresponds to the number of samples
44 and the other to the number of data points per sample as defined by the function
45 space associated with each Data object. The data points themselves are arrays of
46 doubles of rank 0-4.
47 */
48
49 class DataAbstract;
50
51 typedef POINTER_WRAPPER_CLASS(DataAbstract) DataAbstract_ptr;
52 typedef POINTER_WRAPPER_CLASS(const DataAbstract) const_DataAbstract_ptr;
53
54 class DataReady;
55
56 typedef POINTER_WRAPPER_CLASS(DataReady) DataReady_ptr;
57 typedef POINTER_WRAPPER_CLASS(const DataReady) const_DataReady_ptr;
58
59 class DataAbstract : public REFCOUNT_BASE_CLASS(DataAbstract)
60 {
61
62 public:
63
64 typedef DataTypes::ValueType ValueType;
65 typedef DataTypes::ShapeType ShapeType;
66
67 /**
68 \brief Return shared pointer managing this object.
69
70 If there is not already a shared pointer managing this object then create one.
71 Once a shared pointer is created for an object, the deallocation of the object
72 must be handled by shared_ptr.
73
74 \warning So, do not call this on an automatic object.
75 Do not call this in a method where you do not pass the shared_pointer out and
76 you need the object to outlast the method.
77
78 Note: This is _not_ equivalent to weak_ptr::lock.
79
80 */
81 ESCRIPT_DLL_API
82 DataAbstract_ptr getPtr();
83 ESCRIPT_DLL_API
84 const_DataAbstract_ptr getPtr() const;
85
86
87
88 /**
89 \brief
90 Constructor for DataAbstract.
91
92 Description:
93 Constructor for DataAbstract.
94
95 \param what - Input - A description of what this data represents.
96 */
97 ESCRIPT_DLL_API
98 DataAbstract(const FunctionSpace& what, const ShapeType& shape, bool isDataEmpty=false);
99
100 /**
101 \brief
102 Destructor for DataAbstract.
103 */
104 ESCRIPT_DLL_API
105 virtual
106 ~DataAbstract();
107
108 /**
109 \brief
110 Write the data as a string.
111 */
112 ESCRIPT_DLL_API
113 virtual
114 std::string
115 toString() const = 0;
116
117 /**
118 \brief Return a deep copy of the current object.
119 */
120 ESCRIPT_DLL_API
121 virtual
122 DataAbstract*
123 deepCopy()=0;
124
125 /**
126 \brief Return a data object with all points resolved.
127 */
128 ESCRIPT_DLL_API
129 virtual
130 DataReady_ptr
131 resolve()=0;
132
133 /**
134 \brief
135 dumps the object into a netCDF file
136 */
137 ESCRIPT_DLL_API
138 virtual
139 void
140 dump(const std::string fileName) const;
141
142 /**
143 \brief
144 Return the number of data points per sample.
145 */
146 ESCRIPT_DLL_API
147 int
148 getNumDPPSample() const;
149
150 /**
151 \brief
152 Return the number of samples.
153 */
154 ESCRIPT_DLL_API
155 int
156 getNumSamples() const;
157
158 /**
159 \brief
160 Return the shape information for the point data.
161
162 The omission of a non-constant form is deliberate.
163 */
164 ESCRIPT_DLL_API
165 const DataTypes::ShapeType&
166 getShape() const;
167
168 /**
169 \brief
170 Return the rank information for the point data.
171 */
172 ESCRIPT_DLL_API
173 unsigned int
174 getRank() const;
175
176
177
178 /**
179 \brief
180 Return the offset for the given sample. This returns the offset for the given
181 point into the container holding the point data.
182
183 \param sampleNo - Input - sample number.
184 \param dataPointNo - Input - data point number.
185 */
186 ESCRIPT_DLL_API
187 virtual
188 ValueType::size_type
189 getPointOffset(int sampleNo,
190 int dataPointNo) const = 0;
191
192 ESCRIPT_DLL_API
193 virtual
194 ValueType::size_type
195 getPointOffset(int sampleNo,
196 int dataPointNo) = 0;
197
198
199 /**
200 \brief
201 Return the number of doubles stored for this Data object.
202 */
203 ESCRIPT_DLL_API
204 virtual
205 ValueType::size_type
206 getLength() const = 0;
207
208 /**
209 \brief
210 Return the sample data for the given tag key.
211 NB: If the data isn't tagged an exception will be thrown.
212 */
213 ESCRIPT_DLL_API
214 virtual
215 double*
216 getSampleDataByTag(int tag);
217
218 /**
219 This method is used primarily for LazyData.
220 \return the size of the buffer required to evaulate a sample for this object.
221 */
222 ESCRIPT_DLL_API
223 virtual size_t
224 getSampleBufferSize() const=0;
225
226
227
228 /**
229 \brief
230 Check this and the given RHS operands are compatible. Throws
231 an exception if they aren't.
232
233 \param right - Input - The right hand side.
234 */
235 ESCRIPT_DLL_API
236 void
237 operandCheck(const DataAbstract& right) const;
238
239 /**
240 \brief
241 Return true if a valid sample point number.
242 */
243 ESCRIPT_DLL_API
244 bool
245 validSamplePointNo(int samplePointNo) const;
246
247 /**
248 \brief
249 Return true if a valid sample number.
250 */
251 ESCRIPT_DLL_API
252 bool
253 validSampleNo(int sampleNo) const;
254
255
256 /**
257 \brief
258 Return the function space associated with this Data object.
259 */
260 ESCRIPT_DLL_API
261 const
262 FunctionSpace&
263 getFunctionSpace() const;
264
265 /**
266 \brief
267 Return the given slice from this object.
268
269 NB: The caller is responsible for managing the object created.
270 */
271 ESCRIPT_DLL_API
272 virtual
273 DataAbstract*
274 getSlice(const DataTypes::RegionType& region) const = 0;
275
276
277
278 /**
279 \brief
280 setTaggedValue
281
282 Description:
283 Assign the given value to the given tag.
284
285 NB: If the data isn't tagged an exception will be thrown.
286
287 \param tagKey - Input - Integer key.
288 \param pointshape - Input - the shape of the value parameter.
289 \param value - Input -
290 */
291 ESCRIPT_DLL_API
292 virtual
293 void
294 setTaggedValue(int tagKey,
295 const DataTypes::ShapeType& pointshape,
296 const DataTypes::ValueType& value,
297 int dataOffset=0);
298
299
300 /**
301 \brief
302 Copy a double value to the data point dataPointNo of sample sampleNo in this object.
303
304 Description:
305 Copy a double value to the data point dataPointNo of sample sampleNo in this object.
306
307 \param sampleNo Input - sample number
308 \param dataPointNo Input - data point of the sample
309 \param value Input - new values for the data point
310 */
311 ESCRIPT_DLL_API
312 virtual void
313 copyToDataPoint(const int sampleNo, const int dataPointNo, const double value);
314
315 /**
316 \brief
317 Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
318
319 Description:
320 Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
321
322 \param sampleNo Input - sample number
323 \param dataPointNo Input - data point of the sample
324 \param value Input - new values for the data point
325 */
326 ESCRIPT_DLL_API
327 virtual void
328 copyToDataPoint(const int sampleNo, const int dataPointNo, const WrappedArray& value);
329
330
331 /**
332 \brief
333 Return the tag number associated with the given data-point number.
334
335 If the object cannot be referenced by tag numbers, an exception
336 will be thrown.
337 */
338 ESCRIPT_DLL_API
339 virtual
340 int
341 getTagNumber(int dpno);
342
343 /**
344 \brief
345 Computes a symmetric matrix (A + AT) / 2
346
347 \param ev - Output - a symmetric matrix
348
349 */
350 ESCRIPT_DLL_API
351 virtual void
352 symmetric(DataAbstract* ev);
353
354 /**
355 \brief
356 Computes a nonsymmetric matrix (A - AT) / 2
357
358 \param ev - Output - a nonsymmetric matrix
359
360 */
361 ESCRIPT_DLL_API
362 virtual void
363 nonsymmetric(DataAbstract* ev);
364
365 /**
366 \brief
367 Computes the trace of a matrix
368
369 \param ev - Output - the trace of a matrix
370
371 */
372 ESCRIPT_DLL_API
373 virtual void
374 trace(DataAbstract* ev, int axis_offset);
375
376 /**
377 \brief
378 Transpose each data point of this Data object around the given axis.
379
380 \param ev - Output - the transpose of a matrix
381
382 */
383 ESCRIPT_DLL_API
384 virtual void
385 transpose(DataAbstract* ev, int axis_offset);
386
387 /**
388 \brief
389 swaps components axis0 and axis1
390
391 \param ev - Output - swapped components
392
393 */
394 ESCRIPT_DLL_API
395 virtual void
396 swapaxes(DataAbstract* ev, int axis0, int axis1);
397 /**
398 \brief
399 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
400
401 \param ev - Output - eigenvalues in increasing order at each data point
402
403 */
404 ESCRIPT_DLL_API
405 virtual void
406 eigenvalues(DataAbstract* ev);
407
408 /**
409 \brief
410 sets values to zero
411
412 */
413 ESCRIPT_DLL_API
414 virtual void
415 setToZero();
416
417 /**
418 \brief
419 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
420
421 \param ev - Output - eigenvalues in increasing order at each data point
422 \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
423 and the first nonzero component is positive.
424 \param tol - Input - eigenvalue with relative distance tol are treated as equal.
425
426 */
427
428 ESCRIPT_DLL_API
429 virtual void
430 eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
431
432 /**
433 \brief
434 reorders data sample ordered by reference_ids to the ordering of the functions space
435
436 \param reference_ids - Input - reference_ids used for current ordering
437 */
438 ESCRIPT_DLL_API
439 virtual void
440 reorderByReferenceIDs(int *reference_ids);
441
442
443
444 /**
445 \brief
446 Return the number of values in the shape for this object.
447 */
448 ESCRIPT_DLL_API
449 unsigned int
450 getNoValues() const;
451
452
453 ESCRIPT_DLL_API
454 bool isLazy() const; // a test to determine if this object is an instance of DataLazy
455
456 ESCRIPT_DLL_API
457 virtual
458 bool
459 isConstant() const {return false;}
460
461 ESCRIPT_DLL_API
462 virtual
463 bool
464 isExpanded() const {return false;}
465
466
467 /**
468 \brief
469 Return true if this Data is expanded or resolves to expanded.
470 That is, if it has a separate value for each datapoint in the sample.
471 */
472 virtual
473 bool
474 actsExpanded() const {return false;}
475
476 virtual
477 bool
478 isTagged() const {return false;}
479
480 ESCRIPT_DLL_API
481 bool isEmpty() const; // a fast test to determine if this object is an instance of DataEmpty
482
483
484 /**
485 \warning should only be used in single threaded code (or inside a single/critical section)
486 */
487 void
488 addOwner(Data*);
489
490 /**
491 \warning should only be used in single threaded code (or inside a single/critical section)
492 */
493 void
494 removeOwner(Data*);
495
496 /**
497 \brief Is this object owned by more than one Data object
498 */
499 ESCRIPT_DLL_API
500 bool
501 isShared() const
502 {
503 return m_lazyshared || (m_owners.size()>1);
504 }
505
506 protected:
507
508 /**
509 \brief Returns true if this object is not shared.
510 For internal use only. - It may not be particularly fast
511 */
512 ESCRIPT_DLL_API
513 bool checkNoSharing() const;
514
515 /**
516 \brief Marks this DataAbstract shared as LazyData
517 For internal use only.
518 */
519 void
520 makeLazyShared();
521
522 friend class DataLazy;
523
524 private:
525
526 //
527 // The number of samples in this Data object.
528 // This is derived directly from the FunctionSpace.
529 int m_noSamples;
530
531 //
532 // The number of data points per sample in this Data object.
533 // This is derived directly from the FunctionSpace.
534 int m_noDataPointsPerSample;
535
536 //
537 // A FunctionSpace which provides a description of the data associated
538 // with this Data object.
539 FunctionSpace m_functionSpace;
540
541 //
542 // The shape of the points stored in this view
543 DataTypes::ShapeType m_shape;
544
545 //
546 // The number of values in each point
547 unsigned int m_novalues;
548
549 //
550 // The rank of the points stored in this view
551 unsigned int m_rank;
552
553 //
554 // Is this an instance of DataEmpty?
555 bool m_isempty;
556
557 public: // these should be private once I have finished debugging
558 std::vector<Data*> m_owners;
559 bool m_lazyshared;
560 };
561
562 inline
563 bool
564 DataAbstract::isEmpty() const
565 {
566 return m_isempty;
567 }
568
569 inline
570 bool
571 DataAbstract::validSamplePointNo(int samplePointNo) const
572 {
573 return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));
574 }
575
576 inline
577 bool
578 DataAbstract::validSampleNo(int sampleNo) const
579 {
580 return ((0 <= sampleNo) && (sampleNo < m_noSamples));
581 }
582
583 inline
584 int
585 DataAbstract::getNumDPPSample() const
586 {
587 if (isEmpty())
588 {
589 throw DataException("Error - Operations not permitted on instances of DataEmpty.");
590 }
591 return m_noDataPointsPerSample;
592 }
593
594 inline
595 int
596 DataAbstract::getNumSamples() const
597 {
598 if (isEmpty())
599 {
600 throw DataException("Error - Operations not permitted on instances of DataEmpty.");
601 }
602 return m_noSamples;
603 }
604
605 inline
606 const
607 FunctionSpace&
608 DataAbstract::getFunctionSpace() const
609 {
610 return m_functionSpace;
611 }
612
613 inline
614 const DataTypes::ShapeType&
615 DataAbstract::getShape() const
616 {
617 if (isEmpty())
618 {
619 throw DataException("Error - Operations not permitted on instances of DataEmpty.");
620 }
621 return m_shape;
622 }
623
624 inline
625 unsigned int
626 DataAbstract::getRank() const
627 {
628 if (isEmpty())
629 {
630 throw DataException("Error - Operations not permitted on instances of DataEmpty.");
631 }
632 return m_rank;
633 }
634
635 inline
636 unsigned int
637 DataAbstract::getNoValues() const
638 {
639 if (isEmpty())
640 {
641 throw DataException("Error - Operations not permitted on instances of DataEmpty.");
642 }
643 return m_novalues;
644 }
645
646
647 } // end of namespace
648
649 #endif

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26