1 |
// $Id$ |
2 |
/* |
3 |
************************************************************ |
4 |
* Copyright 2006 by ACcESS MNRF * |
5 |
* * |
6 |
* http://www.access.edu.au * |
7 |
* Primary Business: Queensland, Australia * |
8 |
* Licensed under the Open Software License version 3.0 * |
9 |
* http://www.opensource.org/licenses/osl-3.0.php * |
10 |
* * |
11 |
************************************************************ |
12 |
*/ |
13 |
|
14 |
#if !defined escript_DataExpanded_20040323_H |
15 |
#define escript_DataExpanded_20040323_H |
16 |
#include "system_dep.h" |
17 |
|
18 |
#include "DataAbstract.h" |
19 |
#include "DataBlocks2D.h" |
20 |
#include "DataArrayView.h" |
21 |
|
22 |
#include <boost/python/numeric.hpp> |
23 |
|
24 |
namespace escript { |
25 |
|
26 |
// |
27 |
// Forward declarations of other Data types. |
28 |
class DataConstant; |
29 |
class DataTagged; |
30 |
|
31 |
/** |
32 |
\brief |
33 |
Give a short description of what DataExpanded does. |
34 |
|
35 |
Description: |
36 |
Give a detailed description of DataExpanded. |
37 |
|
38 |
Template Parameters: |
39 |
For templates describe any conditions that the parameters used in the |
40 |
template must satisfy. |
41 |
*/ |
42 |
|
43 |
class DataExpanded : public DataAbstract { |
44 |
|
45 |
public: |
46 |
|
47 |
/** |
48 |
\brief |
49 |
Constructor for DataExpanded. |
50 |
|
51 |
Description: |
52 |
Constructor for DataExpanded. |
53 |
|
54 |
The given single data value is copied to all the data points in |
55 |
this data object, where the number of data points is defined by |
56 |
the given function space. |
57 |
|
58 |
\param value - Input - A single data value. |
59 |
\param what - Input - A description of what this data represents. |
60 |
*/ |
61 |
ESCRIPT_DLL_API |
62 |
DataExpanded(const boost::python::numeric::array& value, |
63 |
const FunctionSpace& what); |
64 |
|
65 |
/** |
66 |
\brief |
67 |
Alternative constructor for DataExpanded. |
68 |
|
69 |
Description: |
70 |
Alternative Constructor for DataExpanded. |
71 |
|
72 |
The given single data value is copied to all the data points in |
73 |
this data object, where the number of data points is defined by |
74 |
the given function space. |
75 |
|
76 |
\param value - Input - A single data value. |
77 |
\param what - Input - A description of what this data represents. |
78 |
*/ |
79 |
ESCRIPT_DLL_API |
80 |
DataExpanded(const DataArrayView& value, |
81 |
const FunctionSpace& what); |
82 |
|
83 |
/** |
84 |
\brief |
85 |
Alternative constructor for DataExpanded that copies a slice from |
86 |
another DataExpanded. |
87 |
|
88 |
\param other - Input - DataExpanded object to slice from. |
89 |
\param region - Input - region to copy. |
90 |
*/ |
91 |
ESCRIPT_DLL_API |
92 |
DataExpanded(const DataExpanded& other, |
93 |
const DataArrayView::RegionType& region); |
94 |
|
95 |
/** |
96 |
\brief |
97 |
Alternative constructor for DataExpanded objects. |
98 |
|
99 |
Description: |
100 |
Alternative Constructor for DataExpanded objects. |
101 |
\param what - Input - A description of what this data object represents. |
102 |
\param shape - Input - the shape of each data-point. |
103 |
\param data - the array of data values for the data-points. |
104 |
*/ |
105 |
ESCRIPT_DLL_API |
106 |
DataExpanded(const FunctionSpace& what, |
107 |
const DataArrayView::ShapeType &shape, |
108 |
const DataArrayView::ValueType &data); |
109 |
|
110 |
/** |
111 |
\brief |
112 |
Copy constructor for DataExpanded. |
113 |
Performs a deep copy from another DataExpanded. |
114 |
*/ |
115 |
ESCRIPT_DLL_API |
116 |
DataExpanded(const DataExpanded& other); |
117 |
|
118 |
/** |
119 |
\brief |
120 |
Copy constructor for DataExpanded. |
121 |
Construct a DataExpanded from a DataConstant. |
122 |
*/ |
123 |
ESCRIPT_DLL_API |
124 |
DataExpanded(const DataConstant& other); |
125 |
|
126 |
/** |
127 |
\brief |
128 |
Copy constructor for DataExpanded. |
129 |
Construct a DataExpanded from a DataTagged. |
130 |
*/ |
131 |
ESCRIPT_DLL_API |
132 |
DataExpanded(const DataTagged& other); |
133 |
|
134 |
/** |
135 |
\brief |
136 |
Default destructor for DataExpanded. |
137 |
*/ |
138 |
ESCRIPT_DLL_API |
139 |
virtual |
140 |
~DataExpanded(); |
141 |
|
142 |
/** |
143 |
\brief |
144 |
Return a textual representation of the data. |
145 |
*/ |
146 |
ESCRIPT_DLL_API |
147 |
virtual |
148 |
std::string |
149 |
toString() const; |
150 |
|
151 |
/** |
152 |
\brief |
153 |
Reshape the data point if the data point is currently rank 0. |
154 |
The original data point value is used for all values of the new |
155 |
data point. |
156 |
*/ |
157 |
ESCRIPT_DLL_API |
158 |
void |
159 |
reshapeDataPoint(const DataArrayView::ShapeType& shape); |
160 |
|
161 |
/** |
162 |
\brief |
163 |
Return the offset for the given given data point. This returns |
164 |
the offset in bytes for the given point into the container |
165 |
holding the point data. |
166 |
|
167 |
\param sampleNo - Input - sample number. |
168 |
\param dataPointNo - Input - data point number. |
169 |
*/ |
170 |
ESCRIPT_DLL_API |
171 |
virtual |
172 |
DataArrayView::ValueType::size_type |
173 |
getPointOffset(int sampleNo, |
174 |
int dataPointNo) const; |
175 |
|
176 |
/** |
177 |
\brief |
178 |
Return a view into the data array for the data point specified. |
179 |
|
180 |
NOTE: Construction of the DataArrayView is a relatively expensive |
181 |
operation. |
182 |
|
183 |
\param sampleNo - Input - sample number. |
184 |
\param dataPointNo - Input - data point number. |
185 |
\return DataArrayView for the data point. |
186 |
*/ |
187 |
ESCRIPT_DLL_API |
188 |
DataArrayView |
189 |
getDataPoint(int sampleNo, |
190 |
int dataPointNo); |
191 |
|
192 |
/** |
193 |
\brief |
194 |
Return the number of doubles stored for the Data. |
195 |
*/ |
196 |
ESCRIPT_DLL_API |
197 |
virtual |
198 |
ValueType::size_type |
199 |
getLength() const; |
200 |
|
201 |
/** |
202 |
\brief |
203 |
Factory method that returns a newly created DataExpanded. |
204 |
The caller is reponsible for managing the object created. |
205 |
|
206 |
\param region - Input - Region to copy. |
207 |
*/ |
208 |
ESCRIPT_DLL_API |
209 |
virtual |
210 |
DataAbstract* |
211 |
getSlice(const DataArrayView::RegionType& region) const; |
212 |
|
213 |
/** |
214 |
\brief |
215 |
Copy the specified region from the given value. |
216 |
|
217 |
\param value - Input - Data object to copy from. |
218 |
\param region - Input - Region to copy. |
219 |
*/ |
220 |
ESCRIPT_DLL_API |
221 |
virtual |
222 |
void |
223 |
setSlice(const DataAbstract* value, |
224 |
const DataArrayView::RegionType& region); |
225 |
|
226 |
/** |
227 |
\brief |
228 |
Assign the given value to all data-points associated with the given |
229 |
reference number. |
230 |
|
231 |
A reference number corresponds to a sample, and thus to all data-points |
232 |
in that sample. |
233 |
|
234 |
If the given reference number does not correspond to any sample in this |
235 |
Data object, an exception will be thrown. |
236 |
|
237 |
If the given value is a different shape to this Data object, an exception |
238 |
will be thrown. |
239 |
|
240 |
\param ref - Input - reference number which determines sample numebr to |
241 |
assign given values to. |
242 |
\param value - Input - Value to assign to data-point associated with |
243 |
the given reference number. |
244 |
*/ |
245 |
ESCRIPT_DLL_API |
246 |
virtual |
247 |
void |
248 |
setRefValue(int ref, |
249 |
const DataArray& value); |
250 |
|
251 |
/** |
252 |
\brief |
253 |
Return the value of the first data-point in the sample associated with |
254 |
the given reference number. |
255 |
|
256 |
A reference number corresponds to a sample, and thus to all data-points |
257 |
in that sample. If there is more than one data-point per sample number |
258 |
in this Data object, the value of the first data-point will be returned. |
259 |
|
260 |
If the given reference number does not correspond to any sample in this |
261 |
Data object, an exception will be thrown. |
262 |
|
263 |
If the given value is a different shape to this Data object, an exception |
264 |
will be thrown. |
265 |
|
266 |
\param ref - Input - reference number which determines sample number to |
267 |
read from. |
268 |
\param value - Output - Object to receive data-points associated with |
269 |
the given reference number. |
270 |
*/ |
271 |
ESCRIPT_DLL_API |
272 |
virtual |
273 |
void |
274 |
getRefValue(int ref, |
275 |
DataArray& value); |
276 |
|
277 |
/** |
278 |
\brief |
279 |
Archive the underlying data values to the file referenced |
280 |
by ofstream. A count of the number of values expected to be written |
281 |
is provided as a cross-check. |
282 |
|
283 |
The return value indicates success (0) or otherwise (1). |
284 |
*/ |
285 |
ESCRIPT_DLL_API |
286 |
int |
287 |
archiveData(std::ofstream& archiveFile, |
288 |
const DataArrayView::ValueType::size_type noValues) const; |
289 |
|
290 |
/** |
291 |
\brief |
292 |
Extract the number of values specified by noValues from the file |
293 |
referenced by ifstream to the underlying data structure. |
294 |
|
295 |
The return value indicates success (0) or otherwise (1). |
296 |
*/ |
297 |
ESCRIPT_DLL_API |
298 |
int |
299 |
extractData(std::ifstream& archiveFile, |
300 |
const DataArrayView::ValueType::size_type noValues); |
301 |
|
302 |
/** |
303 |
\brief |
304 |
Computes a symmetric matrix (A + AT) / 2 |
305 |
|
306 |
\param ev - Output - symmetric matrix |
307 |
|
308 |
*/ |
309 |
ESCRIPT_DLL_API |
310 |
virtual void |
311 |
symmetric(DataAbstract* ev); |
312 |
|
313 |
/** |
314 |
\brief |
315 |
Computes a nonsymmetric matrix (A - AT) / 2 |
316 |
|
317 |
\param ev - Output - nonsymmetric matrix |
318 |
|
319 |
*/ |
320 |
ESCRIPT_DLL_API |
321 |
virtual void |
322 |
nonsymmetric(DataAbstract* ev); |
323 |
|
324 |
/** |
325 |
\brief |
326 |
Computes the trace of a matrix |
327 |
|
328 |
\param ev - Output - trace of your matrix |
329 |
|
330 |
*/ |
331 |
ESCRIPT_DLL_API |
332 |
virtual void |
333 |
trace(DataAbstract* ev, int axis_offset); |
334 |
|
335 |
/** |
336 |
\brief |
337 |
Transpose each data point of this Data object around the given axis. |
338 |
|
339 |
\param ev - Output - transpose of your matrix |
340 |
|
341 |
*/ |
342 |
ESCRIPT_DLL_API |
343 |
virtual void |
344 |
transpose(DataAbstract* ev, int axis_offset); |
345 |
|
346 |
/** |
347 |
\brief |
348 |
swaps components axis_offset and axis_offset+1 |
349 |
|
350 |
\param ev - Output - swapped components |
351 |
|
352 |
*/ |
353 |
ESCRIPT_DLL_API |
354 |
virtual void |
355 |
swap(DataAbstract* ev, int axis_offset); |
356 |
|
357 |
|
358 |
/** |
359 |
\brief |
360 |
solves the eigenvalue problem this*V=ev*V for the eigenvalues ev |
361 |
|
362 |
\param ev - Output - eigenvalues in increasing order at each data point |
363 |
|
364 |
*/ |
365 |
ESCRIPT_DLL_API |
366 |
virtual void |
367 |
eigenvalues(DataAbstract* ev); |
368 |
|
369 |
/** |
370 |
\brief |
371 |
solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V |
372 |
|
373 |
\param ev - Output - eigenvalues in increasing order at each data point |
374 |
\param V - Output - corresponding eigenvectors. They are normalized such that their length is one |
375 |
and the first nonzero component is positive. |
376 |
\param tol - Input - eigenvalue with relative distance tol are treated as equal. |
377 |
|
378 |
*/ |
379 |
|
380 |
ESCRIPT_DLL_API |
381 |
virtual void |
382 |
eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13); |
383 |
|
384 |
|
385 |
protected: |
386 |
|
387 |
private: |
388 |
|
389 |
/** |
390 |
\brief |
391 |
Common initialisation called from constructors. |
392 |
|
393 |
Description: |
394 |
Common initialisation called from constructors. |
395 |
|
396 |
Resizes the underlying data array to provide sufficient storage for the |
397 |
given shape and number of data points, and creates the corresponding |
398 |
DataArrayView of this data. |
399 |
|
400 |
\param shape - Input - The shape of the point data. |
401 |
\param noSamples - Input - number of samples. |
402 |
\param noDataPointsPerSample - Input - number of data points per sample. |
403 |
*/ |
404 |
void |
405 |
initialise(const DataArrayView::ShapeType& shape, |
406 |
int noSamples, |
407 |
int noDataPointsPerSample); |
408 |
|
409 |
/** |
410 |
\brief |
411 |
Copy the given data point value to all data points in this object. |
412 |
|
413 |
Description: |
414 |
Copy the given data point to all data points in this object. |
415 |
|
416 |
\param value Input - A single data point value. |
417 |
*/ |
418 |
void |
419 |
copy(const DataArrayView& value); |
420 |
|
421 |
/** |
422 |
\brief |
423 |
Copy the given data point value given a numarray object to all data points in this object. |
424 |
|
425 |
Description: |
426 |
Copy the given data point value given a numarray object to all data points in this object. |
427 |
|
428 |
\param value Input - A single data point value. |
429 |
*/ |
430 |
void |
431 |
copy(const boost::python::numeric::array& value); |
432 |
|
433 |
/** |
434 |
\brief |
435 |
Copy the numarray object to the data points in this object. |
436 |
|
437 |
Description: |
438 |
Copy the numarray object to the data points in this object. |
439 |
|
440 |
\param value Input - new values for the data points |
441 |
*/ |
442 |
void |
443 |
copyAll(const boost::python::numeric::array& value); |
444 |
|
445 |
// |
446 |
// The main data storage array, a 2D array of data blocks. |
447 |
// noSamples * noDataPointsPerSample |
448 |
DataBlocks2D m_data; |
449 |
|
450 |
}; |
451 |
|
452 |
} // end of namespace |
453 |
|
454 |
#endif |