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

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

docs

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