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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

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

  ViewVC Help
Powered by ViewVC 1.1.26