escript/src/DataExpanded.h


/*******************************************************
*
* Copyright (c) 2003-2008 by University of Queensland
* Earth Systems Science Computational Center (ESSCC)
* http://www.uq.edu.au/esscc
*
* 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 "DataReady.h"
#include "DataBlocks2D.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 DataReady {

typedef DataReady parent;

 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 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 DataTypes::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.

TODO Note that this constructor will also copy data to all points if it only contains enough elements to hold a single point.  ie this is the merge of two separate constructors.
  */
  ESCRIPT_DLL_API
  DataExpanded(const FunctionSpace& what,
               const DataTypes::ShapeType &shape,
               const DataTypes::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();

  ESCRIPT_DLL_API
  bool
  isExpanded() const 
  {
    return true;
  };

  ESCRIPT_DLL_API
  bool
  actsExpanded() const
  {
    return true;
  }

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

  /**
     \brief Return a deep copy of the current object.
  */
  ESCRIPT_DLL_API
  virtual
  DataAbstract*
  deepCopy();


 /**
     \brief
     dumps the object into a netCDF file
  */
  ESCRIPT_DLL_API
  virtual
  void
  dump(const std::string fileName) const;

 /**
     \brief
    sets all values to zero
  */
  ESCRIPT_DLL_API
  virtual
  void
  setToZero();

  /**
     \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
  DataTypes::ValueType::size_type
  getPointOffset(int sampleNo,
                 int dataPointNo) const;

  ESCRIPT_DLL_API
  virtual
  DataTypes::ValueType::size_type
  getPointOffset(int sampleNo,
                 int dataPointNo);

  /**
     \brief
     Return a a reference to the underlying DataVector.
  */

  ESCRIPT_DLL_API
  DataTypes::ValueType&
  getVector();

  ESCRIPT_DLL_API
  const DataTypes::ValueType&
  getVector() const;


  /**
     \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 DataTypes::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 DataTypes::RegionType& region);

  /**
     \brief
     setTaggedValue

     Description:
     uses tag to set a new value

     \param tagKey - Input - Integer key.
     \param pointshape - Input - The shape of the value parameter
     \param value - Input - .
  */
  void  
  setTaggedValue(int tagKey,
             const DataTypes::ShapeType& pointshape,
                 const DataTypes::ValueType& value,
         int dataOffset=0);


  /**
     \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 axis0 and axis1

     \param ev - Output - swapped components

  */
  ESCRIPT_DLL_API
  virtual void
  swapaxes(DataAbstract* ev, int axis0, int axis1);


  /**
     \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);

/**
 *      \brief
 *           reorders data sample ordered by reference_ids to the ordering of the functions space
 *
 *                \param reference_ids - Input - reference_ids used for current ordering
 *                  */
  ESCRIPT_DLL_API
  virtual void
  reorderByReferenceIDs(int *reference_ids);


 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 noSamples - Input - number of samples.
     \param noDataPointsPerSample - Input - number of data points per sample.
  */
  void
  initialise(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 DataConstant& 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);

  /**
     \brief
     Copy a double value to the data point dataPointNo of sample sampleNo in this object.

     Description:
     Copy a double value to the data point dataPointNo of sample sampleNo in this object.

     \param sampleNo Input - sample number
     \param dataPointNo Input - data point of the sample
     \param value Input - new values for the data point
  */
  ESCRIPT_DLL_API
  virtual void
  copyToDataPoint(const int sampleNo, const int dataPointNo, const double value);


  /**
     \brief
     Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.

     Description:
     Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.

     \param sampleNo Input - sample number
     \param dataPointNo Input - data point of the sample
     \param value Input - new values for the data point
  */
  void
  copyToDataPoint(const int sampleNo, const int dataPointNo, 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
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_DataExpanded_20040323_H
16	#define escript_DataExpanded_20040323_H
17	#include "system_dep.h"
18
19	#include "DataReady.h"
20	#include "DataBlocks2D.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 DataReady {
44
45	typedef DataReady parent;
46
47	public:
48
49	/**
50	\brief
51	Constructor for DataExpanded.
52
53	Description:
54	Constructor for DataExpanded.
55
56	The given single data value is copied to all the data points in
57	this data object, where the number of data points is defined by
58	the given function space.
59
60	\param value - Input - A single data value.
61	\param what - Input - A description of what this data represents.
62	*/
63	ESCRIPT_DLL_API
64	DataExpanded(const boost::python::numeric::array& value,
65	const FunctionSpace& what);
66
67	/**
68	\brief
69	Alternative constructor for DataExpanded that copies a slice from
70	another DataExpanded.
71
72	\param other - Input - DataExpanded object to slice from.
73	\param region - Input - region to copy.
74	*/
75	ESCRIPT_DLL_API
76	DataExpanded(const DataExpanded& other,
77	const DataTypes::RegionType& region);
78
79	/**
80	\brief
81	Alternative constructor for DataExpanded objects.
82
83	Description:
84	Alternative Constructor for DataExpanded objects.
85	\param what - Input - A description of what this data object represents.
86	\param shape - Input - the shape of each data-point.
87	\param data - the array of data values for the data-points.
88
89	TODO Note that this constructor will also copy data to all points if it only contains enough elements to hold a single point. ie this is the merge of two separate constructors.
90	*/
91	ESCRIPT_DLL_API
92	DataExpanded(const FunctionSpace& what,
93	const DataTypes::ShapeType &shape,
94	const DataTypes::ValueType &data);
95
96	/**
97	\brief
98	Copy constructor for DataExpanded.
99	Performs a deep copy from another DataExpanded.
100	*/
101	ESCRIPT_DLL_API
102	DataExpanded(const DataExpanded& other);
103
104	/**
105	\brief
106	Copy constructor for DataExpanded.
107	Construct a DataExpanded from a DataConstant.
108	*/
109	ESCRIPT_DLL_API
110	DataExpanded(const DataConstant& other);
111
112	/**
113	\brief
114	Copy constructor for DataExpanded.
115	Construct a DataExpanded from a DataTagged.
116	*/
117	ESCRIPT_DLL_API
118	DataExpanded(const DataTagged& other);
119
120	/**
121	\brief
122	Default destructor for DataExpanded.
123	*/
124	ESCRIPT_DLL_API
125	virtual
126	~DataExpanded();
127
128	ESCRIPT_DLL_API
129	bool
130	isExpanded() const
131	{
132	return true;
133	};
134
135	ESCRIPT_DLL_API
136	bool
137	actsExpanded() const
138	{
139	return true;
140	}
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 Return a deep copy of the current object.
153	*/
154	ESCRIPT_DLL_API
155	virtual
156	DataAbstract*
157	deepCopy();
158
159
160	/**
161	\brief
162	dumps the object into a netCDF file
163	*/
164	ESCRIPT_DLL_API
165	virtual
166	void
167	dump(const std::string fileName) const;
168
169	/**
170	\brief
171	sets all values to zero
172	*/
173	ESCRIPT_DLL_API
174	virtual
175	void
176	setToZero();
177
178	/**
179	\brief
180	Return the offset for the given given data point. This returns
181	the offset in bytes for the given point into the container
182	holding the point data.
183
184	\param sampleNo - Input - sample number.
185	\param dataPointNo - Input - data point number.
186	*/
187	ESCRIPT_DLL_API
188	virtual
189	DataTypes::ValueType::size_type
190	getPointOffset(int sampleNo,
191	int dataPointNo) const;
192
193	ESCRIPT_DLL_API
194	virtual
195	DataTypes::ValueType::size_type
196	getPointOffset(int sampleNo,
197	int dataPointNo);
198
199	/**
200	\brief
201	Return a a reference to the underlying DataVector.
202	*/
203
204	ESCRIPT_DLL_API
205	DataTypes::ValueType&
206	getVector();
207
208	ESCRIPT_DLL_API
209	const DataTypes::ValueType&
210	getVector() const;
211
212
213	/**
214	\brief
215	Return the number of doubles stored for the Data.
216	*/
217	ESCRIPT_DLL_API
218	virtual
219	ValueType::size_type
220	getLength() const;
221
222	/**
223	\brief
224	Factory method that returns a newly created DataExpanded.
225	The caller is reponsible for managing the object created.
226
227	\param region - Input - Region to copy.
228	*/
229	ESCRIPT_DLL_API
230	virtual
231	DataAbstract*
232	getSlice(const DataTypes::RegionType& region) const;
233
234	/**
235	\brief
236	Copy the specified region from the given value.
237
238	\param value - Input - Data object to copy from.
239	\param region - Input - Region to copy.
240	*/
241	ESCRIPT_DLL_API
242	virtual
243	void
244	setSlice(const DataAbstract* value,
245	const DataTypes::RegionType& region);
246
247	/**
248	\brief
249	setTaggedValue
250
251	Description:
252	uses tag to set a new value
253
254	\param tagKey - Input - Integer key.
255	\param pointshape - Input - The shape of the value parameter
256	\param value - Input - .
257	*/
258	void
259	setTaggedValue(int tagKey,
260	const DataTypes::ShapeType& pointshape,
261	const DataTypes::ValueType& value,
262	int dataOffset=0);
263
264
265
266	/**
267	\brief
268	Computes a symmetric matrix (A + AT) / 2
269
270	\param ev - Output - symmetric matrix
271
272	*/
273	ESCRIPT_DLL_API
274	virtual void
275	symmetric(DataAbstract* ev);
276
277	/**
278	\brief
279	Computes a nonsymmetric matrix (A - AT) / 2
280
281	\param ev - Output - nonsymmetric matrix
282
283	*/
284	ESCRIPT_DLL_API
285	virtual void
286	nonsymmetric(DataAbstract* ev);
287
288	/**
289	\brief
290	Computes the trace of a matrix
291
292	\param ev - Output - trace of your matrix
293
294	*/
295	ESCRIPT_DLL_API
296	virtual void
297	trace(DataAbstract* ev, int axis_offset);
298
299	/**
300	\brief
301	Transpose each data point of this Data object around the given axis.
302
303	\param ev - Output - transpose of your matrix
304
305	*/
306	ESCRIPT_DLL_API
307	virtual void
308	transpose(DataAbstract* ev, int axis_offset);
309
310	/**
311	\brief
312	swaps components axis0 and axis1
313
314	\param ev - Output - swapped components
315
316	*/
317	ESCRIPT_DLL_API
318	virtual void
319	swapaxes(DataAbstract* ev, int axis0, int axis1);
320
321
322	/**
323	\brief
324	solves the eigenvalue problem thisV=evV for the eigenvalues ev
325
326	\param ev - Output - eigenvalues in increasing order at each data point
327
328	*/
329	ESCRIPT_DLL_API
330	virtual void
331	eigenvalues(DataAbstract* ev);
332
333	/**
334	\brief
335	solves the eigenvalue problem thisV=evV for the eigenvalues ev and eigenvectors V
336
337	\param ev - Output - eigenvalues in increasing order at each data point
338	\param V - Output - corresponding eigenvectors. They are normalized such that their length is one
339	and the first nonzero component is positive.
340	\param tol - Input - eigenvalue with relative distance tol are treated as equal.
341
342	*/
343
344	ESCRIPT_DLL_API
345	virtual void
346	eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
347
348	/**
349	* \brief
350	* reorders data sample ordered by reference_ids to the ordering of the functions space
351	*
352	* \param reference_ids - Input - reference_ids used for current ordering
353	* */
354	ESCRIPT_DLL_API
355	virtual void
356	reorderByReferenceIDs(int *reference_ids);
357
358
359
360	protected:
361
362	private:
363
364	/**
365	\brief
366	Common initialisation called from constructors.
367
368	Description:
369	Common initialisation called from constructors.
370
371	Resizes the underlying data array to provide sufficient storage for the
372	given shape and number of data points, and creates the corresponding
373	DataArrayView of this data.
374
375	\param noSamples - Input - number of samples.
376	\param noDataPointsPerSample - Input - number of data points per sample.
377	*/
378	void
379	initialise(int noSamples,
380	int noDataPointsPerSample);
381
382	/**
383	\brief
384	Copy the given data point value to all data points in this object.
385
386	Description:
387	Copy the given data point to all data points in this object.
388
389	\param value Input - A single data point value.
390	*/
391	void
392	copy(const DataConstant& value);
393
394
395
396	/**
397	\brief
398	Copy the given data point value given a numarray object to all data points in this object.
399
400	Description:
401	Copy the given data point value given a numarray object to all data points in this object.
402
403	\param value Input - A single data point value.
404	*/
405	void
406	copy(const boost::python::numeric::array& value);
407
408	/**
409	\brief
410	Copy the numarray object to the data points in this object.
411
412	Description:
413	Copy the numarray object to the data points in this object.
414
415	\param value Input - new values for the data points
416	*/
417	void
418	copyAll(const boost::python::numeric::array& value);
419
420	/**
421	\brief
422	Copy a double value to the data point dataPointNo of sample sampleNo in this object.
423
424	Description:
425	Copy a double value to the data point dataPointNo of sample sampleNo in this object.
426
427	\param sampleNo Input - sample number
428	\param dataPointNo Input - data point of the sample
429	\param value Input - new values for the data point
430	*/
431	ESCRIPT_DLL_API
432	virtual void
433	copyToDataPoint(const int sampleNo, const int dataPointNo, const double value);
434
435
436	/**
437	\brief
438	Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
439
440	Description:
441	Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
442
443	\param sampleNo Input - sample number
444	\param dataPointNo Input - data point of the sample
445	\param value Input - new values for the data point
446	*/
447	void
448	copyToDataPoint(const int sampleNo, const int dataPointNo, const boost::python::numeric::array& value);
449
450	//
451	// The main data storage array, a 2D array of data blocks.
452	// noSamples * noDataPointsPerSample
453	DataBlocks2D m_data;
454
455	};
456
457	} // end of namespace
458
459	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision