escript/src/DataTagged.h


/* $Id$ */

/*******************************************************
 *
 *           Copyright 2003-2007 by ACceSS MNRF
 *       Copyright 2007 by University of Queensland
 *
 *                http://esscc.uq.edu.au
 *        Primary Business: Queensland, Australia
 *  Licensed under the Open Software License version 3.0
 *     http://www.opensource.org/licenses/osl-3.0.php
 *
 *******************************************************/

#if !defined escript_DataTagged_20040615_H
#define escript_DataTagged_20040615_H
#include "system_dep.h"

#include "DataAbstract.h"
#include "DataArrayView.h"
#include "DataTypes.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 DataTypes::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
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  DataTagged(const FunctionSpace& what,
             const DataTypes::ShapeType &shape,
             const int tags[],
             const ValueType& data);

  /**
     \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 vector of tags, one for each sample number.
     \param data - The data values for each tag.
    NB: no unit testing yet
  */
  ESCRIPT_DLL_API
  DataTagged(const FunctionSpace& what,
             const DataTypes::ShapeType &shape,
             const TagListType& tags,
             const ValueType& data);

  /**
     \brief
     Copy Constructor for DataTagged.
     Performs a deep copy from the given DataTagged object.
    T
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  DataTagged(const DataConstant& other);

  /**
     \brief
     Copies the tags from a DataTagged into a new Data Tagged and assigns them the default value. ** Not unit tested **

     This is different from a deep copy because we are not copying shape or other information, just tags.
     \param what - Input - FunctionSpace for the new DataTagged
     \param shape - Input - Shape for points in the new DataTagged
     \param defaultvalue - Input - Default value for new DataTagged
     \param tagsource - Input - A DataTagged object which supplies the tags. 
  */
  ESCRIPT_DLL_API
  DataTagged(const FunctionSpace& what,
             const DataTypes::ShapeType& shape,
         const DataTypes::ValueType& defaultvalue,
             const DataTagged& tagsource);


  /**
     \brief
     Destructor
  */
  ESCRIPT_DLL_API
  inline virtual
  ~DataTagged() {};

  /**
     \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
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  virtual
  std::string
  toString() const;
 /**
     \brief
     dumps the object into a netCDF file
  */
  ESCRIPT_DLL_API
  virtual
  void
  dump(const std::string fileName) const;

 /**
     \brief
    sets all values to zero
  */
  ESCRIPT_DLL_API
  virtual
  void
  setToZero();

  /**
     \brief
     Return the tag number associated with the given data-point number
     according to the associated function space.
    T
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  void
  addTaggedValue(int tagKey,
                 const DataArrayView& value);

  /**
     \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 pointshape - Shape of the value parameter
     \param value - Input - Single DataArrayView value to be assigned to the tag. 
     \param dataOffset - Input - Offset of the beginning of the point in the value parameter 
  */
  ESCRIPT_DLL_API
  void
  addTaggedValue(int tagKey,
         const DataTypes::ShapeType& pointshape,
                 const ValueType& value,
         int dataOffset=0);

  /**
     \brief
     addTag - does not modify the default value for this object. ** Not unit tested **

     Description:
     Add a single tag. The default value for this DataTagged will be associated with the tag.
     If this tag already has a value associated with it, then no change will be made.
     \param tagKey - Input - Integer tag.
    T
  */
  ESCRIPT_DLL_API
  void
  addTag(int tagKey);


  /**
     \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
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  virtual
  void
  setTaggedValue(int tagKey,
                 const DataArrayView& value);

  /**
     \brief
     setTaggedValue

     Description:
     Assign the given value to the given tag.
     \param tagKey - Input - Integer tag.
     \param pointshape - the shape of the value parameter
     \param value - Input - Single DataArrayView value to be assigned to the tag.
    T
  */
  ESCRIPT_DLL_API
  void
  setTaggedValue(int tagKey,
         const DataTypes::ShapeType& pointshape,
                 const ValueType& value,
         int dataOffset=0);


  /**
     \brief
     getDataPointByTag

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

  /**
     \brief
     getDataByTag

     Return a pointer to the beginning of the datapoint with the specified tag.
     TODO Eventually these should be inlined.
     \param tag - Input - Integer key.
     \param i - position in the underlying datastructure
    T
  */
  ESCRIPT_DLL_API
  DataTypes::ValueType::const_reference
  getDataByTag(int tag, DataTypes::ValueType::size_type i) const;

  ESCRIPT_DLL_API
  DataTypes::ValueType::reference
  getDataByTag(int tag, DataTypes::ValueType::size_type i);


  /**
     \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
  */
  ESCRIPT_DLL_API
  virtual
  DataArrayView
  getDataPoint(int sampleNo,
               int dataPointNo);

  /**
     \brief
     getData

     Description:
     Return pointer to the data
    T
  */
  ESCRIPT_DLL_API
  const DataTypes::ValueType::ElementType*
  getData() const;

  /**
     \brief 
     getTagLookup

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

  ESCRIPT_DLL_API
  const DataArrayView&
  getDefaultValue() 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.
     \param i - position in the underlying datastructure
    T
  */
  ESCRIPT_DLL_API
  DataTypes::ValueType::reference
  getDefaultValue(DataTypes::ValueType::size_type i);

  ESCRIPT_DLL_API
  DataTypes::ValueType::const_reference
  getDefaultValue(DataTypes::ValueType::size_type i) const;


  /**
     \brief
     getLength

     Description:
     Return the total number of doubles stored for this DataTagged object.
    T
  */
  ESCRIPT_DLL_API
  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
  */
  ESCRIPT_DLL_API
  virtual
  DataAbstract*
  getSlice(const DataTypes::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
  */
  ESCRIPT_DLL_API
  DataTagged(const DataTagged& other, 
         const DataTypes::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
  */
  ESCRIPT_DLL_API
  virtual
  void
  setSlice(const DataAbstract* other,
           const DataTypes::RegionType& region);

  /**
     \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).
  */
  ESCRIPT_DLL_API
  int
  archiveData(std::ofstream& archiveFile,
              const DataTypes::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).
  */
  ESCRIPT_DLL_API
  int
  extractData(std::ifstream& archiveFile,
              const DataTypes::ValueType::size_type noValues);

  /**
     \brief
     Computes a symmetric matrix (A + AT) / 2

     \param ev - Output - symmetric matrix

  */
  ESCRIPT_DLL_API
  virtual void
  symmetric(DataAbstract* ev);

  /**
     \brief
     Computes a nonsymmetric matrix (A - AT) / 2

     \param ev - Output - nonsymmetric matrix

  */
  ESCRIPT_DLL_API
  virtual void
  nonsymmetric(DataAbstract* ev);

  /**
     \brief
     Computes the trace of a matrix

     \param ev - Output - the trace of a matrix

  */
  ESCRIPT_DLL_API
  virtual void
  trace(DataAbstract* ev, int axis_offset);

  /**
     \brief
     swaps components axis0 and axis1

     \param ev - Output - swapped components

  */
  ESCRIPT_DLL_API
  virtual void
  swapaxes(DataAbstract* ev, int axis0, int axis1);

  /**
     \brief
     Transpose each data point of this Data object around the given axis.

     \param ev - Output - the transpose of a matrix

  */
  ESCRIPT_DLL_API
  virtual void
  transpose(DataAbstract* ev, int axis_offset);

  /**
     \brief
     solves the eigenvalue problem this*V=ev*V for the eigenvalues ev

     \param ev - Output - eigenvalues in increasing order at each data point

  */
  ESCRIPT_DLL_API
  virtual void
  eigenvalues(DataAbstract* ev);

  /**
     \brief
     solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V

     \param ev - Output - eigenvalues in increasing order at each data point
     \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
                         and the first nonzero component is positive.
     \param tol - Input - eigenvalue with relative distance tol are treated as equal.

  */

  ESCRIPT_DLL_API
  virtual void
  eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);


 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
DataTypes::ValueType::reference
DataTagged::getDefaultValue(DataTypes::ValueType::size_type i)
{
    return getPointDataView().getData()[i];
}

inline
DataTypes::ValueType::const_reference
DataTagged::getDefaultValue(DataTypes::ValueType::size_type i) const
{
    return getPointDataView().getData()[i];
}


inline
const DataTypes::ValueType::ElementType*
DataTagged::getData() const
{
   return &(m_data[0]);
}

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

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

} // end of namespace

#endif
1
2	/* $Id$ */
3
4	/*******************************************************
5	*
6	* Copyright 2003-2007 by ACceSS MNRF
7	* Copyright 2007 by University of Queensland
8	*
9	* http://esscc.uq.edu.au
10	* Primary Business: Queensland, Australia
11	* Licensed under the Open Software License version 3.0
12	* http://www.opensource.org/licenses/osl-3.0.php
13	*
14	*******************************************************/
15
16	#if !defined escript_DataTagged_20040615_H
17	#define escript_DataTagged_20040615_H
18	#include "system_dep.h"
19
20	#include "DataAbstract.h"
21	#include "DataArrayView.h"
22	#include "DataTypes.h"
23
24	#include <vector>
25	#include <map>
26
27	namespace escript {
28
29	class DataConstant;
30
31	/**
32	\brief
33	Simulates a full dataset accessible via sampleNo and dataPointNo.
34
35	Description:
36	Each data-point has an associated tag number, and a given tag can represent a
37	range of dataPointNo and sampleNo. Each tag indexes only a single data-point.
38	Thus only a single data-point needs to be stored for a range of sampleNo and
39	dataPointNo values.
40	*/
41
42	class DataTagged : public DataAbstract {
43
44	public:
45
46	//
47	// Types for the lists of tags and values.
48	typedef std::vector<int> TagListType;
49	typedef std::vector<DataArrayView> ValueListType;
50	typedef DataTypes::ValueType ValueType;
51
52	//
53	// Map from a tag to an offset into the data array.
54	typedef std::map<int, int> DataMapType;
55
56	/**
57	\brief
58	Default constructor for DataTagged.
59
60	Description:
61	Default constructor for DataTagged. Creates a DataTagged object for which
62	the default data-point is a scalar data-point with value 0.0, and no other
63	tag values are stored.
64	T
65	*/
66	ESCRIPT_DLL_API
67	DataTagged();
68
69	/**
70	\brief
71	Constructor for DataTagged.
72
73	Description:
74	Constructor for DataTagged.
75	\param tagKeys - Input - A vector of integer tags.
76	\param values - Input - A vector of DataArrayViews. If this is empty
77	all tag values will be assigned a scalar data-point of value
78	0. If it contains one value all tag values will be assigned
79	this value. Otherwise consecutive tags will be assigned
80	consecutive values. If there is a mismatch between the
81	number of keys and the number of values an exception
82	will be generated.
83	\param defaultValue - Input - Value returned if a requested tag doesn't exist.
84	\param what - Input - A description of what this data represents.
85	T
86	*/
87	ESCRIPT_DLL_API
88	DataTagged(const TagListType& tagKeys,
89	const ValueListType& values,
90	const DataArrayView& defaultValue,
91	const FunctionSpace& what);
92
93	/**
94	\brief
95	Alternative Constructor for DataTagged.
96
97	Description:
98	Alternative Constructor for DataTagged.
99	\param what - Input - A description of what this data object represents.
100	\param shape - Input - The shape of each data-point.
101	\param tags - Input - An array of tags, one for each sample number.
102	\param data - The data values for each tag.
103	NB: no unit testing yet
104	*/
105	ESCRIPT_DLL_API
106	DataTagged(const FunctionSpace& what,
107	const DataTypes::ShapeType &shape,
108	const int tags[],
109	const ValueType& data);
110
111	/**
112	\brief
113	Alternative Constructor for DataTagged.
114
115	Description:
116	Alternative Constructor for DataTagged.
117	\param what - Input - A description of what this data object represents.
118	\param shape - Input - The shape of each data-point.
119	\param tags - Input - An vector of tags, one for each sample number.
120	\param data - The data values for each tag.
121	NB: no unit testing yet
122	*/
123	ESCRIPT_DLL_API
124	DataTagged(const FunctionSpace& what,
125	const DataTypes::ShapeType &shape,
126	const TagListType& tags,
127	const ValueType& data);
128
129	/**
130	\brief
131	Copy Constructor for DataTagged.
132	Performs a deep copy from the given DataTagged object.
133	T
134	*/
135	ESCRIPT_DLL_API
136	DataTagged(const DataTagged& other);
137
138	/**
139	\brief
140	Copy Constructor for DataTagged.
141	Construct a DataTagged object from a DataConstant object.
142	The default value will be the value of the DataConstant object.
143	T
144	*/
145	ESCRIPT_DLL_API
146	DataTagged(const DataConstant& other);
147
148	/**
149	\brief
150	Copies the tags from a DataTagged into a new Data Tagged and assigns them the default value. Not unit tested
151
152	This is different from a deep copy because we are not copying shape or other information, just tags.
153	\param what - Input - FunctionSpace for the new DataTagged
154	\param shape - Input - Shape for points in the new DataTagged
155	\param defaultvalue - Input - Default value for new DataTagged
156	\param tagsource - Input - A DataTagged object which supplies the tags.
157	*/
158	ESCRIPT_DLL_API
159	DataTagged(const FunctionSpace& what,
160	const DataTypes::ShapeType& shape,
161	const DataTypes::ValueType& defaultvalue,
162	const DataTagged& tagsource);
163
164
165
166	/**
167	\brief
168	Destructor
169	*/
170	ESCRIPT_DLL_API
171	inline virtual
172	~DataTagged() {};
173
174	/**
175	\brief
176	getSampleDataByTag
177
178	Description:
179	Return the data-point for the given tag. All of the data for the
180	sample will be visible via the returned pointer.
181
182	** This provides an interface into the data suitable for legacy C code.
183	** NB: need to do array bounds checking when accessing returned value!
184	T
185	*/
186	ESCRIPT_DLL_API
187	virtual
188	double*
189	getSampleDataByTag(int tag);
190
191	/**
192	\brief
193	Write the data as a string.
194	Writes out each tag, including the default, and the data-point which is
195	associated with each tag.
196	T
197	*/
198	ESCRIPT_DLL_API
199	virtual
200	std::string
201	toString() const;
202	/**
203	\brief
204	dumps the object into a netCDF file
205	*/
206	ESCRIPT_DLL_API
207	virtual
208	void
209	dump(const std::string fileName) const;
210
211	/**
212	\brief
213	sets all values to zero
214	*/
215	ESCRIPT_DLL_API
216	virtual
217	void
218	setToZero();
219
220	/**
221	\brief
222	Return the tag number associated with the given data-point number
223	according to the associated function space.
224	T
225	*/
226	ESCRIPT_DLL_API
227	virtual
228	int
229	getTagNumber(int dpno);
230
231	/**
232	\brief
233	getPointOffset
234
235	Description:
236	Return the offset to the given data-point value in the underlying
237	data vector.
238
239	\param sampleNo - Input - sample number.
240	\param dataPointNo - Input - data-point number.
241	T
242	*/
243	ESCRIPT_DLL_API
244	virtual
245	ValueType::size_type
246	getPointOffset(int sampleNo,
247	int dataPointNo) const;
248
249
250
251	/**
252	\brief
253	addTaggedValues
254
255	Description:
256	Add the given tags and values to this DataTagged object.
257	\param tagKeys - Input - A vector of integer tags.
258	\param values - Input - A vector of DataArrayViews. If this is empty
259	all tag values will be assigned a scalar data-point of value
260	0. If it contains one value all tag values will be assigned
261	this value. Otherwise consecutive tags will be assigned
262	consecutive values. If there is a mismatch between the
263	number of keys and the number of values an exception
264	will be generated.
265	T
266	*/
267	ESCRIPT_DLL_API
268	void
269	addTaggedValues(const TagListType& tagKeys,
270	const ValueListType& values);
271
272	/**
273	\brief
274	addTaggedValue
275
276	Description:
277	Add a single tag and value to this DataTagged object. If this tag already has
278	a value associated with it, setTaggedValue will be used to update this value.
279	\param tagKey - Input - Integer tag.
280	\param value - Input - Single DataArrayView value to be assigned to the tag.
281	T
282	*/
283	ESCRIPT_DLL_API
284	void
285	addTaggedValue(int tagKey,
286	const DataArrayView& value);
287
288	/**
289	\brief
290	addTaggedValue
291
292	Description:
293	Add a single tag and value to this DataTagged object. If this tag already has
294	a value associated with it, setTaggedValue will be used to update this value.
295	\param tagKey - Input - Integer tag.
296	\param pointshape - Shape of the value parameter
297	\param value - Input - Single DataArrayView value to be assigned to the tag.
298	\param dataOffset - Input - Offset of the beginning of the point in the value parameter
299	*/
300	ESCRIPT_DLL_API
301	void
302	addTaggedValue(int tagKey,
303	const DataTypes::ShapeType& pointshape,
304	const ValueType& value,
305	int dataOffset=0);
306
307	/**
308	\brief
309	addTag - does not modify the default value for this object. Not unit tested
310
311	Description:
312	Add a single tag. The default value for this DataTagged will be associated with the tag.
313	If this tag already has a value associated with it, then no change will be made.
314	\param tagKey - Input - Integer tag.
315	T
316	*/
317	ESCRIPT_DLL_API
318	void
319	addTag(int tagKey);
320
321
322	/**
323	\brief
324	setTaggedValues
325
326	Description:
327	Set the given tags to the given values in this DataTagged object.
328	\param tagKeys - Input - A vector of integer tag.
329	\param values - Input - A vector of DataArrayViews. If this is empty
330	all tag values will be assigned a scalar data-point of value
331	0. If it contains one value all tag values will be assigned
332	this value. Otherwise consecutive tags will be assigned
333	consecutive values. If there is a mismatch between the
334	number of keys and the number of values an exception
335	will be generated.
336	T
337	*/
338	ESCRIPT_DLL_API
339	void
340	setTaggedValues(const TagListType& tagKeys,
341	const ValueListType& values);
342
343	/**
344	\brief
345	setTaggedValue
346
347	Description:
348	Assign the given value to the given tag.
349	\param tagKey - Input - Integer tag.
350	\param value - Input - Single DataArrayView value to be assigned to the tag.
351	T
352	*/
353	ESCRIPT_DLL_API
354	virtual
355	void
356	setTaggedValue(int tagKey,
357	const DataArrayView& value);
358
359	/**
360	\brief
361	setTaggedValue
362
363	Description:
364	Assign the given value to the given tag.
365	\param tagKey - Input - Integer tag.
366	\param pointshape - the shape of the value parameter
367	\param value - Input - Single DataArrayView value to be assigned to the tag.
368	T
369	*/
370	ESCRIPT_DLL_API
371	void
372	setTaggedValue(int tagKey,
373	const DataTypes::ShapeType& pointshape,
374	const ValueType& value,
375	int dataOffset=0);
376
377
378	/**
379	\brief
380	getDataPointByTag
381
382	Description:
383	Return data-point associated with the given tag as a DataArrayView.
384	\param tag - Input - Integer key.
385	T
386	*/
387	ESCRIPT_DLL_API
388	DataArrayView
389	getDataPointByTag(int tag) const;
390
391	/**
392	\brief
393	getDataByTag
394
395	Return a pointer to the beginning of the datapoint with the specified tag.
396	TODO Eventually these should be inlined.
397	\param tag - Input - Integer key.
398	\param i - position in the underlying datastructure
399	T
400	*/
401	ESCRIPT_DLL_API
402	DataTypes::ValueType::const_reference
403	getDataByTag(int tag, DataTypes::ValueType::size_type i) const;
404
405	ESCRIPT_DLL_API
406	DataTypes::ValueType::reference
407	getDataByTag(int tag, DataTypes::ValueType::size_type i);
408
409
410	/**
411	\brief
412	getDataPoint
413
414	Description:
415	Return the data-point specified by the given sample and data-point
416	numbers as a DataArrayView.
417	\param sampleNo - Input.
418	\param dataPointNo - Input.
419	T
420	*/
421	ESCRIPT_DLL_API
422	virtual
423	DataArrayView
424	getDataPoint(int sampleNo,
425	int dataPointNo);
426
427	/**
428	\brief
429	getData
430
431	Description:
432	Return pointer to the data
433	T
434	*/
435	ESCRIPT_DLL_API
436	const DataTypes::ValueType::ElementType*
437	getData() const;
438
439	/**
440	\brief
441	getTagLookup
442
443	Description:
444	Return a reference to the tag offset lookup table.
445	T
446	*/
447	ESCRIPT_DLL_API
448	const DataMapType&
449	getTagLookup() const;
450
451	/**
452	\brief
453	isCurrentTag
454
455	Description:
456	Return true if the given tag exists within the DataTagged tag map.
457
458	*** NB: The DataTagged tag map does not necessarily coincide with the tag
459	keys in the associated function space.
460	T
461	*/
462	ESCRIPT_DLL_API
463	bool
464	isCurrentTag(int tag) const;
465
466	/**
467	\brief
468	getDefaultValue
469
470	Description:
471	Return the default value. This value is associated with any tag which
472	is not explicitly recorded in this DataTagged object's tag map.
473	T
474	*/
475	ESCRIPT_DLL_API
476	DataArrayView&
477	getDefaultValue();
478
479	ESCRIPT_DLL_API
480	const DataArrayView&
481	getDefaultValue() const;
482
483	/**
484	\brief
485	getDefaultValue
486
487	Description:
488	Return the default value. This value is associated with any tag which
489	is not explicitly recorded in this DataTagged object's tag map.
490	\param i - position in the underlying datastructure
491	T
492	*/
493	ESCRIPT_DLL_API
494	DataTypes::ValueType::reference
495	getDefaultValue(DataTypes::ValueType::size_type i);
496
497	ESCRIPT_DLL_API
498	DataTypes::ValueType::const_reference
499	getDefaultValue(DataTypes::ValueType::size_type i) const;
500
501
502
503
504	/**
505	\brief
506	getLength
507
508	Description:
509	Return the total number of doubles stored for this DataTagged object.
510	T
511	*/
512	ESCRIPT_DLL_API
513	virtual
514	ValueType::size_type
515	getLength() const;
516
517	/**
518	\brief
519	getSlice
520
521	Description:
522	Factory method that returns a newly created DataTagged object generated
523	by taking the specified slice from this DataTagged object.
524	The caller is reponsible for managing the returned object.
525	T
526	*/
527	ESCRIPT_DLL_API
528	virtual
529	DataAbstract*
530	getSlice(const DataTypes::RegionType& region) const;
531
532	/**
533	\brief
534	Slice Constructor for DataTagged.
535
536	Description:
537	Creates a DataTagged object which is the specified slice
538	from the given DataTagged object.
539	\param other - Input - DataTagged object to slice from.
540	\param region - Input - Region to slice.
541	T
542	*/
543	ESCRIPT_DLL_API
544	DataTagged(const DataTagged& other,
545	const DataTypes::RegionType& region);
546
547	/**
548	\brief
549	setSlice
550
551	Description:
552	Copy the given Data object into the specified region in this object.
553	\param other - Input - Data object to copy from.
554	\param region - Input - Region to copy into (NB: must have same shape as other!).
555	T
556	*/
557	ESCRIPT_DLL_API
558	virtual
559	void
560	setSlice(const DataAbstract* other,
561	const DataTypes::RegionType& region);
562
563	/**
564	\brief
565	Archive the underlying data values to the file referenced
566	by ofstream. A count of the number of values expected to be written
567	is provided as a cross-check.
568
569	The return value indicates success (0) or otherwise (1).
570	*/
571	ESCRIPT_DLL_API
572	int
573	archiveData(std::ofstream& archiveFile,
574	const DataTypes::ValueType::size_type noValues) const;
575
576	/**
577	\brief
578	Extract the number of values specified by noValues from the file
579	referenced by ifstream to the underlying data structure.
580
581	The return value indicates success (0) or otherwise (1).
582	*/
583	ESCRIPT_DLL_API
584	int
585	extractData(std::ifstream& archiveFile,
586	const DataTypes::ValueType::size_type noValues);
587
588	/**
589	\brief
590	Computes a symmetric matrix (A + AT) / 2
591
592	\param ev - Output - symmetric matrix
593
594	*/
595	ESCRIPT_DLL_API
596	virtual void
597	symmetric(DataAbstract* ev);
598
599	/**
600	\brief
601	Computes a nonsymmetric matrix (A - AT) / 2
602
603	\param ev - Output - nonsymmetric matrix
604
605	*/
606	ESCRIPT_DLL_API
607	virtual void
608	nonsymmetric(DataAbstract* ev);
609
610	/**
611	\brief
612	Computes the trace of a matrix
613
614	\param ev - Output - the trace of a matrix
615
616	*/
617	ESCRIPT_DLL_API
618	virtual void
619	trace(DataAbstract* ev, int axis_offset);
620
621	/**
622	\brief
623	swaps components axis0 and axis1
624
625	\param ev - Output - swapped components
626
627	*/
628	ESCRIPT_DLL_API
629	virtual void
630	swapaxes(DataAbstract* ev, int axis0, int axis1);
631
632	/**
633	\brief
634	Transpose each data point of this Data object around the given axis.
635
636	\param ev - Output - the transpose of a matrix
637
638	*/
639	ESCRIPT_DLL_API
640	virtual void
641	transpose(DataAbstract* ev, int axis_offset);
642
643	/**
644	\brief
645	solves the eigenvalue problem thisV=evV for the eigenvalues ev
646
647	\param ev - Output - eigenvalues in increasing order at each data point
648
649	*/
650	ESCRIPT_DLL_API
651	virtual void
652	eigenvalues(DataAbstract* ev);
653
654	/**
655	\brief
656	solves the eigenvalue problem thisV=evV for the eigenvalues ev and eigenvectors V
657
658	\param ev - Output - eigenvalues in increasing order at each data point
659	\param V - Output - corresponding eigenvectors. They are normalized such that their length is one
660	and the first nonzero component is positive.
661	\param tol - Input - eigenvalue with relative distance tol are treated as equal.
662
663	*/
664
665	ESCRIPT_DLL_API
666	virtual void
667	eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
668
669
670	protected:
671
672	private:
673
674	//
675	// The offset lookup table
676	DataMapType m_offsetLookup;
677
678	//
679	// the offset to the default value
680	static const int m_defaultValueOffset = 0;
681
682	//
683	// The actual data
684	ValueType m_data;
685
686	};
687
688	inline
689	bool
690	DataTagged::isCurrentTag(int tag) const
691	{
692	DataMapType::const_iterator pos(m_offsetLookup.find(tag));
693	return (pos!=m_offsetLookup.end());
694	}
695
696	inline
697	DataArrayView&
698	DataTagged::getDefaultValue()
699	{
700	// The default value is always the first value.
701	return getPointDataView();
702	}
703
704	inline
705	const DataArrayView&
706	DataTagged::getDefaultValue() const
707	{
708	// The default value is always the first value.
709	return getPointDataView();
710	}
711
712	inline
713	DataTypes::ValueType::reference
714	DataTagged::getDefaultValue(DataTypes::ValueType::size_type i)
715	{
716	return getPointDataView().getData()[i];
717	}
718
719	inline
720	DataTypes::ValueType::const_reference
721	DataTagged::getDefaultValue(DataTypes::ValueType::size_type i) const
722	{
723	return getPointDataView().getData()[i];
724	}
725
726
727
728
729	inline
730	const DataTypes::ValueType::ElementType*
731	DataTagged::getData() const
732	{
733	return &(m_data[0]);
734	}
735
736	inline
737	const DataTagged::DataMapType&
738	DataTagged::getTagLookup() const
739	{
740	return m_offsetLookup;
741	}
742
743	inline
744	DataTypes::ValueType::size_type
745	DataTagged::getLength() const
746	{
747	return m_data.size();
748	}
749
750	} // end of namespace
751
752	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision