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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3992 - (show annotations)
Wed Sep 26 02:50:48 2012 UTC (6 years, 11 months ago) by caltinay
File MIME type: text/plain
File size: 13241 byte(s)
Data.cpp: Removed some namespace ambiguities which fixes doxygen warnings, some
cleanup and reindent.
*: doxygen fixes.

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

  ViewVC Help
Powered by ViewVC 1.1.26