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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 519 - (show annotations)
Tue Feb 14 05:30:50 2006 UTC (13 years, 7 months ago) by jgs
File MIME type: text/plain
File size: 12167 byte(s)
fix comments for setSlice - were totally misleading!

1 // $Id$
2
3 /*
4 ******************************************************************************
5 * *
6 * COPYRIGHT ACcESS 2004 - All Rights Reserved *
7 * *
8 * This software is the property of ACcESS. No part of this code *
9 * may be copied in any form or by any means without the expressed written *
10 * consent of ACcESS. Copying, use or modification of this software *
11 * by any unauthorised person is illegal unless that person has a software *
12 * license agreement with ACcESS. *
13 * *
14 ******************************************************************************
15 */
16
17 #if !defined escript_DataTagged_20040615_H
18 #define escript_DataTagged_20040615_H
19
20 #include "DataAbstract.h"
21 #include "DataArrayView.h"
22
23 #include <vector>
24 #include <map>
25
26 namespace escript {
27
28 class DataConstant;
29
30 /**
31 \brief
32 Simulates a full dataset accessible via sampleNo and dataPointNo.
33
34 Description:
35 Each data-point has an associated tag number, and a given tag can represent a
36 range of dataPointNo and sampleNo. Each tag indexes only a single data-point.
37 Thus only a single data-point needs to be stored for a range of sampleNo and
38 dataPointNo values.
39 */
40
41 class DataTagged : public DataAbstract {
42
43 public:
44
45 //
46 // Types for the lists of tags and values.
47 typedef std::vector<int> TagListType;
48 typedef std::vector<DataArrayView> ValueListType;
49 typedef DataArrayView::ValueType ValueType;
50
51 //
52 // Map from a tag to an offset into the data array.
53 typedef std::map<int, int> DataMapType;
54
55 /**
56 \brief
57 Default constructor for DataTagged.
58
59 Description:
60 Default constructor for DataTagged. Creates a DataTagged object for which
61 the default data-point is a scalar data-point with value 0.0, and no other
62 tag values are stored.
63 T
64 */
65 DataTagged();
66
67 /**
68 \brief
69 Constructor for DataTagged.
70
71 Description:
72 Constructor for DataTagged.
73 \param tagKeys - Input - A vector of integer tags.
74 \param values - Input - A vector of DataArrayViews. If this is empty
75 all tag values will be assigned a scalar data-point of value
76 0. If it contains one value all tag values will be assigned
77 this value. Otherwise consecutive tags will be assigned
78 consecutive values. If there is a mismatch between the
79 number of keys and the number of values an exception
80 will be generated.
81 \param defaultValue - Input - Value returned if a requested tag doesn't exist.
82 \param what - Input - A description of what this data represents.
83 T
84 */
85 DataTagged(const TagListType& tagKeys,
86 const ValueListType& values,
87 const DataArrayView& defaultValue,
88 const FunctionSpace& what);
89
90 /**
91 \brief
92 Alternative Constructor for DataTagged.
93
94 Description:
95 Alternative Constructor for DataTagged.
96 \param what - Input - A description of what this data object represents.
97 \param shape - Input - The shape of each data-point.
98 \param tags - Input - An array of tags, one for each sample number.
99 \param data - The data values for each tag.
100 */
101 DataTagged(const FunctionSpace& what,
102 const DataArrayView::ShapeType &shape,
103 const int tags[],
104 const ValueType& data);
105
106 /**
107 \brief
108 Copy Constructor for DataTagged.
109 Performs a deep copy from the given DataTagged object.
110 T
111 */
112 DataTagged(const DataTagged& other);
113
114 /**
115 \brief
116 Copy Constructor for DataTagged.
117 Construct a DataTagged object from a DataConstant object.
118 The default value will be the value of the DataConstant object.
119 T
120 */
121 DataTagged(const DataConstant& other);
122
123 /**
124 \brief
125 getSampleDataByTag
126
127 Description:
128 Return the data-point for the given tag. All of the data for the
129 sample will be visible via the returned pointer.
130
131 ** This provides an interface into the data suitable for legacy C code.
132 ** NB: need to do array bounds checking when accessing returned value!
133 T
134 */
135 virtual
136 double*
137 getSampleDataByTag(int tag);
138
139 /**
140 \brief
141 Write the data as a string.
142 Writes out each tag, including the default, and the data-point which is
143 associated with each tag.
144 T
145 */
146 virtual
147 std::string
148 toString() const;
149
150 /**
151 \brief
152 Return the tag number associated with the given data-point number
153 according to the associated function space.
154 T
155 */
156 virtual
157 int
158 getTagNumber(int dpno);
159
160 /**
161 \brief
162 getPointOffset
163
164 Description:
165 Return the offset to the given data-point value in the underlying
166 data vector.
167
168 \param sampleNo - Input - sample number.
169 \param dataPointNo - Input - data-point number.
170 T
171 */
172 virtual
173 ValueType::size_type
174 getPointOffset(int sampleNo,
175 int dataPointNo) const;
176
177 /**
178 \brief
179 addTaggedValues
180
181 Description:
182 Add the given tags and values to this DataTagged object.
183 \param tagKeys - Input - A vector of integer tags.
184 \param values - Input - A vector of DataArrayViews. If this is empty
185 all tag values will be assigned a scalar data-point of value
186 0. If it contains one value all tag values will be assigned
187 this value. Otherwise consecutive tags will be assigned
188 consecutive values. If there is a mismatch between the
189 number of keys and the number of values an exception
190 will be generated.
191 T
192 */
193 void
194 addTaggedValues(const TagListType& tagKeys,
195 const ValueListType& values);
196
197 /**
198 \brief
199 addTaggedValue
200
201 Description:
202 Add a single tag and value to this DataTagged object. If this tag already has
203 a value associated with it, setTaggedValue will be used to update this value.
204 \param tagKey - Input - Integer tag.
205 \param value - Input - Single DataArrayView value to be assigned to the tag.
206 T
207 */
208 void
209 addTaggedValue(int tagKey,
210 const DataArrayView& value);
211
212 /**
213 \brief
214 setTaggedValues
215
216 Description:
217 Set the given tags to the given values in this DataTagged object.
218 \param tagKeys - Input - A vector of integer tag.
219 \param values - Input - A vector of DataArrayViews. If this is empty
220 all tag values will be assigned a scalar data-point of value
221 0. If it contains one value all tag values will be assigned
222 this value. Otherwise consecutive tags will be assigned
223 consecutive values. If there is a mismatch between the
224 number of keys and the number of values an exception
225 will be generated.
226 T
227 */
228 void
229 setTaggedValues(const TagListType& tagKeys,
230 const ValueListType& values);
231
232 /**
233 \brief
234 setTaggedValue
235
236 Description:
237 Assign the given value to the given tag.
238 \param tagKey - Input - Integer tag.
239 \param value - Input - Single DataArrayView value to be assigned to the tag.
240 T
241 */
242 virtual
243 void
244 setTaggedValue(int tagKey,
245 const DataArrayView& value);
246
247 /**
248 \brief
249 getDataPointByTag
250
251 Description:
252 Return data-point associated with the given tag as a DataArrayView.
253 \param tag - Input - Integer key.
254 T
255 */
256 DataArrayView
257 getDataPointByTag(int tag) const;
258
259 /**
260 \brief
261 getDataPoint
262
263 Description:
264 Return the data-point specified by the given sample and data-point
265 numbers as a DataArrayView.
266 \param sampleNo - Input.
267 \param dataPointNo - Input.
268 T
269 */
270 virtual
271 DataArrayView
272 getDataPoint(int sampleNo,
273 int dataPointNo);
274
275 /**
276 \brief
277 getTagLookup
278
279 Description:
280 Return a reference to the tag offset lookup table.
281 T
282 */
283 const DataMapType&
284 getTagLookup() const;
285
286 /**
287 \brief
288 isCurrentTag
289
290 Description:
291 Return true if the given tag exists within the DataTagged tag map.
292
293 *** NB: The DataTagged tag map does not necessarily coincide with the tag
294 keys in the associated function space.
295 T
296 */
297 bool
298 isCurrentTag(int tag) const;
299
300 /**
301 \brief
302 getDefaultValue
303
304 Description:
305 Return the default value. This value is associated with any tag which
306 is not explicitly recorded in this DataTagged object's tag map.
307 T
308 */
309 DataArrayView&
310 getDefaultValue();
311
312 const DataArrayView&
313 getDefaultValue() const;
314
315 /**
316 \brief
317 getLength
318
319 Description:
320 Return the total number of doubles stored for this DataTagged object.
321 T
322 */
323 virtual
324 ValueType::size_type
325 getLength() const;
326
327 /**
328 \brief
329 getSlice
330
331 Description:
332 Factory method that returns a newly created DataTagged object generated
333 by taking the specified slice from this DataTagged object.
334 The caller is reponsible for managing the returned object.
335 */
336 virtual
337 DataAbstract*
338 getSlice(const DataArrayView::RegionType& region) const;
339
340 /**
341 \brief
342 Slice Constructor for DataTagged.
343
344 Description:
345 Creates a DataTagged object which is the specified slice
346 from the given DataTagged object.
347 \param other - Input - DataTagged object to slice from.
348 \param region - Input - Region to slice.
349 */
350 DataTagged(const DataTagged& other,
351 const DataArrayView::RegionType& region);
352
353 /**
354 \brief
355 setSlice
356
357 Description:
358 Copy the given Data object into the specified region in this object.
359 \param other - Input - Data object to copy from.
360 \param region - Input - Region to copy into (NB: must have same shape as other!).
361 */
362 virtual
363 void
364 setSlice(const DataAbstract* other,
365 const DataArrayView::RegionType& region);
366
367 /**
368 \brief
369 reshapeDataPoint
370
371 Description:
372 Reshape each data-point in this object to the given shape, only
373 if current data-points are scalars. An exception is thrown if
374 the current data-points have rank other than 0.
375 The original values of the data-points are used for all values
376 of the new data-points.
377 T
378 */
379 void
380 reshapeDataPoint(const DataArrayView::ShapeType& shape);
381
382 /**
383 \brief
384 Archive the underlying data values to the file referenced
385 by ofstream. A count of the number of values expected to be written
386 is provided as a cross-check.
387
388 The return value indicates success (0) or otherwise (1).
389 */
390 int
391 archiveData(std::ofstream& archiveFile,
392 const DataArrayView::ValueType::size_type noValues) const;
393
394 /**
395 \brief
396 Extract the number of values specified by noValues from the file
397 referenced by ifstream to the underlying data structure.
398
399 The return value indicates success (0) or otherwise (1).
400 */
401 int
402 extractData(std::ifstream& archiveFile,
403 const DataArrayView::ValueType::size_type noValues);
404
405 protected:
406
407 private:
408
409 //
410 // The offset lookup table
411 DataMapType m_offsetLookup;
412
413 //
414 // the offset to the default value
415 static const int m_defaultValueOffset = 0;
416
417 //
418 // The actual data
419 ValueType m_data;
420
421 };
422
423 inline
424 bool
425 DataTagged::isCurrentTag(int tag) const
426 {
427 DataMapType::const_iterator pos(m_offsetLookup.find(tag));
428 return (pos!=m_offsetLookup.end());
429 }
430
431 inline
432 DataArrayView&
433 DataTagged::getDefaultValue()
434 {
435 // The default value is always the first value.
436 return getPointDataView();
437 }
438
439 inline
440 const DataArrayView&
441 DataTagged::getDefaultValue() const
442 {
443 // The default value is always the first value.
444 return getPointDataView();
445 }
446
447 inline
448 const DataTagged::DataMapType&
449 DataTagged::getTagLookup() const
450 {
451 return m_offsetLookup;
452 }
453
454 inline
455 DataArrayView::ValueType::size_type
456 DataTagged::getLength() const
457 {
458 return m_data.size();
459 }
460
461 } // end of namespace
462
463 #endif

Properties

Name Value
svn:eol-style native
svn:keywords Author Date Id Revision

  ViewVC Help
Powered by ViewVC 1.1.26