This is gsl-ref.info, produced by Makeinfo version 3.12h from
gsl-ref.texi.

INFO-DIR-SECTION Scientific software
START-INFO-DIR-ENTRY
* gsl-ref: (gsl-ref).                   GNU Scientific Library - Reference
END-INFO-DIR-ENTRY

   This file documents the GNU Scientific Library.

   Copyright (C) 1996, 1997, 1998, 1999 The GSL Project.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: gsl-ref.info,  Node: The block struct,  Next: Block allocation,  Prev: Data types,  Up: Vectors and Matrices

The block struct
================

   For consistency all memory is allocated through a `gsl_block'
structure.  The structure contains two members, the size of an area of
memory and a pointer to the memory.  The `gsl_block' structure looks
like this,

     typedef struct
     {
       size_t size;
       double * data;
     } gsl_block ;

Vectors and matrices are made by "slicing" an underlying block. A slice
is a set of elements formed from an initial offset and a combination of
indices and step-sizes. In the case of a matrix the step-size for the
column index represents the row-length.  The step-size for a vector is
known as the "stride".

   The functions for allocating and deallocating blocks are defined in
`gsl_block.h'


File: gsl-ref.info,  Node: Block allocation,  Next: Reading and writing blocks,  Prev: The block struct,  Up: Vectors and Matrices

Block allocation
================

   The functions for allocating memory to a block follow the style of
`malloc' and `free'.  In addition they also perform their own error
checking.  If there is insufficient memory available to allocate a
block then the functions call the GSL error handler (with an error
number of `GSL_ENOMEM') in addition to returning a null pointer.  Thus
if you use the library error handler to abort your program then it
isn't necessary to check every `alloc'.

 - Function: gsl_block * gsl_block_alloc (size_t N)
     This function allocates memory for a block of N double-precision
     elements, returning a pointer to the block struct.  The block is
     not initialized and so the values of its elements are undefined.
     Use the function `gsl_block_calloc' if you want to ensure that all
     the elements are initialized to zero.

     A null pointer is returned if insufficient memory is available to
     create the block.

 - Function: gsl_block * gsl_block_calloc (size_t N)
     This function allocates memory for a block and initializes all the
     elements of the block to zero.

 - Function: void gsl_block_free (gsl_block * B)
     This function frees the memory used by a block B previously
     allocated with `gsl_block_alloc' or `gsl_block_calloc'.


File: gsl-ref.info,  Node: Reading and writing blocks,  Next: Example programs for blocks,  Prev: Block allocation,  Up: Vectors and Matrices

Reading and writing blocks
==========================

   The library provides functions for reading and writing blocks to a
file as binary data or formatted text.

 - Function: int gsl_block_fwrite (FILE * STREAM, const gsl_block * B)
     This function writes the elements of the block B to the stream
     STREAM in binary format.  The return value is 0 for success and
     `GSL_EFAILED' if there was a problem writing to the file.  Since
     the data is written in the native binary format it may not be
     portable between different architectures.

 - Function: int gsl_block_fread (FILE * STREAM, gsl_block * B)
     This function reads into the block B from the open stream STREAM
     in binary format.  The block B must be preallocated with the
     correct length since the function uses the size of B to determine
     how many bytes to read.  The return value is 0 for success and
     `GSL_EFAILED' if there was a problem reading from the file.  The
     data is assumed to have been written in the native binary format
     on the same architecture.

 - Function: int gsl_block_fprintf (FILE * STREAM, const gsl_block * B,
          const char * FORMAT)
     This function writes the elements of the block B line-by-line to
     the stream STREAM using the format specifier FORMAT, which should
     be one of the `%g', `%e' or `%f' formats for floating point
     numbers and `%d' for integers.  The function returns 0 for success
     and `GSL_EFAILED' if there was a problem writing to the file.

 - Function: int gsl_block_fscanf (FILE * STREAM, gsl_block * B)
     This function reads formatted data from the stream STREAM into the
     block B.  The block B must be preallocated with the correct length
     since the function uses the size of B to determine how many
     numbers to read.  The function returns 0 for success and
     `GSL_EFAILED' if there was a problem reading from the file.


File: gsl-ref.info,  Node: Example programs for blocks,  Next: The vector struct,  Prev: Reading and writing blocks,  Up: Vectors and Matrices

Example programs for blocks
===========================

   The following program shows how to allocate a block,

     #include <stdio.h>
     #include <gsl/gsl_block.h>
     
     int main ()
     {
       gsl_block * b = gsl_block_alloc (100) ;
     
       printf("length of block = %u\n", b->size);
       printf("block data address = %#x\n", b->data);
     
       gsl_block_free (b);
     }

Here is the output from the program,

     length of block = 100
     block data address = 0x804b0d8


File: gsl-ref.info,  Node: The vector struct,  Next: Vector allocation,  Prev: Example programs for blocks,  Up: Vectors and Matrices

The vector struct
=================

   Vectors are defined by a `gsl_vector' structure which describes a
slice of a block. A vector represents a "view" of an area of memory,
and different vectors can be created which point to the same block.  For
example, it is possible to make two vectors which point to the even and
odd elements of another vector, or to make vectors which correspond to
the rows and columns of a matrix.

   The `gsl_vector' structure contains four members, the "size", the
"stride", a pointer to the memory where the elements are stored, DATA,
and a pointer to the block owned by the vector, BLOCK, if any.  The
structure is very simple and looks like this,

     typedef struct
     {
       size_t size;
       size_t stride;
       double * data;
       gsl_block * block;
     } gsl_vector ;

The SIZE is simply the number of vector elements.  The range of valid
indices runs from 0 to `size-1'.  The STRIDE is the step-size from one
element to the next in physical memory, measured in units of the
appropriate datatype.  The pointer DATA gives the location of the first
element of the vector in memory.  The pointer BLOCK stores the location
of the memory block owned by the vector (if any).  This block will be
deallocated when the vector is freed.  If the vector is only a view of
another object then the pointer BLOCK is null.

   The functions for allocating and accessing vectors are defined in
`gsl_vector.h'


File: gsl-ref.info,  Node: Vector allocation,  Next: Accessing vector elements,  Prev: The vector struct,  Up: Vectors and Matrices

Vector allocation
=================

   The functions for allocating memory to a vector follow the style of
`malloc' and `free'.  In addition they also perform their own error
checking.  If there is insufficient memory available to allocate a
vector then the functions call the GSL error handler (with an error
number of `GSL_ENOMEM') in addition to returning a null pointer.  Thus
if you use the library error handler to abort your program then it
isn't necessary to check every `alloc'.

 - Function: gsl_vector * gsl_vector_alloc (size_t N)
     This function creates a vector of length N, returning a pointer to
     a newly initialized vector struct. A new block is allocated for the
     elements of the vector, and stored in the BLOCK member of the
     vector struct.  The block is "owned" by the vector, and will be
     deallocated when the vector is deallocated.

 - Function: gsl_vector * gsl_vector_calloc (size_t N)
     This function allocates memory for a vector of length N and
     initializes all the elements of the vector to zero.

 - Function: void gsl_vector_free (gsl_vector * V)
     This function frees a previously allocated vector V.  If the
     vector was created using `gsl_vector_alloc' then the block
     underlying the vector will also be deallocated.  If the vector has
     been created from another object then the memory is still owned by
     that object and will not be deallocated.


File: gsl-ref.info,  Node: Accessing vector elements,  Next: Initializing vector elements,  Prev: Vector allocation,  Up: Vectors and Matrices

Accessing vector elements
=========================

   Unlike FORTRAN compilers, C compilers do not usually provide support
for range checking of vectors and matrices (1).  However, the functions
`gsl_vector_get' and `gsl_vector_set' can perform range checking for
you and report an error if you attempt to access elements outside the
allowed range.

   The functions for accessing the elements of a vector or matrix are
defined in `gsl_vector.h' and declared `extern inline' to eliminate
function-call overhead.  If necessary you can turn off range checking
completely without modifying any source files by recompiling your
program with the preprocessor definition `GSL_RANGE_CHECK_OFF'.
Provided your compiler supports inline functions the effect of turning
off range checking is to replace calls to `gsl_vector_get(v,i)' by
`v->data[i*v->stride]' and and calls to `gsl_vector_set(v,i,x)' by
`v->data[i*v->stride]=x'.  Thus there should be no performance penalty
for using the range checking functions when range checking is turned
off.

 - Function: double gsl_vector_get (const gsl_vector * V, size_t I)
     This function returns the I-th element of a vector V.  If I lies
     outside the allowed range of 0 to N-1 then the error handler is
     invoked and 0 is returned.

 - Function: void gsl_vector_set (gsl_vector * V, size_t I, double X)
     This function sets the value of the I-th element of a vector V to
     X.  If I lies outside the allowed range of 0 to N-1 then the error
     handler is invoked.

   ---------- Footnotes ----------

   (1) Range checking is available in the GNU C Compiler extension
`checkergcc', as part of its full memory checking facility


File: gsl-ref.info,  Node: Initializing vector elements,  Next: Reading and writing vectors,  Prev: Accessing vector elements,  Up: Vectors and Matrices

Initializing vector elements
============================

 - Function: void gsl_vector_set_all (gsl_vector * V, double X)
     This function sets all the elements of the vector V to the value X.

 - Function: void gsl_vector_set_zero (gsl_vector * V)
     This function sets all the elements of the vector V to zero.

 - Function: int gsl_vector_set_basis (gsl_vector * V, size_t I)
     This function makes a basis vector by setting all the elements of
     the vector V to zero except for the I-th element which is set to
     one.


File: gsl-ref.info,  Node: Reading and writing vectors,  Next: Creating subvector views,  Prev: Initializing vector elements,  Up: Vectors and Matrices

Reading and writing vectors
===========================

   The library provides functions for reading and writing vectors to a
file as binary data or formatted text.

 - Function: int gsl_vector_fwrite (FILE * STREAM, const gsl_vector * V)
     This function writes the elements of the vector V to the stream
     STREAM in binary format.  The return value is 0 for success and
     `GSL_EFAILED' if there was a problem writing to the file.  Since
     the data is written in the native binary format it may not be
     portable between different architectures.

 - Function: int gsl_vector_fread (FILE * STREAM, gsl_vector * V)
     This function reads into the vector V from the open stream STREAM
     in binary format.  The vector V must be preallocated with the
     correct length since the function uses the size of V to determine
     how many bytes to read.  The return value is 0 for success and
     `GSL_EFAILED' if there was a problem reading from the file.  The
     data is assumed to have been written in the native binary format
     on the same architecture.

 - Function: int gsl_vector_fprintf (FILE * STREAM, const gsl_vector *
          V, const char * FORMAT)
     This function writes the elements of the vector V line-by-line to
     the stream STREAM using the format specifier FORMAT, which should
     be one of the `%g', `%e' or `%f' formats for floating point
     numbers and `%d' for integers.  The function returns 0 for success
     and `GSL_EFAILED' if there was a problem writing to the file.

 - Function: int gsl_vector_fscanf (FILE * STREAM, gsl_vector * V)
     This function reads formatted data from the stream STREAM into the
     vector V.  The vector V must be preallocated with the correct
     length since the function uses the size of V to determine how many
     numbers to read.  The function returns 0 for success and
     `GSL_EFAILED' if there was a problem reading from the file.


File: gsl-ref.info,  Node: Creating subvector views,  Next: Copying vectors,  Prev: Reading and writing vectors,  Up: Vectors and Matrices

Creating subvector views
========================

 - Function: gsl_vector gsl_vector_subvector (gsl_vector *V, size_t I,
          size_t N)
     This function returns a `gsl_vector' struct which is a view of a
     subvector of another vector V.  The start of the new vector is
     offset by OFFSET elements from the start of the original vector.
     The new vector has N elements.  Mathematically, the I-th element
     of the new vector V' is given by,

          v'(i) = v->data[(offset + i)*v->stride]

     where the index I runs from 0 to `n-1'.

     The `data' pointer of the returned vector struct is set to null if
     the combined parameters (OFFSET,N) overrun the end of the original
     vector.

     The new vector is only a view of the block underlying the original
     vector, V.  The block containing the elements of V is not owned by
     the new vector.  When the new vector goes out of scope the
     original vector V and its block will continue to exist.  The
     original memory can only be deallocated by freeing the original
     vector.  Of course, the original vector should not be deallocated
     while the new vector is still in use.

 - Function: gsl_vector gsl_vector_subvector_with_stride (gsl_vector
          *V, size_t I, size_t N, size_t STRIDE)
     This function returns a `gsl_vector' struct which is a view of a
     subvector of another vector V. The subvector is formed in the same
     way as for `gsl_vector_subvector' but with an additional stride
     argument. The new vector has N elements, with a step-size of
     STRIDE from one element to the next in the original vector.
     Mathematically, the I-th element of the new vector V' is given by,

          v'(i) = v->data[(offset + i*stride)*v->stride]

     where the index I runs from 0 to `n-1'.

Note that subvector views give direct access to the underlying elements
of the original vector. For example, the following code will zero the
even elements of the vector `v' of length `n', while leaving the odd
elements untouched,

     gsl_vector v_even = gsl_vector_subvector_with_stride (v, 0, n/2, 2);
     gsl_vector_set_zero (&v_even);

A vector view can be passed to any subroutine which takes a vector
argument, using the `&' operator, just as a directly allocated vector
would be.  For example, the following code computes the norm of odd
elements of `v' using the BLAS routine DNRM2,

     gsl_vector v_odd = gsl_vector_subvector_with_stride (v, 1, n/2, 2);
     double r = gsl_blas_dnrm2 (&v_odd);


File: gsl-ref.info,  Node: Copying vectors,  Next: Exchanging elements,  Prev: Creating subvector views,  Up: Vectors and Matrices

Copying vectors
===============

   Common operations on vectors such as addition and multiplication are
available in the BLAS part of the library (*note BLAS Support::.).
However, it is useful to have a small number of utility functions which
do not require the full BLAS code.  The following functions fall into
this category.

 - Function: int gsl_vector_memcpy (gsl_vector * DEST, const gsl_vector
          * SRC)
     This function copies the elements of the vector SRC into the
     vector DEST.  The two vectors must be the same length.

 - Function: int gsl_vector_swap (gsl_vector * V, gsl_vector * W)
     This function exchanges the elements of the vectors V and W by
     copying.


File: gsl-ref.info,  Node: Exchanging elements,  Next: Vector operations,  Prev: Copying vectors,  Up: Vectors and Matrices

Exchanging elements
===================

   The following function can be used to exchange, or permute, the
elements of a vector.

 - Function: int gsl_vector_swap_elements (gsl_vector * V, size_t i,
          size_t j)
     This function exchanges the I-th and J-th elements of the vector V
     in-place.

 - Function: int gsl_vector_reverse (gsl_vector * V)
     This function reverses the order of the elements of the vector V.


File: gsl-ref.info,  Node: Vector operations,  Next: Finding maximum and minimum elements of vectors,  Prev: Exchanging elements,  Up: Vectors and Matrices

Vector operations
=================

 - Function: int gsl_vector_add (gsl_vector * A, const gsl_vector * B)
     This function adds the elements of vector B to the elements of
     vector A, a'_i = a_i + b_i. The two vectors must have the same
     length.

 - Function: int gsl_vector_sub (gsl_vector * A, const gsl_vector * B)
     This function subtracts the elements of vector B from the elements
     of vector A, a'_i = a_i - b_i. The two vectors must have the same
     length.

 - Function: int gsl_vector_mul (gsl_vector * A, const gsl_vector * B)
     This function multiplies the elements of vector A by the elements
     of vector B, a'_i = a_i * b_i. The two vectors must have the same
     length.

 - Function: int gsl_vector_div (gsl_vector * A, const gsl_vector * B)
     This function divides the elements of vector A by the elements of
     vector B, a'_i = a_i / b_i. The two vectors must have the same
     length.

 - Function: int gsl_vector_scale (gsl_vector * A, const double X)
     This function multiplies the elements of vector A by the constant
     factor X, a'_i = x a_i.

 - Function: int gsl_vector_add_constant (gsl_vector * A, const double
          X)
     This function adds the constant value X to the elements of the
     vector A, a'_i = a_i + x.


File: gsl-ref.info,  Node: Finding maximum and minimum elements of vectors,  Next: Vector properties,  Prev: Vector operations,  Up: Vectors and Matrices

Finding maximum and minimum elements of vectors
===============================================

 - Function: double gsl_vector_max (const gsl_vector * V)
     This function returns the maximum value in the vector V.

 - Function: double gsl_vector_min (const gsl_vector * V)
     This function returns the minimum value in the vector V.

 - Function: void gsl_vector_minmax (const gsl_vector * V, double *
          MIN_OUT, double * MAX_OUT)
     This function returns the minimum and maximum values in the vector
     V, storing them in MIN_OUT and MAX_OUT.

 - Function: size_t gsl_vector_max_index (const gsl_vector * V)
     This function returns the index of the maximum value in the vector
     V.  When there are several equal maximum elements then the lowest
     index is returned.

 - Function: size_t gsl_vector_min_index (const gsl_vector * V)
     This function returns the index of the minimum value in the vector
     V.  When there are several equal minimum elements then the lowest
     index is returned.

 - Function: void gsl_vector_minmax_index (const gsl_vector * V, size_t
          * IMIN, size_t * IMAX)
     This function returns the indices of the minimum and maximum
     values in the vector V, storing them in IMIN and IMAX. When there
     are several equal minimum or maximum elements then the lowest
     indices are returned.


File: gsl-ref.info,  Node: Vector properties,  Next: Example programs for vectors,  Prev: Finding maximum and minimum elements of vectors,  Up: Vectors and Matrices

Vector properties
=================

 - Function: int gsl_vector_isnull (const gsl_vector * V)
     This function returns 1 if all the elements of the vector V are
     zero, and 0 otherwise.


File: gsl-ref.info,  Node: Example programs for vectors,  Next: The matrix struct,  Prev: Vector properties,  Up: Vectors and Matrices

Example programs for vectors
============================

   This program shows how to allocate, initialize and read from a vector
using the functions `gsl_vector_alloc', `gsl_vector_set' and
`gsl_vector_get'.

     #include <stdio.h>
     #include <gsl/gsl_vector.h>
     
     int main ()
     {
       int i;
       gsl_vector * v = gsl_vector_alloc (3) ;
     
       for (i = 0; i < 3; i++)
         {
           gsl_vector_set (v, i, 1.23 + i);
         }
     
       for (i = 0; i < 100; i++)
         {
           printf("v_%d = %g\n", i, gsl_vector_get (v, i));
         }
     }

Here is the output from the program.  The final loop attempts to read
outside the range of the vector `v', and the error is trapped by the
range-checking code in `gsl_vector_get'.

     v_0 = 1.23
     v_1 = 2.23
     v_2 = 3.23
     gsl: vector_source.c:12: ERROR: index out of range
     IOT trap/Abort (core dumped)

The next program shows how to write a vector to a file.

     #include <stdio.h>
     #include <gsl/gsl_vector.h>
     
     int main ()
     {
       int i;
       gsl_vector * v = gsl_vector_alloc (100) ;
     
       for (i = 0; i < 100; i++)
         {
           gsl_vector_set (v, i, 1.23 + i);
         }
     
       {
          FILE * f = fopen("test.dat", "w") ;
          gsl_vector_fprintf (f, v, "%.5g");
          fclose (f);
       }
     }

After running this program the file `test.dat' should contain the
elements of `v', written using the format specifier `%.5g'.  The vector
could then be read back in using the function `gsl_vector_fscanf (f,
v)'.


File: gsl-ref.info,  Node: The matrix struct,  Next: Matrix allocation,  Prev: Example programs for vectors,  Up: Vectors and Matrices

The matrix struct
=================

   Matrices are defined by a `gsl_matrix' structure which describes a
generalized slice of a block.  Like a vector it represents a "view" of
an area of memory, but uses two indices instead of one.

   The `gsl_matrix' structure contains five members, the two dimensions
of the matrix, a physical dimension, a pointer to the memory where the
elements of the matrix are stored, DATA, and a pointer to the block
owned by the matrix BLOCK, if any.  The physical dimension determines
the memory layout and can differ from the matrix dimension to allow the
use of submatrices.  The `gsl_matrix' structure is very simple and
looks like this,

     typedef struct
     {
       size_t size1;
       size_t size2;
       size_t tda;
       double * data;
       gsl_block * block;
     } gsl_matrix ;

Matrices are stored in row-major order, meaning that each row of
elements forms a contiguous block in memory.  This is the standard
"C-ordering" of two-dimensional arrays. Note that FORTRAN stores arrays
in column-major order. The number of rows is SIZE1.  The range of valid
row indices runs from 0 to `size1-1'.  Similarly SIZE2 is the number of
columns.  The range of valid column indices runs from 0 to `size2-1'.
The physical row dimension TDA, or "trailing dimension", specifies the
size of a row of the matrix as laid out in memory.

   For example, in the following matrix SIZE1 is 3, SIZE2 is 4, and TDA
is 8.  The physical memory layout of the matrix begins in the top left
hand-corner and proceeds from left to right along each row in turn.

     00 01 02 03 XX XX XX XX
     10 11 12 13 XX XX XX XX
     20 21 22 23 XX XX XX XX

Each unused memory location is represented by "`XX'".  The pointer DATA
gives the location of the first element of the matrix in memory.  The
pointer BLOCK stores the location of the memory block owned by the
matrix (if any).  This block will be deallocated when the matrix is
freed.  If the matrix is only a view of another object then the pointer
BLOCK is null.

   The functions for allocating and accessing matrices are defined in
`gsl_matrix.h'


File: gsl-ref.info,  Node: Matrix allocation,  Next: Accessing matrix elements,  Prev: The matrix struct,  Up: Vectors and Matrices

Matrix allocation
=================

   The functions for allocating memory to a matrix follow the style of
`malloc' and `free'.  They also perform their own error checking.  If
there is insufficient memory available to allocate a vector then the
functions call the GSL error handler (with an error number of
`GSL_ENOMEM') in addition to returning a null pointer.  Thus if you use
the library error handler to abort your program then it isn't necessary
to check every `alloc'.

 - Function: gsl_matrix * gsl_matrix_alloc (size_t N1, size_t N2)
     This function creates a matrix of size N1 rows by N2 columns,
     returning a pointer to a newly initialized matrix struct. A new
     block is allocated for the elements of the matrix, and stored in
     the BLOCK member of the matrix struct.  The block is "owned" by the
     matrix, and will be deallocated when the matrix is deallocated.

 - Function: gsl_matrix * gsl_matrix_calloc (size_t N1, size_t N2)
     This function allocates memory for a matrix of size N1 rows by N2
     columns and initializes all the elements of the matrix to zero.

 - Function: void gsl_matrix_free (gsl_matrix * M)
     This function frees a previously allocated matrix M.  If the
     matrix was created using `gsl_matrix_alloc' then the block
     underlying the matrix will also be deallocated.  If the matrix has
     been created from another object then the memory is still owned by
     that object and will not be deallocated.


File: gsl-ref.info,  Node: Accessing matrix elements,  Next: Initializing matrix elements,  Prev: Matrix allocation,  Up: Vectors and Matrices

Accessing matrix elements
=========================

   The functions for accessing the elements of a matrix use the same
range checking system as vectors.  You turn off range checking by
recompiling your program with the preprocessor definition
`GSL_RANGE_CHECK_OFF'.

   The elements of the matrix are stored in "C-order", where the second
index moves continuously through memory.  More precisely, the element
accessed by the function `gsl_matrix_get(m,i,j)' and
`gsl_matrix_set(m,i,j,x)' is

     m->data[i * m->tda + j]

where TDA is the physical row-length of the matrix.

 - Function: double gsl_matrix_get (const gsl_matrix * M, size_t I,
          size_t J)
     These functions return the (I,J)th element of a matrix M.  If I or
     J lie outside the allowed range of 0 to N1-1 and 0 to N2-1 then
     the error handler is invoked and 0 is returned.

 - Function: void gsl_matrix_set (gsl_matrix * M, size_t I, size_t J,
          double X)
     These functions set the value of the (I,J)th element of a matrix M
     to X.  If I or J lies outside the allowed range of 0 to N1-1 and 0
     to N2-1 then the error handler is invoked.


File: gsl-ref.info,  Node: Initializing matrix elements,  Next: Reading and writing matrices,  Prev: Accessing matrix elements,  Up: Vectors and Matrices

Initializing matrix elements
============================

 - Function: void gsl_matrix_set_all (gsl_matrix * M, double X)
     This function sets all the elements of the matrix M to the value X.

 - Function: void gsl_matrix_set_zero (gsl_matrix * M)
     This function sets all the elements of the matrix M to zero.

 - Function: void gsl_matrix_set_identity (gsl_matrix * M)
     This function sets the elements of the matrix M to the
     corresponding elements of the identity matrix, m(i,j) =
     \delta(i,j), i.e. a unit diagonal with all off-diagonal elements
     zero.  This applies to both square and rectangular matrices.


File: gsl-ref.info,  Node: Reading and writing matrices,  Next: Creating submatrix views,  Prev: Initializing matrix elements,  Up: Vectors and Matrices

Reading and writing matrices
============================

   The library provides functions for reading and writing matrices to a
file as binary data or formatted text.

 - Function: int gsl_matrix_fwrite (FILE * STREAM, const gsl_matrix * M)
     This function writes the elements of the matrix M to the stream
     STREAM in binary format.  The return value is 0 for success and
     `GSL_EFAILED' if there was a problem writing to the file.  Since
     the data is written in the native binary format it may not be
     portable between different architectures.

 - Function: int gsl_matrix_fread (FILE * STREAM, gsl_matrix * M)
     This function reads into the matrix M from the open stream STREAM
     in binary format.  The matrix M must be preallocated with the
     correct dimensions since the function uses the size of M to
     determine how many bytes to read.  The return value is 0 for
     success and `GSL_EFAILED' if there was a problem reading from the
     file.  The data is assumed to have been written in the native
     binary format on the same architecture.

 - Function: int gsl_matrix_fprintf (FILE * STREAM, const gsl_matrix *
          M, const char * FORMAT)
     This function writes the elements of the matrix M line-by-line to
     the stream STREAM using the format specifier FORMAT, which should
     be one of the `%g', `%e' or `%f' formats for floating point
     numbers and `%d' for integers.  The function returns 0 for success
     and `GSL_EFAILED' if there was a problem writing to the file.

 - Function: int gsl_matrix_fscanf (FILE * STREAM, gsl_matrix * M)
     This function reads formatted data from the stream STREAM into the
     matrix M.  The matrix M must be preallocated with the correct
     dimensions since the function uses the size of M to determine how
     many numbers to read.  The function returns 0 for success and
     `GSL_EFAILED' if there was a problem reading from the file.


File: gsl-ref.info,  Node: Creating submatrix views,  Next: Creating row and column views,  Prev: Reading and writing matrices,  Up: Vectors and Matrices

Creating submatrix views
========================

 - Function: gsl_matrix gsl_matrix_submatrix (gsl_matrix * M, size_t I,
          size_t J, size_t N1, size_t N2)
     This function returns a `gsl_matrix' struct which is a view of a
     submatrix of the matrix M.  The upper-left element of the
     submatrix is the element (K1,K2) of the original matrix.  The
     submatrix has N1 rows and N2 columns.  The physical number of
     columns in memory given by TDA is unchanged.  Mathematically, the
     (I,J)-th element of the new matrix is given by,

          m'(i,j) = m->data[(k1*m->tda + k2) + i*m->tda + j]

     where the index I runs from 0 to `n1-1' and the index J runs from
     0 to `n2-1'.

     The `data' pointer of the returned matrix struct is set to null if
     the combined parameters (K1,K2,N1,N2,TDA) overrun the ends of the
     original matrix.

     The new matrix is only a view of the block underlying the existing
     matrix, M.  The block containing the elements of M is not owned by
     the new matrix.  When the new matrix goes out of scope the
     original matrix M and its block will continue to exist.  The
     original memory can only be deallocated by freeing the original
     matrix.  Of course, the original matrix should not be deallocated
     while the new matrix is still in use.


File: gsl-ref.info,  Node: Creating row and column views,  Next: Copying matrices,  Prev: Creating submatrix views,  Up: Vectors and Matrices

Creating row and column views
=============================

   In general there are two ways to access an object, by reference or by
copying.  The functions described in this section create vectors which
allow access to a row or column of a matrix by reference.  Modifying
elements of the vector is equivalent to modifying the matrix, since both
the vector and the matrix point to the same memory block.

 - Function: gsl_vector gsl_matrix_row (gsl_matrix * M, size_t I)
     This function returns `gsl_vector' struct which is a view of the
     I-th row of the matrix M.  The `data' pointer of the new vector is
     set to null if I is out of range.

 - Function: gsl_vector gsl_matrix_column (gsl_matrix * M, size_t J)
     This function returns a `gsl_vector' struct which is a view of the
     J-th column of the matrix M.  The `data' pointer of the new vector
     is set to null if J is out of range.

 - Function: gsl_vector gsl_matrix_diagonal (gsl_matrix * M)
     This function returns a `gsl_vector' struct which is a view of the
     diagonal of the matrix M. The matrix M 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.


File: gsl-ref.info,  Node: Copying matrices,  Next: Copying rows and columns,  Prev: Creating row and column views,  Up: Vectors and Matrices

Copying matrices
================

 - Function: int gsl_matrix_memcpy (gsl_matrix * DEST, const gsl_matrix
          * SRC)
     This function copies the elements of the matrix SRC into the
     matrix DEST.  The two matrices must have the same size.

 - Function: int gsl_matrix_swap (gsl_matrix * M1, const gsl_matrix *
          M2)
     This function exchanges the elements of the matrices M1 and M2 by
     copying.  The two matrices must have the same size.


File: gsl-ref.info,  Node: Copying rows and columns,  Next: Exchanging rows and columns,  Prev: Copying matrices,  Up: Vectors and Matrices

Copying rows and columns
========================

   The functions described in this section copy a row or column of a
matrix into a vector.  This allows the elements of the vector and the
matrix to be modified independently.  Note that if the matrix and the
vector point to overlapping regions of memory then the result will be
undefined.

 - Function: int gsl_matrix_get_row (gsl_vector * V, const gsl_matrix *
          M, size_t I)
     This function copies the elements of the I-th row of the matrix M
     into the vector V.  The length of the vector must be the same as
     the length of the row.

 - Function: int gsl_matrix_get_col (gsl_vector * V, const gsl_matrix *
          M, size_t J)
     This function copies the elements of the I-th column of the matrix
     M into the vector V.  The length of the vector must be the same as
     the length of the column.

 - Function: int gsl_matrix_set_row (gsl_matrix * M, size_t I, const
          gsl_vector * V)
     This function copies the elements of the vector V into the I-th
     row of the matrix M.  The length of the vector must be the same as
     the length of the row.

 - Function: int gsl_matrix_set_col (gsl_matrix * M, size_t J, const
          gsl_vector * V)
     This function copies the elements of the vector V into the I-th
     column of the matrix M.  The length of the vector must be the same
     as the length of the column.


File: gsl-ref.info,  Node: Exchanging rows and columns,  Next: Matrix operations,  Prev: Copying rows and columns,  Up: Vectors and Matrices

Exchanging rows and columns
===========================

   The following functions can be used to exchange the rows and columns
of a matrix.

 - Function: int gsl_matrix_swap_rows (gsl_matrix * M, size_t I, size_t
          J)
     This function exchanges the I-th and J-th rows of the matrix M
     in-place.

 - Function: int gsl_matrix_swap_columns (gsl_matrix * M, size_t I,
          size_t J)
     This function exchanges the I-th and J-th columns of the matrix M
     in-place.

 - Function: int gsl_matrix_swap_rowcol (gsl_matrix * M, size_t I,
          size_t J)
     This function exchanges the I-th row and J-th column of the matrix
     M in-place.  The matrix must be square for this operation to be
     possible.

 - Function: int gsl_matrix_transpose (gsl_matrix * M)
     This function replaces the matrix M by its transpose by copying
     the elements of the matrix in-place.  The matrix must be square
     for this operation to be possible.


File: gsl-ref.info,  Node: Matrix operations,  Next: Finding maximum and minimum elements of matrices,  Prev: Exchanging rows and columns,  Up: Vectors and Matrices

Matrix operations
=================

 - Function: int gsl_matrix_add (gsl_matrix * A, const gsl_matrix * B)
     This function adds the elements of matrix B to the elements of
     matrix A, a'(i,j) = a(i,j) + b(i,j). The two matrices must have the
     same dimensions.

 - Function: int gsl_matrix_sub (gsl_matrix * A, const gsl_matrix * B)
     This function subtracts the elements of matrix B from the elements
     of matrix A, a'(i,j) = a(i,j) - b(i,j). The two matrices must have
     the same dimensions.

 - Function: int gsl_matrix_mul (gsl_matrix * A, const gsl_matrix * B)
     This function multiplies the elements of matrix A by the elements
     of matrix B, a'(i,j) = a(i,j) * b(i,j). The two matrices must have
     the same dimensions.

 - Function: int gsl_matrix_div (gsl_matrix * A, const gsl_matrix * B)
     This function divides the elements of matrix A by the elements of
     matrix B, a'(i,j) = a(i,j) / b(i,j). The two matrices must have the
     same dimensions.

 - Function: int gsl_matrix_scale (gsl_matrix * A, const double X)
     This function multiplies the elements of matrix A by the constant
     factor X, a'(i,j) = x a(i,j).

 - Function: int gsl_matrix_add_constant (gsl_matrix * A, const double
          X)
     This function adds the constant value X to the elements of the
     matrix A, a'(i,j) = a(i,j) + x.


File: gsl-ref.info,  Node: Finding maximum and minimum elements of matrices,  Next: Matrix properties,  Prev: Matrix operations,  Up: Vectors and Matrices

Finding maximum and minimum elements of matrices
================================================

 - Function: double gsl_matrix_max (const gsl_matrix * M)
     This function returns the maximum value in the matrix M.

 - Function: double gsl_matrix_min (const gsl_matrix * M)
     This function returns the minimum value in the matrix M.

 - Function: void gsl_matrix_minmax (const gsl_matrix * M, double *
          MIN_OUT, double * MAX_OUT)
     This function returns the minimum and maximum values in the matrix
     M, storing them in MIN_OUT and MAX_OUT.

 - Function: void gsl_matrix_max_index (const gsl_matrix * M, size_t *
          IMAX, size_t * JMAX)
     This function returns the indices of the maximum value in the
     matrix M, storing them in IMAX and JMAX.  When there are several
     equal maximum elements then the first element found is returned.

 - Function: void gsl_matrix_min_index (const gsl_matrix * M, size_t *
          IMAX, size_t * JMAX)
     This function returns the indices of the minimum value in the
     matrix M, storing them in IMAX and JMAX.  When there are several
     equal minimum elements then the first element found is returned.

 - Function: void gsl_matrix_minmax_index (const gsl_matrix * M, size_t
          * IMIN, size_t * IMAX)
     This function returns the indices of the minimum and maximum
     values in the matrix M, storing them in (IMIN,JMIN) and
     (IMAX,JMAX. When there are several equal minimum or maximum
     elements then the first elements found are returned.


File: gsl-ref.info,  Node: Matrix properties,  Next: Example programs for matrices,  Prev: Finding maximum and minimum elements of matrices,  Up: Vectors and Matrices

Matrix properties
=================

 - Function: int gsl_matrix_isnull (const gsl_matrix * M)
     This function returns 1 if all the elements of the matrix M are
     zero, and 0 otherwise.


File: gsl-ref.info,  Node: Example programs for matrices,  Next: Vector and Matrix References and Further Reading,  Prev: Matrix properties,  Up: Vectors and Matrices

Example programs for matrices
=============================

   This program shows how to allocate, initialize and read from a matrix
using the functions `gsl_matrix_alloc', `gsl_matrix_set' and
`gsl_matrix_get'.

     #include <stdio.h>
     #include <gsl/gsl_matrix.h>
     
     int main ()
     {
       int i, j;
       gsl_matrix * m = gsl_matrix_alloc (10, 3) ;
     
       for (i = 0; i < 10; i++)
         for (j = 0; j < 3; j++)
           gsl_matrix_set (m, i, j, 0.23 + 100*i + j);
     
       for (i = 0; i < 100; i++)
         for (j = 0; j < 3; j++)
           printf("m(%d,%d) = %g\n", i, j, gsl_matrix_get (m, i, j));
     }

Here is the output from the program.  The final loop attempts to read
outside the range of the matrix `m', and the error is trapped by the
range-checking code in `gsl_matrix_get'.

     m(0,0) = 0.23
     m(0,1) = 1.23
     m(0,2) = 2.23
     m(1,0) = 100.23
     m(1,1) = 101.23
     m(1,2) = 102.23
     ...
     m(9,2) = 902.23
     gsl: matrix_source.c:13: ERROR: first index out of range
     IOT trap/Abort (core dumped)

The next program shows how to write a matrix to a file.

     #include <stdio.h>
     #include <gsl/gsl_matrix.h>
     
     int main ()
     {
       int i, j, differences = 0;
       gsl_matrix * m = gsl_matrix_alloc (100, 100) ;
       gsl_matrix * a = gsl_matrix_alloc (100, 100) ;
     
       for (i = 0; i < 100; i++)
         for (j = 0 ; j < 100; j++)
           gsl_matrix_set (m, i, j, 0.23 + i + j);
     
       {
          FILE * f = fopen("test.dat", "w") ;
          gsl_matrix_fwrite (f, m);
          fclose (f);
       }
     
       {
          FILE * f = fopen("test.dat", "r") ;
          gsl_matrix_fread (f, a);
          fclose (f);
       }
     
       for (i = 0; i < 100; i++)
         for (j = 0 ; j < 100; j++)
             if (gsl_matrix_get(m, i, j) != gsl_matrix_get(a, i, j))
                differences ++ ;
     
       printf("differences = %d (should be zero)\n", differences) ;
     
     }

After running this program the file `test.dat' should contain the
elements of `m', written in binary format.  The matrix which is read
back in using the function `gsl_matrix_fread' should be exactly equal
to the original matrix.


File: gsl-ref.info,  Node: Vector and Matrix References and Further Reading,  Prev: Example programs for matrices,  Up: Vectors and Matrices

References and Further Reading
==============================

   The block, vector and matrix objects in GSL follow the `valarray'
model of C++.  A description of this model can be found in the following
reference,

     B. Stroustrup, `The C++ Programming Language' (3rd Ed), Section
     22.4 Vector Arithmetic.  Addison-Wesley 1997, ISBN 0-201-88954-4.


File: gsl-ref.info,  Node: BLAS Support,  Next: Linear Algebra,  Prev: Vectors and Matrices,  Up: Top

BLAS Support
************

* Menu:

* Introduction::
* Organization::
* GSL BLAS Interface::
* Raw BLAS Interface::
* BLAS References and Further Reading::


File: gsl-ref.info,  Node: Introduction,  Next: Organization,  Up: BLAS Support

Introduction
============

   The Basic Linear Algebra Standard (BLAS) prescribes a set of
fundamental operations on vectors and matrices which can be used to
create higher-level linear algebra functionality.  Because of the many
possible types of vectors and matrices, including variations in base
precision, the number of functions specified by the BLAS standard is
tediously large.

   Furthermore, because of the long history of BLAS and BLAS-like
implementations, and the need for interoperability, the complexity of
this part of GSL is somewhat high.  Casual users will often find what
they need in the `gsl_linalg' library, which implements a set of common
high-level linear algebra operations on GSL vector and matrix objects.
Some familiarity with the BLAS standards, including both the legacy and
draft interface standards, is assumed in this chapter.


File: gsl-ref.info,  Node: Organization,  Next: GSL BLAS Interface,  Prev: Introduction,  Up: BLAS Support

Organization
============

   GSL provides two layers of BLAS functionality, a low-level or "raw"
layer, which corresponds directly to the BLAS standard, and a GSL
specific layer for operation on GSL vector and matrix objects.  Users
who are interested in simple operations on GSL vector and matrix objects
should use the high-level GSL specific layer, which is specified in the
file `gsl_blas.h'.  Also, users interested in simple linear algebra
functionality for GSL vector and matrix objects are directed to the
`gsl_linalg' library.  This should satisfy the needs of most users.
Note that full BLAS functionality is not available for GSL vector and
matrix objects since GSL provides only standard dense storage-format
objects, for which much of the BLAS functionality does not apply.

   The interface for the `gsl_blas_raw' layer is specified in the file
`gsl_blas_raw.h'.  The functionality described by this interface is
semantically equivalent to the BLAST reference draft for a C interface
to legacy BLAS implementations.

   The `gsl_blas_raw' layer exists in order to provide an extra layer
of indirection over legacy BLAS functionality, so that users have the
ability to switch BLAS implementations at link time. GSL itself
provides two implementations conforming to the `gsl_blas_raw'
interface, each in the form of a compiled library.

   The first implementation, `libgslblasnative', is a native GSL
implementation of level-1, level-2, and a portion of level-3
functionality.  Users who need to use the low-level `gsl_blas_raw'
functions and who do not have access to a vendor-supplied or other
CBLAS implementation, or who are not interested in optimal performance,
can use this native functionality by writing their code to the
`gsl_blas_raw' interface and linking with `libgslblasnative'.

   The second provided implementation `libgslblascblas', is a wrapper
over a conforming CBLAS implementation, which is assumed to exist (and
which in some cases can be detected at configure time).  Users who have
access to a conforming CBLAS implementation can use such a library by
writing their code to the `gsl_blas_raw' interface and linking with
`libgslblascblas'.  Note that users who have only a legacy Fortran
source BLAS library will need to first obtain a CBLAS conformant
wrapper and compile that. A reference CBLAS implementation, written as
a wrapper over a legacy Fortran implementation, exists as part of the
draft CBLAS standard and can be obtained via Netlib.

   Using the extra layer provided by the `gsl_blas_raw' interface,
users or third-parties can also create their own implementations.  Any
implementation conforming to the `gsl_blas_raw' interface (or perhaps
some portion thereof) can be linked against the same client code.  We
hope that this will provide some insulation for client code against
arbitrariness in BLAS or BLAS-like implementations.

