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.
  */
  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.
  */
  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.
  */
  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.
  */
  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.
  */
  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.
  */
  virtual
  std::string
  toString() const;

  /**
     \brief
     Return the tag number associated with the given data-point number
     according to the associated function space.
  */
  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.
   */
  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 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 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.
  */
  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.
  */
  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.
  */
  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.
  */
  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.
  */
  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.
  */
  virtual
  DataArrayView
  getDataPoint(int sampleNo,
               int dataPointNo);

  /**
     \brief 
     getTagLookup

     Description:
     Return a reference to the tag offset lookup table.
  */
  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.
   */
  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.
  */
  DataArrayView&
  getDefaultValue();

  const DataArrayView&
  getDefaultValue() const;

  /**
     \brief
     getLength

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