=begin
= Matrices

== Class methods

--- GSL::Matrix.new(n)
--- GSL::Matrix.new(size1, size2)
--- GSL::Matrix.new(array) 
--- GSL::Matrix.new(arrays)
    These methods create a (({GSL::Matrix})) object.

    ex1:
            irb(main):002:0> m = Matrix.new([1, 2, 3], [4, 5, 6], [7, 8, 9])
            [ 1.000e+00 2.000e+00 3.000e+00 
              4.000e+00 5.000e+00 6.000e+00 
              7.000e+00 8.000e+00 9.000e+00 ]
            => #<GSL::Matrix:0x6e9644>

      
    ex2: With an array and rows&cols,
            m = Matrix.new([1, 2, 3, 4, 5, 6, 7, 8, 9], 3, 3)

    ex3: With range objects,
            irb(main):002:0> m = Matrix.new(1..3, 4..6, 7..9)
            [ 1.000e+00 2.000e+00 3.000e+00 
              4.000e+00 5.000e+00 6.000e+00 
              7.000e+00 8.000e+00 9.000e+00 ]
            => #<GSL::Matrix:0x6eb1ec>
            irb(main):004:0> m2 = Matrix.new(1..6, 2, 3)
            [ 1.000e+00 2.000e+00 3.000e+00 
              4.000e+00 5.000e+00 6.000e+00 ]
            => #<GSL::Matrix:0x6e51c0>

--- GSL::Matrix.eye(n, val = 1.0)
--- GSL::Matrix.diagonal(n, val = 1.0)
    Create diagonal matrix of dimensions n*n, of values ((|val|)).
 
--- GSL::Matrix.identity(n)
--- GSL::Matrix.unit(n)
--- GSL::Matrix.I(n)
    Create diagonal matrix of dimensions n*n, of values 1.0.
    
=== NOTE:
Matrix dimensions are limited within the range of Fixnum.
For 32-bit CPU, the maximum of matrix dimension is 2^30 ~ 1e9.

== Methods

--- GSL::Matrix#set(argv)
    This method sets elements of the matrix in various manners.
      * with two integers and a number,
          m.set(1, 2, 3.2)         -> the (1, 2) element is set to 3.2
      * with arrays,
          m.set([6, 5, 6], [4, 5, 7], [8, 5, 21])	
             ->
                  6   5   6
                  4   5   7
                  8   5  21
      * with an array and sizes,
          m.set([4, 5, 6, 8, 98, 6, 4, 3, 1], 3, 3)
             ->
                  4   5   6
                  8  98   6
                  4   3   1

--- GSL::Matrix#get(i, j)
    This method returns the ((|(i,j)|))-th element of the matrix ((|self|)). 

--- GSL::Matrix#set_all(x)
    This method sets all the elements of the matrix ((|self|)) to the value x.

--- GSL::Matrix#set_zero
    This method sets all the elements of the matrix to zero. 

--- GSL::Matrix#set_identity
    This method sets the elements of the matrix to the corresponding 
    elements of the identity matrix, i.e. a unit diagonal with all off-diagonal 
    elements zero. This applies to both square and rectangular matrices. 

=== IO
--- GSL::Matrix#fwrite(io)
--- GSL::Matrix#fwrite(filename)
--- GSL::Matrix#fread(io)
--- GSL::Matrix#fread(filename)
--- GSL::Matrix#fprintf(io, format = "%e")
--- GSL::Matrix#fprintf(filename, format = "%e")
--- GSL::Matrix#fscanf(io)
--- GSL::Matrix#fscanf(filename)

=== Matrix views
The (({GSL::Matrix::View})) class is defined to be used as "references" to
the matrices. The (({Matrix::View})) class is a subclass of the class (({Matrix})),
an instance of the (({View})) class created by slicing a (({Matrix})) object 
can be used same as the original matrix. The
(({View})) object shares the data with the original vector, i.e. any changes
in the elements of the (({View})) object affect to the original.

--- GSL::Matrix#submatrix(k1, k2, n1, n2)
    This returns a (({GSL::Matirx::View})) object, a submatrix of the matrix 
    ((|self|)). The upper-left element of the submatrix is the element ((|(k1,k2)|)) 
    of the original matrix. The submatrix has ((|n1|)) rows and ((|n2|)) columns. 

--- GSL::Vectir#matrix_view(n1, n2)
    This creates a (({Matrix::View})) object from the vector ((|self|)).

    * 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 ]

=== Creating row and column views

--- GSL::Matrix#row(i)
    This method returns a vector view of the ((|i|))-th row of the matrix.

--- GSL::Matrix#column(i)
--- GSL::Matrix#col(i) 
    These methods return a vector view of the ((|j|))-th column of the matrix.

--- GSL::Matrix#diagonal 
    This method returns a vector view of the diagonal of the matrix.
    The matrix is not required to be square. For a rectangular matrix the 
    length of the diagonal is the same as the smaller dimension of the matrix.

--- GSL::Matrix#subdiagonal(k)
    Returns a vector view view of the ((|k|))-th subdiagonal 
    of the matrix ((|self|)). 
    The matrix is not required to be square. The diagonal of the matrix 
    corresponds to k = 0.

--- GSL::Matrix#superdiagonal(k)
    Returns a vector view of the ((|k|))-th superdiagonal of the matrix ((|self|)). 
    The matrix is not required to be square. The diagonal of the matrix 
    corresponds to k = 0.

=== Iterators
--- GSL::Matrix#each_row
    Iterator for each of rows in the matrix ((|self|)). 
--- GSL::Matrix#each_col
    Iterator for each of columns in the matrix ((|self|)). 

=== Copying matrices
--- GSL::Matrix#clone
--- GSL::Matrix.memcpy(dest, src)
--- GSL::Matrix.swap(dest, src)

=== Copying rows and columns

--- GSL::Matrix#get_row(i, v)
    This method returns a new vector (not a view) which contains the elements of the ((|i|))-th 
    row of the matrix ((|self|)).

--- GSL::Matrix#get_col(j, v)
    This method returns a new vector (not a view) which contains the elements of the ((|j|))-th 
    column of the matrix ((|self|)).

--- GSL::Matrix#set_row(i, v)
    This method copies the elements of the vector ((|v|)) into the ((|i|))-th 
    row of the matrix. 
    The length of the vector must be the same as the length of the row. 

--- GSL::Matrix#set_col(j, v)
    This method copies the elements of the vector ((|v|)) into the ((|j|))-th 
    column of the 
    matrix. The length of the vector must be the same as the length of the column. 

=== Exchanging rows and columns
--- GSL::Matrix#swap_rows(i, j)
    This method exchanges the i-th and j-th rows of the matrix in-place. 

--- GSL::Matrix#swap_columns(i, j)
    This method exchanges the i-th and j-th columns of the matrix in-place. 

--- GSL::Matrix#swap_rowcol(i, j)
    This method exchanges the i-th row and j-th column of the matrix.
    The matrix must be square for this operation to be possible.

--- GSL::Matrix#transpose!
    This method returns a matrix of a transpose of the matrix.

--- GSL::Matrix#transpose_memcpy
--- GSL::Matrix#transpose
    This method replaces the matrix by its transpose by copying the 
    elements of the matrix in-place. The matrix must be square for this
    operation to be possible. 

=== Matrix operations

--- GSL::Matrix#add(b)
--- GSL::Matrix#+(b)
--- GSL::Matrix#add!(b)
--- GSL::Matrix#+=(b)
    This method adds the elements of matrix ((|b|)) to the elements of the  matrix. 
    The two matrices must have the same dimensions. 

    If ((|b|)) is a scalar, these methods add it to all the elements
    of the matrix ((|self|)) (equivalent to the method (({add_constant}))).

--- GSL::Matrix#sub(b)
--- GSL::Matrix#-(b)
--- GSL::Matrix#sub!(b)
--- GSL::Matrix#-=(b)
    This method subtracts the elements of matrix ((|b|)) from the elements of the  
    matrix. The two matrices must have the same dimensions. 

--- GSL::Matrix#mul_elements(b)
--- GSL::Matrix#*(b)
--- GSL::Matrix#mul_elements!(b)
--- GSL::Matrix#*=(b)
    This method multiplies the elements of the matrix by the elements of 
    matrix ((|b|)). The two matrices must have the same dimensions. 

--- GSL::Matrix#**(b)
    Matrix multiplication

--- GSL::Matrix#div_elements(b)
--- GSL::Matrix#/(b)
--- GSL::Matrix#div_elements!(b)
--- GSL::Matrix#/=(b)
    This method divides the elements of the  matrix by the elements of 
    matrix ((|b|)). The two matrices must have the same dimensions. 

--- GSL::Matrix#scale!(x)
--- GSL::Matrix#scale(x)
    This method multiplies the elements of the  matrix by the constant 
    factor ((|x|)).

--- GSL::Matrix#add_constant!(x)
--- GSL::Matrix#add_constant(x)
    This method adds the constant value ((|x|)) to the elements of the matrix.

=== Finding maximum and minimum elements of matrices

--- GSL::Matrix#max
--- GSL::Matrix#min
    These methods return the max/min value in the  matrix.

--- GSL::Matrix#minmax 
    This method returns a two elements array [min, max], which contains the minimum
    and the maximum values in the  matrix.

--- GSL::Matrix#max_index 
--- GSL::Matrix#min_index 
    These methods return the index of the max/min value in the  matrix.

--- GSL::Matrix#minmax_index 
    This method returns a two elements array [imin, imax], which contains the indices
    of the minimum and the maximum value in the matrix.

=== Matrix properties
--- GSL::Matrix#isnull
    This returns 1 if all the elements of the matrix ((|self|)) are zero, 
    and 0 otherwise.

--- GSL::Matrix#isnull?
    This returns (({true})) if all the elements of the matrix ((|self|)) are zero, 
    and (({false})) otherwise.

--- GSL:Matrix#trace
    This returns trace of the matrix ((|self|)), the sum of the diagonal elements.

=== NArray

--- GSL::Matrix#to_na
    The Matrix object ((|self|)) is converted into an NMatrix object. 
    The matrix data are copied to newly allocated memory.

--- GSL::Vector.na_to_gm(na)
--- GSL::Matrix.to_gm(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 ((|na|)). The View object can be used as a reference to the NMatrix
    object.

((<back|URL:index.html>))
=end
