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