1 |
/* $Id$ */ |
2 |
|
3 |
/******************************************************* |
4 |
* |
5 |
* Copyright 2003-2007 by ACceSS MNRF |
6 |
* Copyright 2007 by University of Queensland |
7 |
* |
8 |
* http://esscc.uq.edu.au |
9 |
* Primary Business: Queensland, Australia |
10 |
* Licensed under the Open Software License version 3.0 |
11 |
* http://www.opensource.org/licenses/osl-3.0.php |
12 |
* |
13 |
*******************************************************/ |
14 |
|
15 |
#if !defined escript_DataAbstract_20040315_H |
16 |
#define escript_DataAbstract_20040315_H |
17 |
#include "system_dep.h" |
18 |
|
19 |
#include "DataArrayView.h" |
20 |
#include "FunctionSpace.h" |
21 |
|
22 |
#include <boost/scoped_ptr.hpp> |
23 |
#include <boost/python/numeric.hpp> |
24 |
|
25 |
#include <string> |
26 |
#include <fstream> |
27 |
|
28 |
namespace escript { |
29 |
|
30 |
/** |
31 |
\brief |
32 |
DataAbstract provides an abstract interface for the class of containers |
33 |
which hold ESyS data. |
34 |
|
35 |
Description: |
36 |
DataAbstract provides an abstract interface for the class of containers |
37 |
which hold ESyS data. The container may be thought of as a 2 dimensional |
38 |
array of data points where one dimension corresponds to the number of samples |
39 |
and the other to the number of data points per sample as defined by the function |
40 |
space associated with each Data object. The data points themselves are arrays of |
41 |
doubles of rank 0-4. |
42 |
*/ |
43 |
|
44 |
class DataAbstract { |
45 |
|
46 |
public: |
47 |
|
48 |
typedef DataArrayView::ValueType ValueType; |
49 |
typedef DataArrayView::ShapeType ShapeType; |
50 |
|
51 |
/** |
52 |
\brief |
53 |
Constructor for DataAbstract. |
54 |
|
55 |
Description: |
56 |
Constructor for DataAbstract. |
57 |
|
58 |
\param what - Input - A description of what this data represents. |
59 |
*/ |
60 |
ESCRIPT_DLL_API |
61 |
DataAbstract(const FunctionSpace& what); |
62 |
|
63 |
/** |
64 |
\brief |
65 |
Destructor for DataAbstract. |
66 |
*/ |
67 |
ESCRIPT_DLL_API |
68 |
virtual |
69 |
~DataAbstract(); |
70 |
|
71 |
/** |
72 |
\brief |
73 |
Write the data as a string. |
74 |
*/ |
75 |
ESCRIPT_DLL_API |
76 |
virtual |
77 |
std::string |
78 |
toString() const = 0; |
79 |
|
80 |
/** |
81 |
\brief |
82 |
dumps the object into a netCDF file |
83 |
*/ |
84 |
ESCRIPT_DLL_API |
85 |
virtual |
86 |
void |
87 |
dump(const std::string fileName) const; |
88 |
|
89 |
/** |
90 |
\brief |
91 |
Return the number of data points per sample. |
92 |
*/ |
93 |
ESCRIPT_DLL_API |
94 |
int |
95 |
getNumDPPSample() const; |
96 |
|
97 |
/** |
98 |
\brief |
99 |
Return the number of samples. |
100 |
*/ |
101 |
ESCRIPT_DLL_API |
102 |
int |
103 |
getNumSamples() const; |
104 |
|
105 |
/** |
106 |
\brief |
107 |
Return the DataArrayView of the point data. This essentially contains |
108 |
the shape information for each data point although it also may be used |
109 |
to manipulate the point data. |
110 |
*/ |
111 |
ESCRIPT_DLL_API |
112 |
DataArrayView& |
113 |
getPointDataView(); |
114 |
|
115 |
ESCRIPT_DLL_API |
116 |
const DataArrayView& |
117 |
getPointDataView() const; |
118 |
|
119 |
/** |
120 |
\brief |
121 |
Return the offset for the given sample. This returns the offset for the given |
122 |
point into the container holding the point data. Only really necessary to |
123 |
avoid creating many DataArrayView objects. |
124 |
|
125 |
\param sampleNo - Input - sample number. |
126 |
\param dataPointNo - Input - data point number. |
127 |
*/ |
128 |
ESCRIPT_DLL_API |
129 |
virtual |
130 |
ValueType::size_type |
131 |
getPointOffset(int sampleNo, |
132 |
int dataPointNo) const = 0; |
133 |
|
134 |
/** |
135 |
\brief |
136 |
Return the sample data for the given sample number. |
137 |
*/ |
138 |
ESCRIPT_DLL_API |
139 |
double* |
140 |
getSampleData(ValueType::size_type sampleNo); |
141 |
|
142 |
/** |
143 |
\brief |
144 |
Return the number of doubles stored for this Data object. |
145 |
*/ |
146 |
ESCRIPT_DLL_API |
147 |
virtual |
148 |
ValueType::size_type |
149 |
getLength() const = 0; |
150 |
|
151 |
/** |
152 |
\brief |
153 |
Return the sample data for the given tag key. |
154 |
NB: If the data isn't tagged an exception will be thrown. |
155 |
*/ |
156 |
ESCRIPT_DLL_API |
157 |
virtual |
158 |
double* |
159 |
getSampleDataByTag(int tag); |
160 |
|
161 |
|
162 |
/** |
163 |
\brief |
164 |
Check this and the given RHS operands are compatible. Throws |
165 |
an exception if they aren't. |
166 |
|
167 |
\param right - Input - The right hand side. |
168 |
*/ |
169 |
ESCRIPT_DLL_API |
170 |
void |
171 |
operandCheck(const DataAbstract& right) const; |
172 |
|
173 |
/** |
174 |
\brief |
175 |
Return true if a valid sample point number. |
176 |
*/ |
177 |
ESCRIPT_DLL_API |
178 |
bool |
179 |
validSamplePointNo(int samplePointNo) const; |
180 |
|
181 |
/** |
182 |
\brief |
183 |
Return true if a valid sample number. |
184 |
*/ |
185 |
ESCRIPT_DLL_API |
186 |
bool |
187 |
validSampleNo(int sampleNo) const; |
188 |
|
189 |
/** |
190 |
\brief |
191 |
Return a view into the data for the data point specified. |
192 |
NOTE: Construction of the DataArrayView is a relatively expensive |
193 |
operation. |
194 |
|
195 |
\param sampleNo - Input - the sample number. |
196 |
\param dataPointNo - Input - the data point number. |
197 |
*/ |
198 |
ESCRIPT_DLL_API |
199 |
virtual |
200 |
DataArrayView |
201 |
getDataPoint(int sampleNo, |
202 |
int dataPointNo) = 0; |
203 |
|
204 |
/** |
205 |
\brief |
206 |
Return the function space associated with this Data object. |
207 |
*/ |
208 |
ESCRIPT_DLL_API |
209 |
const |
210 |
FunctionSpace& |
211 |
getFunctionSpace() const; |
212 |
|
213 |
/** |
214 |
\brief |
215 |
Return the given slice from this object. |
216 |
|
217 |
NB: The caller is responsible for managing the object created. |
218 |
*/ |
219 |
ESCRIPT_DLL_API |
220 |
virtual |
221 |
DataAbstract* |
222 |
getSlice(const DataArrayView::RegionType& region) const = 0; |
223 |
|
224 |
/** |
225 |
\brief |
226 |
Copy the specified region from the given object. |
227 |
|
228 |
\param value - Input - Data to copy from |
229 |
\param region - Input - Region to copy. |
230 |
*/ |
231 |
ESCRIPT_DLL_API |
232 |
virtual |
233 |
void |
234 |
setSlice(const DataAbstract* value, |
235 |
const DataArrayView::RegionType& region) = 0; |
236 |
|
237 |
|
238 |
/** |
239 |
\brief |
240 |
setTaggedValue |
241 |
|
242 |
Description: |
243 |
Assign the given value to the given tag. |
244 |
|
245 |
NB: If the data isn't tagged an exception will be thrown. |
246 |
|
247 |
\param tagKey - Input - Integer key. |
248 |
\param value - Input - Single DataArrayView value to be assigned to the tag. |
249 |
*/ |
250 |
ESCRIPT_DLL_API |
251 |
virtual |
252 |
void |
253 |
setTaggedValue(int tagKey, |
254 |
const DataArrayView& value); |
255 |
|
256 |
/** |
257 |
\brief |
258 |
Archive the underlying data values to the file referenced |
259 |
by ofstream. A count of the number of values expected to be written |
260 |
is provided as a cross-check. |
261 |
|
262 |
The return value indicates success (0) or otherwise (1). |
263 |
*/ |
264 |
ESCRIPT_DLL_API |
265 |
virtual |
266 |
int |
267 |
archiveData(std::ofstream& archiveFile, |
268 |
const ValueType::size_type noValues) const; |
269 |
|
270 |
/** |
271 |
\brief |
272 |
Extract the number of values specified by noValues from the file |
273 |
referenced by ifstream to the underlying data structure. |
274 |
|
275 |
The return value indicates success (0) or otherwise (1). |
276 |
*/ |
277 |
ESCRIPT_DLL_API |
278 |
virtual |
279 |
int |
280 |
extractData(std::ifstream& archiveFile, |
281 |
const ValueType::size_type noValues); |
282 |
|
283 |
/** |
284 |
\brief |
285 |
Copy the numarray object to the data points in this object. |
286 |
|
287 |
Description: |
288 |
Copy the numarray object to the data points in this object. |
289 |
|
290 |
\param value Input - new values for the data points |
291 |
*/ |
292 |
ESCRIPT_DLL_API |
293 |
virtual void |
294 |
copyAll(const boost::python::numeric::array& value); |
295 |
|
296 |
/** |
297 |
\brief |
298 |
Copy a double value to the data point dataPointNo of sample sampleNo in this object. |
299 |
|
300 |
Description: |
301 |
Copy a double value to the data point dataPointNo of sample sampleNo in this object. |
302 |
|
303 |
\param sampleNo Input - sample number |
304 |
\param dataPointNo Input - data point of the sample |
305 |
\param value Input - new values for the data point |
306 |
*/ |
307 |
ESCRIPT_DLL_API |
308 |
virtual void |
309 |
copyToDataPoint(const int sampleNo, const int dataPointNo, const double value); |
310 |
|
311 |
/** |
312 |
\brief |
313 |
Copy the numarray object to the data point dataPointNo of sample sampleNo in this object. |
314 |
|
315 |
Description: |
316 |
Copy the numarray object to the data point dataPointNo of sample sampleNo in this object. |
317 |
|
318 |
\param sampleNo Input - sample number |
319 |
\param dataPointNo Input - data point of the sample |
320 |
\param value Input - new values for the data point |
321 |
*/ |
322 |
ESCRIPT_DLL_API |
323 |
virtual void |
324 |
copyToDataPoint(const int sampleNo, const int dataPointNo, const boost::python::numeric::array& value); |
325 |
|
326 |
|
327 |
/** |
328 |
\brief |
329 |
Return the tag number associated with the given data-point number. |
330 |
|
331 |
If the object cannot be referenced by tag numbers, an exception |
332 |
will be thrown. |
333 |
*/ |
334 |
ESCRIPT_DLL_API |
335 |
virtual |
336 |
int |
337 |
getTagNumber(int dpno); |
338 |
|
339 |
/** |
340 |
\brief |
341 |
Computes a symmetric matrix (A + AT) / 2 |
342 |
|
343 |
\param ev - Output - a symmetric matrix |
344 |
|
345 |
*/ |
346 |
ESCRIPT_DLL_API |
347 |
virtual void |
348 |
symmetric(DataAbstract* ev); |
349 |
|
350 |
/** |
351 |
\brief |
352 |
Computes a nonsymmetric matrix (A - AT) / 2 |
353 |
|
354 |
\param ev - Output - a nonsymmetric matrix |
355 |
|
356 |
*/ |
357 |
ESCRIPT_DLL_API |
358 |
virtual void |
359 |
nonsymmetric(DataAbstract* ev); |
360 |
|
361 |
/** |
362 |
\brief |
363 |
Computes the trace of a matrix |
364 |
|
365 |
\param ev - Output - the trace of a matrix |
366 |
|
367 |
*/ |
368 |
ESCRIPT_DLL_API |
369 |
virtual void |
370 |
trace(DataAbstract* ev, int axis_offset); |
371 |
|
372 |
/** |
373 |
\brief |
374 |
Transpose each data point of this Data object around the given axis. |
375 |
|
376 |
\param ev - Output - the transpose of a matrix |
377 |
|
378 |
*/ |
379 |
ESCRIPT_DLL_API |
380 |
virtual void |
381 |
transpose(DataAbstract* ev, int axis_offset); |
382 |
|
383 |
/** |
384 |
\brief |
385 |
swaps components axis0 and axis1 |
386 |
|
387 |
\param ev - Output - swapped components |
388 |
|
389 |
*/ |
390 |
ESCRIPT_DLL_API |
391 |
virtual void |
392 |
swapaxes(DataAbstract* ev, int axis0, int axis1); |
393 |
/** |
394 |
\brief |
395 |
solves the eigenvalue problem this*V=ev*V for the eigenvalues ev |
396 |
|
397 |
\param ev - Output - eigenvalues in increasing order at each data point |
398 |
|
399 |
*/ |
400 |
ESCRIPT_DLL_API |
401 |
virtual void |
402 |
eigenvalues(DataAbstract* ev); |
403 |
|
404 |
/** |
405 |
\brief |
406 |
sets values to zero |
407 |
|
408 |
*/ |
409 |
ESCRIPT_DLL_API |
410 |
virtual void |
411 |
setToZero(); |
412 |
|
413 |
/** |
414 |
\brief |
415 |
solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V |
416 |
|
417 |
\param ev - Output - eigenvalues in increasing order at each data point |
418 |
\param V - Output - corresponding eigenvectors. They are normalized such that their length is one |
419 |
and the first nonzero component is positive. |
420 |
\param tol - Input - eigenvalue with relative distance tol are treated as equal. |
421 |
|
422 |
*/ |
423 |
|
424 |
ESCRIPT_DLL_API |
425 |
virtual void |
426 |
eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13); |
427 |
|
428 |
/** |
429 |
\brief |
430 |
reorders data sample ordered by reference_ids to the ordering of the functions space |
431 |
|
432 |
\param reference_ids - Input - reference_ids used for current ordering |
433 |
*/ |
434 |
ESCRIPT_DLL_API |
435 |
virtual void |
436 |
reorderByReferenceIDs(int *reference_ids); |
437 |
|
438 |
protected: |
439 |
|
440 |
/** |
441 |
\brief |
442 |
Set the pointDataView DataArrayView associated with this object. |
443 |
|
444 |
\param input - Input - The point data view. DataAbstract takes ownership |
445 |
of the DataArrayView provided. It will delete it when it is destructed. |
446 |
*/ |
447 |
ESCRIPT_DLL_API |
448 |
void |
449 |
setPointDataView(const DataArrayView& input); |
450 |
|
451 |
ESCRIPT_DLL_API |
452 |
void |
453 |
resetPointDataView(); |
454 |
|
455 |
|
456 |
|
457 |
private: |
458 |
|
459 |
// |
460 |
// The number of samples in this Data object. |
461 |
// This is derived directly from the FunctionSpace. |
462 |
int m_noSamples; |
463 |
|
464 |
// |
465 |
// The number of data points per sample in this Data object. |
466 |
// This is derived directly from the FunctionSpace. |
467 |
int m_noDataPointsPerSample; |
468 |
|
469 |
// |
470 |
// The DataArrayView of the data array associated with this object. |
471 |
// The data array is defined only in child classes of this class, it |
472 |
// is not defined in this abstract parent class. |
473 |
boost::scoped_ptr<DataArrayView> m_pointDataView; |
474 |
|
475 |
// |
476 |
// A FunctionSpace which provides a description of the data associated |
477 |
// with this Data object. |
478 |
FunctionSpace m_functionSpace; |
479 |
|
480 |
}; |
481 |
|
482 |
inline |
483 |
bool |
484 |
DataAbstract::validSamplePointNo(int samplePointNo) const |
485 |
{ |
486 |
return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample)); |
487 |
} |
488 |
|
489 |
inline |
490 |
bool |
491 |
DataAbstract::validSampleNo(int sampleNo) const |
492 |
{ |
493 |
return ((0 <= sampleNo) && (sampleNo < m_noSamples)); |
494 |
} |
495 |
|
496 |
inline |
497 |
DataAbstract::ValueType::value_type* |
498 |
DataAbstract::getSampleData(ValueType::size_type sampleNo) |
499 |
{ |
500 |
return &(m_pointDataView->getData(getPointOffset(sampleNo,0))); |
501 |
} |
502 |
|
503 |
inline |
504 |
int |
505 |
DataAbstract::getNumDPPSample() const |
506 |
{ |
507 |
return m_noDataPointsPerSample; |
508 |
} |
509 |
|
510 |
inline |
511 |
int |
512 |
DataAbstract::getNumSamples() const |
513 |
{ |
514 |
return m_noSamples; |
515 |
} |
516 |
|
517 |
inline |
518 |
const |
519 |
FunctionSpace& |
520 |
DataAbstract::getFunctionSpace() const |
521 |
{ |
522 |
return m_functionSpace; |
523 |
} |
524 |
|
525 |
inline |
526 |
const |
527 |
DataArrayView& |
528 |
DataAbstract::getPointDataView() const |
529 |
{ |
530 |
return *(m_pointDataView.get()); |
531 |
} |
532 |
|
533 |
inline |
534 |
DataArrayView& |
535 |
DataAbstract::getPointDataView() |
536 |
{ |
537 |
return *(m_pointDataView.get()); |
538 |
} |
539 |
} // end of namespace |
540 |
|
541 |
#endif |