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>
#include <boost/python/list.hpp>
#include "paso/Paso_MPI.h"

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;

  /**
        \brief
                  return the number of tags in use and a pointer to an array with the number of tags in use
  */
  ESCRIPT_DLL_API
  virtual int getNumberOfTagsInUse(int functionSpaceCode) const;

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