escript/src/DataAbstract.h

// $Id$
/* 
 ******************************************************************************
 *                                                                            *
 *       COPYRIGHT  ACcESS 2004 -  All Rights Reserved                        *
 *                                                                            *
 * This software is the property of ACcESS. No part of this code              *
 * may be copied in any form or by any means without the expressed written    *
 * consent of ACcESS.  Copying, use or modification of this software          *
 * by any unauthorised person is illegal unless that person has a software    *
 * license agreement with ACcESS.                                             *
 *                                                                            *
 ******************************************************************************
*/

#if !defined escript_DataAbstract_20040315_H
#define escript_DataAbstract_20040315_H

#include "DataArrayView.h"
#include "DataArray.h"
#include "FunctionSpace.h"

#include <boost/scoped_ptr.hpp>
#include <boost/python/numeric.hpp>

#include <string>
#include <fstream>

namespace escript {

/**
   \brief
   DataAbstract provides an abstract interface for the class of containers
   which hold ESyS data. 

   Description:
   DataAbstract provides an abstract interface for the class of containers
   which hold ESyS data. The container may be thought of as a 2 dimensional
   array of data points where one dimension corresponds to the number of samples
   and the other to the number of data points per sample as defined by the function
   space associated with each Data object. The data points themselves are arrays of
   doubles of rank 0-4.
*/

class DataAbstract {

 public:

  typedef DataArrayView::ValueType ValueType;
  typedef DataArrayView::ShapeType ShapeType;

  /**
     \brief
     Constructor for DataAbstract.

     Description:
     Constructor for DataAbstract.

     \param what - Input - A description of what this data represents.
  */
  DataAbstract(const FunctionSpace& what);

  /**
    \brief
    Destructor for DataAbstract.
  */
  virtual
  ~DataAbstract();

  /**
     \brief
     Write the data as a string.
  */
  virtual
  std::string
  toString() const = 0;

  /**
     \brief
     Return the number of data points per sample.
  */
  int
  getNumDPPSample() const;

  /**
     \brief
     Return the number of samples.
  */
  int
  getNumSamples() const;

  /**
     \brief
     Return the DataArrayView of the point data. This essentially contains 
     the shape information for each data point although it also may be used
     to manipulate the point data.
  */
  DataArrayView&
  getPointDataView();

  const DataArrayView&
  getPointDataView() const;

  /**
     \brief
     Return the offset for the given sample. This returns the offset for the given
     point into the container holding the point data. Only really necessary to
     avoid creating many DataArrayView objects.

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

  /**
     \brief
     Return the sample data for the given sample number.
  */
  double*
  getSampleData(ValueType::size_type sampleNo);

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

  /**
     \brief
     Return the sample data for the given tag key.
     NB: If the data isn't tagged an exception will be thrown.
  */
  virtual
  double*
  getSampleDataByTag(int tag);

  /**
     \brief
     Assign the given value to the data-points(s) referenced by the given
     reference number.

     If this Data object cannot be accessed by reference numbers an
     exception will be thrown.

     \param ref - Input - reference number.
     \param value - Input - value to assign to data-points associated with
                            the given reference number.
  */
  virtual
  void
  setRefValue(int ref,
              const DataArray& value);

  /**
     \brief
     Return the values associated with the data-point(s) referenced by the given
     reference number.

     If this Data object cannot be accessed by reference numbers an
     exception will be thrown.

     \param ref - Input - reference number.
     \param value - Output - object to receive data-points associated with
                             the given reference number.
  */
  virtual
  void
  getRefValue(int ref,
              DataArray& value);

  /**
     \brief
     Check this and the given RHS operands are compatible. Throws
     an exception if they aren't.

     \param right - Input - The right hand side.
  */
  void
  operandCheck(const DataAbstract& right) const;

  /**
     \brief
     Return true if a valid sample point number.
  */
  bool
  validSamplePointNo(int samplePointNo) const;

  /**
     \brief
     Return true if a valid sample number.
  */
  bool
  validSampleNo(int sampleNo) const;
 
  /**
     \brief
     Return a view into the data for the data point specified.
     NOTE: Construction of the DataArrayView is a relatively expensive 
     operation.

     \param sampleNo - Input - the sample number.
     \param dataPointNo - Input - the data point number.
  */
  virtual
  DataArrayView
  getDataPoint(int sampleNo,
               int dataPointNo) = 0;

  /**
     \brief
     Return the function space associated with this Data object.
  */
  const
  FunctionSpace&
  getFunctionSpace() const;

  /**
     \brief
     Return the given slice from this object.

     NB: The caller is responsible for managing the object created.
  */
  virtual
  DataAbstract*
  getSlice(const DataArrayView::RegionType& region) const = 0;

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

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

  /**
     \brief
     Reshape the data points if they are currently rank 0.
     Will throw an exception if the data points are not rank 0.
     The original data point value is used for all values of the new
     data point.
  */
  virtual
  void
  reshapeDataPoint(const ShapeType& shape) = 0;

  /**
     \brief
     setTaggedValue
                                                                                                                                   
     Description:
     Assign the given value to the given tag.

     NB: If the data isn't tagged an exception will be thrown.

     \param tagKey - Input - Integer key.
     \param value - Input - Single DataArrayView value to be assigned to the tag.
  */
  virtual
  void
  setTaggedValue(int tagKey,
                 const DataArrayView& 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).
  */
  virtual
  int
  archiveData(std::ofstream& archiveFile,
              const 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).
  */
  virtual
  int
  extractData(std::ifstream& archiveFile,
              const ValueType::size_type noValues);

  /**
     \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
  */
  virtual void
  copyAll(const boost::python::numeric::array& value);

  /**
     \brief
     Return the tag number associated with the given data-point number.

     If the object cannot be referenced by tag numbers, an exception
     will be thrown.
  */
  virtual
  int
  getTagNumber(int dpno);

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

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

  */
  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.

  */

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

 protected:

  /**
     \brief
     Set the pointDataView DataArrayView associated with this object.

     \param input - Input - The point data view. DataAbstract takes ownership
     of the DataArrayView provided. It will delete it when it is destructed.
  */
  void
  setPointDataView(const DataArrayView& input);

  void
  resetPointDataView();

 private:

  //
  // The number of samples in this Data object.
  // This is derived directly from the FunctionSpace.
  int m_noSamples;

  //
  // The number of data points per sample in this Data object.
  // This is derived directly from the FunctionSpace.
  int m_noDataPointsPerSample;

  //
  // The DataArrayView of the data array associated with this object.
  // The data array is defined only in child classes of this class, it
  // is not defined in this abstract parent class.
  boost::scoped_ptr<DataArrayView> m_pointDataView;

  //
  // A FunctionSpace which provides a description of the data associated
  // with this Data object.
  FunctionSpace m_functionSpace;

};

inline
bool
DataAbstract::validSamplePointNo(int samplePointNo) const 
{
  return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));
}

inline
bool
DataAbstract::validSampleNo(int sampleNo) const
{
  return ((0 <= sampleNo) && (sampleNo < m_noSamples));
}

inline
DataAbstract::ValueType::value_type*
DataAbstract::getSampleData(ValueType::size_type sampleNo)
{
  return &(m_pointDataView->getData(getPointOffset(sampleNo,0)));
}

inline
int
DataAbstract::getNumDPPSample() const 
{
  return m_noDataPointsPerSample;
}

inline
int
DataAbstract::getNumSamples() const
{
  return m_noSamples;
}

inline
const
FunctionSpace&
DataAbstract::getFunctionSpace() const
{
  return m_functionSpace;
}

inline
const
DataArrayView&
DataAbstract::getPointDataView() const
{
  return *(m_pointDataView.get());
}

inline
DataArrayView&
DataAbstract::getPointDataView()
{
  return *(m_pointDataView.get());
}
} // end of namespace

#endif
1	// $Id$
2	/*
3	******************************************************************************
4	* *
5	* COPYRIGHT ACcESS 2004 - All Rights Reserved *
6	* *
7	* This software is the property of ACcESS. No part of this code *
8	* may be copied in any form or by any means without the expressed written *
9	* consent of ACcESS. Copying, use or modification of this software *
10	* by any unauthorised person is illegal unless that person has a software *
11	* license agreement with ACcESS. *
12	* *
13	******************************************************************************
14	*/
15
16	#if !defined escript_DataAbstract_20040315_H
17	#define escript_DataAbstract_20040315_H
18
19	#include "DataArrayView.h"
20	#include "DataArray.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	DataAbstract(const FunctionSpace& what);
62
63	/**
64	\brief
65	Destructor for DataAbstract.
66	*/
67	virtual
68	~DataAbstract();
69
70	/**
71	\brief
72	Write the data as a string.
73	*/
74	virtual
75	std::string
76	toString() const = 0;
77
78	/**
79	\brief
80	Return the number of data points per sample.
81	*/
82	int
83	getNumDPPSample() const;
84
85	/**
86	\brief
87	Return the number of samples.
88	*/
89	int
90	getNumSamples() const;
91
92	/**
93	\brief
94	Return the DataArrayView of the point data. This essentially contains
95	the shape information for each data point although it also may be used
96	to manipulate the point data.
97	*/
98	DataArrayView&
99	getPointDataView();
100
101	const DataArrayView&
102	getPointDataView() const;
103
104	/**
105	\brief
106	Return the offset for the given sample. This returns the offset for the given
107	point into the container holding the point data. Only really necessary to
108	avoid creating many DataArrayView objects.
109
110	\param sampleNo - Input - sample number.
111	\param dataPointNo - Input - data point number.
112	*/
113	virtual
114	ValueType::size_type
115	getPointOffset(int sampleNo,
116	int dataPointNo) const = 0;
117
118	/**
119	\brief
120	Return the sample data for the given sample number.
121	*/
122	double*
123	getSampleData(ValueType::size_type sampleNo);
124
125	/**
126	\brief
127	Return the number of doubles stored for this Data object.
128	*/
129	virtual
130	ValueType::size_type
131	getLength() const = 0;
132
133	/**
134	\brief
135	Return the sample data for the given tag key.
136	NB: If the data isn't tagged an exception will be thrown.
137	*/
138	virtual
139	double*
140	getSampleDataByTag(int tag);
141
142	/**
143	\brief
144	Assign the given value to the data-points(s) referenced by the given
145	reference number.
146
147	If this Data object cannot be accessed by reference numbers an
148	exception will be thrown.
149
150	\param ref - Input - reference number.
151	\param value - Input - value to assign to data-points associated with
152	the given reference number.
153	*/
154	virtual
155	void
156	setRefValue(int ref,
157	const DataArray& value);
158
159	/**
160	\brief
161	Return the values associated with the data-point(s) referenced by the given
162	reference number.
163
164	If this Data object cannot be accessed by reference numbers an
165	exception will be thrown.
166
167	\param ref - Input - reference number.
168	\param value - Output - object to receive data-points associated with
169	the given reference number.
170	*/
171	virtual
172	void
173	getRefValue(int ref,
174	DataArray& value);
175
176	/**
177	\brief
178	Check this and the given RHS operands are compatible. Throws
179	an exception if they aren't.
180
181	\param right - Input - The right hand side.
182	*/
183	void
184	operandCheck(const DataAbstract& right) const;
185
186	/**
187	\brief
188	Return true if a valid sample point number.
189	*/
190	bool
191	validSamplePointNo(int samplePointNo) const;
192
193	/**
194	\brief
195	Return true if a valid sample number.
196	*/
197	bool
198	validSampleNo(int sampleNo) const;
199
200	/**
201	\brief
202	Return a view into the data for the data point specified.
203	NOTE: Construction of the DataArrayView is a relatively expensive
204	operation.
205
206	\param sampleNo - Input - the sample number.
207	\param dataPointNo - Input - the data point number.
208	*/
209	virtual
210	DataArrayView
211	getDataPoint(int sampleNo,
212	int dataPointNo) = 0;
213
214	/**
215	\brief
216	Return the function space associated with this Data object.
217	*/
218	const
219	FunctionSpace&
220	getFunctionSpace() const;
221
222	/**
223	\brief
224	Return the given slice from this object.
225
226	NB: The caller is responsible for managing the object created.
227	*/
228	virtual
229	DataAbstract*
230	getSlice(const DataArrayView::RegionType& region) const = 0;
231
232	/**
233	\brief
234	Copy the specified region from the given object.
235
236	\param value - Input - Data to copy from
237	\param region - Input - Region to copy.
238	*/
239	virtual
240	void
241	setSlice(const DataAbstract* value,
242	const DataArrayView::RegionType& region) = 0;
243
244	/**
245	\brief
246	Reshape the data points if they are currently rank 0.
247	Will throw an exception if the data points are not rank 0.
248	The original data point value is used for all values of the new
249	data point.
250	*/
251	virtual
252	void
253	reshapeDataPoint(const ShapeType& shape) = 0;
254
255	/**
256	\brief
257	setTaggedValue
258
259	Description:
260	Assign the given value to the given tag.
261
262	NB: If the data isn't tagged an exception will be thrown.
263
264	\param tagKey - Input - Integer key.
265	\param value - Input - Single DataArrayView value to be assigned to the tag.
266	*/
267	virtual
268	void
269	setTaggedValue(int tagKey,
270	const DataArrayView& value);
271
272	/**
273	\brief
274	Archive the underlying data values to the file referenced
275	by ofstream. A count of the number of values expected to be written
276	is provided as a cross-check.
277
278	The return value indicates success (0) or otherwise (1).
279	*/
280	virtual
281	int
282	archiveData(std::ofstream& archiveFile,
283	const ValueType::size_type noValues) const;
284
285	/**
286	\brief
287	Extract the number of values specified by noValues from the file
288	referenced by ifstream to the underlying data structure.
289
290	The return value indicates success (0) or otherwise (1).
291	*/
292	virtual
293	int
294	extractData(std::ifstream& archiveFile,
295	const ValueType::size_type noValues);
296
297	/**
298	\brief
299	Copy the numarray object to the data points in this object.
300
301	Description:
302	Copy the numarray object to the data points in this object.
303
304	\param value Input - new values for the data points
305	*/
306	virtual void
307	copyAll(const boost::python::numeric::array& value);
308
309	/**
310	\brief
311	Return the tag number associated with the given data-point number.
312
313	If the object cannot be referenced by tag numbers, an exception
314	will be thrown.
315	*/
316	virtual
317	int
318	getTagNumber(int dpno);
319
320	/**
321	\brief
322	solves the eigenvalue problem thisV=evV for the eigenvalues ev
323
324	\param ev - Output - eigenvalues in increasing order at each data point
325
326	*/
327	virtual void
328	eigenvalues(DataAbstract* ev);
329
330	/**
331	\brief
332	solves the eigenvalue problem thisV=evV for the eigenvalues ev and eigenvectors V
333
334	\param ev - Output - eigenvalues in increasing order at each data point
335	\param V - Output - corresponding eigenvectors. They are normalized such that their length is one
336	and the first nonzero component is positive.
337	\param tol - Input - eigenvalue with relative distance tol are treated as equal.
338
339	*/
340
341	virtual void
342	eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
343
344	protected:
345
346	/**
347	\brief
348	Set the pointDataView DataArrayView associated with this object.
349
350	\param input - Input - The point data view. DataAbstract takes ownership
351	of the DataArrayView provided. It will delete it when it is destructed.
352	*/
353	void
354	setPointDataView(const DataArrayView& input);
355
356	void
357	resetPointDataView();
358
359	private:
360
361	//
362	// The number of samples in this Data object.
363	// This is derived directly from the FunctionSpace.
364	int m_noSamples;
365
366	//
367	// The number of data points per sample in this Data object.
368	// This is derived directly from the FunctionSpace.
369	int m_noDataPointsPerSample;
370
371	//
372	// The DataArrayView of the data array associated with this object.
373	// The data array is defined only in child classes of this class, it
374	// is not defined in this abstract parent class.
375	boost::scoped_ptr<DataArrayView> m_pointDataView;
376
377	//
378	// A FunctionSpace which provides a description of the data associated
379	// with this Data object.
380	FunctionSpace m_functionSpace;
381
382	};
383
384	inline
385	bool
386	DataAbstract::validSamplePointNo(int samplePointNo) const
387	{
388	return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));
389	}
390
391	inline
392	bool
393	DataAbstract::validSampleNo(int sampleNo) const
394	{
395	return ((0 <= sampleNo) && (sampleNo < m_noSamples));
396	}
397
398	inline
399	DataAbstract::ValueType::value_type*
400	DataAbstract::getSampleData(ValueType::size_type sampleNo)
401	{
402	return &(m_pointDataView->getData(getPointOffset(sampleNo,0)));
403	}
404
405	inline
406	int
407	DataAbstract::getNumDPPSample() const
408	{
409	return m_noDataPointsPerSample;
410	}
411
412	inline
413	int
414	DataAbstract::getNumSamples() const
415	{
416	return m_noSamples;
417	}
418
419	inline
420	const
421	FunctionSpace&
422	DataAbstract::getFunctionSpace() const
423	{
424	return m_functionSpace;
425	}
426
427	inline
428	const
429	DataArrayView&
430	DataAbstract::getPointDataView() const
431	{
432	return *(m_pointDataView.get());
433	}
434
435	inline
436	DataArrayView&
437	DataAbstract::getPointDataView()
438	{
439	return *(m_pointDataView.get());
440	}
441	} // end of namespace
442
443	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision