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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2519 - (show annotations)
Mon Jul 6 00:43:08 2009 UTC (10 years, 4 months ago) by jfenwick
File MIME type: text/plain
File size: 13909 byte(s)
Correcting some doxygen errors
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 \param what - Input - The functionspace to use.
93 \param shape - Input - Shape of each data value.
94 \param isDataEmpty - Input - Is this an instance of DataEmpty (for internal use only)
95 */
96 ESCRIPT_DLL_API
97 DataAbstract(const FunctionSpace& what, const ShapeType& shape, bool isDataEmpty=false);
98
99 /**
100 \brief
101 Destructor for DataAbstract.
102 */
103 ESCRIPT_DLL_API
104 virtual
105 ~DataAbstract();
106
107 /**
108 \brief
109 Write the data as a string.
110 */
111 ESCRIPT_DLL_API
112 virtual
113 std::string
114 toString() const = 0;
115
116 /**
117 \brief Return a deep copy of the current object.
118 */
119 ESCRIPT_DLL_API
120 virtual
121 DataAbstract*
122 deepCopy()=0;
123
124 /**
125 \brief Return a data object with all points resolved.
126 */
127 ESCRIPT_DLL_API
128 virtual
129 DataReady_ptr
130 resolve()=0;
131
132 /**
133 \brief
134 dumps the object into a netCDF file
135 */
136 ESCRIPT_DLL_API
137 virtual
138 void
139 dump(const std::string fileName) const;
140
141 /**
142 \brief
143 Return the number of data points per sample.
144 */
145 ESCRIPT_DLL_API
146 int
147 getNumDPPSample() const;
148
149 /**
150 \brief
151 Return the number of samples.
152 */
153 ESCRIPT_DLL_API
154 int
155 getNumSamples() const;
156
157 /**
158 \brief
159 Return the shape information for the point data.
160
161 The omission of a non-constant form is deliberate.
162 */
163 ESCRIPT_DLL_API
164 const DataTypes::ShapeType&
165 getShape() const;
166
167 /**
168 \brief
169 Return the rank information for the point data.
170 */
171 ESCRIPT_DLL_API
172 unsigned int
173 getRank() const;
174
175
176
177 /**
178 \brief
179 Return the offset for the given sample. This returns the offset for the given
180 point into the container holding the point data.
181
182 \param sampleNo - Input - sample number.
183 \param dataPointNo - Input - data point number.
184 */
185 ESCRIPT_DLL_API
186 virtual
187 ValueType::size_type
188 getPointOffset(int sampleNo,
189 int dataPointNo) const = 0;
190
191 ESCRIPT_DLL_API
192 virtual
193 ValueType::size_type
194 getPointOffset(int sampleNo,
195 int dataPointNo) = 0;
196
197
198 /**
199 \brief
200 Return the number of doubles stored for this Data object.
201 */
202 ESCRIPT_DLL_API
203 virtual
204 ValueType::size_type
205 getLength() const = 0;
206
207 /**
208 \brief
209 Return the sample data for the given tag key.
210 NB: If the data isn't tagged an exception will be thrown.
211 */
212 ESCRIPT_DLL_API
213 virtual
214 double*
215 getSampleDataByTag(int tag);
216
217 /**
218 This method is used primarily for LazyData.
219 \return the size of the buffer required to evaulate a sample for this object.
220 */
221 ESCRIPT_DLL_API
222 virtual size_t
223 getSampleBufferSize() const=0;
224
225
226
227 /**
228 \brief
229 Check this and the given RHS operands are compatible. Throws
230 an exception if they aren't.
231
232 \param right - Input - The right hand side.
233 */
234 ESCRIPT_DLL_API
235 void
236 operandCheck(const DataAbstract& right) const;
237
238 /**
239 \brief
240 Return true if a valid sample point number.
241 */
242 ESCRIPT_DLL_API
243 bool
244 validSamplePointNo(int samplePointNo) const;
245
246 /**
247 \brief
248 Return true if a valid sample number.
249 */
250 ESCRIPT_DLL_API
251 bool
252 validSampleNo(int sampleNo) const;
253
254
255 /**
256 \brief
257 Return the function space associated with this Data object.
258 */
259 ESCRIPT_DLL_API
260 const
261 FunctionSpace&
262 getFunctionSpace() const;
263
264 /**
265 \brief
266 Return the given slice from this object.
267
268 NB: The caller is responsible for managing the object created.
269 */
270 ESCRIPT_DLL_API
271 virtual
272 DataAbstract*
273 getSlice(const DataTypes::RegionType& region) const = 0;
274
275
276
277 /**
278 \brief
279 setTaggedValue
280
281 Description:
282 Assign the given value to the given tag.
283
284 NB: If the data isn't tagged an exception will be thrown.
285
286 \param tagKey - Input - Integer key.
287 \param pointshape - Input - the shape of the value parameter.
288 \param value - Input - vector to copy data value from
289 \param dataOffset - Input - Offset within value to begin copying from
290
291 The final parameter is to allow for the case whete the vector contains
292 multiple data values.
293 */
294 ESCRIPT_DLL_API
295 virtual
296 void
297 setTaggedValue(int tagKey,
298 const DataTypes::ShapeType& pointshape,
299 const DataTypes::ValueType& value,
300 int dataOffset=0);
301
302
303 /**
304 \brief
305 Copy a double value to the data point dataPointNo of sample sampleNo in this object.
306
307 Description:
308 Copy a double value to the data point dataPointNo of sample sampleNo in this object.
309
310 \param sampleNo Input - sample number
311 \param dataPointNo Input - data point of the sample
312 \param value Input - new values for the data point
313 */
314 ESCRIPT_DLL_API
315 virtual void
316 copyToDataPoint(const int sampleNo, const int dataPointNo, const double value);
317
318 /**
319 \brief
320 Copy the array 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 \param axis_offset
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 \param axis_offset
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 \param axis0
393 \param axis1
394 */
395 ESCRIPT_DLL_API
396 virtual void
397 swapaxes(DataAbstract* ev, int axis0, int axis1);
398 /**
399 \brief
400 solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
401
402 \param ev - Output - eigenvalues in increasing order at each data point
403
404 */
405 ESCRIPT_DLL_API
406 virtual void
407 eigenvalues(DataAbstract* ev);
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 virtual
474 bool
475 actsExpanded() const {return false;}
476
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