/[escript]/trunk/escript/src/DataTypes.h
ViewVC logotype

Contents of /trunk/escript/src/DataTypes.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1811 - (show annotations)
Thu Sep 25 23:11:13 2008 UTC (10 years, 3 months ago) by ksteube
File MIME type: text/plain
File size: 12349 byte(s)
Copyright updated in all files

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_DataTypes_20080811_H
16 #define escript_DataTypes_20080811_H
17 #include "system_dep.h"
18 #include "DataVector.h"
19 #include <vector>
20 #include <string>
21 #include <boost/python/object.hpp>
22 #include <boost/python/extract.hpp>
23
24 namespace escript {
25
26 namespace DataTypes {
27
28 /**
29 \namespace escript::DataTypes
30 \brief Contains the types to represent Shapes, Regions, RegionLoop ranges and vectors of data as well as the functions to manipulate them.
31 */
32 //
33 // Some basic types which define the data values and view shapes.
34 typedef DataVector ValueType;//!< Vector to store underlying data.
35 typedef std::vector<int> ShapeType;//!< The shape of a single datapoint.
36 typedef std::vector<std::pair<int, int> > RegionType;
37 typedef std::vector<std::pair<int, int> > RegionLoopRangeType;
38 static const int maxRank=4;//!< The maximum number of dimensions a datapoint can have.
39 static const ShapeType scalarShape;//!< Use this instead of creating empty shape objects for scalars.
40
41 /**
42 \brief
43 Calculate the number of values in a datapoint with the given shape.
44
45 \param shape
46 */
47 ESCRIPT_DLL_API
48 int
49 noValues(const DataTypes::ShapeType& shape);
50
51 /**
52 \brief
53 Calculate the number of values for the given region.
54
55 \param region
56 */
57 ESCRIPT_DLL_API
58 int
59 noValues(const DataTypes::RegionLoopRangeType& region);
60
61 /**
62 \brief
63 Return the given shape as a string.
64
65 \param shape - Input.
66 */
67 ESCRIPT_DLL_API
68 std::string
69 shapeToString(const DataTypes::ShapeType& shape);
70
71 /**
72 \brief
73 Determine the shape of the specified slice region.
74
75 \param region - Input -
76 Slice region.
77 */
78 ESCRIPT_DLL_API
79 DataTypes::ShapeType
80 getResultSliceShape(const DataTypes::RegionType& region);
81
82
83 /**
84 \brief
85 Determine the region specified by the given python slice object.
86
87 \param shape - Input - Shape of the object being sliced.
88 \param key - Input -
89 python slice object specifying region to be returned.
90
91 The slice object is a tuple of n python slice specifiers, where
92 n <= the rank of this Data object. Each slice specifier specifies the
93 range of indexes to be sliced from the corresponding dimension. The
94 first specifier corresponds to the first dimension, the second to the
95 second and so on. Where n < the rank, the remaining dimensions are
96 sliced across the full range of their indicies.
97
98 Each slice specifier is of the form "a:b", which specifies a slice
99 from index a, up to but not including index b. Where index a is ommitted
100 a is assumed to be 0. Where index b is ommitted, b is assumed to be the
101 length of this dimension. Where both are ommitted (eg: ":") the slice is
102 assumed to encompass that entire dimension.
103
104 Where one of the slice specifiers is a single integer, eg: [1], we
105 want to generate a rank-1 dimension object, as opposed to eg: [1,2]
106 which implies we want to take a rank dimensional object with one
107 dimension of size 1.
108
109 The return value is a vector of pairs with length equal to the rank of
110 this object. Each pair corresponds to the range of indicies from the
111 corresponding dimension to be sliced from, as specified in the input
112 slice object.
113
114 Examples:
115
116 For a rank 1 object of shape(5):
117
118 getSliceRegion(:) => < <0,5> >
119 getSliceRegion(2:3) => < <2,3> >
120 getSliceRegion(:3) => < <0,3> >
121 getSliceRegion(2:) => < <2,5> >
122
123 For a rank 2 object of shape(4,5):
124
125 getSliceRegion(2:3) => < <2,3> <0,5> >
126 getSliceRegion(2) => < <2,3> <0,5> >
127 NB: but return object requested will have rank 1, shape(5), with
128 values taken from index 2 of this object's first dimension.
129
130 For a rank 3 object of shape (2,4,6):
131
132 getSliceRegion(0:2,0:4,0:6) => < <0,2> <0,4> <0,6> >
133 getSliceRegion(:,:,:) => < <0,2> <0,4> <0,6> >
134 getSliceRegion(0:1) => < <0,1> <0,4> <0,6> >
135 getSliceRegion(:1,0:2) => < <0,1> <0,2> <0,6> >
136
137
138 Note: Not unit tested in c++.
139 */
140 ESCRIPT_DLL_API
141 DataTypes::RegionType
142 getSliceRegion(const DataTypes::ShapeType& shape, const boost::python::object& key);
143
144 /**
145 \brief
146 Modify region to copy from in order to
147 deal with the case where one range in the region contains identical indexes,
148 eg: <<1,1><0,3><0,3>>
149 This situation implies we want to copy from an object with rank greater than that of this
150 object. eg: we want to copy the values from a two dimensional slice out of a three
151 dimensional object into a two dimensional object.
152 We do this by taking a slice from the other object where one dimension of
153 the slice region is of size 1. So in the above example, we modify the above
154 region like so: <<1,2><0,3><0,3>> and take this slice.
155 */
156 DataTypes::RegionLoopRangeType
157 getSliceRegionLoopRange(const DataTypes::RegionType& region);
158
159 /**
160 \brief Return the rank (number of dimensions) of the given shape.
161
162 \param shape
163 \return the rank.
164 */
165 ESCRIPT_DLL_API
166 inline
167 int
168 getRank(const DataTypes::ShapeType& shape)
169 {
170 return shape.size();
171 }
172
173
174 /**
175 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
176
177 \param shape - Input - Shape of the datapoint.
178 \param i - Input - subscript to locate.
179 \return offset relative to the beginning of the datapoint.
180 */
181 ESCRIPT_DLL_API
182 inline
183 DataTypes::ValueType::size_type
184 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i)
185 {
186 EsysAssert((getRank(shape)==1),"Incorrect number of indices for the rank of this object.");
187 EsysAssert((i < DataTypes::noValues(shape)), "Error - Invalid index.");
188 return i;
189 }
190
191 /**
192 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
193
194 \param shape - Input - Shape of the datapoint.
195 \param i,j - Input - subscripts to locate.
196 \return offset relative to the beginning of the datapoint.
197 */
198 ESCRIPT_DLL_API
199 inline
200 DataTypes::ValueType::size_type
201 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i,
202 DataTypes::ValueType::size_type j)
203 {
204 EsysAssert((getRank(shape)==2),"Incorrect number of indices for the rank of this object.");
205 DataTypes::ValueType::size_type temp=i+j*shape[0];
206 EsysAssert((temp < DataTypes::noValues(shape)), "Error - Invalid index.");
207 return temp;
208 }
209
210 /**
211 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
212
213 \param shape - Input - Shape of the datapoint.
214 \param i,j,k - Input - subscripts to locate.
215 \return offset relative to the beginning of the datapoint.
216 */
217 ESCRIPT_DLL_API
218 inline
219 DataTypes::ValueType::size_type
220 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i,
221 DataTypes::ValueType::size_type j, DataTypes::ValueType::size_type k)
222 {
223 EsysAssert((getRank(shape)==3),"Incorrect number of indices for the rank of this object.");
224 DataTypes::ValueType::size_type temp=i+j*shape[0]+k*shape[1]*shape[0];
225 EsysAssert((temp < DataTypes::noValues(shape)), "Error - Invalid index.");
226 return temp;
227 }
228
229 /**
230 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
231
232 \param shape - Input - Shape of the datapoint.
233 \param i,j,k,m - Input - subscripts to locate.
234 \return offset relative to the beginning of the datapoint.
235 */
236 ESCRIPT_DLL_API
237 inline
238 DataTypes::ValueType::size_type
239 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i,
240 DataTypes::ValueType::size_type j, DataTypes::ValueType::size_type k,
241 DataTypes::ValueType::size_type m)
242 {
243 EsysAssert((getRank(shape)==4),"Incorrect number of indices for the rank of this object.");
244 DataTypes::ValueType::size_type temp=i+j*shape[0]+k*shape[1]*shape[0]+m*shape[2]*shape[1]*shape[0];
245 EsysAssert((temp < DataTypes::noValues(shape)), "Error - Invalid index.");
246 return temp;
247 }
248
249 /**
250 \brief Test if two shapes are equal.
251 */
252 ESCRIPT_DLL_API
253 inline
254 bool
255 checkShape(const ShapeType& s1, const ShapeType& s2)
256 {
257 return s1==s2;
258 }
259
260 /**
261 \brief Produce a string containing two shapes.
262
263 \param messagePrefix - Beginning of the message.
264 \param other - displayed in the message as "Other shape"
265 \param thisShape - displayed in the message as "This shape"
266 */
267 std::string
268 createShapeErrorMessage(const std::string& messagePrefix,
269 const DataTypes::ShapeType& other,
270 const DataTypes::ShapeType& thisShape);
271
272
273 /**
274 \brief
275 Copy a data slice specified by the given region and offset from the
276 "other" view into the "left" view at the given offset.
277
278 \param left - vector to copy into
279 \param leftShape - shape of datapoints for the left vector
280 \param leftOffset - location within left to start copying to
281 \param other - vector to copy from
282 \param otherShape - shape of datapoints for the other vector
283 \param otherOffset - location within other vector to start copying from
284 \param region - Input -
285 Region in other view to copy data from.
286 */
287 void
288 copySlice(ValueType& left,
289 const ShapeType& leftShape,
290 ValueType::size_type leftOffset,
291 const ValueType& other,
292 const ShapeType& otherShape,
293 ValueType::size_type otherOffset,
294 const RegionLoopRangeType& region);
295
296 /**
297 \brief
298 Copy data into a slice specified by the given region and offset in
299 the left vector from the other vector at the given offset.
300
301 \param left - vector to copy into
302 \param leftShape - shape of datapoints for the left vector
303 \param leftOffset - location within left to start copying to
304 \param other - vector to copy from
305 \param otherShape - shape of datapoints for the other vector
306 \param otherOffset - location within other vector to start copying from
307 \param region - Input -
308 Region in the left vector to copy data to.
309 */
310 void
311 copySliceFrom(ValueType& left,
312 const ShapeType& leftShape,
313 ValueType::size_type leftOffset,
314 const ValueType& other,
315 const ShapeType& otherShape,
316 ValueType::size_type otherOffset,
317 const RegionLoopRangeType& region);
318
319
320 /**
321 \brief Display a single value (with the specified shape) from the data.
322
323 \param data - vector containing the datapoint
324 \param shape - shape of the datapoint
325 \param offset - start of the datapoint within data
326 \param prefix - string to prepend to the output
327 */
328 std::string
329 pointToString(const ValueType& data,const ShapeType& shape, int offset, const std::string& prefix);
330
331
332 /**
333 \brief Extract shape information from the supplied numarray.
334 */
335 inline
336 ShapeType
337 shapeFromNumArray(const boost::python::numeric::array& value)
338 {
339 // extract the shape of the numarray
340 DataTypes::ShapeType tempShape;
341 for (int i=0; i < value.getrank(); i++) {
342 tempShape.push_back(boost::python::extract<int>(value.getshape()[i]));
343 }
344 return tempShape;
345 }
346
347
348 /**
349 \brief Copy a point from one vector to another. Note: This version does not check to see if shapes are the same.
350
351 \param dest - vector to copy to
352 \param doffset - beginning of the target datapoint in dest
353 \param nvals - the number of values comprising the datapoint
354 \param src - vector to copy from
355 \param soffset - beginning of the datapoint in src
356 */
357 void copyPoint(ValueType& dest, ValueType::size_type doffset, ValueType::size_type nvals, const ValueType& src, ValueType::size_type soffset);
358
359 } // End namespace DataTypes
360
361
362 } // end of namespace escipt
363
364 #endif
365

  ViewVC Help
Powered by ViewVC 1.1.26