source: trunk/src/vector.h @ 257

// $Id: vector.h 257 2005-03-04 00:53:34Z jari $

#ifndef _theplu_gslapi_vector_ 
#define _theplu_gslapi_vector_

#include <iostream>
#include <vector>
#include <utility>

#include <gsl/gsl_vector.h>

// Jari, this should probably go somewhere else for doxygen to process.
///
/// All our C++ projects should ideally be defined within theplu
/// namespace.
///
namespace theplu {
// Jari, this should probably go somewhere else for doxygen to process.
///
/// All GSL wrapper functionality is to be defined within gslapi
/// namespace.
///
/// There are a number of support operators and functions for the
/// wrapper classes that do not belong to the classes themselves, but
/// still are defined in this namespace.
///
namespace gslapi {

  ///
  /// This is the C++ tools interface to GSL vector. 'double' is the
  /// only type supported, maybe we should add a 'complex' type as
  /// well in the future.
  ///
  /// \par[File streams] Reading and writing vectors to file streams
  /// are of course supported. These are implemented without using GSL
  /// functionality, and thus binary read and write to streams are not
  /// supported.
  ///
  /// \par[Vector views] GSL vector views are supported and these are
  /// disguised as ordinary gslapi::vectors. A support function is
  /// added, gslapi::vector::is_view(), that can be used to check if
  /// the vector object is a view. Note that view vectors do not own
  /// the undelying data, and is not valid if the original vector is
  /// deallocated.
  ///
  class vector
  {
  public:

    ///
    /// The default constructor.
    ///
    vector(void);

    ///
    /// Constructor. Allocates memory space for \a n elements, and
    /// sets all elements to \a init_value.
    ///
    vector(const size_t n, const double init_value=0);

    ///
    /// The copy constructor.
    ///
    /// @note If the object to be copied is a vector view, the values
    /// of the view will be copied, i.e. the view is not copied.
    ///
    vector(const vector&);

    ///
    /// The vector view constructor.
    ///
    /// Create a view of vector \a v, with starting index \a offset,
    /// size \a n, and an optional \a stride.
    ///
    /// A vector view can be used as any vector with the difference
    /// that changes made to the view will also change the object that
    /// is viewed. Also, using the copy constructor will create a new
    /// vector object that is a copy of whatever is viewed. If a copy
    /// of the view is needed the you should use this consturctor to
    /// get one.
    ///
    /// @note If the object viewed by the view goes out of scope or is
    /// deleted, the view becomes invalid.
    ///
    vector(vector& v, size_t offset, size_t n, size_t stride=1);

    ///
    /// Constructor that imports a GSL vector. The GSL object is owned
    /// by the created object.
    ///
    vector(gsl_vector*);

    ///
    /// The istream constructor.
    ///
    /// Elements should be separated with white space characters, the
    /// end of input to the vector is at end of file marker.
    ///
    explicit vector(std::istream &);

    ///
    /// The destructor.
    ///
    ~vector(void);

    ///
    /// Vector addition, \f$this_i = this_i + other_i \; \forall i\f$.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Vector operators
    inline int add(const vector& other) { return gsl_vector_add(v_,other.v_); }

    ///
    /// Add a constant to a vector, \f$this_i = this_i + term \;
    /// \forall i\f$.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Vector operators
    inline int
    add_constant(double term) { return gsl_vector_add_constant(v_,term); }

    ///
    /// This function performs element-wise division, \f$this_i =
    /// this_i/other_i \; \forall i\f$.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Vector operators
    inline int div(const vector& other) { return gsl_vector_div(v_,other.v_); }

    ///
    /// @return True if all elements in the vector is zero, false
    /// othwerwise;
    ///
    inline bool isnull(void) const { return gsl_vector_isnull(v_); }

    ///
    /// Check if the vector object is a view (sub vector) to another
    /// vector.
    ///
    /// @return True if the object is a view, false othwerwise;
    ///
    inline bool isview(void) const { return view_; }

    ///
    /// @return A const pointer to the internal GSL vector,
    ///
    inline const gsl_vector* gsl_vector_pointer(void) const { return v_; }

    ///
    /// @return A pointer to the internal GSL vector,
    ///
    inline gsl_vector* TEMP_gsl_vector_pointer(void) { return v_; }

    ///
    /// @return The maximum value of the vector.
    ///
    // Jari, doxygen group as Finding maximum and minimum elements
    inline double max(void) const { return gsl_vector_max(v_); }

    ///
    /// @return The element index to the maximum value of the
    /// vector. The lowest index has precedence.
    ///
    // Jari, doxygen group as Finding maximum and minimum elements
    inline size_t max_index(void) const { return gsl_vector_max_index(v_); }

    ///
    /// @return The minimum value of the vector.
    ///
    // Jari, doxygen group as Finding maximum and minimum elements
    inline double min(void) const { return gsl_vector_min(v_); }

    ///
    /// @return The element index to the minimum value of the
    /// vector. The lowest index has precedence.
    ///
    // Jari, doxygen group as Finding maximum and minimum elements
    inline size_t min_index(void) const { return gsl_vector_min_index(v_); }

    ///
    /// @return The minimum and maximum values of the vector, as the
    /// \a first and \a second member of the returned \a pair,
    /// respectively.
    ///
    // Jari, doxygen group as Finding maximum and minimum elements
    std::pair<double,double> vector::minmax(void) const;

    ///
    /// @return The indecies to the minimum and maximum values of the
    /// vector, as the \a first and \a second member of the returned
    /// \a pair, respectively. The lowest index has precedence.
    ///
    // Jari, doxygen group as Finding maximum and minimum elements
    std::pair<size_t,size_t> vector::minmax_index(void) const;

    ///
    /// This function performs element-wise multiplication, \f$this_i =
    /// this_i * other_i \; \forall i\f$.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Vector operators
    inline int mul(const vector& other) { return gsl_vector_mul(v_,other.v_); }

    ///
    /// Reverse the order of elements in the vector.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Exchanging elements
    inline int reverse(void) { return gsl_vector_reverse(v_);}

    ///
    /// Rescale vector, \f$this_i = this_i * factor \; \forall i\f$.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Vector operators
    inline int scale(double factor) { return gsl_vector_scale(v_,factor); }

    ///
    /// Set all elements to \a value.
    ///
    // Jari, doxygen group as Initializing vector elements
    inline void set_all(const double& value) { gsl_vector_set_all(v_,value); }

    ///
    /// Makes a basis vector by setting all elements to
    /// zero except the \a i-th element which is set to
    /// one.
    ///
    // Jari, doxygen group as Initializing vector elements
    inline void set_basis(const size_t i) { gsl_vector_set_basis(v_,i); }
    
    ///
    /// Set all elements to zero.
    ///
    // Jari, doxygen group as Initializing vector elements
    inline void set_zero(void) { gsl_vector_set_zero(v_); }

    ///
    /// Randomly shuffles the elements in vector @return resulting
    /// vector
    ///
    void vector::shuffle(void) const; 

    ///
    /// @return the number of elements in the vector.
    ///
    inline size_t size(void) const { return v_->size; }

    ///
    /// Vector subtraction, \f$this_i = this_i - other_i \; \forall i\f$.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Vector operators
    inline int sub(const vector& other) { return gsl_vector_sub(v_,other.v_); }

    ///
    /// Calculate the sum of all vector elements.
    ///
    /// @return The sum.
    ///
    // Jari, doxygen group as "Extends GSL".
    double vector::sum(void) const;

    ///
    /// Swap vector elements by copying. The two vectors must have the
    /// same length.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    inline int swap(vector& other) { return gsl_vector_swap(v_,other.v_); }

    ///
    /// Exchange elements \a i and \a j.
    ///
    /// @return .GSL_SUCCESS on normal exit.
    ///
    // Jari, doxygen group as Exchanging elements
    inline int
    swap_elements(size_t i,size_t j) { return gsl_vector_swap_elements(v_,i,j);}

    ///
    /// Element access operator.
    ///
    /// @return Reference to element \a i.
    ///
    // Jari, doxygen group as Accessing vector elements
    inline double& operator()(size_t i) { return *gsl_vector_ptr(v_,i); }

    ///
    /// Const element access operator.
    ///
    /// @return The value of element \a i.
    ///
    // Jari, doxygen group as Accessing vector elements
    inline const double& operator()(size_t i) const
      { return *gsl_vector_const_ptr(v_,i); }
    
    ///
    /// Element access operator.
    ///
    /// @return Reference to element \a i.
    ///
    // Jari, doxygen group as Accessing vector elements
    inline double& operator[](size_t i) { return *gsl_vector_ptr(v_,i); }

    ///
    /// Const element access operator.
    ///
    /// @return The value of element \a i.
    ///
    // Jari, doxygen group as Accessing vector elements
    inline const double& operator[](size_t i) const
      { return *gsl_vector_const_ptr(v_,i); }
    
    ///
    /// @return The negation of the vector.
    ///
    vector operator-(void) const;

    ///
    /// @return The dot product.
    ///
    double operator*( const vector &other ) const;

    ///
    /// Vector addition.
    ///
    /// @return The resulting vector.
    ///
    vector operator+( const vector& other ) const;

    ///
    /// Vector subtraction.
    ///
    /// @return The resulting vector.
    ///
    vector operator-( const vector& other ) const;

    ///
    /// The assignment operator. There is no requirements on
    /// dimensions.
    ///
    vector& operator=(const vector&);

    ///
    /// Multiply with scalar and assign operator.
    ///
    vector& operator*=(const double d) { gsl_vector_scale(v_,d); return *this; }

    ///
    /// Vector with scalar multiplication.
    ///
    /// \note This operator is not implemented!
    ///
    vector operator*(const double d) const;


  private:

    ///
    /// Create a new copy of the internal GSL vector.
    ///
    /// Necessary memory for the new GSL vector is allocated and the
    /// caller is responsible for freeing the allocated memory.
    ///
    /// @return A pointer to a copy of the internal GSL vector.
    ///
    gsl_vector* TEMP_gsl_vector_copy(void) const;

    gsl_vector* v_;
    gsl_vector_view* view_;
  };

  ///
  /// The output operator for the vector class.
  ///
  std::ostream& operator<< ( std::ostream&, const vector& );


}} // of namespace gslapi and namespace theplu

#endif