GSL::Vector class

# Title: GSL::Vector class

## 1 Class methods

`GSL::Vector.alloc(ary)`
`GSL::Vector.new(ary)`
`GSL::Vector.new(range)`
`GSL::Vector.new(size)`
`GSL::Vector.new(n, [xmin, xmax])`
`GSL::Vector.new(elm0, elm1, ....)`

  These methods create a `GSL::Vector` object. This example initializes a vector of length 10,

      require('gsl')
      v = Vector.new(10)         ( or use 'alloc' )

  Vector elements will be set with the 'set' method.

  One can create a vector by giving an array, as

      v = Vector.new([1, 2, 3])

  or with a range object,

      v = Vector.new(1..3)

`GSL::Vector.GSL::Vector.calloc(size)`
  This method also creates a vector object, and initializes all the elements to zero.

### 1.1 NArray Extension

If a `NArray` object is given, a newly allocated vector is created.

ex)

    na = NArray[1.0, 2, 3, 4, 5]
    p na                <----- NArray.float(5):
                               [ 1.0, 2.0, 3.0, 4.0, 5.0]
    v = Vector.new(na)
    p v                 <----- [ 1 2 3 4 5 ]
                               #<GSL::Vector:0x367ff4>

## 2 NOTE:

In Ruby/GSL, vector lendth is limited within the range of Fixnum. For 32-bit CPU, the maximum of vector length is 2^30 ~ 1e9.

## 3 Methods

`GSL::Vector#get(i)`
  This returns the i-th element of the vector self. The method '[]' is also available.
`GSL::Vector#set(i, val)`

  This method sets the i-th element of the vector self to val.

      ex) v.set(2, 3.5)      # v[2] = 3.5

`GSL::Vector#set_all(x)`
  This method sets all the elements of the vector to the value x.
`GSL::Vector#set_zero`
  This method sets all the elements of the vector to zero.
`GSL::Vector#set_basis!(i)`

  This method makes a basis vector by setting all the elements of the vector to zero except for the i-th element, which is set to one. For a vector v of the size 10, the method

      v.set_basis!(4)

  sets the vector self to a basis vector [0, 0, 0, 0, 1, 0, 0, 0, 0, 0]. The vector self is modified.

`GSL::Vector#set_basis(i)`

  This method returns a basis vector by setting all the elements of the vector to zero except for the i-th element which is set to one. For a vector v of the size 10, the method

      vb = v.set_basis(4)

  creates a new vector self with elements [0, 0, 0, 0, 1, 0, 0, 0, 0, 0]. The vector self is not changed.

`GSL::Vector#each`

  Iterator for each vector element, used as

      v.each do |x|
        p x
      end

`GSL::Vector#each_index`
  Another iterator, as the one of Ruby Array.

### 3.1 IO

`GSL::Vector#print`
  Show all the elements of the vector in %4.3e format.
`GSL::Vector#fprintf(io, format = "%e")`
`GSL::Vector#fprintf(filename, format = "%e")`
`GSL::Vector#fscanf(io)`
`GSL::Vector#fscanf(filename)`
`GSL::Vector#fwrite(io)`
`GSL::Vector#fwrite(filename)`
`GSL::Vector#fread(io)`
`GSL::Vector#fread(filename)`
  Methods for writing or reading the vector. The first argument is IO or String object.
`GSL::Vector#clone`
  This method creates a new vector of the same elements.
`GSL::Vector#swap_elements(i, j)`
  This method exchanges the i-th and j-th elements of the vector in-place.
`GSL::Vector#reverse`
`GSL::Vector#reverse!`
  These methods reverse the order of the elements of the vector.

### 3.2 Vector views

The `GSL::Vector::View` class is defined to be used as "references" to the vectors. Since the `Vector::View` class is a subclass of the class `Vector`, an instance of the `View` class created by slicing a `Vector` object can be used same as the original vector. The `View` object shares the data with the original vector, i.e. changes in the elements of the `View` object affect to the original.

`GSL::Vector#subvector(offset, n)`
`GSL::Vector#subvector(n)`
`GSL::Vector#subvector`
  This method creates a `Vector::View` object slicing n elements of the vector self from the offset offset. If called with only one argument n, offset is set to 0. With no arguments, a view is created with the same length of the original vector.

  - ex:

        #!/usr/bin/env ruby
        require("gsl")

        v = Vector.new([1, 2, 3, 4, 5, 6])
        view = v.subvector(1, 4)
        p view.class         <----- GSL::Vector::View
        view.print           <----- [ 2 3 4 5 ]

        view[2] = 99
        view.print           <----- [ 2 3 99 5 ]
        v.print              <----- [ 1 2 3 99 5 6 ]

`GSL::Vector#subvector_with_stride(offset, n, stride)`
`GSL::Vectir#matrix_view(n1, n2)`
  This creates a `Matrix::View` object from the vector self. It enables to use the vector as a Matrix object.

  - ex:

        v2 = Vector.new([1, 2, 3, 4, 5, 6, 7, 8, 9])
        mview = v2.matrix_view(3, 3)
        p mview.class            <----- GSL::Matrix::View
        mview.print              <----- [ 1 2 3
                                          4 5 6
                                          7 8 9 ]
        mview.set(2, 1, 99.9)
        mview.print              <----- [ 1 2 3
                                          4 5 6
                                          7 99.9 9 ]
        v2.print
            <----- [ 1 2 3 4 5 6 7 99.9 9 ]

### 3.3 Vector operations

`GSL::Vector#trans`
`GSL::Vector#transpose`
`GSL::Vector#col`
`GSL::Vector#row`
  Transpose the vector to a column or a row vector.
`GSL::Vector#add!(b)`
`GSL::Vector#+=(b)`
  This method adds the elements of vector b to the elements of vector self. The vector self is modified in place. The two vectors must have the same length.
`GSL::Vector#add(b)`
`GSL::Vector#*(b)`
  This method adds the elements of vector b to the elements of the vector self, and returns a new vector. The vector self is not changed.
`GSL::Vector#sub!(b)`
`GSL::Vector#-=(b)`
  This method subtracts the elements of vector b from the elements of vector self. The two vectors must have the same length. The vector self is modified in place.
`GSL::Vector#sub(b)`
`GSL::Vector#-(b)`
  Same as GSL::Vector#sub!(b), but not modifies the vector itself, and returns a new vector.
`GSL::Vector#div!(b)`
`GSL::Vector#/=(b)`
  This method divides the elements of vector self by the elements of vector b. The two vectors must have the same length. The vector self is modified.
`GSL::Vector#div(b)`
`GSL::Vector#/(b)`
  Same as GSL::Vector#div!(b), but not modifies the vector self, and returns a new vector.
`GSL::Vector#mul(b)`
`GSL::Vector#*(b)`
  Vector multiplication.

  - ex1: Scale

        irb(main):027:0> v = Vector.new(1, 2)
        [ 1 2 ]
        => #<GSL::Vector:0x77a8d0>
        irb(main):028:0> v*2
        [ 2 4 ]
        => #<GSL::Vector:0x7794e4>

  - ex2: Element-by-element multiplication

        irb(main):018:0> a = Vector.new(1, 2); b = Vector.new(3, 4)
        [ 3 4 ]
        => #<GSL::Vector:0x78f500>
        irb(main):020:0> a*b
        [ 3 8 ]
        => #<GSL::Vector:0x78e074>

  - ex3: Inner product

        irb(main):023:0> a = Vector.new(1, 2); b = Vector::Col.new(3, 4)
        [ 3
          4 ]
        => #<GSL::Vector::Col:0x7840c4>
        irb(main):024:0> a*b
        => 11.0

  - ex4: Vector::Col*Vector -> Matrix

        irb(main):025:0> a = Vector::Col.new(1, 2); b = Vector.new(3, 4)
        [ 3 4 ]
        => #<GSL::Vector:0x77e458>
        irb(main):026:0> a*b
        [ 3 4
          6 8 ]
        => #<GSL::Matrix:0x77cfcc>

  - ex5: Matrix*Vector::Col -> Vector::Col

        irb(main):029:0> a = Vector.new(1, 2); m = Matrix.new([2, 3], [4, 5])
        [ 2 3
          4 5 ]
        => #<GSL::Matrix:0x774160>
        irb(main):030:0> m*a          <--- Error
        TypeError: Operation with GSL::Vector is not defined (GSL::Vector::Col expected)
                from (irb):30:in `*'
                from (irb):30
        irb(main):031:0> m*a.col
        [ 8
          14 ]
        => #<GSL::Vector::Col:0x771230>

`GSL::Vector#scale!(x)`
`GSL::Vector#scale(x)`
  This method multiplies the elements of vector self by the constant factor x.
`GSL::Vector#add_constant!(x)`
`GSL::Vector#add_constant(x)`
  This method adds the constant value x to the elements of the vector self.
`GSL::Vector#reverse`
`GSL::Vector#swap_elements`
`GSL::Vector#clone`
  This creates a copy of the vector self.

### 3.4 Finding maximum and minimum elements of vectors

`GSL::Vector#max`
  This method returns the maximum value in the vector.
`GSL::Vector#min`
  This method returns the minimum value in the vector.
`GSL::Vector#minmax`
  This method returns an array of two elements, the minimum and the maximum values in the vector self.
`GSL::Vector#max_index`
  This method returns the index of the maximum value in the vector. When there are several equal maximum elements then the lowest index is returned.
`GSL::Vector#min_index`
  This method returns the index of the minimum value in the vector. When there are several equal minimum elements then the lowest index is returned.
`GSL::Vector#minmax_index`
  This method returns an array of two elements which has the indices of the minimum and the maximum values in the vector self.

### 3.5 Vector Properties

`GSL::Vector#isnull`
  This method returns 1 if all the elements of the vector self are zero, and 0 otherwise.
`GSL::Vector#isnull?`
  This method returns `true` if all the elements of the vector self are zero, and `false` otherwise.
`GSL::Vector#to_a`

  This method converts the vector into a Ruby array. A Ruby array also can be converted into a GSL::Vector object with the `to_gv` method. For example,

      v = GSL::Vector.alloc([1, 2, 3, 4, 5])
      a = v.to_a   -> GSL::Vector to an array
      p a          -> [1.0, 2.0, 3.0, 4.0, 5.0]
      a[2] = 12.0
      v2 = a.to_gv  -> a new GSL::Vector object
      v2.print     -> 1.0000e+00 2.0000e+00 1.2000e+01 4.0000e+00 5.0000e+00

## 4 NArray

`GSL::Vector#to_na`
  The Vector object self is converted into an NArray object. The array data are copied to newly allocated memory.
`GSL::Vector.na_to_gv(na)`
`GSL::Vector.na_to_gslv(na)`
`GSL::Vector.to_gv(na)`
`GSL::Vector.to_gslv(na)`
  A `GSL::Vector::View` object is created from the NArray object na. The data of na are not copied, thus any modifications to the View object affect on the original NArray object. The View object can be used as a reference to the NArray object.

back