escript/src/DataTagged.h

// $Id$

/*
 ******************************************************************************
 *                                                                            *
 *       COPYRIGHT  ACcESS 2004 -  All Rights Reserved                        *
 *                                                                            *
 * This software is the property of ACcESS. No part of this code              *
 * may be copied in any form or by any means without the expressed written    *
 * consent of ACcESS.  Copying, use or modification of this software          *
 * by any unauthorised person is illegal unless that person has a software    *
 * license agreement with ACcESS.                                             *
 *                                                                            *
 ******************************************************************************
*/

#if !defined escript_DataTagged_20040615_H
#define escript_DataTagged_20040615_H

#include "DataAbstract.h"
#include "DataArrayView.h"

#include <vector>
#include <map>

namespace escript {

class DataConstant;

/**
   \brief
   Simulates a full dataset accessible via sampleNo and dataPointNo. 

   Description:
   Each data-point has an associated tag number, and a given tag can represent a
   range of dataPointNo and sampleNo. Each tag indexes only a single data-point.
   Thus only a single data-point needs to be stored for a range of sampleNo and
   dataPointNo values.
*/

class DataTagged : public DataAbstract {

 public:

  //
  // Types for the lists of tags and values.
  typedef std::vector<int>           TagListType;
  typedef std::vector<DataArrayView> ValueListType;
  typedef DataArrayView::ValueType   ValueType;

  //
  // Map from a tag to an offset into the data array. 
  typedef std::map<int, int> DataMapType;

  /**
     \brief
     Default constructor for DataTagged.

     Description:
     Default constructor for DataTagged. Creates a DataTagged object for which
     the default data-point is a scalar data-point with value 0.0, and no other
     tag values are stored.
    T
  */
  DataTagged();

  /**
     \brief
     Constructor for DataTagged.

     Description:
     Constructor for DataTagged.
     \param tagKeys - Input - A vector of integer tags.
     \param values - Input - A vector of DataArrayViews. If this is empty
                     all tag values will be assigned a scalar data-point of value
                     0. If it contains one value all tag values will be assigned
             this value. Otherwise consecutive tags will be assigned 
                     consecutive values.  If there is a mismatch between  the
             number of keys and the number of values an exception 
             will be generated.
     \param defaultValue - Input - Value returned if a requested tag doesn't exist.
     \param what - Input - A description of what this data represents.
    T
  */
  DataTagged(const TagListType& tagKeys,
             const ValueListType& values,
         const DataArrayView& defaultValue,
         const FunctionSpace& what);

  /**
     \brief
     Alternative Constructor for DataTagged.

     Description:
     Alternative Constructor for DataTagged.
     \param what - Input - A description of what this data object represents.
     \param shape - Input - The shape of each data-point.
     \param tags - Input - An array of tags, one for each sample number.
     \param data - The data values for each tag.
  */
  DataTagged(const FunctionSpace& what,
             const DataArrayView::ShapeType &shape,
             const int tags[],
             const ValueType& data);

  /**
     \brief
     Copy Constructor for DataTagged.
     Performs a deep copy from the given DataTagged object.
    T
  */
  DataTagged(const DataTagged& other);

  /**
     \brief
     Copy Constructor for DataTagged.
     Construct a DataTagged object from a DataConstant object.
     The default value will be the value of the DataConstant object.
    T
  */
  DataTagged(const DataConstant& other);

  /**
     \brief
     getSampleDataByTag

     Description:
     Return the data-point for the given tag. All of the data for the
     sample will be visible via the returned pointer.

     ** This provides an interface into the data suitable for legacy C code.
     ** NB: need to do array bounds checking when accessing returned value!
    T
  */
  virtual
  double*
  getSampleDataByTag(int tag);

  /**
     \brief
     Write the data as a string.
     Writes out each tag, including the default, and the data-point which is
     associated with each tag.
    T
  */
  virtual
  std::string
  toString() const;

  /**
     \brief
     Return the tag number associated with the given data-point number
     according to the associated function space.
    T
  */
  virtual
  int
  getTagNumber(int dpno);

  /**
     \brief
     getPointOffset

     Description:
     Return the offset to the given data-point value in the underlying
     data vector.

     \param sampleNo - Input - sample number.
     \param dataPointNo - Input - data-point number.
    T
  */
  virtual
  ValueType::size_type
  getPointOffset(int sampleNo,
                 int dataPointNo) const;

  /**
     \brief
     addTaggedValues

     Description:
     Add the given tags and values to this DataTagged object.
     \param tagKeys - Input - A vector of integer tags.
     \param values - Input - A vector of DataArrayViews. If this is empty
                     all tag values will be assigned a scalar data-point of value
                     0. If it contains one value all tag values will be assigned
             this value. Otherwise consecutive tags will be assigned 
                     consecutive values.  If there is a mismatch between  the
             number of keys and the number of values an exception 
             will be generated.
    T
  */
  void
  addTaggedValues(const TagListType& tagKeys,
                  const ValueListType& values);  

  /**
     \brief
     addTaggedValue

     Description:
     Add a single tag and value to this DataTagged object. If this tag already has
     a value associated with it, setTaggedValue will be used to update this value.
     \param tagKey - Input - Integer tag.
     \param value - Input - Single DataArrayView value to be assigned to the tag.
    T
  */
  void
  addTaggedValue(int tagKey,
                 const DataArrayView& value);

  /**
     \brief
     setTaggedValues

     Description:
     Set the given tags to the given values in this DataTagged object.
     \param tagKeys - Input - A vector of integer tag.
     \param values - Input - A vector of DataArrayViews. If this is empty
                     all tag values will be assigned a scalar data-point of value
                     0. If it contains one value all tag values will be assigned
             this value. Otherwise consecutive tags will be assigned 
                     consecutive values.  If there is a mismatch between  the
             number of keys and the number of values an exception 
             will be generated.
    T
  */
  void
  setTaggedValues(const TagListType& tagKeys,
                  const ValueListType& values); 

  /**
     \brief
     setTaggedValue

     Description:
     Assign the given value to the given tag.
     \param tagKey - Input - Integer tag.
     \param value - Input - Single DataArrayView value to be assigned to the tag.
    T
  */
  virtual
  void
  setTaggedValue(int tagKey,
                 const DataArrayView& value);

  /**
     \brief
     getDataPointByTag

     Description:
     Return data-point associated with the given tag as a DataArrayView.
     \param tag - Input - Integer key.
    T
  */
  DataArrayView
  getDataPointByTag(int tag) const;

  /**
     \brief
     getDataPoint

     Description:
     Return the data-point specified by the given sample and data-point
     numbers as a DataArrayView.
     \param sampleNo - Input.
     \param dataPointNo - Input.
    T
  */
  virtual
  DataArrayView
  getDataPoint(int sampleNo,
               int dataPointNo);

  /**
     \brief 
     getTagLookup

     Description:
     Return a reference to the tag offset lookup table.
    T
  */
  const DataMapType&
  getTagLookup() const;

  /**
     \brief
     isCurrentTag

     Description:
     Return true if the given tag exists within the DataTagged tag map.

     *** NB: The DataTagged tag map does not necessarily coincide with the tag
     keys in the associated function space.
    T
  */
  bool
  isCurrentTag(int tag) const;

  /**
     \brief
     getDefaultValue

     Description:
     Return the default value. This value is associated with any tag which
     is not explicitly recorded in this DataTagged object's tag map.
    T
  */
  DataArrayView&
  getDefaultValue();

  const DataArrayView&
  getDefaultValue() const;

  /**
     \brief
     getLength

     Description:
     Return the total number of doubles stored for this DataTagged object.
    T
  */
  virtual
  ValueType::size_type
  getLength() const;

  /**
     \brief
     getSlice

     Description:
     Factory method that returns a newly created DataTagged object generated
     by taking the specified slice from this DataTagged object.
     The caller is reponsible for managing the returned object.
  */
  virtual
  DataAbstract*
  getSlice(const DataArrayView::RegionType& region) const;

  /**
     \brief
     Slice Constructor for DataTagged.

     Description:
     Slice Constructor for DataTagged.
     Creates a DataTagged object which is the specified slice
     from another DataTagged object.
     \param other - Input - DataTagged object to copy from.
     \param region - Input - Region to copy.
  */
  DataTagged(const DataTagged& other, 
         const DataArrayView::RegionType& region);

  /**
     \brief
     setSlice

     Description:
     Copy the specified region from the given Data object into this object.
     \param other - Input - Data object to copy from.
     \param region - Input - Region to copy (NB: must have same shape as this!).
  */
  virtual
  void
  setSlice(const DataAbstract* other,
           const DataArrayView::RegionType& region);

  /**
     \brief
     reshapeDataPoint

     Description:
     Reshape each data-point in this object to the given shape, only
     if current data-points are scalars. An exception is thrown if
     the current data-points have rank other than 0.
     The original values of the data-points are used for all values
     of the new data-points.
    T
  */
  void
  reshapeDataPoint(const DataArrayView::ShapeType& shape);

  /**
     \brief
     Archive the underlying data values to the file referenced
     by ofstream. A count of the number of values expected to be written
     is provided as a cross-check.

     The return value indicates success (0) or otherwise (1).
  */
  int
  archiveData(std::ofstream& archiveFile,
              const DataArrayView::ValueType::size_type noValues) const;

  /**
     \brief
     Extract the number of values specified by noValues from the file
     referenced by ifstream to the underlying data structure.

     The return value indicates success (0) or otherwise (1).
  */
  int
  extractData(std::ifstream& archiveFile,
              const DataArrayView::ValueType::size_type noValues);

 protected:

 private:

  //
  // The offset lookup table
  DataMapType m_offsetLookup;

  //
  // the offset to the default value
  static const int m_defaultValueOffset = 0;

  //
  // The actual data
  ValueType m_data;

};

inline
bool
DataTagged::isCurrentTag(int tag) const
{
  DataMapType::const_iterator pos(m_offsetLookup.find(tag));
  return (pos!=m_offsetLookup.end());
}

inline
DataArrayView&
DataTagged::getDefaultValue()
{
  // The default value is always the first value.
  return getPointDataView();
}

inline
const DataArrayView&
DataTagged::getDefaultValue() const
{
  // The default value is always the first value.
  return getPointDataView();
}

inline
const DataTagged::DataMapType&
DataTagged::getTagLookup() const
{
  return m_offsetLookup;
}

inline
DataArrayView::ValueType::size_type
DataTagged::getLength() const
{
  return m_data.size();
}

} // end of namespace

#endif
1	jgs	82	// $Id$
2	jgs	121
3			/*
4	jgs	82	******************************************************************************
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	jgs	121
17	jgs	82	#if !defined escript_DataTagged_20040615_H
18			#define escript_DataTagged_20040615_H
19
20	jgs	474	#include "DataAbstract.h"
21			#include "DataArrayView.h"
22	jgs	82
23			#include <vector>
24			#include <map>
25
26			namespace escript {
27
28			class DataConstant;
29
30			/**
31			\brief
32	jgs	496	Simulates a full dataset accessible via sampleNo and dataPointNo.
33	jgs	82
34			Description:
35	jgs	496	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	jgs	82	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	jgs	119	//
46	jgs	496	// Types for the lists of tags and values.
47	jgs	121	typedef std::vector<int> TagListType;
48	jgs	82	typedef std::vector<DataArrayView> ValueListType;
49	jgs	121	typedef DataArrayView::ValueType ValueType;
50	jgs	82
51			//
52	jgs	496	// Map from a tag to an offset into the data array.
53	jgs	82	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	jgs	509	the default data-point is a scalar data-point with value 0.0, and no other
62			tag values are stored.
63	jgs	507	T
64	jgs	82	*/
65			DataTagged();
66
67			/**
68			\brief
69			Constructor for DataTagged.
70
71			Description:
72			Constructor for DataTagged.
73	jgs	509	\param tagKeys - Input - A vector of integer tags.
74	jgs	82	\param values - Input - A vector of DataArrayViews. If this is empty
75	jgs	509	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	jgs	496	will be generated.
81	jgs	82	\param defaultValue - Input - Value returned if a requested tag doesn't exist.
82			\param what - Input - A description of what this data represents.
83	jgs	507	T
84	jgs	82	*/
85			DataTagged(const TagListType& tagKeys,
86			const ValueListType& values,
87			const DataArrayView& defaultValue,
88			const FunctionSpace& what);
89
90			/**
91			\brief
92	jgs	496	Alternative Constructor for DataTagged.
93	jgs	119
94			Description:
95	jgs	496	Alternative Constructor for DataTagged.
96	jgs	119	\param what - Input - A description of what this data object represents.
97	jgs	496	\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	jgs	119	*/
101			DataTagged(const FunctionSpace& what,
102			const DataArrayView::ShapeType &shape,
103			const int tags[],
104	jgs	500	const ValueType& data);
105	jgs	119
106			/**
107			\brief
108	jgs	496	Copy Constructor for DataTagged.
109	jgs	82	Performs a deep copy from the given DataTagged object.
110	jgs	507	T
111	jgs	82	*/
112			DataTagged(const DataTagged& other);
113
114			/**
115			\brief
116	jgs	496	Copy Constructor for DataTagged.
117	jgs	509	Construct a DataTagged object from a DataConstant object.
118			The default value will be the value of the DataConstant object.
119	jgs	507	T
120	jgs	82	*/
121			DataTagged(const DataConstant& other);
122
123			/**
124			\brief
125			getSampleDataByTag
126
127			Description:
128	jgs	496	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	jgs	507	** NB: need to do array bounds checking when accessing returned value!
133			T
134	jgs	82	*/
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	jgs	507	T
145	jgs	82	*/
146			virtual
147			std::string
148			toString() const;
149
150			/**
151			\brief
152	jgs	496	Return the tag number associated with the given data-point number
153			according to the associated function space.
154	jgs	507	T
155	jgs	149	*/
156			virtual
157			int
158			getTagNumber(int dpno);
159
160			/**
161			\brief
162	jgs	82	getPointOffset
163
164			Description:
165	jgs	496	Return the offset to the given data-point value in the underlying
166			data vector.
167	jgs	82
168			\param sampleNo - Input - sample number.
169			\param dataPointNo - Input - data-point number.
170	jgs	507	T
171			*/
172	jgs	82	virtual
173	jgs	121	ValueType::size_type
174	jgs	82	getPointOffset(int sampleNo,
175			int dataPointNo) const;
176
177			/**
178			\brief
179			addTaggedValues
180
181			Description:
182	jgs	509	Add the given tags and values to this DataTagged object.
183	jgs	507	\param tagKeys - Input - A vector of integer tags.
184	jgs	82	\param values - Input - A vector of DataArrayViews. If this is empty
185	jgs	509	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	jgs	507	T
192	jgs	82	*/
193			void
194			addTaggedValues(const TagListType& tagKeys,
195			const ValueListType& values);
196
197			/**
198			\brief
199			addTaggedValue
200
201			Description:
202	jgs	121	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	jgs	509	\param tagKey - Input - Integer tag.
205	jgs	121	\param value - Input - Single DataArrayView value to be assigned to the tag.
206	jgs	507	T
207	jgs	82	*/
208			void
209			addTaggedValue(int tagKey,
210			const DataArrayView& value);
211
212			/**
213			\brief
214			setTaggedValues
215
216			Description:
217	jgs	509	Set the given tags to the given values in this DataTagged object.
218			\param tagKeys - Input - A vector of integer tag.
219	jgs	82	\param values - Input - A vector of DataArrayViews. If this is empty
220	jgs	509	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	jgs	507	T
227	jgs	82	*/
228			void
229			setTaggedValues(const TagListType& tagKeys,
230			const ValueListType& values);
231
232			/**
233			\brief
234			setTaggedValue
235
236			Description:
237	jgs	509	Assign the given value to the given tag.
238			\param tagKey - Input - Integer tag.
239	jgs	82	\param value - Input - Single DataArrayView value to be assigned to the tag.
240	jgs	507	T
241	jgs	82	*/
242			virtual
243			void
244			setTaggedValue(int tagKey,
245			const DataArrayView& value);
246
247			/**
248			\brief
249			getDataPointByTag
250
251			Description:
252	jgs	509	Return data-point associated with the given tag as a DataArrayView.
253	jgs	82	\param tag - Input - Integer key.
254	jgs	507	T
255	jgs	82	*/
256			DataArrayView
257			getDataPointByTag(int tag) const;
258
259			/**
260			\brief
261			getDataPoint
262
263			Description:
264	jgs	509	Return the data-point specified by the given sample and data-point
265			numbers as a DataArrayView.
266	jgs	82	\param sampleNo - Input.
267			\param dataPointNo - Input.
268	jgs	507	T
269	jgs	82	*/
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	jgs	507	T
282	jgs	82	*/
283			const DataMapType&
284			getTagLookup() const;
285
286			/**
287			\brief
288			isCurrentTag
289
290			Description:
291	jgs	496	Return true if the given tag exists within the DataTagged tag map.
292
293	jgs	509	*** NB: The DataTagged tag map does not necessarily coincide with the tag
294	jgs	496	keys in the associated function space.
295	jgs	507	T
296			*/
297	jgs	82	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	jgs	496	is not explicitly recorded in this DataTagged object's tag map.
307	jgs	507	T
308	jgs	82	*/
309			DataArrayView&
310			getDefaultValue();
311
312			const DataArrayView&
313			getDefaultValue() const;
314
315			/**
316			\brief
317			getLength
318
319			Description:
320	jgs	509	Return the total number of doubles stored for this DataTagged object.
321	jgs	507	T
322	jgs	82	*/
323			virtual
324			ValueType::size_type
325			getLength() const;
326
327			/**
328			\brief
329			getSlice
330
331			Description:
332	jgs	513	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	jgs	82	*/
336			virtual
337			DataAbstract*
338			getSlice(const DataArrayView::RegionType& region) const;
339
340			/**
341			\brief
342	jgs	513	Slice Constructor for DataTagged.
343	jgs	82
344			Description:
345	jgs	513	Slice Constructor for DataTagged.
346			Creates a DataTagged object which is the specified slice
347			from another DataTagged object.
348			\param other - Input - DataTagged object to copy from.
349	jgs	82	\param region - Input - Region to copy.
350			*/
351	jgs	513	DataTagged(const DataTagged& other,
352			const DataArrayView::RegionType& region);
353
354			/**
355			\brief
356			setSlice
357
358			Description:
359			Copy the specified region from the given Data object into this object.
360			\param other - Input - Data object to copy from.
361			\param region - Input - Region to copy (NB: must have same shape as this!).
362			*/
363	jgs	82	virtual
364			void
365	jgs	513	setSlice(const DataAbstract* other,
366	jgs	82	const DataArrayView::RegionType& region);
367
368			/**
369			\brief
370			reshapeDataPoint
371
372			Description:
373	jgs	509	Reshape each data-point in this object to the given shape, only
374			if current data-points are scalars. An exception is thrown if
375			the current data-points have rank other than 0.
376			The original values of the data-points are used for all values
377			of the new data-points.
378			T
379	jgs	82	*/
380			void
381			reshapeDataPoint(const DataArrayView::ShapeType& shape);
382
383	jgs	123	/**
384	jgs	509	\brief
385			Archive the underlying data values to the file referenced
386			by ofstream. A count of the number of values expected to be written
387			is provided as a cross-check.
388	jgs	123
389	jgs	509	The return value indicates success (0) or otherwise (1).
390	jgs	123	*/
391			int
392			archiveData(std::ofstream& archiveFile,
393			const DataArrayView::ValueType::size_type noValues) const;
394
395			/**
396	jgs	509	\brief
397			Extract the number of values specified by noValues from the file
398			referenced by ifstream to the underlying data structure.
399	jgs	123
400	jgs	509	The return value indicates success (0) or otherwise (1).
401	jgs	123	*/
402			int
403			extractData(std::ifstream& archiveFile,
404			const DataArrayView::ValueType::size_type noValues);
405
406	jgs	82	protected:
407
408			private:
409
410			//
411			// The offset lookup table
412			DataMapType m_offsetLookup;
413
414			//
415	jgs	496	// the offset to the default value
416	jgs	119	static const int m_defaultValueOffset = 0;
417
418			//
419	jgs	82	// The actual data
420	jgs	121	ValueType m_data;
421	jgs	82
422			};
423
424			inline
425			bool
426			DataTagged::isCurrentTag(int tag) const
427			{
428			DataMapType::const_iterator pos(m_offsetLookup.find(tag));
429			return (pos!=m_offsetLookup.end());
430			}
431
432			inline
433			DataArrayView&
434			DataTagged::getDefaultValue()
435			{
436			// The default value is always the first value.
437			return getPointDataView();
438			}
439
440			inline
441			const DataArrayView&
442			DataTagged::getDefaultValue() const
443			{
444			// The default value is always the first value.
445			return getPointDataView();
446			}
447
448	jgs	496	inline
449			const DataTagged::DataMapType&
450			DataTagged::getTagLookup() const
451			{
452			return m_offsetLookup;
453			}
454
455			inline
456			DataArrayView::ValueType::size_type
457			DataTagged::getLength() const
458			{
459			return m_data.size();
460			}
461
462	jgs	82	} // end of namespace
463
464			#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision