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
     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
     addTag - does not modify the default value for this object.

     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
     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	Destructor
151	*/
152	ESCRIPT_DLL_API
153	inline virtual
154	~DataTagged() {};
155
156	/**
157	\brief
158	getSampleDataByTag
159
160	Description:
161	Return the data-point for the given tag. All of the data for the
162	sample will be visible via the returned pointer.
163
164	** This provides an interface into the data suitable for legacy C code.
165	** NB: need to do array bounds checking when accessing returned value!
166	T
167	*/
168	ESCRIPT_DLL_API
169	virtual
170	double*
171	getSampleDataByTag(int tag);
172
173	/**
174	\brief
175	Write the data as a string.
176	Writes out each tag, including the default, and the data-point which is
177	associated with each tag.
178	T
179	*/
180	ESCRIPT_DLL_API
181	virtual
182	std::string
183	toString() const;
184	/**
185	\brief
186	dumps the object into a netCDF file
187	*/
188	ESCRIPT_DLL_API
189	virtual
190	void
191	dump(const std::string fileName) const;
192
193	/**
194	\brief
195	sets all values to zero
196	*/
197	ESCRIPT_DLL_API
198	virtual
199	void
200	setToZero();
201
202	/**
203	\brief
204	Return the tag number associated with the given data-point number
205	according to the associated function space.
206	T
207	*/
208	ESCRIPT_DLL_API
209	virtual
210	int
211	getTagNumber(int dpno);
212
213	/**
214	\brief
215	getPointOffset
216
217	Description:
218	Return the offset to the given data-point value in the underlying
219	data vector.
220
221	\param sampleNo - Input - sample number.
222	\param dataPointNo - Input - data-point number.
223	T
224	*/
225	ESCRIPT_DLL_API
226	virtual
227	ValueType::size_type
228	getPointOffset(int sampleNo,
229	int dataPointNo) const;
230
231
232
233	/**
234	\brief
235	addTaggedValues
236
237	Description:
238	Add the given tags and values to this DataTagged object.
239	\param tagKeys - Input - A vector of integer tags.
240	\param values - Input - A vector of DataArrayViews. If this is empty
241	all tag values will be assigned a scalar data-point of value
242	0. If it contains one value all tag values will be assigned
243	this value. Otherwise consecutive tags will be assigned
244	consecutive values. If there is a mismatch between the
245	number of keys and the number of values an exception
246	will be generated.
247	T
248	*/
249	ESCRIPT_DLL_API
250	void
251	addTaggedValues(const TagListType& tagKeys,
252	const ValueListType& values);
253
254	/**
255	\brief
256	addTaggedValue
257
258	Description:
259	Add a single tag and value to this DataTagged object. If this tag already has
260	a value associated with it, setTaggedValue will be used to update this value.
261	\param tagKey - Input - Integer tag.
262	\param value - Input - Single DataArrayView value to be assigned to the tag.
263	T
264	*/
265	ESCRIPT_DLL_API
266	void
267	addTaggedValue(int tagKey,
268	const DataArrayView& value);
269
270	/**
271	\brief
272	addTag - does not modify the default value for this object.
273
274	Description:
275	Add a single tag. The default value for this DataTagged will be associated with the tag.
276	If this tag already has a value associated with it, then no change will be made.
277	\param tagKey - Input - Integer tag.
278	T
279	*/
280	ESCRIPT_DLL_API
281	void
282	addTag(int tagKey);
283
284
285	/**
286	\brief
287	setTaggedValues
288
289	Description:
290	Set the given tags to the given values in this DataTagged object.
291	\param tagKeys - Input - A vector of integer tag.
292	\param values - Input - A vector of DataArrayViews. If this is empty
293	all tag values will be assigned a scalar data-point of value
294	0. If it contains one value all tag values will be assigned
295	this value. Otherwise consecutive tags will be assigned
296	consecutive values. If there is a mismatch between the
297	number of keys and the number of values an exception
298	will be generated.
299	T
300	*/
301	ESCRIPT_DLL_API
302	void
303	setTaggedValues(const TagListType& tagKeys,
304	const ValueListType& values);
305
306	/**
307	\brief
308	setTaggedValue
309
310	Description:
311	Assign the given value to the given tag.
312	\param tagKey - Input - Integer tag.
313	\param value - Input - Single DataArrayView value to be assigned to the tag.
314	T
315	*/
316	ESCRIPT_DLL_API
317	virtual
318	void
319	setTaggedValue(int tagKey,
320	const DataArrayView& value);
321
322	/**
323	\brief
324	getDataPointByTag
325
326	Description:
327	Return data-point associated with the given tag as a DataArrayView.
328	\param tag - Input - Integer key.
329	T
330	*/
331	ESCRIPT_DLL_API
332	DataArrayView
333	getDataPointByTag(int tag) const;
334
335	/**
336	\brief
337	getDataByTag
338
339	Return a pointer to the beginning of the datapoint with the specified tag.
340	TODO Eventually these should be inlined.
341	\param tag - Input - Integer key.
342	\param i - position in the underlying datastructure
343	T
344	*/
345	ESCRIPT_DLL_API
346	DataTypes::ValueType::const_reference
347	getDataByTag(int tag, DataTypes::ValueType::size_type i) const;
348
349	ESCRIPT_DLL_API
350	DataTypes::ValueType::reference
351	getDataByTag(int tag, DataTypes::ValueType::size_type i);
352
353
354	/**
355	\brief
356	getDataPoint
357
358	Description:
359	Return the data-point specified by the given sample and data-point
360	numbers as a DataArrayView.
361	\param sampleNo - Input.
362	\param dataPointNo - Input.
363	T
364	*/
365	ESCRIPT_DLL_API
366	virtual
367	DataArrayView
368	getDataPoint(int sampleNo,
369	int dataPointNo);
370
371	/**
372	\brief
373	getData
374
375	Description:
376	Return pointer to the data
377	T
378	*/
379	ESCRIPT_DLL_API
380	const DataTypes::ValueType::ElementType*
381	getData() const;
382
383	/**
384	\brief
385	getTagLookup
386
387	Description:
388	Return a reference to the tag offset lookup table.
389	T
390	*/
391	ESCRIPT_DLL_API
392	const DataMapType&
393	getTagLookup() const;
394
395	/**
396	\brief
397	isCurrentTag
398
399	Description:
400	Return true if the given tag exists within the DataTagged tag map.
401
402	*** NB: The DataTagged tag map does not necessarily coincide with the tag
403	keys in the associated function space.
404	T
405	*/
406	ESCRIPT_DLL_API
407	bool
408	isCurrentTag(int tag) const;
409
410	/**
411	\brief
412	getDefaultValue
413
414	Description:
415	Return the default value. This value is associated with any tag which
416	is not explicitly recorded in this DataTagged object's tag map.
417	T
418	*/
419	ESCRIPT_DLL_API
420	DataArrayView&
421	getDefaultValue();
422
423	ESCRIPT_DLL_API
424	const DataArrayView&
425	getDefaultValue() const;
426
427	/**
428	\brief
429	getDefaultValue
430
431	Description:
432	Return the default value. This value is associated with any tag which
433	is not explicitly recorded in this DataTagged object's tag map.
434	\param i - position in the underlying datastructure
435	T
436	*/
437	ESCRIPT_DLL_API
438	DataTypes::ValueType::reference
439	getDefaultValue(DataTypes::ValueType::size_type i);
440
441	ESCRIPT_DLL_API
442	DataTypes::ValueType::const_reference
443	getDefaultValue(DataTypes::ValueType::size_type i) const;
444
445
446
447
448	/**
449	\brief
450	getLength
451
452	Description:
453	Return the total number of doubles stored for this DataTagged object.
454	T
455	*/
456	ESCRIPT_DLL_API
457	virtual
458	ValueType::size_type
459	getLength() const;
460
461	/**
462	\brief
463	getSlice
464
465	Description:
466	Factory method that returns a newly created DataTagged object generated
467	by taking the specified slice from this DataTagged object.
468	The caller is reponsible for managing the returned object.
469	T
470	*/
471	ESCRIPT_DLL_API
472	virtual
473	DataAbstract*
474	getSlice(const DataTypes::RegionType& region) const;
475
476	/**
477	\brief
478	Slice Constructor for DataTagged.
479
480	Description:
481	Creates a DataTagged object which is the specified slice
482	from the given DataTagged object.
483	\param other - Input - DataTagged object to slice from.
484	\param region - Input - Region to slice.
485	T
486	*/
487	ESCRIPT_DLL_API
488	DataTagged(const DataTagged& other,
489	const DataTypes::RegionType& region);
490
491	/**
492	\brief
493	setSlice
494
495	Description:
496	Copy the given Data object into the specified region in this object.
497	\param other - Input - Data object to copy from.
498	\param region - Input - Region to copy into (NB: must have same shape as other!).
499	T
500	*/
501	ESCRIPT_DLL_API
502	virtual
503	void
504	setSlice(const DataAbstract* other,
505	const DataTypes::RegionType& region);
506
507	/**
508	\brief
509	Archive the underlying data values to the file referenced
510	by ofstream. A count of the number of values expected to be written
511	is provided as a cross-check.
512
513	The return value indicates success (0) or otherwise (1).
514	*/
515	ESCRIPT_DLL_API
516	int
517	archiveData(std::ofstream& archiveFile,
518	const DataTypes::ValueType::size_type noValues) const;
519
520	/**
521	\brief
522	Extract the number of values specified by noValues from the file
523	referenced by ifstream to the underlying data structure.
524
525	The return value indicates success (0) or otherwise (1).
526	*/
527	ESCRIPT_DLL_API
528	int
529	extractData(std::ifstream& archiveFile,
530	const DataTypes::ValueType::size_type noValues);
531
532	/**
533	\brief
534	Computes a symmetric matrix (A + AT) / 2
535
536	\param ev - Output - symmetric matrix
537
538	*/
539	ESCRIPT_DLL_API
540	virtual void
541	symmetric(DataAbstract* ev);
542
543	/**
544	\brief
545	Computes a nonsymmetric matrix (A - AT) / 2
546
547	\param ev - Output - nonsymmetric matrix
548
549	*/
550	ESCRIPT_DLL_API
551	virtual void
552	nonsymmetric(DataAbstract* ev);
553
554	/**
555	\brief
556	Computes the trace of a matrix
557
558	\param ev - Output - the trace of a matrix
559
560	*/
561	ESCRIPT_DLL_API
562	virtual void
563	trace(DataAbstract* ev, int axis_offset);
564
565	/**
566	\brief
567	swaps components axis0 and axis1
568
569	\param ev - Output - swapped components
570
571	*/
572	ESCRIPT_DLL_API
573	virtual void
574	swapaxes(DataAbstract* ev, int axis0, int axis1);
575
576	/**
577	\brief
578	Transpose each data point of this Data object around the given axis.
579
580	\param ev - Output - the transpose of a matrix
581
582	*/
583	ESCRIPT_DLL_API
584	virtual void
585	transpose(DataAbstract* ev, int axis_offset);
586
587	/**
588	\brief
589	solves the eigenvalue problem thisV=evV for the eigenvalues ev
590
591	\param ev - Output - eigenvalues in increasing order at each data point
592
593	*/
594	ESCRIPT_DLL_API
595	virtual void
596	eigenvalues(DataAbstract* ev);
597
598	/**
599	\brief
600	solves the eigenvalue problem thisV=evV for the eigenvalues ev and eigenvectors V
601
602	\param ev - Output - eigenvalues in increasing order at each data point
603	\param V - Output - corresponding eigenvectors. They are normalized such that their length is one
604	and the first nonzero component is positive.
605	\param tol - Input - eigenvalue with relative distance tol are treated as equal.
606
607	*/
608
609	ESCRIPT_DLL_API
610	virtual void
611	eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
612
613
614	protected:
615
616	private:
617
618	//
619	// The offset lookup table
620	DataMapType m_offsetLookup;
621
622	//
623	// the offset to the default value
624	static const int m_defaultValueOffset = 0;
625
626	//
627	// The actual data
628	ValueType m_data;
629
630	};
631
632	inline
633	bool
634	DataTagged::isCurrentTag(int tag) const
635	{
636	DataMapType::const_iterator pos(m_offsetLookup.find(tag));
637	return (pos!=m_offsetLookup.end());
638	}
639
640	inline
641	DataArrayView&
642	DataTagged::getDefaultValue()
643	{
644	// The default value is always the first value.
645	return getPointDataView();
646	}
647
648	inline
649	const DataArrayView&
650	DataTagged::getDefaultValue() const
651	{
652	// The default value is always the first value.
653	return getPointDataView();
654	}
655
656	inline
657	DataTypes::ValueType::reference
658	DataTagged::getDefaultValue(DataTypes::ValueType::size_type i)
659	{
660	return getPointDataView().getData()[i];
661	}
662
663	inline
664	DataTypes::ValueType::const_reference
665	DataTagged::getDefaultValue(DataTypes::ValueType::size_type i) const
666	{
667	return getPointDataView().getData()[i];
668	}
669
670
671
672
673	inline
674	const DataTypes::ValueType::ElementType*
675	DataTagged::getData() const
676	{
677	return &(m_data[0]);
678	}
679
680	inline
681	const DataTagged::DataMapType&
682	DataTagged::getTagLookup() const
683	{
684	return m_offsetLookup;
685	}
686
687	inline
688	DataTypes::ValueType::size_type
689	DataTagged::getLength() const
690	{
691	return m_data.size();
692	}
693
694	} // end of namespace
695
696	#endif
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision