/[escript]/branches/arrexp_2137_win_merge/escript/src/DataTypes.h
ViewVC logotype

Contents of /branches/arrexp_2137_win_merge/escript/src/DataTypes.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2219 - (show annotations)
Wed Jan 14 04:31:34 2009 UTC (10 years, 7 months ago) by jfenwick
File MIME type: text/plain
File size: 12328 byte(s)
Merging changes from trunk 2098:2218
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 indices.
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 omitted
100 a is assumed to be 0. Where index b is omitted, b is assumed to be the
101 length of this dimension. Where both are omitted (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 indices 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 ESCRIPT_DLL_API
157 DataTypes::RegionLoopRangeType
158 getSliceRegionLoopRange(const DataTypes::RegionType& region);
159
160 /**
161 \brief Return the rank (number of dimensions) of the given shape.
162
163 \param shape
164 \return the rank.
165 */
166 ESCRIPT_DLL_API
167 inline
168 int
169 getRank(const DataTypes::ShapeType& shape)
170 {
171 return shape.size();
172 }
173
174
175 /**
176 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
177
178 \param shape - Input - Shape of the datapoint.
179 \param i - Input - subscript to locate.
180 \return offset relative to the beginning of the datapoint.
181 */
182 ESCRIPT_DLL_API
183 inline
184 DataTypes::ValueType::size_type
185 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i)
186 {
187 EsysAssert((getRank(shape)==1),"Incorrect number of indices for the rank of this object.");
188 EsysAssert((i < DataTypes::noValues(shape)), "Error - Invalid index.");
189 return i;
190 }
191
192 /**
193 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
194
195 \param shape - Input - Shape of the datapoint.
196 \param i - Input - row
197 \param j - Input - column
198 \return offset relative to the beginning of the datapoint.
199 */
200 ESCRIPT_DLL_API
201 inline
202 DataTypes::ValueType::size_type
203 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i,
204 DataTypes::ValueType::size_type j)
205 {
206 // Warning: This is not C ordering. Do not try to figure out the params by looking at the code
207 EsysAssert((getRank(shape)==2),"Incorrect number of indices for the rank of this object.");
208 DataTypes::ValueType::size_type temp=i+j*shape[0];
209 EsysAssert((temp < DataTypes::noValues(shape)), "Error - Invalid index.");
210 return temp;
211 }
212
213 /**
214 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
215
216 \param shape - Input - Shape of the datapoint.
217 \param i,j,k - Input - subscripts to locate.
218 \return offset relative to the beginning of the datapoint.
219 */
220 ESCRIPT_DLL_API
221 inline
222 DataTypes::ValueType::size_type
223 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i,
224 DataTypes::ValueType::size_type j, DataTypes::ValueType::size_type k)
225 {
226 // Warning: This is not C ordering. Do not try to figure out the params by looking at the code
227 EsysAssert((getRank(shape)==3),"Incorrect number of indices for the rank of this object.");
228 DataTypes::ValueType::size_type temp=i+j*shape[0]+k*shape[1]*shape[0];
229 EsysAssert((temp < DataTypes::noValues(shape)), "Error - Invalid index.");
230 return temp;
231 }
232
233 /**
234 \brief Compute the offset (in 1D vector) of a given subscript with a shape.
235
236 \param shape - Input - Shape of the datapoint.
237 \param i,j,k,m - Input - subscripts to locate.
238 \return offset relative to the beginning of the datapoint.
239 */
240 ESCRIPT_DLL_API
241 inline
242 DataTypes::ValueType::size_type
243 getRelIndex(const DataTypes::ShapeType& shape, DataTypes::ValueType::size_type i,
244 DataTypes::ValueType::size_type j, DataTypes::ValueType::size_type k,
245 DataTypes::ValueType::size_type m)
246 {
247 // Warning: This is not C ordering. Do not try to figure out the params by looking at the code
248 EsysAssert((getRank(shape)==4),"Incorrect number of indices for the rank of this object.");
249 DataTypes::ValueType::size_type temp=i+j*shape[0]+k*shape[1]*shape[0]+m*shape[2]*shape[1]*shape[0];
250 EsysAssert((temp < DataTypes::noValues(shape)), "Error - Invalid index.");
251 return temp;
252 }
253
254 /**
255 \brief Test if two shapes are equal.
256 */
257 ESCRIPT_DLL_API
258 inline
259 bool
260 checkShape(const ShapeType& s1, const ShapeType& s2)
261 {
262 return s1==s2;
263 }
264
265 /**
266 \brief Produce a string containing two shapes.
267
268 \param messagePrefix - Beginning of the message.
269 \param other - displayed in the message as "Other shape"
270 \param thisShape - displayed in the message as "This shape"
271 */
272 ESCRIPT_DLL_API
273 std::string
274 createShapeErrorMessage(const std::string& messagePrefix,
275 const DataTypes::ShapeType& other,
276 const DataTypes::ShapeType& thisShape);
277
278
279 /**
280 \brief
281 Copy a data slice specified by the given region and offset from the
282 "other" view into the "left" view at the given offset.
283
284 \param left - vector to copy into
285 \param leftShape - shape of datapoints for the left vector
286 \param leftOffset - location within left to start copying to
287 \param other - vector to copy from
288 \param otherShape - shape of datapoints for the other vector
289 \param otherOffset - location within other vector to start copying from
290 \param region - Input -
291 Region in other view to copy data from.
292 */
293 ESCRIPT_DLL_API
294 void
295 copySlice(ValueType& left,
296 const ShapeType& leftShape,
297 ValueType::size_type leftOffset,
298 const ValueType& other,
299 const ShapeType& otherShape,
300 ValueType::size_type otherOffset,
301 const RegionLoopRangeType& region);
302
303 /**
304 \brief
305 Copy data into a slice specified by the given region and offset in
306 the left vector from the other vector at the given offset.
307
308 \param left - vector to copy into
309 \param leftShape - shape of datapoints for the left vector
310 \param leftOffset - location within left to start copying to
311 \param other - vector to copy from
312 \param otherShape - shape of datapoints for the other vector
313 \param otherOffset - location within other vector to start copying from
314 \param region - Input -
315 Region in the left vector to copy data to.
316 */
317 ESCRIPT_DLL_API
318 void
319 copySliceFrom(ValueType& left,
320 const ShapeType& leftShape,
321 ValueType::size_type leftOffset,
322 const ValueType& other,
323 const ShapeType& otherShape,
324 ValueType::size_type otherOffset,
325 const RegionLoopRangeType& region);
326
327
328 /**
329 \brief Display a single value (with the specified shape) from the data.
330
331 \param data - vector containing the datapoint
332 \param shape - shape of the datapoint
333 \param offset - start of the datapoint within data
334 \param prefix - string to prepend to the output
335 */
336 std::string
337 pointToString(const ValueType& data,const ShapeType& shape, int offset, const std::string& prefix);
338
339
340 /**
341 \brief Copy a point from one vector to another. Note: This version does not check to see if shapes are the same.
342
343 \param dest - vector to copy to
344 \param doffset - beginning of the target datapoint in dest
345 \param nvals - the number of values comprising the datapoint
346 \param src - vector to copy from
347 \param soffset - beginning of the datapoint in src
348 */
349 void copyPoint(ValueType& dest, ValueType::size_type doffset, ValueType::size_type nvals, const ValueType& src, ValueType::size_type soffset);
350
351 } // End of namespace DataTypes
352
353
354 } // End of namespace escript
355
356 #endif
357

  ViewVC Help
Powered by ViewVC 1.1.26