/[escript]/trunk/escript/src/DataAbstract.h
ViewVC logotype

Diff of /trunk/escript/src/DataAbstract.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

trunk/esys2/escript/src/Data/DataAbstract.h revision 106 by jgs, Thu Dec 23 07:20:12 2004 UTC trunk/escript/src/DataAbstract.h revision 1358 by gross, Wed Dec 5 03:41:06 2007 UTC
# Line 1  Line 1 
1  // $Id$  /* $Id$ */
2  /*  
3   ******************************************************************************  /*******************************************************
4   *                                                                            *   *
5   *       COPYRIGHT  ACcESS 2004 -  All Rights Reserved                        *   *           Copyright 2003-2007 by ACceSS MNRF
6   *                                                                            *   *       Copyright 2007 by University of Queensland
7   * This software is the property of ACcESS. No part of this code              *   *
8   * may be copied in any form or by any means without the expressed written    *   *                http://esscc.uq.edu.au
9   * consent of ACcESS.  Copying, use or modification of this software          *   *        Primary Business: Queensland, Australia
10   * by any unauthorised person is illegal unless that person has a software    *   *  Licensed under the Open Software License version 3.0
11   * license agreement with ACcESS.                                             *   *     http://www.opensource.org/licenses/osl-3.0.php
12   *                                                                            *   *
13   ******************************************************************************   *******************************************************/
14  */  
                                                                             
15  #if !defined escript_DataAbstract_20040315_H  #if !defined escript_DataAbstract_20040315_H
16  #define escript_DataAbstract_20040315_H  #define escript_DataAbstract_20040315_H
17    #include "system_dep.h"
18    
19  #include "escript/Data/DataException.h"  #include "DataArrayView.h"
20  #include "escript/Data/DataArrayView.h"  #include "FunctionSpace.h"
 #include "escript/Data/FunctionSpace.h"  
21    
 #include <iostream>  
22  #include <boost/scoped_ptr.hpp>  #include <boost/scoped_ptr.hpp>
23  #include <functional>  #include <boost/python/numeric.hpp>
24    
25  #include <string>  #include <string>
26    #include <fstream>
27    
28  namespace escript {  namespace escript {
29    
30  /**  /**
31     \brief     \brief
32     DataAbstract provides an interface for the class of containers     DataAbstract provides an abstract interface for the class of containers
33     which hold ESyS data.     which hold ESyS data.
34    
35     Description:     Description:
36     DataAbstract provides an interface for the class of containers     DataAbstract provides an abstract interface for the class of containers
37     which hold ESyS data. The container may be thought of as a 2 dimensional     which hold ESyS data. The container may be thought of as a 2 dimensional
38     array of data points. The data points themselves are arrays of rank 0-4.     array of data points where one dimension corresponds to the number of samples
39       and the other to the number of data points per sample as defined by the function
40       space associated with each Data object. The data points themselves are arrays of
41       doubles of rank 0-4.
42  */  */
43    
44  class DataAbstract {  class DataAbstract {
# Line 51  class DataAbstract { Line 54  class DataAbstract {
54    
55       Description:       Description:
56       Constructor for DataAbstract.       Constructor for DataAbstract.
57    
58       \param what - Input - A description of what this data represents.       \param what - Input - A description of what this data represents.
59    */    */
60      ESCRIPT_DLL_API
61    DataAbstract(const FunctionSpace& what);    DataAbstract(const FunctionSpace& what);
62    
63    /**    /**
64      \brief      \brief
65      Destructor for DataAbstract.      Destructor for DataAbstract.
66    */    */
67      ESCRIPT_DLL_API
68    virtual    virtual
69    ~DataAbstract();    ~DataAbstract();
70    
# Line 66  class DataAbstract { Line 72  class DataAbstract {
72       \brief       \brief
73       Write the data as a string.       Write the data as a string.
74    */    */
75      ESCRIPT_DLL_API
76    virtual    virtual
77    std::string    std::string
78    toString() const = 0;    toString() const = 0;
79    
80     /**
81         \brief
82         dumps the object into a netCDF file
83      */
84      ESCRIPT_DLL_API
85      virtual
86      void
87      dump(const std::string fileName) const;
88    
89    /**    /**
90       \brief       \brief
91       Return the number of data points per sample.       Return the number of data points per sample.
92    */    */
93      ESCRIPT_DLL_API
94    int    int
95    getNumDPPSample() const;    getNumDPPSample() const;
96    
# Line 81  class DataAbstract { Line 98  class DataAbstract {
98       \brief       \brief
99       Return the number of samples.       Return the number of samples.
100    */    */
101      ESCRIPT_DLL_API
102    int    int
103    getNumSamples() const;    getNumSamples() const;
104    
105    /**    /**
106       \brief       \brief
107       Return the DataArrayView of the point data. This essentially contains       Return the DataArrayView of the point data. This essentially contains
108       the shape information for each data point although it also may be used       the shape information for each data point although it also may be used
109       to manipulate the point data.       to manipulate the point data.
110    */    */
111    const DataArrayView&    ESCRIPT_DLL_API
   getPointDataView() const;  
   
112    DataArrayView&    DataArrayView&
113    getPointDataView();    getPointDataView();
114    
115      ESCRIPT_DLL_API
116      const DataArrayView&
117      getPointDataView() const;
118    
119    /**    /**
120       \brief       \brief
121       Return the offset for the given sample. This is somewhat artificial notion       Return the offset for the given sample. This returns the offset for the given
122       but returns the offset for the given point into the container       point into the container holding the point data. Only really necessary to
123       holding the point data. Only really necessary to avoid many DataArrayView       avoid creating many DataArrayView objects.
124       objects.  
125       \param sampleNo - Input - sample number.       \param sampleNo - Input - sample number.
126       \param dataPointNo - Input - Input.       \param dataPointNo - Input - data point number.
127     */     */
128      ESCRIPT_DLL_API
129    virtual    virtual
130    ValueType::size_type    ValueType::size_type
131    getPointOffset(int sampleNo,    getPointOffset(int sampleNo,
# Line 112  class DataAbstract { Line 133  class DataAbstract {
133    
134    /**    /**
135       \brief       \brief
136       Return the sample data for the given sample no.       Return the sample data for the given sample number.
137    */    */
138      ESCRIPT_DLL_API
139    double*    double*
140    getSampleData(ValueType::size_type sampleNo);    getSampleData(ValueType::size_type sampleNo);
141    
142    /**    /**
143       \brief       \brief
144       Return the number of doubles stored for the Data.       Return the number of doubles stored for this Data object.
145    */    */
146      ESCRIPT_DLL_API
147    virtual    virtual
148    ValueType::size_type    ValueType::size_type
149    getLength() const = 0;    getLength() const = 0;
# Line 130  class DataAbstract { Line 153  class DataAbstract {
153       Return the sample data for the given tag key.       Return the sample data for the given tag key.
154       NB: If the data isn't tagged an exception will be thrown.       NB: If the data isn't tagged an exception will be thrown.
155    */    */
156      ESCRIPT_DLL_API
157    virtual    virtual
158    double*    double*
159    getSampleDataByTag(int tag);    getSampleDataByTag(int tag);
160    
161    
162    /**    /**
163       \brief       \brief
164       Check this and the right operands are compatible. Throws       Check this and the given RHS operands are compatible. Throws
165       an exception if they aren't.       an exception if they aren't.
166    
167       \param right - Input - The right hand side.       \param right - Input - The right hand side.
168    */    */
169      ESCRIPT_DLL_API
170    void    void
171    operandCheck(const DataAbstract& right) const;    operandCheck(const DataAbstract& right) const;
172    
# Line 147  class DataAbstract { Line 174  class DataAbstract {
174       \brief       \brief
175       Return true if a valid sample point number.       Return true if a valid sample point number.
176    */    */
177      ESCRIPT_DLL_API
178    bool    bool
179    validSamplePointNo(int samplePointNo) const;    validSamplePointNo(int samplePointNo) const;
180    
181    /**    /**
182       \brief       \brief
183       Return true if a valid number.       Return true if a valid sample number.
184    */    */
185      ESCRIPT_DLL_API
186    bool    bool
187    validSampleNo(int sampleNo) const;    validSampleNo(int sampleNo) const;
188    
189    /**    /**
190       \brief       \brief
191       Return a view into the data for the data point specified.       Return a view into the data for the data point specified.
192       NOTE: Construction of the DataArrayView is a relatively expensive       NOTE: Construction of the DataArrayView is a relatively expensive
193       operation.       operation.
194       \param samplesNo Input  
195       \param dataPointNo Input       \param sampleNo - Input - the sample number.
196         \param dataPointNo - Input - the data point number.
197    */    */
198      ESCRIPT_DLL_API
199    virtual    virtual
200    DataArrayView    DataArrayView
201    getDataPoint(int samplesNo,    getDataPoint(int sampleNo,
202                 int dataPointNo) = 0;                 int dataPointNo) = 0;
203    
204    /**    /**
205       \brief       \brief
206       Return the function space.       Return the function space associated with this Data object.
207    */    */
208    const FunctionSpace&    ESCRIPT_DLL_API
209      const
210      FunctionSpace&
211    getFunctionSpace() const;    getFunctionSpace() const;
212    
213    /**    /**
214       \brief       \brief
215       Return a newly constructed DataAbstract. The caller is responsible for       Return the given slice from this object.
216       managing the object created.  
217         NB: The caller is responsible for managing the object created.
218    */    */
219      ESCRIPT_DLL_API
220    virtual    virtual
221    DataAbstract*    DataAbstract*
222    getSlice(const DataArrayView::RegionType& region) const = 0;    getSlice(const DataArrayView::RegionType& region) const = 0;
223    
224    /**    /**
225       \brief       \brief
226       Copy the specified region from the given value.       Copy the specified region from the given object.
227    
228       \param value - Input - Data to copy from       \param value - Input - Data to copy from
229       \param region - Input - Region to copy.       \param region - Input - Region to copy.
230    */    */
231      ESCRIPT_DLL_API
232    virtual    virtual
233    void    void
234    setSlice(const DataAbstract* value,    setSlice(const DataAbstract* value,
235             const DataArrayView::RegionType& region) = 0;             const DataArrayView::RegionType& region) = 0;
236    
   /**  
      \brief  
      Reshape the data point if the data point is currently rank 0.  
      Will throw an exception if the data points are not rank 0.  
      The original data point value is used for all values of the new  
      data point.  
   */  
   virtual  
   void  
   reshapeDataPoint(const DataArrayView::ShapeType& shape) = 0;  
237    
238    /**    /**
239       \brief       \brief
240       setTaggedValue       setTaggedValue
241                                                                                                                                      
242       Description:       Description:
243       Assign the given value to the given tag.       Assign the given value to the given tag.
244    
245         NB: If the data isn't tagged an exception will be thrown.
246    
247       \param tagKey - Input - Integer key.       \param tagKey - Input - Integer key.
248       \param value - Input - Single DataArrayView value to be assigned to the tag.       \param value - Input - Single DataArrayView value to be assigned to the tag.
      NB: If the data isn't tagged an exception will be thrown.  
249    */    */
250      ESCRIPT_DLL_API
251    virtual    virtual
252    void    void
253    setTaggedValue(int tagKey,    setTaggedValue(int tagKey,
254                   const DataArrayView& value);                   const DataArrayView& value);
255    
256      /**
257        \brief
258        Archive the underlying data values to the file referenced
259        by ofstream. A count of the number of values expected to be written
260        is provided as a cross-check.
261    
262        The return value indicates success (0) or otherwise (1).
263      */
264      ESCRIPT_DLL_API
265      virtual
266      int
267      archiveData(std::ofstream& archiveFile,
268                  const ValueType::size_type noValues) const;
269    
270      /**
271        \brief
272        Extract the number of values specified by noValues from the file
273        referenced by ifstream to the underlying data structure.
274    
275        The return value indicates success (0) or otherwise (1).
276      */
277      ESCRIPT_DLL_API
278      virtual
279      int
280      extractData(std::ifstream& archiveFile,
281                  const ValueType::size_type noValues);
282    
283      /**
284         \brief
285         Copy the numarray object to the data points in this object.
286    
287         Description:
288         Copy the numarray object to the data points in this object.
289    
290         \param value Input - new values for the data points
291      */
292      ESCRIPT_DLL_API
293      virtual void
294      copyAll(const boost::python::numeric::array& value);
295    
296      /**
297         \brief
298         Copy a double value to the data point dataPointNo of sample sampleNo in this object.
299    
300         Description:
301         Copy a double value to the data point dataPointNo of sample sampleNo in this object.
302    
303         \param sampleNo Input - sample number
304         \param dataPointNo Input - data point of the sample
305         \param value Input - new values for the data point
306      */
307      ESCRIPT_DLL_API
308      virtual void
309      copyToDataPoint(const int sampleNo, const int dataPointNo, const double value);
310    
311      /**
312         \brief
313         Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
314    
315         Description:
316         Copy the numarray object to the data point dataPointNo of sample sampleNo in this object.
317    
318         \param sampleNo Input - sample number
319         \param dataPointNo Input - data point of the sample
320         \param value Input - new values for the data point
321      */
322      ESCRIPT_DLL_API
323      virtual void
324      copyToDataPoint(const int sampleNo, const int dataPointNo, const boost::python::numeric::array& value);
325    
326    
327      /**
328         \brief
329         Return the tag number associated with the given data-point number.
330    
331         If the object cannot be referenced by tag numbers, an exception
332         will be thrown.
333      */
334      ESCRIPT_DLL_API
335      virtual
336      int
337      getTagNumber(int dpno);
338    
339      /**
340         \brief
341         Computes a symmetric matrix (A + AT) / 2
342    
343         \param ev - Output - a symmetric matrix
344    
345      */
346      ESCRIPT_DLL_API
347      virtual void
348      symmetric(DataAbstract* ev);
349    
350      /**
351         \brief
352         Computes a nonsymmetric matrix (A - AT) / 2
353    
354         \param ev - Output - a nonsymmetric matrix
355    
356      */
357      ESCRIPT_DLL_API
358      virtual void
359      nonsymmetric(DataAbstract* ev);
360    
361      /**
362         \brief
363         Computes the trace of a matrix
364    
365         \param ev - Output - the trace of a matrix
366    
367      */
368      ESCRIPT_DLL_API
369      virtual void
370      trace(DataAbstract* ev, int axis_offset);
371    
372      /**
373         \brief
374         Transpose each data point of this Data object around the given axis.
375    
376         \param ev - Output - the transpose of a matrix
377    
378      */
379      ESCRIPT_DLL_API
380      virtual void
381      transpose(DataAbstract* ev, int axis_offset);
382    
383      /**
384         \brief
385         swaps components axis0 and axis1
386    
387         \param ev - Output - swapped components
388    
389      */
390      ESCRIPT_DLL_API
391      virtual void
392      swapaxes(DataAbstract* ev, int axis0, int axis1);
393      /**
394         \brief
395         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev
396    
397         \param ev - Output - eigenvalues in increasing order at each data point
398    
399      */
400      ESCRIPT_DLL_API
401      virtual void
402      eigenvalues(DataAbstract* ev);
403    
404      /**
405         \brief
406         sets values to zero
407    
408      */
409      ESCRIPT_DLL_API
410      virtual void
411      setToZero();
412    
413      /**
414         \brief
415         solves the eigenvalue problem this*V=ev*V for the eigenvalues ev and eigenvectors V
416    
417         \param ev - Output - eigenvalues in increasing order at each data point
418         \param V - Output - corresponding eigenvectors. They are normalized such that their length is one
419                             and the first nonzero component is positive.
420         \param tol - Input - eigenvalue with relative distance tol are treated as equal.
421    
422      */
423    
424      ESCRIPT_DLL_API
425      virtual void
426      eigenvalues_and_eigenvectors(DataAbstract* ev,DataAbstract* V,const double tol=1.e-13);
427    
428   protected:   protected:
429    
430    /**    /**
431       \brief       \brief
432       Set the pointDataView       Set the pointDataView DataArrayView associated with this object.
433       \param right - Input - The point data view. DataAbstract takes ownership  
434         \param input - Input - The point data view. DataAbstract takes ownership
435       of the DataArrayView provided. It will delete it when it is destructed.       of the DataArrayView provided. It will delete it when it is destructed.
436    */    */
437      ESCRIPT_DLL_API
438    void    void
439    setPointDataView(const DataArrayView& input);    setPointDataView(const DataArrayView& input);
440    
441   private:    ESCRIPT_DLL_API
442      void
443      resetPointDataView();
444    
445    int m_noDataPointsPerSample;   private:
446    
447      //
448      // The number of samples in this Data object.
449      // This is derived directly from the FunctionSpace.
450    int m_noSamples;    int m_noSamples;
451    
452    //    //
453    // Provides a view of the data as point data    // The number of data points per sample in this Data object.
454      // This is derived directly from the FunctionSpace.
455      int m_noDataPointsPerSample;
456    
457      //
458      // The DataArrayView of the data array associated with this object.
459      // The data array is defined only in child classes of this class, it
460      // is not defined in this abstract parent class.
461    boost::scoped_ptr<DataArrayView> m_pointDataView;    boost::scoped_ptr<DataArrayView> m_pointDataView;
462    
463    //    //
464    // function space    // A FunctionSpace which provides a description of the data associated
465      // with this Data object.
466    FunctionSpace m_functionSpace;    FunctionSpace m_functionSpace;
467    
468  };  };
469    
470  inline  inline
471  bool  bool
472  DataAbstract::validSamplePointNo(int samplePointNo) const  DataAbstract::validSamplePointNo(int samplePointNo) const
473  {  {
474    return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));    return ((0 <= samplePointNo) && (samplePointNo < m_noDataPointsPerSample));
475  }  }
# Line 273  DataAbstract::getSampleData(ValueType::s Line 490  DataAbstract::getSampleData(ValueType::s
490    
491  inline  inline
492  int  int
493  DataAbstract::getNumDPPSample() const  DataAbstract::getNumDPPSample() const
494  {  {
495    return m_noDataPointsPerSample;    return m_noDataPointsPerSample;
496  }  }
# Line 307  DataAbstract::getPointDataView() Line 524  DataAbstract::getPointDataView()
524  {  {
525    return *(m_pointDataView.get());    return *(m_pointDataView.get());
526  }  }
   
527  } // end of namespace  } // end of namespace
528    
529  #endif  #endif

Legend:
Removed from v.106  
changed lines
  Added in v.1358

  ViewVC Help
Powered by ViewVC 1.1.26