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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26