escript/src/AbstractDomain.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_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"


#include "Pointers.h"

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

   Description:
   Base class for all escript domains.
*/

class AbstractDomain;

typedef POINTER_WRAPPER_CLASS(AbstractDomain) Domain_ptr;
typedef POINTER_WRAPPER_CLASS(const AbstractDomain) const_Domain_ptr;

class AbstractDomain : public REFCOUNT_BASE_CLASS(AbstractDomain){

 public:

/**
\brief Returns smart pointer which is managing this object.
If one does not exist yet it creates one.

Note: This is _not_ equivalent to weak_ptr::lock.
*/
   ESCRIPT_DLL_API
   Domain_ptr getPtr();
   ESCRIPT_DLL_API
   const_Domain_ptr getPtr() const; 

   // 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
     If compiled for MPI then execute an MPI_Barrier, else do nothing
  */

  ESCRIPT_DLL_API
  virtual void MPIBarrier() const;
  /**
     \brief
     Return true if on MPI master, else false
  */

  ESCRIPT_DLL_API
  virtual bool onMasterProcessor() 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;

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