escript/src/FunctionSpace.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_FunctionSpace_20040323_H
#define escript_FunctionSpace_20040323_H
#include "system_dep.h"

#include "AbstractDomain.h"
#include "NullDomain.h"

#include <string>

#define DEBUG_PY_STRINGS

class FunctionSpaceTestCase;

namespace escript {

//
// Forward declaration for class Data.
class Data;

/**
   \brief
   Give a short description of what FunctionSpace does.

   Description:
   Give a detailed description of FunctionSpace.

   Template Parameters:
   For templates describe any conditions that the parameters used in the
   template must satisfy.
*/

class FunctionSpace {

  // These are using operator=()
  friend class AbstractSystemMatrix;
  friend class AbstractTransportProblem;
  friend class ::FunctionSpaceTestCase;

 public:
  /**
     \brief
     Default constructor for FunctionSpace.

     Description:
     Default constructor for FunctionSpace
     Generates a function space with a null domain.

     Preconditions:
     Describe any preconditions.

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

  /**
     \brief
     Constructor for FunctionSpace.

     Description:
     Constructor for FunctionSpace.

     NOTE: The FunctionSpace class relies on the domain existing
     for the lifetime of the FunctionSpace object. ie: domain must
     be an externally managed object (!).
  */
  ESCRIPT_DLL_API
  FunctionSpace(const AbstractDomain& domain,
                int functionSpaceType);

  /**
    \brief
    Return the function space type code.
  */
  ESCRIPT_DLL_API
  int
  getTypeCode() const;

  /**
   \brief
   Return the function space domain.
  */
  ESCRIPT_DLL_API
  const
  AbstractDomain&
  getDomain() const;


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

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


  /**
   \brief
   Return the shape of the data needed to represent the function space.
  */
  ESCRIPT_DLL_API
  std::pair<int,int>
  getDataShape() const;

  /**
   \brief
   Comparison operator.
   Return true if function spaces are equal.
   ie: Same domain and same function space type.
  */
  ESCRIPT_DLL_API
  bool
  operator==(const FunctionSpace& other) const;

  ESCRIPT_DLL_API
  bool
  operator!=(const FunctionSpace& other) const;

  /**
   \brief
   Return a text description of the function space.
  */
  ESCRIPT_DLL_API
  const std::string &
  toString() const;

#ifdef DEBUG_PY_STRINGS
  /**
   \brief
   Return a text description of the function space
   as a python string.
   NOTE: This code was used to debug a conversion of
   std::string to python string problem on windows. 
   An alternative approach was sought.
  */
  ESCRIPT_DLL_API
  PyObject *
  toPyString() const;
#endif

  /**
   \brief
   Return the tag associated with the given sample number.
  */
  ESCRIPT_DLL_API
  int
  getTagFromSampleNo(int sampleNo) const;

  /**
   \brief
   Return the tag associated with the given data-point number.
  */
  ESCRIPT_DLL_API
  int
  getTagFromDataPointNo(int dataPointNo) const;

  /**
   \brief
   Return the reference number associated with the given sample number.
   This function is not efficient. It is better to first call 
   borrowSampleReferenceIDs and then when iterating over sampleNo to use sampleNo as an offset.
  */
  ESCRIPT_DLL_API
  inline
  int
  getReferenceIDOfSample(int sampleNo) const
  {
      return borrowSampleReferenceIDs()[sampleNo];
  }
  /**
   \brief
   Return a borrowed reference to the list of sample reference IDs
  */
  ESCRIPT_DLL_API
  int*
  borrowSampleReferenceIDs() const;

  /**
   \brief
   Return the spatial locations of the data points.
  */
  ESCRIPT_DLL_API
  escript::Data
  getX() const;
 
  /**
   \brief
   Return the surface normal field.
  */
  ESCRIPT_DLL_API
  escript::Data
  getNormal() const;

  /**
   \brief
   Return the sample size (e.g. the diameter of elements, radius of particles).
  */
  ESCRIPT_DLL_API
  escript::Data
  getSize() const;

  /**
   \brief
   Return the number of samples.
  */
  ESCRIPT_DLL_API
  inline
  int
  getNumSamples() const {
     return getDataShape().second;
  }

  /**
   \brief
   Return the number of data points per sample.
  */
  ESCRIPT_DLL_API
  inline
  int
  getNumDPPSample() const {
     return getNumDataPointsPerSample();
  }

  ESCRIPT_DLL_API
  inline
  int
  getNumDataPointsPerSample() const {
     return getDataShape().first;
  }

  /**
   \brief
   Return the spatial dimension of the underlying domain.
  */
  ESCRIPT_DLL_API
  inline
  int
  getDim() const {
      return getDomain().getDim();
  }

 protected:

 private:
  /**
   \brief
   Assignment operator. 
   NOTE: Assignment copies the domain object pointer
   as this object is managed externally to this class.
   NOTE Also, breaks the non-mutability of FunctionSpace
   assumed by toString(). Allowing this would also have
   unknown effects at the python level, and could
   leave python with an incorrect view of the object.
  */
  // yes, yes I know, but the test case is in another
  // linkage unit external to the dll.
  // This IS supposed to be temporary.
  ESCRIPT_DLL_API
  FunctionSpace&
  operator=(const FunctionSpace& other);

  //
  // static null domain value
  static const NullDomain nullDomainValue;

  //
  // function space domain
  const AbstractDomain*  m_domain;

  //
  // function space type code.
  int m_functionSpaceType;

  //
  // return value of toString.
  // made mutable for lazy initialisation in 1st call to toString.
  // So, this is conceptually immutable, meaning it expects the FunctionSpace
  // object to be immutable.
  mutable std::string type_str;

};

} // end of namespace

#endif
1	jgs	115
2	ksteube	1312	/* $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	jgs	115	#if !defined escript_FunctionSpace_20040323_H
17	jgs	82	#define escript_FunctionSpace_20040323_H
18	woo409	757	#include "system_dep.h"
19	jgs	82
20	jgs	474	#include "AbstractDomain.h"
21			#include "NullDomain.h"
22	jgs	82
23			#include <string>
24
25	trankine	1421	#define DEBUG_PY_STRINGS
26
27			class FunctionSpaceTestCase;
28
29	jgs	82	namespace escript {
30
31	jgs	117	//
32			// Forward declaration for class Data.
33			class Data;
34	jgs	82
35			/**
36			\brief
37			Give a short description of what FunctionSpace does.
38
39			Description:
40	jgs	117	Give a detailed description of FunctionSpace.
41	jgs	82
42			Template Parameters:
43			For templates describe any conditions that the parameters used in the
44	jgs	117	template must satisfy.
45	jgs	82	*/
46
47	trankine	1420	class FunctionSpace {
48	jgs	82
49	trankine	1421	// These are using operator=()
50			friend class AbstractSystemMatrix;
51			friend class AbstractTransportProblem;
52			friend class ::FunctionSpaceTestCase;
53	trankine	1420
54	jgs	82	public:
55			/**
56			\brief
57	jgs	117	Default constructor for FunctionSpace.
58	jgs	82
59			Description:
60			Default constructor for FunctionSpace
61			Generates a function space with a null domain.
62
63			Preconditions:
64	jgs	117	Describe any preconditions.
65	jgs	82
66			Throws:
67	jgs	117	Describe any exceptions thrown.
68	jgs	82	*/
69	trankine	1420	ESCRIPT_DLL_API
70	jgs	82	FunctionSpace();
71
72			/**
73			\brief
74	jgs	117	Constructor for FunctionSpace.
75	jgs	82
76			Description:
77			Constructor for FunctionSpace.
78	jgs	115
79	jgs	82	NOTE: The FunctionSpace class relies on the domain existing
80	jgs	115	for the lifetime of the FunctionSpace object. ie: domain must
81			be an externally managed object (!).
82	jgs	82	*/
83	trankine	1420	ESCRIPT_DLL_API
84	jgs	117	FunctionSpace(const AbstractDomain& domain,
85			int functionSpaceType);
86	jgs	82
87			/**
88			\brief
89			Return the function space type code.
90			*/
91	trankine	1420	ESCRIPT_DLL_API
92	jgs	117	int
93			getTypeCode() const;
94	jgs	82
95			/**
96			\brief
97			Return the function space domain.
98			*/
99	trankine	1420	ESCRIPT_DLL_API
100	jgs	117	const
101			AbstractDomain&
102			getDomain() const;
103	jgs	82
104
105	gross	767
106	jgs	82	/**
107	gross	767	\brief assigns new tag newTag to all samples with a positive
108			value of mask for any its sample point.
109
110			*/
111	trankine	1420	ESCRIPT_DLL_API
112	gross	767	void setTags(const int newTag, const escript::Data& mask) const;
113
114
115			/**
116	jgs	82	\brief
117			Return the shape of the data needed to represent the function space.
118			*/
119	trankine	1420	ESCRIPT_DLL_API
120	jgs	117	std::pair<int,int>
121			getDataShape() const;
122	jgs	82
123			/**
124			\brief
125			Comparison operator.
126			Return true if function spaces are equal.
127			ie: Same domain and same function space type.
128			*/
129	trankine	1420	ESCRIPT_DLL_API
130	jgs	117	bool
131			operator==(const FunctionSpace& other) const;
132	jgs	82
133	trankine	1420	ESCRIPT_DLL_API
134	jgs	117	bool
135			operator!=(const FunctionSpace& other) const;
136
137	jgs	82	/**
138			\brief
139	jgs	115	Return a text description of the function space.
140	jgs	82	*/
141	trankine	1420	ESCRIPT_DLL_API
142			const std::string &
143	jgs	117	toString() const;
144	ksteube	1312
145	trankine	1421	#ifdef DEBUG_PY_STRINGS
146	jgs	82	/**
147			\brief
148	trankine	1420	Return a text description of the function space
149			as a python string.
150			NOTE: This code was used to debug a conversion of
151			std::string to python string problem on windows.
152			An alternative approach was sought.
153			*/
154			ESCRIPT_DLL_API
155			PyObject *
156			toPyString() const;
157			#endif
158
159			/**
160			\brief
161	jgs	82	Return the tag associated with the given sample number.
162			*/
163	trankine	1420	ESCRIPT_DLL_API
164	jgs	117	int
165			getTagFromSampleNo(int sampleNo) const;
166	jgs	115
167	jgs	110	/**
168			\brief
169	jgs	149	Return the tag associated with the given data-point number.
170	jgs	110	*/
171	trankine	1420	ESCRIPT_DLL_API
172	jgs	117	int
173	jgs	149	getTagFromDataPointNo(int dataPointNo) const;
174
175			/**
176			\brief
177			Return the reference number associated with the given sample number.
178	gross	964	This function is not efficient. It is better to first call
179			borrowSampleReferenceIDs and then when iterating over sampleNo to use sampleNo as an offset.
180	jgs	149	*/
181	trankine	1420	ESCRIPT_DLL_API
182	gross	964	inline
183	jgs	149	int
184	gross	964	getReferenceIDOfSample(int sampleNo) const
185			{
186			return borrowSampleReferenceIDs()[sampleNo];
187			}
188			/**
189			\brief
190			Return a borrowed reference to the list of sample reference IDs
191			*/
192	trankine	1420	ESCRIPT_DLL_API
193	gross	964	int*
194			borrowSampleReferenceIDs() const;
195	jgs	82
196			/**
197			\brief
198	jgs	149	Return the spatial locations of the data points.
199	jgs	82	*/
200	trankine	1420	ESCRIPT_DLL_API
201	jgs	117	escript::Data
202			getX() const;
203	jgs	149
204	jgs	82	/**
205			\brief
206			Return the surface normal field.
207			*/
208	trankine	1420	ESCRIPT_DLL_API
209	jgs	117	escript::Data
210			getNormal() const;
211	jgs	82
212			/**
213			\brief
214			Return the sample size (e.g. the diameter of elements, radius of particles).
215			*/
216	trankine	1420	ESCRIPT_DLL_API
217	jgs	117	escript::Data
218			getSize() const;
219	jgs	82
220			/**
221			\brief
222	jgs	115	Return the number of samples.
223	jgs	82	*/
224	trankine	1420	ESCRIPT_DLL_API
225	jgs	117	inline
226			int
227			getNumSamples() const {
228	jgs	82	return getDataShape().second;
229			}
230
231			/**
232			\brief
233			Return the number of data points per sample.
234			*/
235	trankine	1420	ESCRIPT_DLL_API
236	jgs	117	inline
237			int
238			getNumDPPSample() const {
239	jgs	82	return getNumDataPointsPerSample();
240			}
241	jgs	149
242	trankine	1420	ESCRIPT_DLL_API
243	jgs	117	inline
244			int
245			getNumDataPointsPerSample() const {
246	jgs	82	return getDataShape().first;
247			}
248
249			/**
250			\brief
251			Return the spatial dimension of the underlying domain.
252			*/
253	trankine	1420	ESCRIPT_DLL_API
254	jgs	117	inline
255			int
256			getDim() const {
257	jgs	82	return getDomain().getDim();
258			}
259	jgs	115
260	jgs	82	protected:
261
262			private:
263	trankine	1420	/**
264			\brief
265			Assignment operator.
266			NOTE: Assignment copies the domain object pointer
267			as this object is managed externally to this class.
268			NOTE Also, breaks the non-mutability of FunctionSpace
269			assumed by toString(). Allowing this would also have
270			unknown effects at the python level, and could
271			leave python with an incorrect view of the object.
272			*/
273	trankine	1421	// yes, yes I know, but the test case is in another
274			// linkage unit external to the dll.
275			// This IS supposed to be temporary.
276			ESCRIPT_DLL_API
277	trankine	1420	FunctionSpace&
278			operator=(const FunctionSpace& other);
279	jgs	82
280			//
281			// static null domain value
282	trankine	1420	static const NullDomain nullDomainValue;
283	jgs	82
284			//
285			// function space domain
286			const AbstractDomain* m_domain;
287	jgs	149
288	jgs	82	//
289			// function space type code.
290			int m_functionSpaceType;
291
292	trankine	1420	//
293			// return value of toString.
294			// made mutable for lazy initialisation in 1st call to toString.
295			// So, this is conceptually immutable, meaning it expects the FunctionSpace
296			// object to be immutable.
297			mutable std::string type_str;
298
299	jgs	82	};
300
301			} // end of namespace
302	jgs	117
303	jgs	82	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision