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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 6469 - (show annotations)
Tue Jan 17 07:45:36 2017 UTC (2 years, 3 months ago) by jfenwick
File MIME type: text/plain
File size: 15602 byte(s)
Add zeroed copy

1
2 /*****************************************************************************
3 *
4 * Copyright (c) 2003-2016 by The University of Queensland
5 * http://www.uq.edu.au
6 *
7 * Primary Business: Queensland, Australia
8 * Licensed under the Apache License, version 2.0
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Development until 2012 by Earth Systems Science Computational Center (ESSCC)
12 * Development 2012-2013 by School of Earth Sciences
13 * Development from 2014 by Centre for Geoscience Computing (GeoComp)
14 *
15 *****************************************************************************/
16
17 #ifndef __ESCRIPT_DATAABSTRACT_H__
18 #define __ESCRIPT_DATAABSTRACT_H__
19
20 #include "system_dep.h"
21 #include "DataTypes.h"
22 #include "DataVector.h"
23 #include "FunctionSpace.h"
24
25 #include <boost/scoped_ptr.hpp>
26
27 #include "DataException.h"
28
29 #include <string>
30 #include <fstream>
31 #include <vector>
32
33 #include "Pointers.h"
34
35 namespace escript {
36
37 /**
38 \brief
39 DataAbstract provides an abstract interface for the class of containers
40 which hold ESyS data.
41
42 Description:
43 DataAbstract provides an abstract interface for the class of containers
44 which hold ESyS data. The container may be thought of as a 2 dimensional
45 array of data points where one dimension corresponds to the number of samples
46 and the other to the number of data points per sample as defined by the function
47 space associated with each Data object. The data points themselves are arrays of
48 reals or complexes of rank 0-4.
49 */
50
51 class DataAbstract;
52
53 typedef POINTER_WRAPPER_CLASS(DataAbstract) DataAbstract_ptr;
54 typedef POINTER_WRAPPER_CLASS(const DataAbstract) const_DataAbstract_ptr;
55
56 class DataReady;
57
58 typedef POINTER_WRAPPER_CLASS(DataReady) DataReady_ptr;
59 typedef POINTER_WRAPPER_CLASS(const DataReady) const_DataReady_ptr;
60
61 class ESCRIPT_DLL_API DataAbstract : public REFCOUNT_BASE_CLASS(DataAbstract)
62 {
63
64 public:
65
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 DataAbstract_ptr getPtr();
83 const_DataAbstract_ptr getPtr() const;
84
85
86
87 /**
88 \brief
89 Constructor for DataAbstract.
90
91 \param what - Input - The functionspace to use.
92 \param shape - Input - Shape of each data value.
93 \param isDataEmpty - Input - Is this an instance of DataEmpty (for internal use only)
94 */
95 DataAbstract(const FunctionSpace& what, const ShapeType& shape, bool isDataEmpty=false,bool isCplx=false);
96
97 /**
98 \brief
99 Destructor for DataAbstract.
100 */
101 virtual
102 ~DataAbstract();
103
104 /**
105 \brief
106 Write the data as a string.
107 */
108 virtual
109 std::string
110 toString() const = 0;
111
112 /**
113 \brief Return a deep copy of the current object.
114 */
115 virtual
116 DataAbstract*
117 deepCopy() const =0 ;
118
119 /**
120 \brief Return an object with the same type, domain (and tags if appropriate)
121 as this, but all values are zeroed.
122 */
123 virtual
124 DataAbstract*
125 zeroedCopy() const =0 ;
126
127
128
129 /**
130 \brief Return a data object with all points resolved.
131 */
132 virtual
133 DataReady_ptr
134 resolve()=0;
135
136 /**
137 \brief
138 dumps the object into a netCDF file
139 */
140 virtual
141 void
142 dump(const std::string fileName) const;
143
144 /**
145 \brief
146 Return the number of data points per sample.
147 */
148 int
149 getNumDPPSample() const;
150
151 /**
152 \brief
153 Return the number of samples.
154 */
155 int
156 getNumSamples() const;
157
158 bool
159 hasNoSamples() const
160 {
161 return getNumSamples()==0;
162 }
163
164 /**
165 \brief
166 Return the shape information for the point data.
167
168 The omission of a non-constant form is deliberate.
169 */
170 const DataTypes::ShapeType&
171 getShape() const;
172
173 /**
174 \brief
175 Return the rank information for the point data.
176 */
177 unsigned int
178 getRank() const;
179
180
181
182 /**
183 \brief
184 Return the offset for the given sample. This returns the offset for the given
185 point into the container holding the point data.
186
187 \param sampleNo - Input - sample number.
188 \param dataPointNo - Input - data point number.
189 */
190 virtual
191 DataTypes::RealVectorType::size_type
192 getPointOffset(int sampleNo,
193 int dataPointNo) const = 0;
194
195
196
197 /**
198 \brief
199 Return the number of doubles stored for this Data object.
200 */
201 virtual
202 DataTypes::RealVectorType::size_type
203 getLength() const = 0;
204
205 /**
206 \brief
207 Return the real sample data for the given tag key.
208 NB: If the data isn't tagged an exception will be thrown.
209 */
210 virtual
211 DataTypes::real_t*
212 getSampleDataByTag(int tag, DataTypes::real_t dummy=0);
213
214 /**
215 \brief
216 Return the complex sample data for the given tag key.
217 NB: If the data isn't tagged an exception will be thrown.
218 */
219 virtual
220 DataTypes::cplx_t*
221 getSampleDataByTag(int tag, DataTypes::cplx_t dummy);
222
223 /**
224 \brief Return number of tagged values stored in the data object
225 \warning results are only meaningful for DataTagged. All other types return 0.
226 This functionality is only currently used by reducers and should
227 not be exposed to Python without making it more generally applicable
228 */
229 virtual
230 size_t
231 getTagCount() const;
232
233 /**
234 \brief
235 Check this and the given RHS operands are compatible. Throws
236 an exception if they aren't.
237
238 \param right - Input - The right hand side.
239 */
240 void
241 operandCheck(const DataAbstract& right) const;
242
243 /**
244 \brief
245 Return true if a valid sample point number.
246 */
247 bool
248 validSamplePointNo(int samplePointNo) const;
249
250 /**
251 \brief
252 Return true if a valid sample number.
253 */
254 bool
255 validSampleNo(int sampleNo) const;
256
257
258 /**
259 \brief
260 Return the function space associated with this Data object.
261 */
262 const
263 FunctionSpace&
264 getFunctionSpace() const;
265
266 /**
267 \brief
268 Return the given slice from this object.
269
270 NB: The caller is responsible for managing the object created.
271 */
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 - vector to copy data value from
290 \param dataOffset - Input - Offset within value to begin copying from
291
292 The final parameter is to allow for the case whete the vector contains
293 multiple data values.
294 */
295 virtual
296 void
297 setTaggedValue(int tagKey,
298 const DataTypes::ShapeType& pointshape,
299 const DataTypes::RealVectorType& value,
300 int dataOffset=0);
301
302 virtual
303 void
304 setTaggedValue(int tagKey,
305 const DataTypes::ShapeType& pointshape,
306 const DataTypes::CplxVectorType& value,
307 int dataOffset=0);
308
309 /**
310 \brief
311 Copy a double value to the data point dataPointNo of sample sampleNo in this object.
312
313 Description:
314 Copy a double value to the data point dataPointNo of sample sampleNo in this object.
315
316 \param sampleNo Input - sample number
317 \param dataPointNo Input - data point of the sample
318 \param value Input - new values for the data point
319 */
320 virtual void
321 copyToDataPoint(const int sampleNo, const int dataPointNo, const DataTypes::real_t value);
322
323 virtual void
324 copyToDataPoint(const int sampleNo, const int dataPointNo, const DataTypes::cplx_t value);
325
326 /**
327 \brief
328 Copy the array object to the data point dataPointNo of sample sampleNo in this object.
329
330 \param sampleNo Input - sample number
331 \param dataPointNo Input - data point of the sample
332 \param value Input - new values for the data point
333 */
334 virtual void
335 copyToDataPoint(const int sampleNo, const int dataPointNo, const WrappedArray& value);
336
337
338 /**
339 \brief
340 Return the tag number associated with the given data-point number.
341
342 If the object cannot be referenced by tag numbers, an exception
343 will be thrown.
344 */
345 virtual
346 int
347 getTagNumber(int dpno);
348
349 /**
350 \brief
351 Computes a symmetric matrix (A + AT) / 2
352
353 \param ev - Output - a symmetric matrix
354
355 */
356 virtual void
357 symmetric(DataAbstract* ev);
358
359 /**
360 \brief
361 Computes a antisymmetric matrix (A - AT) / 2
362
363 \param ev - Output - a nonsymmetric matrix
364
365 */
366 virtual void
367 antisymmetric(DataAbstract* ev);
368
369 /**
370 \brief
371 Computes a symmetric matrix (A + A*) / 2
372
373 \param ev - Output - an hermitian matrix
374
375 */
376 virtual void
377 hermitian(DataAbstract* ev);
378
379 /**
380 \brief
381 Computes a antisymmetric matrix (A - A*) / 2
382
383 \param ev - Output - an antihermitian matrix
384
385 */
386 virtual void
387 antihermitian(DataAbstract* ev);
388
389 /**
390 \brief
391 Computes the trace of a matrix
392
393 \param ev - Output - the trace of a matrix
394 \param axis_offset
395 */
396 virtual void
397 trace(DataAbstract* ev, int axis_offset);
398
399 /**
400 \brief
401 Transpose each data point of this Data object around the given axis.
402
403 \param ev - Output - the transpose of a matrix
404 \param axis_offset
405 */
406 virtual void
407 transpose(DataAbstract* ev, int axis_offset);
408
409 /**
410 \brief
411 swaps components axis0 and axis1
412
413 \param ev - Output - swapped components
414 \param axis0
415 \param axis1
416 */
417 virtual void
418 swapaxes(DataAbstract* ev, int axis0, int axis1);
419 /**
420 \brief
421 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
422
423 \param ev - Output - eigenvalues in increasing order at each data point
424
425 */
426 virtual void
427 eigenvalues(DataAbstract* ev);
428
429 /**
430 \brief invert square matricies
431 \param out - Where to store the results
432 \return errorcode (0 indicates success)
433 */
434 virtual int
435 matrixInverse(DataAbstract* out) const;
436
437 /**
438 \brief
439 sets values to zero
440
441 */
442 virtual void
443 setToZero();
444
445 /**
446 \brief
447 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
448
449 \param ev - Output - eigenvalues in increasing order at each data point
450 \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
451 and the first nonzero component is positive.
452 \param tol - Input - eigenvalue with relative distance tol are treated as equal.
453
454 */
455
456 virtual void
457 eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
458
459 /**
460 \brief
461 reorders data sample ordered by reference_ids to the ordering of the functions space
462
463 \param reference_ids - Input - reference_ids used for current ordering
464 */
465 virtual void
466 reorderByReferenceIDs(DataTypes::dim_t *reference_ids);
467
468
469
470 /**
471 \brief
472 Return the number of values in the shape for this object.
473 */
474 unsigned int
475 getNoValues() const;
476
477
478 bool isLazy() const; // a test to determine if this object is an instance of DataLazy
479
480 virtual
481 bool
482 isConstant() const {return false;}
483
484 virtual
485 bool
486 isExpanded() const {return false;}
487
488
489 /**
490 \brief
491 Return true if this Data is expanded or resolves to expanded.
492 That is, if it has a separate value for each datapoint in the sample.
493 */
494 virtual
495 bool
496 actsExpanded() const {return false;}
497
498 virtual
499 bool
500 isTagged() const {return false;}
501
502 bool isEmpty() const; // a fast test to determine if this object is an instance of DataEmpty
503
504 /**
505 \brief true if the components of datapoints are complex
506 */
507 bool isComplex() const;
508
509 #ifdef SLOWSHARECHECK
510
511 // For this to be threadsafe, we need to be sure that this is the
512 // only way shared-ness is tested.
513 /**
514 \brief Is this object owned by more than one Data object
515 */
516 bool
517 isShared() const
518 {
519 bool shared=false;
520 #pragma omp critical // because two treads could try
521 { // this check at the same time
522 try // and shared_from_this increments count
523 {
524 shared=shared_from_this().use_count()>2;
525 }
526 catch (...)
527 {
528 }
529 }
530 return shared;
531 }
532 #endif
533
534 #ifdef EXWRITECHK
535 bool exclusivewritecalled; // used to check for some potential programming faults
536 // involving shared data.
537 // This flag only asserts that exclusive write has been called
538 // on this object, it does not definitively guarantee that
539 // sharing has not occurred since that call
540 // This flag is for internal use only may be removed without warning
541 #endif
542
543 /*
544 * Make the object complex
545 */
546 virtual void complicate();
547
548 protected:
549 friend class DataLazy;
550
551 //
552 // The number of samples in this Data object.
553 // This is derived directly from the FunctionSpace.
554 int m_noSamples;
555
556 //
557 // The number of data points per sample in this Data object.
558 // This is derived directly from the FunctionSpace.
559 int m_noDataPointsPerSample;
560
561 //
562 // is the data made of complex components
563 bool m_iscompl;
564 private:
565
566 //
567 // A FunctionSpace which provides a description of the data associated
568 // with this Data object.
569 FunctionSpace m_functionSpace;
570
571 //
572 // The shape of the points stored in this view
573 DataTypes::ShapeType m_shape;
574
575 //
576 // The number of values in each point
577 unsigned int m_novalues;
578
579 //
580 // The rank of the points stored in this view
581 unsigned int m_rank;
582
583 //
584 // Is this an instance of DataEmpty?
585 bool m_isempty;
586 };
587
588 inline
589 bool
590 DataAbstract::isEmpty() const
591 {
592 return m_isempty;
593 }
594
595 inline
596 bool
597 DataAbstract::validSamplePointNo(int samplePointNo) const
598 {
599 return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));
600 }
601
602 inline
603 bool
604 DataAbstract::validSampleNo(int sampleNo) const
605 {
606 return ((0 <= sampleNo) && (sampleNo < m_noSamples));
607 }
608
609 inline
610 int
611 DataAbstract::getNumDPPSample() const
612 {
613 if (isEmpty())
614 {
615 throw DataException("Error - Operations (getNumDPPSample) not permitted on instances of DataEmpty.");
616 }
617 return m_noDataPointsPerSample;
618 }
619
620 inline
621 int
622 DataAbstract::getNumSamples() const
623 {
624 if (isEmpty())
625 {
626 throw DataException("Error - Operations (getNumSamples) not permitted on instances of DataEmpty.");
627 }
628 return m_noSamples;
629 }
630
631 inline
632 const
633 FunctionSpace&
634 DataAbstract::getFunctionSpace() const
635 {
636 return m_functionSpace;
637 }
638
639 inline
640 const DataTypes::ShapeType&
641 DataAbstract::getShape() const
642 {
643 if (isEmpty())
644 {
645 throw DataException("Error - Operations (getShape) not permitted on instances of DataEmpty.");
646 }
647 return m_shape;
648 }
649
650 inline
651 unsigned int
652 DataAbstract::getRank() const
653 {
654 if (isEmpty())
655 {
656 throw DataException("Error - Operations (getRank) not permitted on instances of DataEmpty.");
657 }
658 return m_rank;
659 }
660
661 inline
662 unsigned int
663 DataAbstract::getNoValues() const
664 {
665 if (isEmpty())
666 {
667 throw DataException("Error - Operations (getNoValues) not permitted on instances of DataEmpty.");
668 }
669 return m_novalues;
670 }
671
672 } // end of namespace
673
674 #endif // __ESCRIPT_DATAABSTRACT_H__
675

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26