Gnu Scientific Library

Extracted from the Gnu Scientific Library reference manual which is available
online at
http://www.gnu.org/software/gsl/
where you will find the reference manual and can download the library
routines. GSL is installed on the cphys2 system and other machines in College.

1.1 Routines available in GSL

The library covers a wide range of topics in numerical computing. Routines are
available for the following areas,

Complex Numbers Roots of Polynomials

Special Functions Vectors and Matrices
Permutations Combinations
Sorting BLAS Support
Linear Algebra CBLAS Library
Fast Fourier Transforms Eigensystems
Random Numbers Quadrature
Random Distributions Quasi-Random Sequences
Histograms Statistics
Monte Carlo Integration N-Tuples
Differential Equations Simulated Annealing
Numerical Differentiation Interpolation
Series Acceleration Chebyshev Approximations
Root-Finding Discrete Hankel Transforms
Least-Squares Fitting Minimization
IEEE Floating-Point Physical Constants
Wavelets
2.1 An Example Program
The following short program demonstrates the use of the library by computing
the value of the Bessel function J_0(x) for x=5,
#include <stdio.h>
#include </usr/include/gsl/gsl_sf_bessel.h>

int
main (void)
{
double x = 5.0;
double y = gsl_sf_bessel_J0 (x);
printf ("J0(%g) = %.18e\n", x, y);
return 0;
}

The output is shown below, and should be correct to double-precision accuracy,

J0(5) = -1.775967713143382920e-01

Go to

www.tcd.ie/Physics/People/Charles.Patterson/teaching/PY4062/index.php

Download bessel.c and compile and run it using

gcc -o bessel bessel.c -lgsl -lgslcblas
./bessel

5 Complex Numbers
The functions described in this chapter provide support for complex numbers.
The algorithms take care to avoid unnecessary intermediate underflows and
overflows, allowing the functions to be evaluated over as much of the complex
plane as possible.
The complex types are defined in the header file gsl_complex.h, while the
corresponding complex functions and arithmetic operations are defined in
gsl_complex_math.h.

5.1 Complex numbers

Complex numbers are represented using the type gsl_complex. The internal
representation of this type may vary across platforms and should not be
accessed directly. The functions and macros described below allow complex
numbers to be manipulated in a portable way.
The default form of the gsl_complex type is given by the following struct,
typedef struct
{
double dat[2];
} gsl_complex;
The real and imaginary part are stored in contiguous elements of a two
element array. This eliminates any padding between the real and imaginary
parts, dat[0] and dat[1], allowing the struct to be mapped correctly onto
packed complex arrays.
Function: gsl_complex gsl_complex_rect (double x, double y)
This function uses the rectangular cartesian components (x,y) to
return the complex number z = x + i y. An inline version of this
function is used when HAVE_INLINE is defined.

Function: gsl_complex gsl_complex_polar (double r, double theta)

This function returns the complex number z = r \exp(i \theta) = r
(\cos(\theta) + i \sin(\theta)) from the polar representation (r,theta).

7 Special Functions
The special functions are available in two calling conventions, a natural form
which returns the numerical value of the function and an error-handling form
which returns an error code. The two types of function provide alternative ways
of accessing the same underlying code.
The natural form returns only the value of the function and can be used directly
in mathematical expressions. For example, the following function call will
compute the value of the Bessel function J_0(x),
double y = gsl_sf_bessel_J0 (x);

There is no way to access an error code or to estimate the error using this
method. To allow access to this information the alternative error-handling form
stores the value and error in a modifiable argument,
gsl_sf_result result;
int status = gsl_sf_bessel_J0_e (x, &result);

The error-handling functions have the suffix _e. The returned status value
indicates error conditions such as overflow, underflow or loss of precision. If
there are no errors the error-handling functions return GSL_SUCCESS.

8 Vectors and Matrices

The functions described in this chapter provide a simple vector and matrix
interface to ordinary C arrays. The memory management of these arrays is
implemented using a single underlying type, known as a block. By writing your
functions in terms of vectors and matrices you can pass a single structure
containing both data and dimensions as an argument without needing
additional function parameters. The structures are compatible with the vector
and matrix formats used by blas routines.
8.2 Blocks
For consistency all memory is allocated through a gsl_block structure. The
structure contains two components, 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

Go to

www.tcd.ie/Physics/People/Charles.Patterson/teaching/PY4062/index.php

Download block.c and compile and run it using

gcc -o block block.c -lgsl -lgslcblas
./block

8.3 Vectors
Vectors are defined by a gsl_vector structure which describes a slice of a
block. Different vectors can be created which point to the same block. A vector
slice is a set of equally-spaced elements of an area of memory.
The gsl_vector structure contains five components, the size, the stride, a
pointer to the memory where the elements are stored, data, a pointer to the
block owned by the vector, block, if any, and an ownership flag, owner. The
structure is very simple and looks like this,
typedef struct
{
size_t size;
size_t stride;
double * data;
gsl_block * block;
int owner;
} 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 in which the vector
elements are located (if any). If the vector owns this block then the owner field
is set to one and the block will be deallocated when the vector is freed. If the
vector points to a block owned by another object then the owner field is zero
and any underlying block will not be deallocated with the vector.
The functions for allocating and accessing vectors are defined in gsl_vector.h

8.3.1 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 component 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. The vector v must be a valid vector object (a null
pointer is not allowed).

8.3.5 Vector views

In addition to creating vectors from slices of blocks it is also possible to slice
vectors and create vector views. For example, a subvector of another vector
can be described with a view, or two views can be made which provide access
to the even and odd elements of a vector.
A vector view is a temporary object, stored on the stack, which can be used to
operate on a subset of vector elements. Vector views can be defined for both
constant and non-constant vectors, using separate types that preserve
constness. A vector view has the type gsl_vector_view and a constant vector
view has the type gsl_vector_const_view. In both cases the elements of the
view can be accessed as a gsl_vector using the vector component of the
view object. A pointer to a vector of type gsl_vector * or const gsl_vector
* can be obtained by taking the address of this component with the & operator.
When using this pointer it is important to ensure that the view itself remains in
scope—the simplest way to do so is by always writing the pointer as
&view.vector, and never storing this value in another variable.

Function: gsl_vector_view gsl_vector_view_array (double * base, size_t n)

Function: gsl_vector_const_view gsl_vector_const_view_array (const double

* base, size_t n)

These functions return a vector view of an array. The start of the new
vector is given by base and has n elements. Mathematically, the i-th
element of the new vector v' is given by,

v'(i) = base[i]

where the index i runs from 0 to n-1.

The array containing the elements of v is not owned by the new
vector view. When the view goes out of scope the original array will
continue to exist. The original memory can only be deallocated by
freeing the original pointer base. Of course, the original array should
not be deallocated while the view is still in use.

Go to

www.tcd.ie/Physics/People/Charles.Patterson/teaching/PY4062/index.php

Download vector.c and compile and run it using

gcc -o vector vector.c -lgsl -lgslcblas
./vector

8.4 Matrices
Matrices are defined by a gsl_matrix structure which describes a generalized
slice of a block. Like a vector it represents a set of elements in an area of
memory, but uses two indices instead of one.
The gsl_matrix structure contains six components, the two dimensions of the
matrix, a physical dimension, a pointer to the memory where the elements of
the matrix are stored, data, a pointer to the block owned by the matrix block, if
any, and an ownership flag, owner. 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;
int owner;
} 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-language
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 in which the elements of the matrix
are located (if any). If the matrix owns this block then the owner field is set to
one and the block will be deallocated when the matrix is freed. If the matrix is
only a slice of a block owned by another object then the owner field is zero and
any underlying block will not be freed.
The functions for allocating and accessing matrices are defined in
gsl_matrix.h

8.4.1 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
component 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. The matrix m must be a valid matrix object (a null
pointer is not allowed).

8.4.5 Matrix views

A matrix view is a temporary object, stored on the stack, which can be used to
operate on a subset of matrix elements. Matrix views can be defined for both
constant and non-constant matrices using separate types that preserve
constness. A matrix view has the type gsl_matrix_view and a constant matrix
view has the type gsl_matrix_const_view. In both cases the elements of the
view can by accessed using the matrix component of the view object. A
pointer gsl_matrix * or const gsl_matrix * can be obtained by taking the
address of the matrix component with the & operator. In addition to matrix
views it is also possible to create vector views of a matrix, such as row or
column views.
Function: gsl_matrix_view gsl_matrix_submatrix (gsl_matrix * m, size_t k1,
size_t k2, size_t n1, size_t n2)

Function: gsl_matrix_const_view gsl_matrix_const_submatrix (const

gsl_matrix * m, size_t k1, size_t k2, size_t n1, size_t n2)

These functions return a matrix 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 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 (i,j,n1,n2,tda) overrun the ends of the original
matrix.

The new matrix view 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 view. When the view 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 view is
still in use.

The function gsl_matrix_const_submatrix is equivalent to

gsl_matrix_submatrix but can be used for matrices which are
declared const.

Function: gsl_matrix_view gsl_matrix_view_array (double * base, size_t n1,

size_t n2)
Function: gsl_matrix_const_view gsl_matrix_const_view_array (const double
* base, size_t n1, size_t n2)

These functions return a matrix view of the array base. The matrix
has n1 rows and n2 columns. The physical number of columns in
memory is also given by n2. Mathematically, the (i,j)-th element of
the new matrix is given by,

m'(i,j) = base[i*n2 + j]

where index i runs from 0 to n1-1 and the index j runs from 0 to n2-1.
The new matrix is only a view of the array base. When the view goes
out of scope the original array base will continue to exist. The original
memory can only be deallocated by freeing the original array. Of
course, the original array should not be deallocated while the view is
still in use.

Go to

www.tcd.ie/Physics/People/Charles.Patterson/teaching/PY4062/index.php

Download matrix.c and compile and run it using

gcc -o matrix matrix.c -lgsl -lgslcblas
./matrix

12 BLAS Support
The Basic Linear Algebra Subprograms (blas) define a set of fundamental
operations on vectors and matrices which can be used to create optimized
higher-level linear algebra functionality.
The library provides a low-level layer which corresponds directly to the C-
language blas standard, referred to here as “cblas”, and a higher-level
interface for operations on GSL vectors and matrices. Users who are interested
in simple operations on GSL vector and matrix objects should use the high-level
layer, which is declared in the file gsl_blas.h. This should satisfy the needs of
most users. Note that GSL matrices are implemented using dense-storage so
the interface only includes the corresponding dense-storage blas functions. The
full blas functionality for band-format and packed-format matrices is available
through the low-level cblas interface.
The interface for the gsl_cblas layer is specified in the file gsl_cblas.h. This
interface corresponds to the blas Technical Forum's draft standard for the C
interface to legacy blas implementations. Users who have access to other
conforming cblas implementations can use these in place of the version
provided by the library. Note that users who have only a Fortran blas library
can use a cblas conformant wrapper to convert it into a cblas library. A
reference cblas wrapper for legacy Fortran implementations exists as part of
the draft cblas standard and can be obtained from Netlib. The complete set of
cblas functions is listed in an appendix (see GSL CBLAS Library).

There are three levels of blas operations,

Level 1
Vector operations, e.g. y = \alpha x + y
Level 2
Matrix-vector operations, e.g. y = \alpha A x + \beta y
Level 3
Matrix-matrix operations, e.g. C = \alpha A B + C

Each routine has a name which specifies the operation, the type of matrices
involved and their precisions. Some of the most common operations and their
names are given below,
DOT
scalar product, x^T y
AXPY
vector sum, \alpha x + y
MV
matrix-vector product, A x
SV
matrix-vector solve, inv(A) x
MM
matrix-matrix product, A B
SM
matrix-matrix solve, inv(A) B

The types of matrices are,

GE
general
GB
general band
SY
symmetric
SB
symmetric band
SP
symmetric packed
HE
hermitian
HB
hermitian band
HP
hermitian packed
TR
triangular
TB
triangular band
TP
triangular packed

Each operation is defined for four precisions,

S
single real
D
double real
C
single complex
Z
double complex

Thus, for example, the name sgemm stands for “single-precision general
matrix-matrix multiply” and zgemm stands for “double-precision complex
matrix-matrix multiply”.

13 Linear Algebra
This chapter describes functions for solving linear systems. The library provides
linear algebra operations which operate directly on the gsl_vector and
gsl_matrix objects. These routines use the standard algorithms from Golub &
Van Loan's Matrix Computations with Level-1 and Level-2 BLAS calls for
efficiency. The functions described in this chapter are declared in the header
file gsl_linalg.h.

14 Eigensystems
This chapter describes functions for computing eigenvalues and eigenvectors
of matrices. There are routines for real symmetric, real nonsymmetric, complex
hermitian, real generalized symmetric-definite, complex generalized hermitian-
definite, and real generalized nonsymmetric eigensystems. Eigenvalues can be
computed with or without eigenvectors. The hermitian and real symmetric
matrix algorithms are symmetric bidiagonalization followed by QR reduction.
The nonsymmetric algorithm is the Francis QR double-shift. The generalized
nonsymmetric algorithm is the QZ method due to Moler and Stewart. The
functions described in this chapter are declared in the header file gsl_eigen.h.