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.
    NB: no unit testing yet
  */
  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.
    T
  */
  virtual
  DataAbstract*
  getSlice(const DataArrayView::RegionType& region) const;

  /**
     \brief
     Slice Constructor for DataTagged.

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

  /**
     \brief
     setSlice

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