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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1779 - (hide annotations)
Thu Sep 11 01:06:15 2008 UTC (11 years, 2 months ago) by jfenwick
Original Path: branches/arrayview_from_1695_trunk/escript/src/DataTypes.h
File MIME type: text/plain
File size: 12383 byte(s)
Branch commit:

Updated the doxyfile for deprecated/modified options (eg encoding is set 
to UTF-8).
Also set it not to scan directories called .svn or deprecated.

Removed #includes of DataArrayView.h
Moved DataArrayView into a new deprecated directory

Commented out setTaggedValue in DataExpanded which still referred to 
DataArrayView

Fixed some of the doxygen comments in DataMaths.h, DataTypes.h, 
DataTagged.h

Removed the empty JoelMods.cpp_

Unit tests appear to indicate that this branch is now "no more broken" 
than the version I branched from.



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

  ViewVC Help
Powered by ViewVC 1.1.26