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 only data-point is a scalar data-point with value 0.0. All tags
     will map to this single data-point.
    T
  */
  DataTagged();

  /**
     \brief
     Constructor for DataTagged.

     Description:
     Constructor for DataTagged.
     \param tagKeys - Input - A vector of integer keys.
     \param values - Input - A vector of DataArrayViews. If this is empty
                     all tag values will be assigned a value of zero. If 
                     it contains one value all tag values will be assigned the 
             same value. Otherwise 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 tagged data from a DataConstant object.
     The default value will be that held by 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, by repeatedly
     using addTaggedValue for each given tag/value pair.
     \param tagKeys - Input - A vector of integer tags.
     \param values - Input - A vector of DataArrayViews. If this is empty
                      then all given tags will be assigned a value of zero. If 
                      it contains one value all tags will be assigned the same value.
                      Otherwise if there is a mismatch between the number of tags 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 key.
     \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, by repeatedly
     using setTaggedValue for each given tag/value pair.
     \param tagKeys - Input - A vector of integer keys.
     \param values - Input - A vector of DataArrayViews. If this is empty
                      then all given tags will be assigned a value of zero. If 
                      it contains one value all tag values will be assigned the same value.
                      Otherwise 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. If this tag does not already have a value
     associated with it, addTaggedValue will be used to add this tag/value pair.
     \param tagKey - Input - Integer key.
     \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 a view into the data-point associated with the given tag.
     \param tag - Input - Integer key.
    T
  */
  DataArrayView
  getDataPointByTag(int tag) const;

  /**
     \brief
     getDataPoint

     Description:
     Return a view into the data-point specified by the given sample
     and data-point numbers.
     \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.

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