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>

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;

   //#define DEBUG_PY_STRINGS

#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
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_FunctionSpace_20040323_H
17	#define escript_FunctionSpace_20040323_H
18	#include "system_dep.h"
19
20	#include "AbstractDomain.h"
21	#include "NullDomain.h"
22
23	#include <string>
24
25	class FunctionSpaceTestCase;
26
27	namespace escript {
28
29	//
30	// Forward declaration for class Data.
31	class Data;
32
33	/**
34	\brief
35	Give a short description of what FunctionSpace does.
36
37	Description:
38	Give a detailed description of FunctionSpace.
39
40	Template Parameters:
41	For templates describe any conditions that the parameters used in the
42	template must satisfy.
43	*/
44
45	class FunctionSpace {
46
47	// These are using operator=()
48	friend class AbstractSystemMatrix;
49	friend class AbstractTransportProblem;
50	friend class ::FunctionSpaceTestCase;
51
52	public:
53	/**
54	\brief
55	Default constructor for FunctionSpace.
56
57	Description:
58	Default constructor for FunctionSpace
59	Generates a function space with a null domain.
60
61	Preconditions:
62	Describe any preconditions.
63
64	Throws:
65	Describe any exceptions thrown.
66	*/
67	ESCRIPT_DLL_API
68	FunctionSpace();
69
70	/**
71	\brief
72	Constructor for FunctionSpace.
73
74	Description:
75	Constructor for FunctionSpace.
76
77	NOTE: The FunctionSpace class relies on the domain existing
78	for the lifetime of the FunctionSpace object. ie: domain must
79	be an externally managed object (!).
80	*/
81	ESCRIPT_DLL_API
82	FunctionSpace(const AbstractDomain& domain,
83	int functionSpaceType);
84
85	/**
86	\brief
87	Return the function space type code.
88	*/
89	ESCRIPT_DLL_API
90	int
91	getTypeCode() const;
92
93	/**
94	\brief
95	Return the function space domain.
96	*/
97	ESCRIPT_DLL_API
98	const
99	AbstractDomain&
100	getDomain() const;
101
102
103
104	/**
105	\brief assigns new tag newTag to all samples with a positive
106	value of mask for any its sample point.
107
108	*/
109	ESCRIPT_DLL_API
110	void setTags(const int newTag, const escript::Data& mask) const;
111
112
113	/**
114	\brief
115	Return the shape of the data needed to represent the function space.
116	*/
117	ESCRIPT_DLL_API
118	std::pair<int,int>
119	getDataShape() const;
120
121	/**
122	\brief
123	Comparison operator.
124	Return true if function spaces are equal.
125	ie: Same domain and same function space type.
126	*/
127	ESCRIPT_DLL_API
128	bool
129	operator==(const FunctionSpace& other) const;
130
131	ESCRIPT_DLL_API
132	bool
133	operator!=(const FunctionSpace& other) const;
134
135	/**
136	\brief
137	Return a text description of the function space.
138	*/
139	ESCRIPT_DLL_API
140	const std::string &
141	toString() const;
142
143	//#define DEBUG_PY_STRINGS
144
145	#ifdef DEBUG_PY_STRINGS
146	/**
147	\brief
148	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	Return the tag associated with the given sample number.
162	*/
163	ESCRIPT_DLL_API
164	int
165	getTagFromSampleNo(int sampleNo) const;
166
167	/**
168	\brief
169	Return the tag associated with the given data-point number.
170	*/
171	ESCRIPT_DLL_API
172	int
173	getTagFromDataPointNo(int dataPointNo) const;
174
175	/**
176	\brief
177	Return the reference number associated with the given sample number.
178	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	*/
181	ESCRIPT_DLL_API
182	inline
183	int
184	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	ESCRIPT_DLL_API
193	int*
194	borrowSampleReferenceIDs() const;
195
196	/**
197	\brief
198	Return the spatial locations of the data points.
199	*/
200	ESCRIPT_DLL_API
201	escript::Data
202	getX() const;
203
204	/**
205	\brief
206	Return the surface normal field.
207	*/
208	ESCRIPT_DLL_API
209	escript::Data
210	getNormal() const;
211
212	/**
213	\brief
214	Return the sample size (e.g. the diameter of elements, radius of particles).
215	*/
216	ESCRIPT_DLL_API
217	escript::Data
218	getSize() const;
219
220	/**
221	\brief
222	Return the number of samples.
223	*/
224	ESCRIPT_DLL_API
225	inline
226	int
227	getNumSamples() const {
228	return getDataShape().second;
229	}
230
231	/**
232	\brief
233	Return the number of data points per sample.
234	*/
235	ESCRIPT_DLL_API
236	inline
237	int
238	getNumDPPSample() const {
239	return getNumDataPointsPerSample();
240	}
241
242	ESCRIPT_DLL_API
243	inline
244	int
245	getNumDataPointsPerSample() const {
246	return getDataShape().first;
247	}
248
249	/**
250	\brief
251	Return the spatial dimension of the underlying domain.
252	*/
253	ESCRIPT_DLL_API
254	inline
255	int
256	getDim() const {
257	return getDomain().getDim();
258	}
259
260	protected:
261
262	private:
263	/**
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	// 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	FunctionSpace&
278	operator=(const FunctionSpace& other);
279
280	//
281	// static null domain value
282	static const NullDomain nullDomainValue;
283
284	//
285	// function space domain
286	const AbstractDomain* m_domain;
287
288	//
289	// function space type code.
290	int m_functionSpaceType;
291
292	//
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	};
300
301	} // end of namespace
302
303	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision