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
};

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;


  /**
    \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	const std::string&
67	opToString(ES_optype op);
68
69	/**
70	\class escript::DataLazy
71	\brief Wraps an expression tree of other DataObjects.
72	The data will be evaluated when required.
73
74
75	NOTE: This class assumes that the Data being pointed at are immutable.
76	*/
77
78	class DataLazy;
79
80	typedef POINTER_WRAPPER_CLASS(DataLazy) DataLazy_ptr;
81	typedef POINTER_WRAPPER_CLASS(const DataLazy) const_DataLazy_ptr;
82
83	class DataLazy : public DataAbstract
84	{
85
86	typedef DataAbstract parent;
87	typedef DataTypes::ValueType ValueType;
88	typedef DataTypes::ShapeType ShapeType;
89
90	public:
91	/**
92	\brief Create an IDENTITY DataLazy for the given DataAbstract.
93	\param p DataAbstract to be wrapped.
94	\throws DataException if p is lazy data or it is not constant, tagged or expanded.
95	*/
96	ESCRIPT_DLL_API
97	DataLazy(DataAbstract_ptr p);
98
99
100	/**
101	\brief Produce a DataLazy for a unary operation.
102	\param left DataAbstract to be operated on.
103	\param op unary operation to perform.
104	\throws DataException if op is not a unary operation or if p cannot be converted to a DataLazy.
105	Note that IDENTITY is not considered a unary operation.
106	*/
107	ESCRIPT_DLL_API
108	DataLazy(DataAbstract_ptr left, ES_optype op);
109
110	/**
111	\brief Produce a DataLazy for a binary operation.
112	\param left left operand
113	\param right right operand
114	\param op unary operation to perform.
115	\throws DataException if op is not a binary operation or if left or right cannot be converted to a DataLazy.
116	*/
117	ESCRIPT_DLL_API
118	DataLazy(DataAbstract_ptr left, DataAbstract_ptr right, ES_optype op);
119
120	ESCRIPT_DLL_API
121	~DataLazy();
122
123	/**
124	\brief Evaluate the lazy expression.
125	\return A DataReady with the value of the lazy expresion.
126	*/
127	ESCRIPT_DLL_API
128	DataReady_ptr
129	resolve();
130
131	ESCRIPT_DLL_API
132	std::string
133	toString() const;
134
135	ESCRIPT_DLL_API
136	DataAbstract*
137	deepCopy();
138
139
140	/**
141	\brief
142	Return the number of doubles that would be stored for this Data object if it were resolved.
143	*/
144	ESCRIPT_DLL_API
145	ValueType::size_type
146	getLength() const;
147
148
149	ESCRIPT_DLL_API
150	DataAbstract*
151	getSlice(const DataTypes::RegionType& region) const;
152
153
154	DataTypes::ValueType::size_type
155	getPointOffset(int sampleNo,
156	int dataPointNo) const;
157
158
159	/**
160	\return the number of samples which need to be stored to evaluate the expression.
161	*/
162	ESCRIPT_DLL_API
163	int
164	getBuffsRequired() const;
165
166	/**
167	\brief Produces an IDENTITY DataLazy containing zero.
168	The result will have the same shape and functionspace as before.
169	*/
170	ESCRIPT_DLL_API
171	virtual void
172	setToZero();
173
174	private:
175	DataReady_ptr m_id; // For IDENTITY nodes, stores a wrapped value.
176	DataLazy_ptr m_left, m_right; // operands for operation.
177	ES_optype m_op; // operation to perform.
178	size_t m_length; // number of values represented by the operation
179
180	int m_buffsRequired; // how many samples are required to evaluate this expression
181	size_t m_samplesize; // number of values required to store a sample
182
183	char m_readytype; // E for expanded, T for tagged, C for constant
184
185
186	/**
187	Does the work for toString.
188	*/
189	void
190	intoString(std::ostringstream& oss) const;
191
192	/**
193	\brief Converts the DataLazy into an IDENTITY storing the value of the expression.
194	This method uses the original methods on the Data class to evaluate the expressions.
195	For this reason, it should not be used on DataExpanded instances. (To do so would defeat
196	the purpose of using DataLazy in the first place).
197	*/
198	void
199	collapse(); // converts the node into an IDENTITY node
200
201
202	/**
203	\brief Evaluates the expression using methods on Data.
204	This does the work for the collapse method.
205	For reasons of efficiency do not call this method on DataExpanded nodes.
206	*/
207	DataReady_ptr
208	collapseToReady();
209
210	/**
211	\brief Compute the value of the expression for the given sample.
212	\return Vector which stores the value of the subexpression for the given sample.
213	\param v A vector to store intermediate results.
214	\param offset Index in v to begin storing results.
215	\param sampleNo Sample number to evaluate.
216	\param roffset (output parameter) the offset in the return vector where the result begins.
217
218	The return value will be an existing vector so do not deallocate it.
219	*/
220	const ValueType*
221	resolveSample(ValueType& v, size_t offset ,int sampleNo, size_t& roffset);
222
223	/**
224	\brief Compute the value of the expression (binary operation) for the given sample.
225	\return Vector which stores the value of the subexpression for the given sample.
226	\param v A vector to store intermediate results.
227	\param offset Index in v to begin storing results.
228	\param sampleNo Sample number to evaluate.
229	\param roffset (output parameter) the offset in the return vector where the result begins.
230
231	The return value will be an existing vector so do not deallocate it.
232	If the result is stored in v it should be stored at the offset given.
233	Everything from offset to the end of v should be considered available for this method to use.
234	*/
235	ValueType*
236	resolveUnary(ValueType& v, size_t offset,int sampleNo, size_t& roffset) const;
237
238	/**
239	\brief Compute the value of the expression (binary operation) for the given sample.
240	\return Vector which stores the value of the subexpression for the given sample.
241	\param v A vector to store intermediate results.
242	\param offset Index in v to begin storing results.
243	\param sampleNo Sample number to evaluate.
244	\param roffset (output parameter) the offset in the return vector where the result begins.
245
246	The return value will be an existing vector so do not deallocate it.
247	If the result is stored in v it should be stored at the offset given.
248	Everything from offset to the end of v should be considered available for this method to use.
249	*/
250	ValueType*
251	resolveBinary(ValueType& v, size_t offset,int sampleNo, size_t& roffset) const;
252
253	};
254
255	}
256	#endif