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 "escript/Data/DataException.h"
#include "escript/Data/DataArrayView.h"
#include "escript/Data/FunctionSpace.h"

#include <iostream>
#include <boost/scoped_ptr.hpp>
#include <functional>
#include <string>

namespace escript {

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

   Description:
   DataAbstract provides an interface for the class of containers
   which hold ESyS data. The container may be thought of as a 2 dimensional
   array of data points. The data points themselves are arrays 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.
  */
  const DataArrayView&
  getPointDataView() const;

  DataArrayView&
  getPointDataView();

  /**
     \brief
     Return the offset for the given sample. This is somewhat artificial notion
     but returns the offset for the given point into the container
     holding the point data. Only really necessary to avoid many DataArrayView
     objects.
     \param sampleNo - Input - sample number.
     \param dataPointNo - Input - Input.
   */
  virtual
  ValueType::size_type
  getPointOffset(int sampleNo,
                 int dataPointNo) const = 0;

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

  /**
     \brief
     Return the number of doubles stored for the Data.
  */
  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
     Check this and the right 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 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 samplesNo Input
     \param dataPointNo Input
  */
  virtual
  DataArrayView
  getDataPoint(int samplesNo,
               int dataPointNo) = 0;

  /**
     \brief
     Return the function space.
  */
  const FunctionSpace&
  getFunctionSpace() const;

  /**
     \brief
     Return a newly constructed DataAbstract. 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 value.
     \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 point if the data point is 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 DataArrayView::ShapeType& shape) = 0;

  /**
     \brief
     setTaggedValue
                                                                                                                                   
     Description:
     Assign the given value to the given tag.
     \param tagKey - Input - Integer key.
     \param value - Input - Single DataArrayView value to be assigned to the tag.
     NB: If the data isn't tagged an exception will be thrown.
  */
  virtual
  void
  setTaggedValue(int tagKey,
                 const DataArrayView& value);

 protected:

  /**
     \brief
     Set the pointDataView
     \param right - 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);

 private:

  int m_noDataPointsPerSample;

  int m_noSamples;

  //
  // Provides a view of the data as point data
  boost::scoped_ptr<DataArrayView> m_pointDataView;

  //
  // function space
  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 "escript/Data/DataException.h"
20	#include "escript/Data/DataArrayView.h"
21	#include "escript/Data/FunctionSpace.h"
22
23	#include <iostream>
24	#include <boost/scoped_ptr.hpp>
25	#include <functional>
26	#include <string>
27
28	namespace escript {
29
30	/**
31	\brief
32	DataAbstract provides an interface for the class of containers
33	which hold ESyS data.
34
35	Description:
36	DataAbstract provides an interface for the class of containers
37	which hold ESyS data. The container may be thought of as a 2 dimensional
38	array of data points. The data points themselves are arrays of rank 0-4.
39	*/
40
41	class DataAbstract {
42
43	public:
44
45	typedef DataArrayView::ValueType ValueType;
46	typedef DataArrayView::ShapeType ShapeType;
47
48	/**
49	\brief
50	Constructor for DataAbstract.
51
52	Description:
53	Constructor for DataAbstract.
54	\param what - Input - A description of what this data represents.
55	*/
56	DataAbstract(const FunctionSpace& what);
57
58	/**
59	\brief
60	Destructor for DataAbstract.
61	*/
62	virtual
63	~DataAbstract();
64
65	/**
66	\brief
67	Write the data as a string.
68	*/
69	virtual
70	std::string
71	toString() const = 0;
72
73	/**
74	\brief
75	Return the number of data points per sample.
76	*/
77	int
78	getNumDPPSample() const;
79
80	/**
81	\brief
82	Return the number of samples.
83	*/
84	int
85	getNumSamples() const;
86
87	/**
88	\brief
89	Return the DataArrayView of the point data. This essentially contains
90	the shape information for each data point although it also may be used
91	to manipulate the point data.
92	*/
93	const DataArrayView&
94	getPointDataView() const;
95
96	DataArrayView&
97	getPointDataView();
98
99	/**
100	\brief
101	Return the offset for the given sample. This is somewhat artificial notion
102	but returns the offset for the given point into the container
103	holding the point data. Only really necessary to avoid many DataArrayView
104	objects.
105	\param sampleNo - Input - sample number.
106	\param dataPointNo - Input - Input.
107	*/
108	virtual
109	ValueType::size_type
110	getPointOffset(int sampleNo,
111	int dataPointNo) const = 0;
112
113	/**
114	\brief
115	Return the sample data for the given sample no.
116	*/
117	double*
118	getSampleData(ValueType::size_type sampleNo);
119
120	/**
121	\brief
122	Return the number of doubles stored for the Data.
123	*/
124	virtual
125	ValueType::size_type
126	getLength() const = 0;
127
128	/**
129	\brief
130	Return the sample data for the given tag key.
131	NB: If the data isn't tagged an exception will be thrown.
132	*/
133	virtual
134	double*
135	getSampleDataByTag(int tag);
136
137	/**
138	\brief
139	Check this and the right operands are compatible. Throws
140	an exception if they aren't.
141	\param right - Input - The right hand side.
142	*/
143	void
144	operandCheck(const DataAbstract& right) const;
145
146	/**
147	\brief
148	Return true if a valid sample point number.
149	*/
150	bool
151	validSamplePointNo(int samplePointNo) const;
152
153	/**
154	\brief
155	Return true if a valid number.
156	*/
157	bool
158	validSampleNo(int sampleNo) const;
159
160	/**
161	\brief
162	Return a view into the data for the data point specified.
163	NOTE: Construction of the DataArrayView is a relatively expensive
164	operation.
165	\param samplesNo Input
166	\param dataPointNo Input
167	*/
168	virtual
169	DataArrayView
170	getDataPoint(int samplesNo,
171	int dataPointNo) = 0;
172
173	/**
174	\brief
175	Return the function space.
176	*/
177	const FunctionSpace&
178	getFunctionSpace() const;
179
180	/**
181	\brief
182	Return a newly constructed DataAbstract. The caller is responsible for
183	managing the object created.
184	*/
185	virtual
186	DataAbstract*
187	getSlice(const DataArrayView::RegionType& region) const = 0;
188
189	/**
190	\brief
191	Copy the specified region from the given value.
192	\param value - Input - Data to copy from
193	\param region - Input - Region to copy.
194	*/
195	virtual
196	void
197	setSlice(const DataAbstract* value,
198	const DataArrayView::RegionType& region) = 0;
199
200	/**
201	\brief
202	Reshape the data point if the data point is currently rank 0.
203	Will throw an exception if the data points are not rank 0.
204	The original data point value is used for all values of the new
205	data point.
206	*/
207	virtual
208	void
209	reshapeDataPoint(const DataArrayView::ShapeType& shape) = 0;
210
211	/**
212	\brief
213	setTaggedValue
214
215	Description:
216	Assign the given value to the given tag.
217	\param tagKey - Input - Integer key.
218	\param value - Input - Single DataArrayView value to be assigned to the tag.
219	NB: If the data isn't tagged an exception will be thrown.
220	*/
221	virtual
222	void
223	setTaggedValue(int tagKey,
224	const DataArrayView& value);
225
226	protected:
227
228	/**
229	\brief
230	Set the pointDataView
231	\param right - Input - The point data view. DataAbstract takes ownership
232	of the DataArrayView provided. It will delete it when it is destructed.
233	*/
234	void
235	setPointDataView(const DataArrayView& input);
236
237	private:
238
239	int m_noDataPointsPerSample;
240
241	int m_noSamples;
242
243	//
244	// Provides a view of the data as point data
245	boost::scoped_ptr<DataArrayView> m_pointDataView;
246
247	//
248	// function space
249	FunctionSpace m_functionSpace;
250
251	};
252
253	inline
254	bool
255	DataAbstract::validSamplePointNo(int samplePointNo) const
256	{
257	return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));
258	}
259
260	inline
261	bool
262	DataAbstract::validSampleNo(int sampleNo) const
263	{
264	return ((0 <= sampleNo) && (sampleNo < m_noSamples));
265	}
266
267	inline
268	DataAbstract::ValueType::value_type*
269	DataAbstract::getSampleData(ValueType::size_type sampleNo)
270	{
271	return &(m_pointDataView->getData(getPointOffset(sampleNo,0)));
272	}
273
274	inline
275	int
276	DataAbstract::getNumDPPSample() const
277	{
278	return m_noDataPointsPerSample;
279	}
280
281	inline
282	int
283	DataAbstract::getNumSamples() const
284	{
285	return m_noSamples;
286	}
287
288	inline
289	const
290	FunctionSpace&
291	DataAbstract::getFunctionSpace() const
292	{
293	return m_functionSpace;
294	}
295
296	inline
297	const
298	DataArrayView&
299	DataAbstract::getPointDataView() const
300	{
301	return *(m_pointDataView.get());
302	}
303
304	inline
305	DataArrayView&
306	DataAbstract::getPointDataView()
307	{
308	return *(m_pointDataView.get());
309	}
310
311	} // end of namespace
312	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision