escript/src/DataLazy.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_DataLazy_20081008_H
#define escript_DataLazy_20081008_H
#include "system_dep.h"

#include "DataAbstract.h"

#include <string>
#include <functional>

#include "LocalOps.h"       // for tensor_binary_op

namespace escript {

// For the purposes of unit testing and maintaining sanity, it is important that this enum be contiguous
enum ES_optype
{
    UNKNOWNOP=0,
    IDENTITY=1,
    ADD=2,
    SUB=3,
    MUL=4,
    DIV=5,
    POW=6,
    SIN=POW+1,
    COS=SIN+1,
    TAN=SIN+2,
    ASIN=SIN+3,
    ACOS=SIN+4,
    ATAN=SIN+5,
    SINH=SIN+6,
    COSH=SIN+7,
    TANH=SIN+8,
    ERF=SIN+9,
    ASINH=SIN+10,
    ACOSH=SIN+11,
    ATANH=SIN+12,
    LOG10=ATANH+1,
    LOG=LOG10+1,
    SIGN=LOG10+2,
    ABS=LOG10+3,
    NEG=LOG10+4,
    POS=LOG10+5,
    EXP=LOG10+6,
    SQRT=LOG10+7,
    RECIP=LOG10+8,
    GZ=RECIP+1,
    LZ=GZ+1,
    GEZ=GZ+2,
    LEZ=GZ+3
};

ESCRIPT_DLL_API
const std::string&
opToString(ES_optype op);

/**
\class escript::DataLazy
\brief Wraps an expression tree of other DataObjects.
The data will be evaluated when required.


NOTE: This class assumes that the Data being pointed at are immutable.
*/

class DataLazy;

typedef POINTER_WRAPPER_CLASS(DataLazy) DataLazy_ptr;
typedef POINTER_WRAPPER_CLASS(const DataLazy) const_DataLazy_ptr;

class DataLazy : public DataAbstract
{

typedef DataAbstract parent;
typedef DataTypes::ValueType ValueType;
typedef DataTypes::ShapeType ShapeType;

public:
  /**
  \brief Create an IDENTITY DataLazy for the given DataAbstract.
  \param p DataAbstract to be wrapped.
  \throws DataException if p is lazy data or it is not constant, tagged or expanded.
  */
  ESCRIPT_DLL_API
  DataLazy(DataAbstract_ptr p);


  /**
  \brief Produce a DataLazy for a unary operation.
  \param left DataAbstract to be operated on.
  \param op unary operation to perform.
  \throws DataException if op is not a unary operation or if p cannot be converted to a DataLazy.
  Note that IDENTITY is not considered a unary operation.
  */
  ESCRIPT_DLL_API
  DataLazy(DataAbstract_ptr left, ES_optype op);

  /**
  \brief Produce a DataLazy for a binary operation.
  \param left left operand
  \param right right operand
  \param op unary operation to perform.
  \throws DataException if op is not a binary operation or if left or right cannot be converted to a DataLazy.
  */
  ESCRIPT_DLL_API
  DataLazy(DataAbstract_ptr left, DataAbstract_ptr right, ES_optype op);

  ESCRIPT_DLL_API
  ~DataLazy();

  /**
  \brief Evaluate the lazy expression.
  \return A DataReady with the value of the lazy expresion.
  */
  ESCRIPT_DLL_API
  DataReady_ptr 
  resolve();

  ESCRIPT_DLL_API
  std::string
  toString() const;

  ESCRIPT_DLL_API
  DataAbstract* 
  deepCopy();


  /**
     \brief
     Return the number of doubles that would be stored for this Data object if it were resolved.
  */
  ESCRIPT_DLL_API
  ValueType::size_type
  getLength() const;


  ESCRIPT_DLL_API
  DataAbstract*
  getSlice(const DataTypes::RegionType& region) const;


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

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


  /**
    \return the number of samples which need to be stored to evaluate the expression.
  */
  ESCRIPT_DLL_API
  int
  getBuffsRequired() const;

  /**
     \brief Produces an IDENTITY DataLazy containing zero.
     The result will have the same shape and functionspace as before.
  */
  ESCRIPT_DLL_API
  virtual void
  setToZero();

private:
  DataReady_ptr m_id;   //  For IDENTITY nodes, stores a wrapped value.
  DataLazy_ptr m_left, m_right; // operands for operation.
  ES_optype m_op;   // operation to perform.
  size_t m_length;  // number of values represented by the operation

  int m_buffsRequired;  // how many samples are required to evaluate this expression
  size_t m_samplesize;  // number of values required to store a sample

  char m_readytype; // E for expanded, T for tagged, C for constant


  /**
  Does the work for toString. 
  */
  void
  intoString(std::ostringstream& oss) const;

  /**
   \brief Converts the DataLazy into an IDENTITY storing the value of the expression.
   This method uses the original methods on the Data class to evaluate the expressions.
   For this reason, it should not be used on DataExpanded instances. (To do so would defeat
   the purpose of using DataLazy in the first place).
  */
  void
  collapse();       // converts the node into an IDENTITY node


  /**
  \brief Evaluates the expression using methods on Data.
  This does the work for the collapse method.
  For reasons of efficiency do not call this method on DataExpanded nodes.
  */
  DataReady_ptr
  collapseToReady();

  /**
  \brief Compute the value of the expression for the given sample.
  \return Vector which stores the value of the subexpression for the given sample.
  \param v A vector to store intermediate results.
  \param offset Index in v to begin storing results.
  \param sampleNo Sample number to evaluate.
  \param roffset (output parameter) the offset in the return vector where the result begins.

  The return value will be an existing vector so do not deallocate it.
  */
  const ValueType*
  resolveSample(ValueType& v,  size_t offset ,int sampleNo, size_t& roffset);

  /**
  \brief Compute the value of the expression (binary operation) for the given sample.
  \return Vector which stores the value of the subexpression for the given sample.
  \param v A vector to store intermediate results.
  \param offset Index in v to begin storing results.
  \param sampleNo Sample number to evaluate.
  \param roffset (output parameter) the offset in the return vector where the result begins.

  The return value will be an existing vector so do not deallocate it.
  If the result is stored in v it should be stored at the offset given.
  Everything from offset to the end of v should be considered available for this method to use.
  */
  ValueType*
  resolveUnary(ValueType& v,  size_t offset,int sampleNo,  size_t& roffset) const;

  /**
  \brief Compute the value of the expression (binary operation) for the given sample.
  \return Vector which stores the value of the subexpression for the given sample.
  \param v A vector to store intermediate results.
  \param offset Index in v to begin storing results.
  \param sampleNo Sample number to evaluate.
  \param roffset (output parameter) the offset in the return vector where the result begins.

  The return value will be an existing vector so do not deallocate it.
  If the result is stored in v it should be stored at the offset given.
  Everything from offset to the end of v should be considered available for this method to use.
  */
  ValueType*
  resolveBinary(ValueType& v,  size_t offset,int sampleNo,  size_t& roffset) const;

};

}
#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_DataLazy_20081008_H
16	#define escript_DataLazy_20081008_H
17	#include "system_dep.h"
18
19	#include "DataAbstract.h"
20
21	#include <string>
22	#include <functional>
23
24	#include "LocalOps.h" // for tensor_binary_op
25
26	namespace escript {
27
28	// For the purposes of unit testing and maintaining sanity, it is important that this enum be contiguous
29	enum ES_optype
30	{
31	UNKNOWNOP=0,
32	IDENTITY=1,
33	ADD=2,
34	SUB=3,
35	MUL=4,
36	DIV=5,
37	POW=6,
38	SIN=POW+1,
39	COS=SIN+1,
40	TAN=SIN+2,
41	ASIN=SIN+3,
42	ACOS=SIN+4,
43	ATAN=SIN+5,
44	SINH=SIN+6,
45	COSH=SIN+7,
46	TANH=SIN+8,
47	ERF=SIN+9,
48	ASINH=SIN+10,
49	ACOSH=SIN+11,
50	ATANH=SIN+12,
51	LOG10=ATANH+1,
52	LOG=LOG10+1,
53	SIGN=LOG10+2,
54	ABS=LOG10+3,
55	NEG=LOG10+4,
56	POS=LOG10+5,
57	EXP=LOG10+6,
58	SQRT=LOG10+7,
59	RECIP=LOG10+8,
60	GZ=RECIP+1,
61	LZ=GZ+1,
62	GEZ=GZ+2,
63	LEZ=GZ+3
64	};
65
66	ESCRIPT_DLL_API
67	const std::string&
68	opToString(ES_optype op);
69
70	/**
71	\class escript::DataLazy
72	\brief Wraps an expression tree of other DataObjects.
73	The data will be evaluated when required.
74
75
76	NOTE: This class assumes that the Data being pointed at are immutable.
77	*/
78
79	class DataLazy;
80
81	typedef POINTER_WRAPPER_CLASS(DataLazy) DataLazy_ptr;
82	typedef POINTER_WRAPPER_CLASS(const DataLazy) const_DataLazy_ptr;
83
84	class DataLazy : public DataAbstract
85	{
86
87	typedef DataAbstract parent;
88	typedef DataTypes::ValueType ValueType;
89	typedef DataTypes::ShapeType ShapeType;
90
91	public:
92	/**
93	\brief Create an IDENTITY DataLazy for the given DataAbstract.
94	\param p DataAbstract to be wrapped.
95	\throws DataException if p is lazy data or it is not constant, tagged or expanded.
96	*/
97	ESCRIPT_DLL_API
98	DataLazy(DataAbstract_ptr p);
99
100
101	/**
102	\brief Produce a DataLazy for a unary operation.
103	\param left DataAbstract to be operated on.
104	\param op unary operation to perform.
105	\throws DataException if op is not a unary operation or if p cannot be converted to a DataLazy.
106	Note that IDENTITY is not considered a unary operation.
107	*/
108	ESCRIPT_DLL_API
109	DataLazy(DataAbstract_ptr left, ES_optype op);
110
111	/**
112	\brief Produce a DataLazy for a binary operation.
113	\param left left operand
114	\param right right operand
115	\param op unary operation to perform.
116	\throws DataException if op is not a binary operation or if left or right cannot be converted to a DataLazy.
117	*/
118	ESCRIPT_DLL_API
119	DataLazy(DataAbstract_ptr left, DataAbstract_ptr right, ES_optype op);
120
121	ESCRIPT_DLL_API
122	~DataLazy();
123
124	/**
125	\brief Evaluate the lazy expression.
126	\return A DataReady with the value of the lazy expresion.
127	*/
128	ESCRIPT_DLL_API
129	DataReady_ptr
130	resolve();
131
132	ESCRIPT_DLL_API
133	std::string
134	toString() const;
135
136	ESCRIPT_DLL_API
137	DataAbstract*
138	deepCopy();
139
140
141	/**
142	\brief
143	Return the number of doubles that would be stored for this Data object if it were resolved.
144	*/
145	ESCRIPT_DLL_API
146	ValueType::size_type
147	getLength() const;
148
149
150	ESCRIPT_DLL_API
151	DataAbstract*
152	getSlice(const DataTypes::RegionType& region) const;
153
154
155	DataTypes::ValueType::size_type
156	getPointOffset(int sampleNo,
157	int dataPointNo) const;
158
159	DataTypes::ValueType::size_type
160	getPointOffset(int sampleNo,
161	int dataPointNo);
162
163
164	/**
165	\return the number of samples which need to be stored to evaluate the expression.
166	*/
167	ESCRIPT_DLL_API
168	int
169	getBuffsRequired() const;
170
171	/**
172	\brief Produces an IDENTITY DataLazy containing zero.
173	The result will have the same shape and functionspace as before.
174	*/
175	ESCRIPT_DLL_API
176	virtual void
177	setToZero();
178
179	private:
180	DataReady_ptr m_id; // For IDENTITY nodes, stores a wrapped value.
181	DataLazy_ptr m_left, m_right; // operands for operation.
182	ES_optype m_op; // operation to perform.
183	size_t m_length; // number of values represented by the operation
184
185	int m_buffsRequired; // how many samples are required to evaluate this expression
186	size_t m_samplesize; // number of values required to store a sample
187
188	char m_readytype; // E for expanded, T for tagged, C for constant
189
190
191	/**
192	Does the work for toString.
193	*/
194	void
195	intoString(std::ostringstream& oss) const;
196
197	/**
198	\brief Converts the DataLazy into an IDENTITY storing the value of the expression.
199	This method uses the original methods on the Data class to evaluate the expressions.
200	For this reason, it should not be used on DataExpanded instances. (To do so would defeat
201	the purpose of using DataLazy in the first place).
202	*/
203	void
204	collapse(); // converts the node into an IDENTITY node
205
206
207	/**
208	\brief Evaluates the expression using methods on Data.
209	This does the work for the collapse method.
210	For reasons of efficiency do not call this method on DataExpanded nodes.
211	*/
212	DataReady_ptr
213	collapseToReady();
214
215	/**
216	\brief Compute the value of the expression for the given sample.
217	\return Vector which stores the value of the subexpression for the given sample.
218	\param v A vector to store intermediate results.
219	\param offset Index in v to begin storing results.
220	\param sampleNo Sample number to evaluate.
221	\param roffset (output parameter) the offset in the return vector where the result begins.
222
223	The return value will be an existing vector so do not deallocate it.
224	*/
225	const ValueType*
226	resolveSample(ValueType& v, size_t offset ,int sampleNo, size_t& roffset);
227
228	/**
229	\brief Compute the value of the expression (binary operation) for the given sample.
230	\return Vector which stores the value of the subexpression for the given sample.
231	\param v A vector to store intermediate results.
232	\param offset Index in v to begin storing results.
233	\param sampleNo Sample number to evaluate.
234	\param roffset (output parameter) the offset in the return vector where the result begins.
235
236	The return value will be an existing vector so do not deallocate it.
237	If the result is stored in v it should be stored at the offset given.
238	Everything from offset to the end of v should be considered available for this method to use.
239	*/
240	ValueType*
241	resolveUnary(ValueType& v, size_t offset,int sampleNo, size_t& roffset) const;
242
243	/**
244	\brief Compute the value of the expression (binary operation) for the given sample.
245	\return Vector which stores the value of the subexpression for the given sample.
246	\param v A vector to store intermediate results.
247	\param offset Index in v to begin storing results.
248	\param sampleNo Sample number to evaluate.
249	\param roffset (output parameter) the offset in the return vector where the result begins.
250
251	The return value will be an existing vector so do not deallocate it.
252	If the result is stored in v it should be stored at the offset given.
253	Everything from offset to the end of v should be considered available for this method to use.
254	*/
255	ValueType*
256	resolveBinary(ValueType& v, size_t offset,int sampleNo, size_t& roffset) const;
257
258	};
259
260	}
261	#endif