escript/src/DataExpanded.h

// $Id$
/* 
 ************************************************************
 *          Copyright 2006 by ACcESS MNRF                   *
 *                                                          *
 *              http://www.access.edu.au                    *
 *       Primary Business: Queensland, Australia            *
 *  Licensed under the Open Software License version 3.0    *
 *     http://www.opensource.org/licenses/osl-3.0.php       *
 *                                                          *
 ************************************************************
*/

#if !defined escript_DataExpanded_20040323_H
#define escript_DataExpanded_20040323_H
#include "system_dep.h"

#include "DataAbstract.h"
#include "DataBlocks2D.h"
#include "DataArrayView.h"

#include <boost/python/numeric.hpp>

namespace escript {

//
// Forward declarations of other Data types.
class DataConstant;
class DataTagged;

/**
   \brief
   Give a short description of what DataExpanded does.

   Description:
   Give a detailed description of DataExpanded.

   Template Parameters:
   For templates describe any conditions that the parameters used in the
   template must satisfy.
*/

class DataExpanded : public DataAbstract {

 public:

  /**
     \brief
     Constructor for DataExpanded.

     Description:
     Constructor for DataExpanded.

     The given single data value is copied to all the data points in 
     this data object, where the number of data points is defined by
     the given function space.

     \param value - Input - A single data value.
     \param what - Input - A description of what this data represents.
  */
  ESCRIPT_DLL_API
  DataExpanded(const boost::python::numeric::array& value,
               const FunctionSpace& what);

  /**
     \brief
     Alternative constructor for DataExpanded.

     Description:
     Alternative Constructor for DataExpanded.

     The given single data value is copied to all the data points in 
     this data object, where the number of data points is defined by
     the given function space.

     \param value - Input - A single data value.
     \param what - Input - A description of what this data represents.
  */
  ESCRIPT_DLL_API
  DataExpanded(const DataArrayView& value,
               const FunctionSpace& what);

  /**
     \brief
     Alternative constructor for DataExpanded that copies a slice from
     another DataExpanded.

     \param other - Input - DataExpanded object to slice from.
     \param region - Input - region to copy.
  */
  ESCRIPT_DLL_API
  DataExpanded(const DataExpanded& other,
               const DataArrayView::RegionType& region);

  /**
     \brief
     Alternative constructor for DataExpanded objects.

     Description:
     Alternative Constructor for DataExpanded objects.
     \param what - Input - A description of what this data object represents.
     \param shape - Input - the shape of each data-point.
     \param data - the array of data values for the data-points.
  */
  ESCRIPT_DLL_API
  DataExpanded(const FunctionSpace& what,
               const DataArrayView::ShapeType &shape,
               const DataArrayView::ValueType &data);

  /**
     \brief
     Copy constructor for DataExpanded.
     Performs a deep copy from another DataExpanded.
  */
  ESCRIPT_DLL_API
  DataExpanded(const DataExpanded& other);

  /**
     \brief
     Copy constructor for DataExpanded.
     Construct a DataExpanded from a DataConstant.
  */
  ESCRIPT_DLL_API
  DataExpanded(const DataConstant& other);

  /**
     \brief
     Copy constructor for DataExpanded.
     Construct a DataExpanded from a DataTagged.
  */
  ESCRIPT_DLL_API
  DataExpanded(const DataTagged& other);

  /**
     \brief
     Default destructor for DataExpanded.
  */
  ESCRIPT_DLL_API
  virtual
  ~DataExpanded();

  /**
     \brief
     Return a textual representation of the data.
  */
  ESCRIPT_DLL_API
  virtual
  std::string
  toString() const;

  /**
     \brief
     Reshape the data point if the data point is currently rank 0.
     The original data point value is used for all values of the new
     data point.
  */
  ESCRIPT_DLL_API
  void
  reshapeDataPoint(const DataArrayView::ShapeType& shape);

  /**
     \brief
     Return the offset for the given given data point. This returns
     the offset in bytes for the given point into the container
     holding the point data.

     \param sampleNo - Input - sample number.
     \param dataPointNo - Input - data point number.
  */
  ESCRIPT_DLL_API
  virtual
  DataArrayView::ValueType::size_type
  getPointOffset(int sampleNo,
                 int dataPointNo) const;

  /**
     \brief
     Return a view into the data array for the data point specified.

     NOTE: Construction of the DataArrayView is a relatively expensive 
     operation.

     \param sampleNo - Input - sample number.
     \param dataPointNo - Input - data point number.
     \return DataArrayView for the data point.
  */
  ESCRIPT_DLL_API
  DataArrayView
  getDataPoint(int sampleNo,
               int dataPointNo);

  /**
     \brief
     Return the number of doubles stored for the Data.
  */
  ESCRIPT_DLL_API
  virtual
  ValueType::size_type
  getLength() const;

  /**
     \brief
     Factory method that returns a newly created DataExpanded.
     The caller is reponsible for managing the object created.

     \param region - Input - Region to copy.
  */
  ESCRIPT_DLL_API
  virtual
  DataAbstract*
  getSlice(const DataArrayView::RegionType& region) const;

  /**
     \brief
     Copy the specified region from the given value.

     \param value - Input - Data object to copy from.
     \param region - Input - Region to copy.
  */
  ESCRIPT_DLL_API
  virtual
  void
  setSlice(const DataAbstract* value,
           const DataArrayView::RegionType& region);

  /**
     \brief
     Assign the given value to all data-points associated with the given
     reference number.

     A reference number corresponds to a sample, and thus to all data-points
     in that sample.

     If the given reference number does not correspond to any sample in this
     Data object, an exception will be thrown.

     If the given value is a different shape to this Data object, an exception
     will be thrown.

     \param ref - Input - reference number which determines sample numebr to
                          assign given values to.
     \param value - Input - Value to assign to data-point associated with
                            the given reference number.
  */
  ESCRIPT_DLL_API
  virtual
  void
  setRefValue(int ref,
              const DataArray& value);

  /**
     \brief
     Return the value of the first data-point in the sample associated with
     the given reference number.

     A reference number corresponds to a sample, and thus to all data-points
     in that sample. If there is more than one data-point per sample number
     in this Data object, the value of the first data-point will be returned.

     If the given reference number does not correspond to any sample in this
     Data object, an exception will be thrown.

     If the given value is a different shape to this Data object, an exception
     will be thrown.

     \param ref - Input - reference number which determines sample number to
                          read from.
     \param value - Output - Object to receive data-points associated with
                            the given reference number.
  */
  ESCRIPT_DLL_API
  virtual
  void
  getRefValue(int ref,
              DataArray& value);

  /**
    \brief
    Archive the underlying data values to the file referenced
    by ofstream. A count of the number of values expected to be written
    is provided as a cross-check.

    The return value indicates success (0) or otherwise (1).
  */
  ESCRIPT_DLL_API
  int
  archiveData(std::ofstream& archiveFile,
              const DataArrayView::ValueType::size_type noValues) const;

  /**
    \brief
    Extract the number of values specified by noValues from the file
    referenced by ifstream to the underlying data structure.

    The return value indicates success (0) or otherwise (1).
  */
  ESCRIPT_DLL_API
  int
  extractData(std::ifstream& archiveFile,
              const DataArrayView::ValueType::size_type noValues);

  /**
     \brief
     Computes a symmetric matrix (A + AT) / 2

     \param ev - Output - symmetric matrix

  */
  ESCRIPT_DLL_API
  virtual void
  symmetric(DataAbstract* ev);

  /**
     \brief
     Computes a nonsymmetric matrix (A - AT) / 2

     \param ev - Output - nonsymmetric matrix

  */
  ESCRIPT_DLL_API
  virtual void
  nonsymmetric(DataAbstract* ev);

  /**
     \brief
     Computes the trace of a matrix

     \param ev - Output - trace of your matrix

  */
  ESCRIPT_DLL_API
  virtual void
  trace(DataAbstract* ev, int axis_offset);

  /**
     \brief
     Transpose each data point of this Data object around the given axis.

     \param ev - Output - transpose of your matrix

  */
  ESCRIPT_DLL_API
  virtual void
  transpose(DataAbstract* ev, int axis_offset);

  /**
     \brief
     swaps components axis_offset and axis_offset+1

     \param ev - Output - swapped components

  */
  ESCRIPT_DLL_API
  virtual void
  swap(DataAbstract* ev, int axis_offset);


  /**
     \brief
     solves the eigenvalue problem this*V=ev*V for the eigenvalues ev

     \param ev - Output - eigenvalues in increasing order at each data point

  */
  ESCRIPT_DLL_API
  virtual void
  eigenvalues(DataAbstract* ev);

  /**
     \brief
     solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V

     \param ev - Output - eigenvalues in increasing order at each data point
     \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
                         and the first nonzero component is positive.
     \param tol - Input - eigenvalue with relative distance tol are treated as equal.

  */

  ESCRIPT_DLL_API
  virtual void
  eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);


 protected:

 private:

  /**
     \brief
     Common initialisation called from constructors.

     Description:
     Common initialisation called from constructors.

     Resizes the underlying data array to provide sufficient storage for the
     given shape and number of data points, and creates the corresponding
     DataArrayView of this data.

     \param shape - Input - The shape of the point data.
     \param noSamples - Input - number of samples.
     \param noDataPointsPerSample - Input - number of data points per sample.
  */
  void
  initialise(const DataArrayView::ShapeType& shape,
             int noSamples,
             int noDataPointsPerSample);

  /**
     \brief
     Copy the given data point value to all data points in this object.

     Description:
     Copy the given data point to all data points in this object.

     \param value Input - A single data point value.
  */
  void
  copy(const DataArrayView& value);

  /**
     \brief
     Copy the given data point value given a numarray object to all data points in this object.

     Description:
     Copy the given data point value given a numarray object to all data points in this object.

     \param value Input - A single data point value.
  */
  void
  copy(const boost::python::numeric::array& value);

  /**
     \brief
     Copy the numarray object to the data points in this object.

     Description:
     Copy the numarray object to the data points in this object.

     \param value Input - new values for the data points
  */
  void
  copyAll(const boost::python::numeric::array& value);

  //
  // The main data storage array, a 2D array of data blocks.
  // noSamples * noDataPointsPerSample
  DataBlocks2D m_data;

};

} // end of namespace

#endif
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 thisV=evV 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 thisV=evV 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
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision