source: trunk/yat/utility/VectorBase.h @ 1015

Last change on this file since 1015 was 1015, checked in by Peter, 13 years ago

changing class names vectorView => VectorView? and vectorBase => VectorBase?. Refs #256

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.9 KB
Line 
1#ifndef _theplu_yat_utility_vector_base_
2#define _theplu_yat_utility_vector_base_
3
4// $Id: VectorBase.h 1015 2008-02-01 16:35:32Z peter $
5
6/*
7  Copyright (C) 2003 Daniel Dalevi, Peter Johansson
8  Copyright (C) 2004 Jari Häkkinen, Peter Johansson
9  Copyright (C) 2005 Jari Häkkinen, Markus Ringnér, Peter Johansson
10  Copyright (C) 2006 Jari Häkkinen, Markus Ringnér
11  Copyright (C) 2007 Jari Häkkinen, Peter Johansson
12  Copyright (C) 2008 Peter Johansson
13
14  This file is part of the yat library, http://trac.thep.lu.se/trac/yat
15
16  The yat library is free software; you can redistribute it and/or
17  modify it under the terms of the GNU General Public License as
18  published by the Free Software Foundation; either version 2 of the
19  License, or (at your option) any later version.
20
21  The yat library is distributed in the hope that it will be useful,
22  but WITHOUT ANY WARRANTY; without even the implied warranty of
23  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24  General Public License for more details.
25
26  You should have received a copy of the GNU General Public License
27  along with this program; if not, write to the Free Software
28  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
29  02111-1307, USA.
30*/
31
32#include "Exception.h"
33#include "Iterator.h"
34
35#include <iostream>
36#include <vector>
37#include <utility>
38
39#include <gsl/gsl_vector.h>
40#include <gsl/gsl_sort_vector.h>
41
42namespace theplu {
43namespace yat {
44namespace utility {
45
46  class matrix;
47  class vector;
48
49  /**
50     @brief This is the yat interface to GSL vector.
51
52     For time being 'double' is the only type supported.
53
54     \par File streams:
55     Reading and writing vectors to file streams are of course
56     supported. These are implemented without using GSL functionality,
57     and thus binary read and write to streams are not supported.
58
59     \par Vector views:
60     GSL vector views are supported and these are disguised as
61     ordinary utility::vectors. A support function is added,
62     utility::vector::isview(), that can be used to check if a vector
63     object is a view. Note that view vectors do not own the
64     underlying data, and a view is not valid if the vector/matrix
65     owing the data is deallocated.
66
67     \par
68     Currently there is no restriction on how a vector is used when
69     the vector is a const view into another vector or matrix. To
70     avoid unexpected runtime errors, the programmer must declare
71     const view vectors as 'const' in order to get compile time
72     diagnostics about improper use of a const view vector object. If
73     'const' is not used and the const view vector is used erroneously
74     (such as on the left hand side in assignments), the compiler will
75     not catch the error and runtime error will occur. assert(3) is
76     used to catch the runtime error during development. Example on
77     bad and proper use of const view vectors:
78     @code
79  const vector vm(13,1.0);
80  vector v1(vm,2,4);       // bad code! not const!
81  v1(0)=-123;              // accepted by compiler, runtime abort will occur
82                           // or catched by assert depending on compiler flags
83  const vector v2(vm,2,4); // proper code
84  v2(0)=-123;              // not acceptable for the compiler
85     @endcode
86  */
87
88  class VectorBase
89  {
90  public:
91
92    /// \brief VectorBase::iterator
93    typedef Iterator<double&, VectorBase> iterator;
94
95    /// \brief VectorBase::const_iterator
96    typedef Iterator<const double, const VectorBase> const_iterator;
97
98    /**
99       \brief default constructor
100    */
101    VectorBase(void);
102
103    /**
104       \brief Constructor.
105    */
106    VectorBase(gsl_vector*);
107
108    /**
109       \brief Constructor.
110    */
111    VectorBase(const gsl_vector*);
112
113    ///
114    /// The destructor.
115    ///
116    virtual ~VectorBase(void);
117
118    ///
119    /// Set all elements to \a value.
120    ///
121    void all(double value);
122
123    /**
124       \return mutable iterator to start of VectorBase
125     */
126    iterator begin(void);
127
128    /**
129       \return read-only iterator to start of VectorBase
130     */
131    const_iterator begin(void) const;
132
133    /**
134       \brief This function performs element-wise division, \f$ this_i =
135       this_i/other_i \; \forall i \f$.
136
137       \throw GSL_error if dimensions mis-match.
138    */
139    void div(const VectorBase& other);
140
141    /**
142       \return mutable iterator to end of VectorBase
143     */
144    iterator end(void);
145
146    /**
147       \return read-only iterator to end of VectorBase
148     */
149    const_iterator end(void) const;
150
151    /**
152       \brief Check whether VectorBases are equal within a user defined
153       precision, set by \a precision.
154
155       \return True if each element deviates less or equal than \a
156       d. If any VectorBase contain a NaN, false is always returned.
157
158       \see operator== and operator!=
159    */
160    bool equal(const VectorBase&, const double precision=0) const;
161
162    ///
163    /// @return A pointer to the internal GSL vector,
164    ///
165    gsl_vector* gsl_vector_p(void);
166
167    ///
168    /// @return A const pointer to the internal GSL vector,
169    ///
170    const gsl_vector* gsl_vector_p(void) const;
171
172    /**
173   
174       Check if the vector object is a view (sub-vector) to another
175       vector.
176   
177       \return True if the object is a view, false othwerwise.
178   
179     */
180    virtual bool isview(void) const=0; 
181
182    /**
183       \brief This function performs element-wise multiplication, \f$
184       this_i = this_i * other_i \; \forall i \f$.
185
186       \throw GSL_error if dimensions mis-match.
187    */
188    void mul(const VectorBase& other);
189
190    /**
191       \brief Reverse the order of elements in the VectorBase.
192    */
193    void reverse(void);
194
195    ///
196    /// @return the number of elements in the VectorBase.
197    ///
198    size_t size(void) const;
199
200    /**
201       \brief Exchange elements \a i and \a j.
202
203       \throw GSL_error if VectorBase lengths differs.
204    */
205    void swap(size_t i, size_t j);
206
207    /**
208       \brief Element access operator.
209
210       \return Reference to element \a i.
211
212       \throw If GSL range checks are enabled in the underlying GSL
213       library a GSL_error exception is thrown if either index is out
214       of range.
215    */
216    double& operator()(size_t i);
217    // Peter, remove this one
218    double& operator[](size_t i);
219
220    /**
221       \brief Element access operator.
222
223       \return Const reference to element \a i.
224
225       \throw If GSL range checks are enabled in the underlying GSL
226       library a GSL_error exception is thrown if either index is out
227       of range.
228    */
229    const double& operator()(size_t i) const;
230    // Peter, remove this one
231    const double& operator[](size_t i) const;
232
233    /**
234       \brief Comparison operator. Takes linear time.
235
236       Checks are performed with exact matching, i.e., rounding off
237       effects may destroy comparison. Use the equal function for
238       comparing elements within a user defined precision.
239
240       \return True if all elements are equal otherwise false.
241
242       \see equal(const VectorBase&, const double precision=0)
243    */
244    bool operator==(const VectorBase&) const;
245
246    /**
247       \brief Comparison operator. Takes linear time.
248
249       Checks are performed with exact matching, i.e., rounding off
250       effects may destroy comparison. Use the equal function for
251       comparing elements within a user defined precision.
252
253       \return False if all elements are equal otherwise true.
254
255       \see equal(const VectorBase&, const double precision=0)
256    */
257    bool operator!=(const VectorBase&) const;
258
259    ///
260    /// @return The dot product.
261    ///
262    double operator*(const VectorBase&) const;
263
264    /**
265       \brief The assignment operator.
266
267       Dimensions of the VectorBases must match. If the LHS VectorBase is a
268       view, the underlying data will be changed.
269
270       \return A const reference to the resulting VectorBase.
271
272       \see void set(const VectorBase&).
273
274       \throw GSL_error if dimensions mis-match.
275    */
276    //const VectorBase& operator=(VectorBase&);
277
278    /**
279       \brief Addition and assign operator. VectorBase addition, \f$
280       this_i = this_i + other_i \; \forall i \f$.
281
282       \return A const reference to the resulting VectorBase.
283
284       \throw GSL_error if dimensions mis-match.
285    */
286    const VectorBase& operator+=(const VectorBase&);
287
288    /**
289       \brief Add a constant to a VectorBase, \f$ this_i = this_i + d \;
290       \forall i \f$.
291
292       \return A const reference to the resulting VectorBase.
293    */
294    const VectorBase& operator+=(double d);
295
296    /**
297       \brief Subtract and assign operator. VectorBase subtraction, \f$
298       this_i = this_i - other_i \; \forall i \f$.
299
300       \return A const reference to the resulting VectorBase.
301
302       \throw GSL_error if dimensions mis-match.
303    */
304    const VectorBase& operator-=(const VectorBase&);
305
306    /**
307       \brief Subtract a constant to a VectorBase, \f$ this_i = this_i - d
308       \; \forall i \f$.
309
310       \return A const reference to the resulting VectorBase.
311    */
312    const VectorBase& operator-=(double d);
313
314    /**
315       \brief Multiply with scalar and assign operator, \f$ this_i =
316       this_i * d \; \forall i \f$.
317
318       \return A const reference to the resulting VectorBase.
319    */
320    const VectorBase& operator*=(double d);
321
322
323
324  protected:
325    gsl_vector* vec_;
326    const gsl_vector* const_vec_;
327
328    /*
329    struct proxy
330    {
331      gsl_vector* vec_;
332    };
333    */
334
335  private:
336    // copy assignment no allowed
337    const VectorBase& operator=(const VectorBase&);
338  public:
339    /**
340     */
341    //operator proxy();
342
343  };
344
345  /**
346     \brief Check if all elements of the VectorBase are zero.
347
348     \return True if all elements in the VectorBase is zero, false
349     othwerwise.
350  */
351  bool isnull(const VectorBase&);
352
353  /**
354     \brief Get the maximum value of the VectorBase.
355
356     \return The maximum value of the VectorBase.
357  */
358  double max(const VectorBase&);
359
360  /**
361     \brief Locate the maximum value in the VectorBase.
362
363     \return The index to the maximum value of the VectorBase.
364
365     \note Lower index has precedence.
366  */
367  size_t max_index(const VectorBase&);
368
369  /**
370     \brief Get the minimum value of the VectorBase.
371
372     \return The minimum value of the VectorBase.
373  */
374  double min(const VectorBase&);
375
376  /**
377     \brief Locate the minimum value in the VectorBase.
378
379     \return The index to the minimum value of the VectorBase.
380
381     \note Lower index has precedence.
382  */
383  size_t min_index(const VectorBase&);
384
385  /**
386     \brief Create a VectorBase \a flag indicating NaN's in another VectorBase
387     \a templat.
388
389     The \a flag VectorBase is changed to contain 1's and 0's only. A 1
390     means that the corresponding element in the \a templat VectorBase is
391     valid and a zero means that the corresponding element is a NaN.
392
393     \note Space for VectorBase \a flag is reallocated to fit the size of
394     VectorBase \a templat if sizes mismatch.
395
396     \return True if the \a templat VectorBase contains at least one NaN.
397  */
398  bool nan(const VectorBase& templat, vector& flag);
399
400  /**
401     Randomly shuffles the elements in VectorBase \a invec
402  */
403  void shuffle(VectorBase& invec); 
404
405  /**
406     Sort the elements in the VectorBase.
407  */
408  void sort(VectorBase&);
409
410  /**
411     Create a vector \a sort_index containing the indeces of
412     elements in a another VectorBase \a invec.  The elements of \a
413     sort_index give the index of the VectorBase element which would
414     have been stored in that position if the VectorBase had been sorted
415     in place. The first element of \a sort_index gives the index of the least
416     element in \a invec, and the last element of \a sort_index gives the
417     index of the greatest element in \a invec . The VectorBase \a invec
418     is not changed.
419  */
420  void sort_index(std::vector<size_t>& sort_index, const VectorBase& invec);
421
422  /**
423      Similar to sort_index but creates a VectorBase with indices to the \a k
424  smallest elements in \a invec. 
425  */
426  void sort_smallest_index(std::vector<size_t>& sort_index, size_t k, 
427                           const VectorBase& invec);
428
429  /**
430      Similar to sort_index but creates a VectorBase with indices to the \a k
431  largest elements in \a invec. 
432  */
433  void sort_largest_index(std::vector<size_t>& sort_index, size_t k, 
434                          const VectorBase& invec);
435
436  /**
437     \brief Calculate the sum of all VectorBase elements.
438
439     \return The sum.
440  */
441  double sum(const VectorBase&);
442
443  /**
444     \brief Swap vector elements by copying.
445
446     The two vectorMutables must have the same length.
447
448     \throw GSL_error if vectorMutable lengths differs.
449  */
450  //void swap(vectorMutable&, vectorMutable&);
451
452  /**
453     \brief The output operator for the VectorBase class.
454  */
455  std::ostream& operator<<(std::ostream&, const VectorBase&);
456
457}}} // of namespace utility, yat, and theplu
458
459#endif
Note: See TracBrowser for help on using the repository browser.