escript/src/AbstractDomain.h


/* $Id$ */

/*******************************************************
 *
 *           Copyright 2003-2007 by ACceSS MNRF
 *       Copyright 2007 by University of Queensland
 *
 *                http://esscc.uq.edu.au
 *        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_AbstractDomain_20040609_H
#define escript_AbstractDomain_20040609_H

#include "system_dep.h"

#include <string>
#include <map>
#include <boost/python/dict.hpp>

namespace escript {
// class forward declarations
class Data;
/**
   \brief
   Base class for all escript domains.

   Description:
   Base class for all escript domains.
*/

class AbstractDomain {

 public:


   // structure holding values for X, size and normal
   typedef int StatusType;
   struct ValueBuffer
   {
       StatusType m_status;
       boost::shared_ptr<Data> m_data;
   };
   typedef struct ValueBuffer ValueBuffer;

   // 
   // map from function space type code to value buffer
   typedef std::map<int, ValueBuffer> BufferMapType;


  /**
     \brief
     Default constructor for AbstractDomain.

     Description:
     Default constructor for AbstractDomain. As the name suggests
     this is intended to be an abstract base class but by making it
     constructable we avoid a boost.python wrapper class. A call to 
     almost any of the base class functions will throw an exception
     as they are not intended to be used directly, but are overridden
     by the underlying solver package which escript is linked to.

     By default, this class is overridden by the class NullDomain.

     Preconditions:
     Describe any preconditions.

     Throws:
     Describe any exceptions thrown.
  */
  ESCRIPT_DLL_API
  AbstractDomain();

  /**
     \brief
     Destructor for AbstractDomain.

     Description:
     Destructor for AbstractDomain.
  */
  ESCRIPT_DLL_API
  virtual ~AbstractDomain();

  /**
     \brief
     return the number of processors used for this domain
  */
  ESCRIPT_DLL_API
  virtual int getMPISize() const;
  /**
     \brief
     return the number MPI rank of this processor
  */

  ESCRIPT_DLL_API
  virtual int getMPIRank() const;


  /**
     \brief
     Returns true if the given integer is a valid function space type
     for this domain.
  */
  ESCRIPT_DLL_API
  virtual bool isValidFunctionSpaceType(int functionSpaceType) const;

  /**
     \brief
     Return a description for this domain.
  */
  ESCRIPT_DLL_API
  virtual std::string getDescription() const;

  /**
     \brief
     Return a description for the given function space type code.
  */
  ESCRIPT_DLL_API
  virtual std::string functionSpaceTypeAsString(int functionSpaceType) const;

  /**
     \brief
      Returns the spatial dimension of the domain.

      This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual int getDim() const;

  /**
     \brief
     Return true if given domains are equal.
  */
  ESCRIPT_DLL_API
  virtual bool operator==(const AbstractDomain& other) const;
  ESCRIPT_DLL_API
  virtual bool operator!=(const AbstractDomain& other) const;

  /**
     \brief
     Writes the domain to an external file filename.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void write(const std::string& filename) const;

  /**
     \brief
     dumps the domain to an external file filename.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void dump(const std::string& filename) const;

  /**
     \brief
     Return the number of data points per sample, and the number of samples as a pair.

     This has to be implemented by the actual Domain adapter.

     \param functionSpaceCode Input - Code for the function space type.
     \return pair, first - number of data points per sample, second - number of samples
  */
  ESCRIPT_DLL_API
  virtual std::pair<int,int> getDataShape(int functionSpaceCode) const;

  /**
     \brief
     Return the tag key for the given sample number.
     \param functionSpaceType Input - The function space type.
     \param sampleNo Input - The sample number.
  */
  ESCRIPT_DLL_API
  virtual int getTagFromSampleNo(int functionSpaceType, int sampleNo) const;

  /**
     \brief
     sets a map from a clear tag name to a tag key
     \param name Input - tag name.
     \param tag Input - tag key.
  */
  ESCRIPT_DLL_API
  virtual void setTagMap(const std::string& name,  int tag);

  /**
     \brief
     Return the tag key for tag name.
     \param name Input - tag name
  */
  ESCRIPT_DLL_API
  virtual int getTag(const std::string& name) const;

  /**
     \brief
     Returns True if name is a defined tag name
     \param name Input - tag name
  */
  ESCRIPT_DLL_API
  virtual bool isValidTagName(const std::string& name) const;

  /**
     \brief
     Returns all tag names in a single string sperated by commas
  */
  ESCRIPT_DLL_API
  virtual std::string showTagNames() const;

  /**
     \brief
     Return a borrowed pointer to the sample reference number id list
     \param functionSpaceType Input - The function space type.
  */
  ESCRIPT_DLL_API
  virtual int* borrowSampleReferenceIDs(int functionSpaceType) const;

  /**
     \brief
     Assigns new location to the domain.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void setNewX(const escript::Data& arg);

  /**
     \brief
     Interpolates data given on source onto target where source and target have to be given on the same domain.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void interpolateOnDomain(escript::Data& target,const escript::Data& source) const;
  ESCRIPT_DLL_API
  virtual bool probeInterpolationOnDomain(int functionSpaceType_source,int functionSpaceType_target) const;

  /**
     \brief
     Interpolates data given on source onto target where source and target are given on different domains.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void interpolateACross(escript::Data& target, const escript::Data& source) const;
  ESCRIPT_DLL_API
  virtual bool probeInterpolationACross(int functionSpaceType_source,const AbstractDomain& targetDomain, int functionSpaceType_target) const;

  /**
     \brief
     Returns locations in the domain. The function space is chosen appropriately.
  */
  ESCRIPT_DLL_API
  virtual escript::Data getX() const;

  /**
     \brief
     Return boundary normals. The function space is chosen appropriately.
  */
  ESCRIPT_DLL_API
  virtual escript::Data getNormal() const;

  /**
     \brief
     Returns the local size of samples. The function space is chosen appropriately.
  */
  ESCRIPT_DLL_API
  virtual escript::Data getSize() const;
  
  /**
     \brief
     Copies the location of data points on the domain into out.
     The actual function space to be considered
     is defined by out. out has to be defined on this.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void setToX(escript::Data& out) const;

  /**
     \brief
     Copies the surface normals at data points into out.
     The actual function space to be considered
     is defined by out. out has to be defined on this.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void setToNormal(escript::Data& out) const;

  /**
     \brief
     Copies the size of samples into out. The actual
     function space to be considered
     is defined by out. out has to be defined on this.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void setToSize(escript::Data& out) const;

  /**
     \brief
     Copies the gradient of arg into grad. The actual function space to be considered
     for the gradient is defined by grad. arg and grad have to be defined on this.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void setToGradient(escript::Data& grad, const escript::Data& arg) const;
  /**
     \brief
     Saves a dictonary of Data objects to an OpenDX input file. The keywords are used as identifier

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void saveDX(const std::string& filename,const boost::python::dict& arg) const;

  /**
     \brief
     Saves a dictonary of Data objects to an VTK XML input file. The keywords are used as identifier

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual void saveVTK(const std::string& filename,const boost::python::dict& arg) const;

  /**
     \brief
     returns the function space representation of the type functionSpaceCode on this domain
     as a vtkObject.

     This has to be implemented by the actual Domain adapter.
  */
  //virtual vtkObject createVtkObject(int functionSpaceCode) const;

  /**
     \brief assigns new tag newTag to all samples of functionspace with a positive
     value of mask for any its sample point.

  */
  ESCRIPT_DLL_API
  virtual void setTags(const int functionSpaceType, const int newTag, const escript::Data& mask) const;

  /**
     \brief
     returns true if data on this domain and a function space of type functionSpaceCode has to
     considered as cell centered data.

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual bool isCellOriented(int functionSpaceCode) const;

  /**
     \brief
     returns status of the domain. 

     This has to be implemented by the actual Domain adapter.
  */
  ESCRIPT_DLL_API
  virtual StatusType getStatus() const;

  /**
     \brief
     Throw a standard exception. This function is called if any attempt 
     is made to use a base class function.
  */
  ESCRIPT_DLL_API
  void throwStandardException(const std::string& functionName) const;

 protected:

 private:

   // buffer for coordinates used by function spaces
   BufferMapType m_x_buffer;

   // buffer for normal vectors used by function spaces
   BufferMapType m_normal_buffer;

   // buffer for normal element size used by function spaces
   BufferMapType m_size_buffer;

};

} // end of namespace

#endif
1
2	/* $Id$ */
3
4	/*******************************************************
5	*
6	* Copyright 2003-2007 by ACceSS MNRF
7	* Copyright 2007 by University of Queensland
8	*
9	* http://esscc.uq.edu.au
10	* Primary Business: Queensland, Australia
11	* Licensed under the Open Software License version 3.0
12	* http://www.opensource.org/licenses/osl-3.0.php
13	*
14	*******************************************************/
15
16	#if !defined escript_AbstractDomain_20040609_H
17	#define escript_AbstractDomain_20040609_H
18
19	#include "system_dep.h"
20
21	#include <string>
22	#include <map>
23	#include <boost/python/dict.hpp>
24
25	namespace escript {
26	// class forward declarations
27	class Data;
28	/**
29	\brief
30	Base class for all escript domains.
31
32	Description:
33	Base class for all escript domains.
34	*/
35
36	class AbstractDomain {
37
38	public:
39
40
41	// structure holding values for X, size and normal
42	typedef int StatusType;
43	struct ValueBuffer
44	{
45	StatusType m_status;
46	boost::shared_ptr<Data> m_data;
47	};
48	typedef struct ValueBuffer ValueBuffer;
49
50	//
51	// map from function space type code to value buffer
52	typedef std::map<int, ValueBuffer> BufferMapType;
53
54
55	/**
56	\brief
57	Default constructor for AbstractDomain.
58
59	Description:
60	Default constructor for AbstractDomain. As the name suggests
61	this is intended to be an abstract base class but by making it
62	constructable we avoid a boost.python wrapper class. A call to
63	almost any of the base class functions will throw an exception
64	as they are not intended to be used directly, but are overridden
65	by the underlying solver package which escript is linked to.
66
67	By default, this class is overridden by the class NullDomain.
68
69	Preconditions:
70	Describe any preconditions.
71
72	Throws:
73	Describe any exceptions thrown.
74	*/
75	ESCRIPT_DLL_API
76	AbstractDomain();
77
78	/**
79	\brief
80	Destructor for AbstractDomain.
81
82	Description:
83	Destructor for AbstractDomain.
84	*/
85	ESCRIPT_DLL_API
86	virtual ~AbstractDomain();
87
88	/**
89	\brief
90	return the number of processors used for this domain
91	*/
92	ESCRIPT_DLL_API
93	virtual int getMPISize() const;
94	/**
95	\brief
96	return the number MPI rank of this processor
97	*/
98
99	ESCRIPT_DLL_API
100	virtual int getMPIRank() const;
101
102
103
104	/**
105	\brief
106	Returns true if the given integer is a valid function space type
107	for this domain.
108	*/
109	ESCRIPT_DLL_API
110	virtual bool isValidFunctionSpaceType(int functionSpaceType) const;
111
112	/**
113	\brief
114	Return a description for this domain.
115	*/
116	ESCRIPT_DLL_API
117	virtual std::string getDescription() const;
118
119	/**
120	\brief
121	Return a description for the given function space type code.
122	*/
123	ESCRIPT_DLL_API
124	virtual std::string functionSpaceTypeAsString(int functionSpaceType) const;
125
126	/**
127	\brief
128	Returns the spatial dimension of the domain.
129
130	This has to be implemented by the actual Domain adapter.
131	*/
132	ESCRIPT_DLL_API
133	virtual int getDim() const;
134
135	/**
136	\brief
137	Return true if given domains are equal.
138	*/
139	ESCRIPT_DLL_API
140	virtual bool operator==(const AbstractDomain& other) const;
141	ESCRIPT_DLL_API
142	virtual bool operator!=(const AbstractDomain& other) const;
143
144	/**
145	\brief
146	Writes the domain to an external file filename.
147
148	This has to be implemented by the actual Domain adapter.
149	*/
150	ESCRIPT_DLL_API
151	virtual void write(const std::string& filename) const;
152
153	/**
154	\brief
155	dumps the domain to an external file filename.
156
157	This has to be implemented by the actual Domain adapter.
158	*/
159	ESCRIPT_DLL_API
160	virtual void dump(const std::string& filename) const;
161
162	/**
163	\brief
164	Return the number of data points per sample, and the number of samples as a pair.
165
166	This has to be implemented by the actual Domain adapter.
167
168	\param functionSpaceCode Input - Code for the function space type.
169	\return pair, first - number of data points per sample, second - number of samples
170	*/
171	ESCRIPT_DLL_API
172	virtual std::pair<int,int> getDataShape(int functionSpaceCode) const;
173
174	/**
175	\brief
176	Return the tag key for the given sample number.
177	\param functionSpaceType Input - The function space type.
178	\param sampleNo Input - The sample number.
179	*/
180	ESCRIPT_DLL_API
181	virtual int getTagFromSampleNo(int functionSpaceType, int sampleNo) const;
182
183	/**
184	\brief
185	sets a map from a clear tag name to a tag key
186	\param name Input - tag name.
187	\param tag Input - tag key.
188	*/
189	ESCRIPT_DLL_API
190	virtual void setTagMap(const std::string& name, int tag);
191
192	/**
193	\brief
194	Return the tag key for tag name.
195	\param name Input - tag name
196	*/
197	ESCRIPT_DLL_API
198	virtual int getTag(const std::string& name) const;
199
200	/**
201	\brief
202	Returns True if name is a defined tag name
203	\param name Input - tag name
204	*/
205	ESCRIPT_DLL_API
206	virtual bool isValidTagName(const std::string& name) const;
207
208	/**
209	\brief
210	Returns all tag names in a single string sperated by commas
211	*/
212	ESCRIPT_DLL_API
213	virtual std::string showTagNames() const;
214
215	/**
216	\brief
217	Return a borrowed pointer to the sample reference number id list
218	\param functionSpaceType Input - The function space type.
219	*/
220	ESCRIPT_DLL_API
221	virtual int* borrowSampleReferenceIDs(int functionSpaceType) const;
222
223	/**
224	\brief
225	Assigns new location to the domain.
226
227	This has to be implemented by the actual Domain adapter.
228	*/
229	ESCRIPT_DLL_API
230	virtual void setNewX(const escript::Data& arg);
231
232	/**
233	\brief
234	Interpolates data given on source onto target where source and target have to be given on the same domain.
235
236	This has to be implemented by the actual Domain adapter.
237	*/
238	ESCRIPT_DLL_API
239	virtual void interpolateOnDomain(escript::Data& target,const escript::Data& source) const;
240	ESCRIPT_DLL_API
241	virtual bool probeInterpolationOnDomain(int functionSpaceType_source,int functionSpaceType_target) const;
242
243	/**
244	\brief
245	Interpolates data given on source onto target where source and target are given on different domains.
246
247	This has to be implemented by the actual Domain adapter.
248	*/
249	ESCRIPT_DLL_API
250	virtual void interpolateACross(escript::Data& target, const escript::Data& source) const;
251	ESCRIPT_DLL_API
252	virtual bool probeInterpolationACross(int functionSpaceType_source,const AbstractDomain& targetDomain, int functionSpaceType_target) const;
253
254	/**
255	\brief
256	Returns locations in the domain. The function space is chosen appropriately.
257	*/
258	ESCRIPT_DLL_API
259	virtual escript::Data getX() const;
260
261	/**
262	\brief
263	Return boundary normals. The function space is chosen appropriately.
264	*/
265	ESCRIPT_DLL_API
266	virtual escript::Data getNormal() const;
267
268	/**
269	\brief
270	Returns the local size of samples. The function space is chosen appropriately.
271	*/
272	ESCRIPT_DLL_API
273	virtual escript::Data getSize() const;
274
275	/**
276	\brief
277	Copies the location of data points on the domain into out.
278	The actual function space to be considered
279	is defined by out. out has to be defined on this.
280
281	This has to be implemented by the actual Domain adapter.
282	*/
283	ESCRIPT_DLL_API
284	virtual void setToX(escript::Data& out) const;
285
286	/**
287	\brief
288	Copies the surface normals at data points into out.
289	The actual function space to be considered
290	is defined by out. out has to be defined on this.
291
292	This has to be implemented by the actual Domain adapter.
293	*/
294	ESCRIPT_DLL_API
295	virtual void setToNormal(escript::Data& out) const;
296
297	/**
298	\brief
299	Copies the size of samples into out. The actual
300	function space to be considered
301	is defined by out. out has to be defined on this.
302
303	This has to be implemented by the actual Domain adapter.
304	*/
305	ESCRIPT_DLL_API
306	virtual void setToSize(escript::Data& out) const;
307
308	/**
309	\brief
310	Copies the gradient of arg into grad. The actual function space to be considered
311	for the gradient is defined by grad. arg and grad have to be defined on this.
312
313	This has to be implemented by the actual Domain adapter.
314	*/
315	ESCRIPT_DLL_API
316	virtual void setToGradient(escript::Data& grad, const escript::Data& arg) const;
317	/**
318	\brief
319	Saves a dictonary of Data objects to an OpenDX input file. The keywords are used as identifier
320
321	This has to be implemented by the actual Domain adapter.
322	*/
323	ESCRIPT_DLL_API
324	virtual void saveDX(const std::string& filename,const boost::python::dict& arg) const;
325
326	/**
327	\brief
328	Saves a dictonary of Data objects to an VTK XML input file. The keywords are used as identifier
329
330	This has to be implemented by the actual Domain adapter.
331	*/
332	ESCRIPT_DLL_API
333	virtual void saveVTK(const std::string& filename,const boost::python::dict& arg) const;
334
335	/**
336	\brief
337	returns the function space representation of the type functionSpaceCode on this domain
338	as a vtkObject.
339
340	This has to be implemented by the actual Domain adapter.
341	*/
342	//virtual vtkObject createVtkObject(int functionSpaceCode) const;
343
344	/**
345	\brief assigns new tag newTag to all samples of functionspace with a positive
346	value of mask for any its sample point.
347
348	*/
349	ESCRIPT_DLL_API
350	virtual void setTags(const int functionSpaceType, const int newTag, const escript::Data& mask) const;
351
352	/**
353	\brief
354	returns true if data on this domain and a function space of type functionSpaceCode has to
355	considered as cell centered data.
356
357	This has to be implemented by the actual Domain adapter.
358	*/
359	ESCRIPT_DLL_API
360	virtual bool isCellOriented(int functionSpaceCode) const;
361
362	/**
363	\brief
364	returns status of the domain.
365
366	This has to be implemented by the actual Domain adapter.
367	*/
368	ESCRIPT_DLL_API
369	virtual StatusType getStatus() const;
370
371	/**
372	\brief
373	Throw a standard exception. This function is called if any attempt
374	is made to use a base class function.
375	*/
376	ESCRIPT_DLL_API
377	void throwStandardException(const std::string& functionName) const;
378
379	protected:
380
381	private:
382
383	// buffer for coordinates used by function spaces
384	BufferMapType m_x_buffer;
385
386	// buffer for normal vectors used by function spaces
387	BufferMapType m_normal_buffer;
388
389	// buffer for normal element size used by function spaces
390	BufferMapType m_size_buffer;
391
392	};
393
394	} // end of namespace
395
396	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision