source: trunk/lib/gslapi/vector.h @ 357

Last change on this file since 357 was 357, checked in by Peter, 17 years ago

updated doc and set precision to 12 for vector operator <<

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.7 KB
Line 
1// $Id: vector.h 357 2005-08-03 14:53:06Z peter $
2
3#ifndef _theplu_gslapi_vector_
4#define _theplu_gslapi_vector_
5
6#include <iostream>
7#include <vector>
8#include <utility>
9
10#include <gsl/gsl_vector.h>
11#include <c++_tools/utility/Exception.h>
12
13namespace theplu {
14namespace gslapi {
15  ///
16  /// This is the C++ tools interface to GSL vector. 'double' is the
17  /// only type supported, maybe we should add a 'complex' type as
18  /// well in the future.
19  ///
20  /// \par[File streams] Reading and writing vectors to file streams
21  /// are of course supported. These are implemented without using GSL
22  /// functionality, and thus binary read and write to streams are not
23  /// supported.
24  ///
25  /// \par[Vector views] GSL vector views are supported and these are
26  /// disguised as ordinary gslapi::vectors. A support function is
27  /// added, gslapi::vector::is_view(), that can be used to check if
28  /// the vector object is a view. Note that view vectors do not own
29  /// the undelying data, and is not valid if the original vector is
30  /// deallocated.
31  ///
32  class vector
33  {
34  public:
35
36    ///
37    /// The default constructor.
38    ///
39    vector(void);
40
41    ///
42    /// Constructor. Allocates memory space for \a n elements, and
43    /// sets all elements to \a init_value.
44    ///
45    vector(const size_t n, const double init_value=0);
46
47    ///
48    /// The copy constructor.
49    ///
50    /// @note If the object to be copied is a vector view, the values
51    /// of the view will be copied, i.e. the view is not copied.
52    ///
53    vector(const vector&);
54
55    ///
56    /// The vector view constructor.
57    ///
58    /// Create a view of vector \a v, with starting index \a offset,
59    /// size \a n, and an optional \a stride.
60    ///
61    /// A vector view can be used as any vector with the difference
62    /// that changes made to the view will also change the object that
63    /// is viewed. Also, using the copy constructor will create a new
64    /// vector object that is a copy of whatever is viewed. If a copy
65    /// of the view is needed the you should use this consturctor to
66    /// get one.
67    ///
68    /// @note If the object viewed by the view goes out of scope or is
69    /// deleted, the view becomes invalid.
70    ///
71    vector(vector& v, size_t offset, size_t n, size_t stride=1);
72
73    ///
74    /// Constructor that imports a GSL vector. The GSL object is owned
75    /// by the created object.
76    ///
77    vector(gsl_vector*);
78
79    ///
80    /// The istream constructor.
81    ///
82    /// Elements should be separated with white space characters, the
83    /// end of input to the vector is at end of file marker.
84    ///
85    explicit vector(std::istream &) throw (utility::IO_error,std::exception);
86
87    ///
88    /// The destructor.
89    ///
90    ~vector(void);
91
92    ///
93    /// Vector addition, \f$this_i = this_i + other_i \; \forall i\f$.
94    ///
95    /// @return GSL_SUCCESS on normal exit.
96    ///
97    // Jari, group as vector_operators
98    inline int add(const vector& other) { return gsl_vector_add(v_,other.v_); }
99
100    ///
101    /// Add a constant to a vector, \f$this_i = this_i + term \;
102    /// \forall i\f$.
103    ///
104    /// @return GSL_SUCCESS on normal exit.
105    ///
106    // Jari, group as vector_operators
107    inline int add(double term) { return gsl_vector_add_constant(v_,term); }
108
109    ///
110    /// This function performs element-wise division, \f$this_i =
111    /// this_i/other_i \; \forall i\f$.
112    ///
113    /// @return GSL_SUCCESS on normal exit.
114    ///
115    // Jari, doxygen group as Vector operators
116    inline int div(const vector& other) { return gsl_vector_div(v_,other.v_); }
117
118    ///
119    /// @return True if all elements in the vector is zero, false
120    /// othwerwise;
121    ///
122    inline bool isnull(void) const { return gsl_vector_isnull(v_); }
123
124    ///
125    /// Check if the vector object is a view (sub vector) to another
126    /// vector.
127    ///
128    /// @return True if the object is a view, false othwerwise;
129    ///
130    inline bool isview(void) const { return view_; }
131
132    ///
133    /// @return A const pointer to the internal GSL vector,
134    ///
135    inline const gsl_vector* gsl_vector_pointer(void) const { return v_; }
136
137    ///
138    /// @return A pointer to the internal GSL vector,
139    ///
140    inline gsl_vector* TEMP_gsl_vector_pointer(void) { return v_; }
141
142    ///
143    /// @return The maximum value of the vector.
144    ///
145    // Jari, doxygen group as Finding maximum and minimum elements
146    inline double max(void) const { return gsl_vector_max(v_); }
147
148    ///
149    /// @return The element index to the maximum value of the
150    /// vector. The lowest index has precedence.
151    ///
152    // Jari, doxygen group as Finding maximum and minimum elements
153    inline size_t max_index(void) const { return gsl_vector_max_index(v_); }
154
155    ///
156    /// @return The minimum value of the vector.
157    ///
158    // Jari, doxygen group as Finding maximum and minimum elements
159    inline double min(void) const { return gsl_vector_min(v_); }
160
161    ///
162    /// @return The element index to the minimum value of the
163    /// vector. The lowest index has precedence.
164    ///
165    // Jari, doxygen group as Finding maximum and minimum elements
166    inline size_t min_index(void) const { return gsl_vector_min_index(v_); }
167
168    ///
169    /// @return The minimum and maximum values of the vector, as the
170    /// \a first and \a second member of the returned \a pair,
171    /// respectively.
172    ///
173    // Jari, doxygen group as Finding maximum and minimum elements
174    std::pair<double,double> minmax(void) const;
175
176    ///
177    /// @return The indecies to the minimum and maximum values of the
178    /// vector, as the \a first and \a second member of the returned
179    /// \a pair, respectively. The lowest index has precedence.
180    ///
181    // Jari, doxygen group as Finding maximum and minimum elements
182    std::pair<size_t,size_t> minmax_index(void) const;
183
184    ///
185    /// This function performs element-wise multiplication, \f$this_i =
186    /// this_i * other_i \; \forall i\f$.
187    ///
188    /// @return GSL_SUCCESS on normal exit.
189    ///
190    // Jari, doxygen group as Vector operators
191    inline int mul(const vector& other) { return gsl_vector_mul(v_,other.v_); }
192
193    ///
194    /// Reverse the order of elements in the vector.
195    ///
196    /// @return GSL_SUCCESS on normal exit.
197    ///
198    // Jari, doxygen group as Exchanging elements
199    inline int reverse(void) { return gsl_vector_reverse(v_);}
200
201    ///
202    /// Rescale vector, \f$this_i = this_i * factor \; \forall i\f$.
203    ///
204    /// @return GSL_SUCCESS on normal exit.
205    ///
206    // Jari, doxygen group as Vector operators
207    inline int scale(double factor) { return gsl_vector_scale(v_,factor); }
208
209    ///
210    /// Set all elements to \a value.
211    ///
212    // Jari, doxygen group as Initializing vector elements
213    inline void set_all(const double& value) { gsl_vector_set_all(v_,value); }
214
215    ///
216    /// Makes a basis vector by setting all elements to
217    /// zero except the \a i-th element which is set to
218    /// one.
219    ///
220    // Jari, doxygen group as Initializing vector elements
221    inline void set_basis(const size_t i) { gsl_vector_set_basis(v_,i); }
222   
223    ///
224    /// Set all elements to zero.
225    ///
226    // Jari, doxygen group as Initializing vector elements
227    inline void set_zero(void) { gsl_vector_set_zero(v_); }
228
229    ///
230    /// @return the number of elements in the vector.
231    ///
232    inline size_t size(void) const { return v_->size; }
233
234    ///
235    /// Vector subtraction, \f$this_i = this_i - other_i \; \forall i\f$.
236    ///
237    /// @return GSL_SUCCESS on normal exit.
238    ///
239    // Jari, doxygen group as Vector operators
240    inline int sub(const vector& other) { return gsl_vector_sub(v_,other.v_); }
241
242    ///
243    /// Calculate the sum of all vector elements.
244    ///
245    /// @return The sum.
246    ///
247    // Jari, doxygen group as "Extends GSL".
248    double sum(void) const;
249
250    ///
251    /// Swap vector elements by copying. The two vectors must have the
252    /// same length.
253    ///
254    /// @return GSL_SUCCESS on normal exit.
255    ///
256    inline int swap(vector& other) { return gsl_vector_swap(v_,other.v_); }
257
258    ///
259    /// Exchange elements \a i and \a j.
260    ///
261    /// @return GSL_SUCCESS on normal exit.
262    ///
263    // Jari, doxygen group as Exchanging elements
264    inline int
265    swap_elements(size_t i,size_t j) { return gsl_vector_swap_elements(v_,i,j);}
266
267    ///
268    /// Element access operator.
269    ///
270    /// @return Reference to element \a i.
271    ///
272    // Jari, doxygen group as Accessing vector elements
273    inline double& operator()(size_t i) { return *gsl_vector_ptr(v_,i); }
274
275    ///
276    /// Const element access operator.
277    ///
278    /// @return The value of element \a i.
279    ///
280    // Jari, doxygen group as Accessing vector elements
281    inline const double& operator()(size_t i) const
282      { return *gsl_vector_const_ptr(v_,i); }
283   
284    ///
285    /// Element access operator.
286    ///
287    /// @return Reference to element \a i.
288    ///
289    // Jari, doxygen group as Accessing vector elements
290    inline double& operator[](size_t i) { return *gsl_vector_ptr(v_,i); }
291
292    ///
293    /// Const element access operator.
294    ///
295    /// @return The value of element \a i.
296    ///
297    // Jari, doxygen group as Accessing vector elements
298    inline const double& operator[](size_t i) const
299      { return *gsl_vector_const_ptr(v_,i); }
300   
301    ///
302    /// @return The dot product.
303    ///
304    double operator*( const vector &other ) const;
305
306    ///
307    /// Vector with scalar multiplication.
308    ///
309    /// @note This operator is not implemented!
310    ///
311    vector operator*(const double d) const;
312
313    ///
314    /// Vector addition.
315    ///
316    /// @return The resulting vector.
317    ///
318    vector operator+( const vector& other ) const;
319
320    ///
321    /// Vector subtraction.
322    ///
323    /// @return The resulting vector.
324    ///
325    vector operator-( const vector& other ) const;
326
327    ///
328    /// Comparison operator. Takes linear time.
329    ///
330    /// @return True if the sequence of the elements in the vectors
331    /// are element/wise equal.
332    ///
333    bool operator==(const vector&) const;
334
335    ///
336    /// The assignment operator. There is no requirements on
337    /// dimensions.
338    ///
339    /// @return A const reference to the resulting vector.
340    ///
341    const vector& operator=(const vector&);
342
343    ///
344    /// Addition and assign operator.
345    ///
346    /// @return A const reference to the resulting vector.
347    ///
348    inline const vector& operator+=( const vector& other ) 
349    { gsl_vector_add(v_,other.v_); return *this; }
350
351    ///
352    /// Subtract and assign operator.
353    ///
354    /// @return A const reference to the resulting vector.
355    ///
356    inline const vector& operator-=( const vector& other ) 
357    { gsl_vector_sub(v_,other.v_); return *this; }
358
359    ///
360    /// Multiply with scalar and assign operator.
361    ///
362    /// @return A const reference to the resulting vector.
363    ///
364    inline const vector& operator*=(const double d)
365    { gsl_vector_scale(v_,d); return *this; }
366
367
368  private:
369
370    ///
371    /// Create a new copy of the internal GSL vector.
372    ///
373    /// Necessary memory for the new GSL vector is allocated and the
374    /// caller is responsible for freeing the allocated memory.
375    ///
376    /// @return A pointer to a copy of the internal GSL vector.
377    ///
378    gsl_vector* TEMP_gsl_vector_copy(void) const;
379
380    gsl_vector* v_;
381    gsl_vector_view* view_;
382  };
383
384  ///
385  /// The output operator for the vector class.
386  ///
387  std::ostream& operator<<(std::ostream&, const vector& );
388
389
390}} // of namespace gslapi and namespace theplu
391
392#endif
Note: See TracBrowser for help on using the repository browser.