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
     Slice Constructor for DataTagged.

     Description:
     Slice Constructor for DataTagged.
     Copies a 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
     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.
     The caller is reponsible for managing the object created.
  */
  virtual
  DataAbstract*
  getSlice(const DataArrayView::RegionType& region) const;

  /**
     \brief
     setSlice

     Description:
     Copy the specified region from the given value into this object.
     \param value - Input - Data to copy from.
     \param region - Input - Region to copy.
  */
  virtual
  void
  setSlice(const DataAbstract* value,
           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	// $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	Slice Constructor for DataTagged.
109
110	Description:
111	Slice Constructor for DataTagged.
112	Copies a slice from another DataTagged object.
113	\param other - Input - DataTagged object to copy from.
114	\param region - Input - Region to copy.
115	*/
116	DataTagged(const DataTagged& other,
117	const DataArrayView::RegionType& region);
118
119	/**
120	\brief
121	Copy Constructor for DataTagged.
122	Performs a deep copy from the given DataTagged object.
123	T
124	*/
125	DataTagged(const DataTagged& other);
126
127	/**
128	\brief
129	Copy Constructor for DataTagged.
130	Construct a DataTagged object from a DataConstant object.
131	The default value will be the value of the DataConstant object.
132	T
133	*/
134	DataTagged(const DataConstant& other);
135
136	/**
137	\brief
138	getSampleDataByTag
139
140	Description:
141	Return the data-point for the given tag. All of the data for the
142	sample will be visible via the returned pointer.
143
144	** This provides an interface into the data suitable for legacy C code.
145	** NB: need to do array bounds checking when accessing returned value!
146	T
147	*/
148	virtual
149	double*
150	getSampleDataByTag(int tag);
151
152	/**
153	\brief
154	Write the data as a string.
155	Writes out each tag, including the default, and the data-point which is
156	associated with each tag.
157	T
158	*/
159	virtual
160	std::string
161	toString() const;
162
163	/**
164	\brief
165	Return the tag number associated with the given data-point number
166	according to the associated function space.
167	T
168	*/
169	virtual
170	int
171	getTagNumber(int dpno);
172
173	/**
174	\brief
175	getPointOffset
176
177	Description:
178	Return the offset to the given data-point value in the underlying
179	data vector.
180
181	\param sampleNo - Input - sample number.
182	\param dataPointNo - Input - data-point number.
183	T
184	*/
185	virtual
186	ValueType::size_type
187	getPointOffset(int sampleNo,
188	int dataPointNo) const;
189
190	/**
191	\brief
192	addTaggedValues
193
194	Description:
195	Add the given tags and values to this DataTagged object.
196	\param tagKeys - Input - A vector of integer tags.
197	\param values - Input - A vector of DataArrayViews. If this is empty
198	all tag values will be assigned a scalar data-point of value
199	0. If it contains one value all tag values will be assigned
200	this value. Otherwise consecutive tags will be assigned
201	consecutive values. If there is a mismatch between the
202	number of keys and the number of values an exception
203	will be generated.
204	T
205	*/
206	void
207	addTaggedValues(const TagListType& tagKeys,
208	const ValueListType& values);
209
210	/**
211	\brief
212	addTaggedValue
213
214	Description:
215	Add a single tag and value to this DataTagged object. If this tag already has
216	a value associated with it, setTaggedValue will be used to update this value.
217	\param tagKey - Input - Integer tag.
218	\param value - Input - Single DataArrayView value to be assigned to the tag.
219	T
220	*/
221	void
222	addTaggedValue(int tagKey,
223	const DataArrayView& value);
224
225	/**
226	\brief
227	setTaggedValues
228
229	Description:
230	Set the given tags to the given values in this DataTagged object.
231	\param tagKeys - Input - A vector of integer tag.
232	\param values - Input - A vector of DataArrayViews. If this is empty
233	all tag values will be assigned a scalar data-point of value
234	0. If it contains one value all tag values will be assigned
235	this value. Otherwise consecutive tags will be assigned
236	consecutive values. If there is a mismatch between the
237	number of keys and the number of values an exception
238	will be generated.
239	T
240	*/
241	void
242	setTaggedValues(const TagListType& tagKeys,
243	const ValueListType& values);
244
245	/**
246	\brief
247	setTaggedValue
248
249	Description:
250	Assign the given value to the given tag.
251	\param tagKey - Input - Integer tag.
252	\param value - Input - Single DataArrayView value to be assigned to the tag.
253	T
254	*/
255	virtual
256	void
257	setTaggedValue(int tagKey,
258	const DataArrayView& value);
259
260	/**
261	\brief
262	getDataPointByTag
263
264	Description:
265	Return data-point associated with the given tag as a DataArrayView.
266	\param tag - Input - Integer key.
267	T
268	*/
269	DataArrayView
270	getDataPointByTag(int tag) const;
271
272	/**
273	\brief
274	getDataPoint
275
276	Description:
277	Return the data-point specified by the given sample and data-point
278	numbers as a DataArrayView.
279	\param sampleNo - Input.
280	\param dataPointNo - Input.
281	T
282	*/
283	virtual
284	DataArrayView
285	getDataPoint(int sampleNo,
286	int dataPointNo);
287
288	/**
289	\brief
290	getTagLookup
291
292	Description:
293	Return a reference to the tag offset lookup table.
294	T
295	*/
296	const DataMapType&
297	getTagLookup() const;
298
299	/**
300	\brief
301	isCurrentTag
302
303	Description:
304	Return true if the given tag exists within the DataTagged tag map.
305
306	*** NB: The DataTagged tag map does not necessarily coincide with the tag
307	keys in the associated function space.
308	T
309	*/
310	bool
311	isCurrentTag(int tag) const;
312
313	/**
314	\brief
315	getDefaultValue
316
317	Description:
318	Return the default value. This value is associated with any tag which
319	is not explicitly recorded in this DataTagged object's tag map.
320	T
321	*/
322	DataArrayView&
323	getDefaultValue();
324
325	const DataArrayView&
326	getDefaultValue() const;
327
328	/**
329	\brief
330	getLength
331
332	Description:
333	Return the total number of doubles stored for this DataTagged object.
334	T
335	*/
336	virtual
337	ValueType::size_type
338	getLength() const;
339
340	/**
341	\brief
342	getSlice
343
344	Description:
345	Factory method that returns a newly created DataTagged object.
346	The caller is reponsible for managing the object created.
347	*/
348	virtual
349	DataAbstract*
350	getSlice(const DataArrayView::RegionType& region) const;
351
352	/**
353	\brief
354	setSlice
355
356	Description:
357	Copy the specified region from the given value into this object.
358	\param value - Input - Data to copy from.
359	\param region - Input - Region to copy.
360	*/
361	virtual
362	void
363	setSlice(const DataAbstract* value,
364	const DataArrayView::RegionType& region);
365
366	/**
367	\brief
368	reshapeDataPoint
369
370	Description:
371	Reshape each data-point in this object to the given shape, only
372	if current data-points are scalars. An exception is thrown if
373	the current data-points have rank other than 0.
374	The original values of the data-points are used for all values
375	of the new data-points.
376	T
377	*/
378	void
379	reshapeDataPoint(const DataArrayView::ShapeType& shape);
380
381	/**
382	\brief
383	Archive the underlying data values to the file referenced
384	by ofstream. A count of the number of values expected to be written
385	is provided as a cross-check.
386
387	The return value indicates success (0) or otherwise (1).
388	*/
389	int
390	archiveData(std::ofstream& archiveFile,
391	const DataArrayView::ValueType::size_type noValues) const;
392
393	/**
394	\brief
395	Extract the number of values specified by noValues from the file
396	referenced by ifstream to the underlying data structure.
397
398	The return value indicates success (0) or otherwise (1).
399	*/
400	int
401	extractData(std::ifstream& archiveFile,
402	const DataArrayView::ValueType::size_type noValues);
403
404	protected:
405
406	private:
407
408	//
409	// The offset lookup table
410	DataMapType m_offsetLookup;
411
412	//
413	// the offset to the default value
414	static const int m_defaultValueOffset = 0;
415
416	//
417	// The actual data
418	ValueType m_data;
419
420	};
421
422	inline
423	bool
424	DataTagged::isCurrentTag(int tag) const
425	{
426	DataMapType::const_iterator pos(m_offsetLookup.find(tag));
427	return (pos!=m_offsetLookup.end());
428	}
429
430	inline
431	DataArrayView&
432	DataTagged::getDefaultValue()
433	{
434	// The default value is always the first value.
435	return getPointDataView();
436	}
437
438	inline
439	const DataArrayView&
440	DataTagged::getDefaultValue() const
441	{
442	// The default value is always the first value.
443	return getPointDataView();
444	}
445
446	inline
447	const DataTagged::DataMapType&
448	DataTagged::getTagLookup() const
449	{
450	return m_offsetLookup;
451	}
452
453	inline
454	DataArrayView::ValueType::size_type
455	DataTagged::getLength() const
456	{
457	return m_data.size();
458	}
459
460	} // end of namespace
461
462	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision