escript/src/DataExpanded.h


/* $Id$ */

/*******************************************************
 *
 *           Copyright 2003-2007 by ACceSS MNRF
 *       Copyright 2007 by University of Queensland
 *
 *                http://esscc.uq.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 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.
  */
  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();

  /**
     \brief
     Return a textual representation of the data.
  */
  ESCRIPT_DLL_API
  virtual
  std::string
  toString() const;
 /**
     \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;

  /**
     \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 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
    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 DataTypes::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 DataTypes::ValueType::size_type noValues);

  /**
     \brief
     setTaggedValue

     Description:
     uses tag to set a new value

     \param tagKey - Input - Integer key.
     \param value - Input - Single DataArrayView value to be assigned to the tag.
  */
  ESCRIPT_DLL_API
  virtual
  void
  setTaggedValue(int tagKey,
                 const DataArrayView& value);


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

  /**
     \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	/* $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_DataExpanded_20040323_H
17	#define escript_DataExpanded_20040323_H
18	#include "system_dep.h"
19
20	#include "DataAbstract.h"
21	#include "DataBlocks2D.h"
22	#include "DataArrayView.h"
23
24	#include <boost/python/numeric.hpp>
25
26	namespace escript {
27
28	//
29	// Forward declarations of other Data types.
30	class DataConstant;
31	class DataTagged;
32
33	/**
34	\brief
35	Give a short description of what DataExpanded does.
36
37	Description:
38	Give a detailed description of DataExpanded.
39
40	Template Parameters:
41	For templates describe any conditions that the parameters used in the
42	template must satisfy.
43	*/
44
45	class DataExpanded : public DataAbstract {
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.
70
71	Description:
72	Alternative Constructor for DataExpanded.
73
74	The given single data value is copied to all the data points in
75	this data object, where the number of data points is defined by
76	the given function space.
77
78	\param value - Input - A single data value.
79	\param what - Input - A description of what this data represents.
80	*/
81	ESCRIPT_DLL_API
82	DataExpanded(const DataArrayView& value,
83	const FunctionSpace& what);
84
85	/**
86	\brief
87	Alternative constructor for DataExpanded that copies a slice from
88	another DataExpanded.
89
90	\param other - Input - DataExpanded object to slice from.
91	\param region - Input - region to copy.
92	*/
93	ESCRIPT_DLL_API
94	DataExpanded(const DataExpanded& other,
95	const DataTypes::RegionType& region);
96
97	/**
98	\brief
99	Alternative constructor for DataExpanded objects.
100
101	Description:
102	Alternative Constructor for DataExpanded objects.
103	\param what - Input - A description of what this data object represents.
104	\param shape - Input - the shape of each data-point.
105	\param data - the array of data values for the data-points.
106	*/
107	ESCRIPT_DLL_API
108	DataExpanded(const FunctionSpace& what,
109	const DataTypes::ShapeType &shape,
110	const DataTypes::ValueType &data);
111
112	/**
113	\brief
114	Copy constructor for DataExpanded.
115	Performs a deep copy from another DataExpanded.
116	*/
117	ESCRIPT_DLL_API
118	DataExpanded(const DataExpanded& other);
119
120	/**
121	\brief
122	Copy constructor for DataExpanded.
123	Construct a DataExpanded from a DataConstant.
124	*/
125	ESCRIPT_DLL_API
126	DataExpanded(const DataConstant& other);
127
128	/**
129	\brief
130	Copy constructor for DataExpanded.
131	Construct a DataExpanded from a DataTagged.
132	*/
133	ESCRIPT_DLL_API
134	DataExpanded(const DataTagged& other);
135
136	/**
137	\brief
138	Default destructor for DataExpanded.
139	*/
140	ESCRIPT_DLL_API
141	virtual
142	~DataExpanded();
143
144	/**
145	\brief
146	Return a textual representation of the data.
147	*/
148	ESCRIPT_DLL_API
149	virtual
150	std::string
151	toString() const;
152	/**
153	\brief
154	dumps the object into a netCDF file
155	*/
156	ESCRIPT_DLL_API
157	virtual
158	void
159	dump(const std::string fileName) const;
160
161	/**
162	\brief
163	sets all values to zero
164	*/
165	ESCRIPT_DLL_API
166	virtual
167	void
168	setToZero();
169
170	/**
171	\brief
172	Return the offset for the given given data point. This returns
173	the offset in bytes for the given point into the container
174	holding the point data.
175
176	\param sampleNo - Input - sample number.
177	\param dataPointNo - Input - data point number.
178	*/
179	ESCRIPT_DLL_API
180	virtual
181	DataTypes::ValueType::size_type
182	getPointOffset(int sampleNo,
183	int dataPointNo) const;
184
185	/**
186	\brief
187	Return a view into the data array for the data point specified.
188
189	NOTE: Construction of the DataArrayView is a relatively expensive
190	operation.
191
192	\param sampleNo - Input - sample number.
193	\param dataPointNo - Input - data point number.
194	\return DataArrayView for the data point.
195	*/
196	ESCRIPT_DLL_API
197	DataArrayView
198	getDataPoint(int sampleNo,
199	int dataPointNo);
200
201	/**
202	\brief
203	Return the number of doubles stored for the Data.
204	*/
205	ESCRIPT_DLL_API
206	virtual
207	ValueType::size_type
208	getLength() const;
209
210	/**
211	\brief
212	Factory method that returns a newly created DataExpanded.
213	The caller is reponsible for managing the object created.
214
215	\param region - Input - Region to copy.
216	*/
217	ESCRIPT_DLL_API
218	virtual
219	DataAbstract*
220	getSlice(const DataTypes::RegionType& region) const;
221
222	/**
223	\brief
224	Copy the specified region from the given value.
225
226	\param value - Input - Data object to copy from.
227	\param region - Input - Region to copy.
228	*/
229	ESCRIPT_DLL_API
230	virtual
231	void
232	setSlice(const DataAbstract* value,
233	const DataTypes::RegionType& region);
234
235	/**
236	\brief
237	Archive the underlying data values to the file referenced
238	by ofstream. A count of the number of values expected to be written
239	is provided as a cross-check.
240
241	The return value indicates success (0) or otherwise (1).
242	*/
243	ESCRIPT_DLL_API
244	int
245	archiveData(std::ofstream& archiveFile,
246	const DataTypes::ValueType::size_type noValues) const;
247
248	/**
249	\brief
250	Extract the number of values specified by noValues from the file
251	referenced by ifstream to the underlying data structure.
252
253	The return value indicates success (0) or otherwise (1).
254	*/
255	ESCRIPT_DLL_API
256	int
257	extractData(std::ifstream& archiveFile,
258	const DataTypes::ValueType::size_type noValues);
259
260	/**
261	\brief
262	setTaggedValue
263
264	Description:
265	uses tag to set a new value
266
267	\param tagKey - Input - Integer key.
268	\param value - Input - Single DataArrayView value to be assigned to the tag.
269	*/
270	ESCRIPT_DLL_API
271	virtual
272	void
273	setTaggedValue(int tagKey,
274	const DataArrayView& value);
275
276
277
278	/**
279	\brief
280	setTaggedValue
281
282	Description:
283	uses tag to set a new value
284
285	\param tagKey - Input - Integer key.
286	\param pointshape - Input - The shape of the value parameter
287	\param value - Input - .
288	*/
289	void
290	setTaggedValue(int tagKey,
291	const DataTypes::ShapeType& pointshape,
292	const DataTypes::ValueType& value,
293	int dataOffset=0);
294
295
296
297	/**
298	\brief
299	Computes a symmetric matrix (A + AT) / 2
300
301	\param ev - Output - symmetric matrix
302
303	*/
304	ESCRIPT_DLL_API
305	virtual void
306	symmetric(DataAbstract* ev);
307
308	/**
309	\brief
310	Computes a nonsymmetric matrix (A - AT) / 2
311
312	\param ev - Output - nonsymmetric matrix
313
314	*/
315	ESCRIPT_DLL_API
316	virtual void
317	nonsymmetric(DataAbstract* ev);
318
319	/**
320	\brief
321	Computes the trace of a matrix
322
323	\param ev - Output - trace of your matrix
324
325	*/
326	ESCRIPT_DLL_API
327	virtual void
328	trace(DataAbstract* ev, int axis_offset);
329
330	/**
331	\brief
332	Transpose each data point of this Data object around the given axis.
333
334	\param ev - Output - transpose of your matrix
335
336	*/
337	ESCRIPT_DLL_API
338	virtual void
339	transpose(DataAbstract* ev, int axis_offset);
340
341	/**
342	\brief
343	swaps components axis0 and axis1
344
345	\param ev - Output - swapped components
346
347	*/
348	ESCRIPT_DLL_API
349	virtual void
350	swapaxes(DataAbstract* ev, int axis0, int axis1);
351
352
353	/**
354	\brief
355	solves the eigenvalue problem thisV=evV for the eigenvalues ev
356
357	\param ev - Output - eigenvalues in increasing order at each data point
358
359	*/
360	ESCRIPT_DLL_API
361	virtual void
362	eigenvalues(DataAbstract* ev);
363
364	/**
365	\brief
366	solves the eigenvalue problem thisV=evV for the eigenvalues ev and eigenvectors V
367
368	\param ev - Output - eigenvalues in increasing order at each data point
369	\param V - Output - corresponding eigenvectors. They are normalized such that their length is one
370	and the first nonzero component is positive.
371	\param tol - Input - eigenvalue with relative distance tol are treated as equal.
372
373	*/
374
375	ESCRIPT_DLL_API
376	virtual void
377	eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
378
379	/**
380	* \brief
381	* reorders data sample ordered by reference_ids to the ordering of the functions space
382	*
383	* \param reference_ids - Input - reference_ids used for current ordering
384	* */
385	ESCRIPT_DLL_API
386	virtual void
387	reorderByReferenceIDs(int *reference_ids);
388
389
390
391	protected:
392
393	private:
394
395	/**
396	\brief
397	Common initialisation called from constructors.
398
399	Description:
400	Common initialisation called from constructors.
401
402	Resizes the underlying data array to provide sufficient storage for the
403	given shape and number of data points, and creates the corresponding
404	DataArrayView of this data.
405
406	\param shape - Input - The shape of the point data.
407	\param noSamples - Input - number of samples.
408	\param noDataPointsPerSample - Input - number of data points per sample.
409	*/
410	void
411	initialise(const DataTypes::ShapeType& shape,
412	int noSamples,
413	int noDataPointsPerSample);
414
415	/**
416	\brief
417	Copy the given data point value to all data points in this object.
418
419	Description:
420	Copy the given data point to all data points in this object.
421
422	\param value Input - A single data point value.
423	*/
424	void
425	copy(const DataArrayView& value);
426
427	/**
428	\brief
429	Copy the given data point value given a numarray object to all data points in this object.
430
431	Description:
432	Copy the given data point value given a numarray object to all data points in this object.
433
434	\param value Input - A single data point value.
435	*/
436	void
437	copy(const boost::python::numeric::array& value);
438
439	/**
440	\brief
441	Copy the numarray object to the data points in this object.
442
443	Description:
444	Copy the numarray object to the data points in this object.
445
446	\param value Input - new values for the data points
447	*/
448	void
449	copyAll(const boost::python::numeric::array& value);
450
451	/**
452	\brief
453	Copy a double value to the data point dataPointNo of sample sampleNo in this object.
454
455	Description:
456	Copy a double value to the data point dataPointNo of sample sampleNo in this object.
457
458	\param sampleNo Input - sample number
459	\param dataPointNo Input - data point of the sample
460	\param value Input - new values for the data point
461	*/
462	ESCRIPT_DLL_API
463	virtual void
464	copyToDataPoint(const int sampleNo, const int dataPointNo, const double value);
465
466
467	/**
468	\brief
469	Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
470
471	Description:
472	Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
473
474	\param sampleNo Input - sample number
475	\param dataPointNo Input - data point of the sample
476	\param value Input - new values for the data point
477	*/
478	void
479	copyToDataPoint(const int sampleNo, const int dataPointNo, const boost::python::numeric::array& value);
480
481	//
482	// The main data storage array, a 2D array of data blocks.
483	// noSamples * noDataPointsPerSample
484	DataBlocks2D m_data;
485
486	};
487
488	} // end of namespace
489
490	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision