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	jfenwick	1865
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	jfenwick	1868	#include <functional>
23	jfenwick	1865
24	jfenwick	1879	#include "LocalOps.h" // for tensor_binary_op
25
26	jfenwick	1865	namespace escript {
27
28	jfenwick	1926	// For the purposes of unit testing and maintaining sanity, it is important that this enum be contiguous
29	jfenwick	1865	enum ES_optype
30			{
31			UNKNOWNOP=0,
32	jfenwick	1868	IDENTITY=1,
33			ADD=2,
34			SUB=3,
35			MUL=4,
36	jfenwick	1886	DIV=5,
37	jfenwick	1910	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	jfenwick	1865	};
65
66	phornby	1992	ESCRIPT_DLL_API
67	jfenwick	1865	const std::string&
68			opToString(ES_optype op);
69
70			/**
71			\class escript::DataLazy
72			\brief Wraps an expression tree of other DataObjects.
73	jfenwick	1903	The data will be evaluated when required.
74	jfenwick	1879
75	jfenwick	1903
76	jfenwick	1879	NOTE: This class assumes that the Data being pointed at are immutable.
77	jfenwick	1865	*/
78
79	jfenwick	1879	class DataLazy;
80
81			typedef POINTER_WRAPPER_CLASS(DataLazy) DataLazy_ptr;
82			typedef POINTER_WRAPPER_CLASS(const DataLazy) const_DataLazy_ptr;
83
84	jfenwick	1865	class DataLazy : public DataAbstract
85			{
86
87			typedef DataAbstract parent;
88			typedef DataTypes::ValueType ValueType;
89			typedef DataTypes::ShapeType ShapeType;
90
91			public:
92	jfenwick	1899	/**
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	jfenwick	1865	ESCRIPT_DLL_API
98			DataLazy(DataAbstract_ptr p);
99
100	jfenwick	1899
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	jfenwick	1865	ESCRIPT_DLL_API
109	jfenwick	1886	DataLazy(DataAbstract_ptr left, ES_optype op);
110
111	jfenwick	1899	/**
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	jfenwick	1886	ESCRIPT_DLL_API
119	jfenwick	1865	DataLazy(DataAbstract_ptr left, DataAbstract_ptr right, ES_optype op);
120
121			ESCRIPT_DLL_API
122			~DataLazy();
123
124			/**
125	jfenwick	1899	\brief Evaluate the lazy expression.
126			\return A DataReady with the value of the lazy expresion.
127	jfenwick	1865	*/
128			ESCRIPT_DLL_API
129	jfenwick	1879	DataReady_ptr
130			resolve();
131	jfenwick	1865
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	jfenwick	1935	DataTypes::ValueType::size_type
160			getPointOffset(int sampleNo,
161			int dataPointNo);
162	jfenwick	1879
163	jfenwick	1935
164	jfenwick	1899	/**
165			\return the number of samples which need to be stored to evaluate the expression.
166			*/
167	jfenwick	1879	ESCRIPT_DLL_API
168			int
169			getBuffsRequired() const;
170
171	jfenwick	1901	/**
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	jfenwick	1889
179	jfenwick	1865	private:
180	jfenwick	1899	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	jfenwick	1879	size_t m_length; // number of values represented by the operation
184
185	jfenwick	1899	int m_buffsRequired; // how many samples are required to evaluate this expression
186	jfenwick	1879	size_t m_samplesize; // number of values required to store a sample
187
188	jfenwick	1899	char m_readytype; // E for expanded, T for tagged, C for constant
189	jfenwick	1879
190	jfenwick	1889
191	jfenwick	1899	/**
192			Does the work for toString.
193			*/
194	jfenwick	1886	void
195			intoString(std::ostringstream& oss) const;
196
197	jfenwick	1899	/**
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	jfenwick	1889	void
204			collapse(); // converts the node into an IDENTITY node
205
206	jfenwick	1899
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	jfenwick	1889	DataReady_ptr
213			collapseToReady();
214
215	jfenwick	1899	/**
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	jfenwick	1889
223	jfenwick	1899	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	jfenwick	1889
228	jfenwick	1899	/**
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	jfenwick	1898	ValueType*
241			resolveUnary(ValueType& v, size_t offset,int sampleNo, size_t& roffset) const;
242	jfenwick	1889
243	jfenwick	1899	/**
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	jfenwick	1898	ValueType*
256			resolveBinary(ValueType& v, size_t offset,int sampleNo, size_t& roffset) const;
257
258	jfenwick	1865	};
259
260			}
261			#endif