vectors.texi

开放gsl矩阵运算

This function creates a matrix of size @var{n1} rows by @var{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
@var{block} component of the matrix struct.  The block is ``owned'' by the
matrix, and will be deallocated when the matrix is deallocated.
@end deftypefun

@deftypefun {gsl_matrix *} gsl_matrix_calloc (size_t @var{n1}, size_t @var{n2})
This function allocates memory for a matrix of size @var{n1} rows by
@var{n2} columns and initializes all the elements of the matrix to zero.
@end deftypefun

@deftypefun void gsl_matrix_free (gsl_matrix * @var{m})
This function frees a previously allocated matrix @var{m}.  If the
matrix was created using @code{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.
@end deftypefun

@node Accessing matrix elements
@subsection Accessing matrix elements
@cindex matrices, range-checking
@cindex range-checking for matrices

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
@code{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 @code{gsl_matrix_get(m,i,j)} and
@code{gsl_matrix_set(m,i,j,x)} is 

@example
m->data[i * m->tda + j]
@end example
@comment 
@noindent
where @var{tda} is the physical row-length of the matrix.

@deftypefun double gsl_matrix_get (const gsl_matrix * @var{m}, size_t @var{i}, size_t @var{j})
This function returns the (@var{i},@var{j})th element of a matrix
@var{m}.  If @var{i} or @var{j} lie outside the allowed range of 0 to
@var{n1-1} and 0 to @var{n2-1} then the error handler is invoked and 0
is returned.
@end deftypefun

@deftypefun void gsl_matrix_set (gsl_matrix * @var{m}, size_t @var{i}, size_t @var{j}, double @var{x})
This function sets the value of the (@var{i},@var{j})th element of a
matrix @var{m} to @var{x}.  If @var{i} or @var{j} lies outside the
allowed range of 0 to @var{n1-1} and 0 to @var{n2-1} then the error
handler is invoked.
@end deftypefun

@deftypefun {double *} gsl_matrix_ptr (gsl_matrix * @var{m}, size_t @var{i}, size_t @var{j})
@deftypefunx {const double *} gsl_matrix_ptr (const gsl_matrix * @var{m}, size_t @var{i}, size_t @var{j})
These functions return a pointer to the (@var{i},@var{j})th element of a
matrix @var{m}.  If @var{i} or @var{j} lie outside the allowed range of
0 to @var{n1-1} and 0 to @var{n2-1} then the error handler is invoked
and a null pointer is returned.
@end deftypefun

@node Initializing matrix elements
@subsection Initializing matrix elements
@cindex matrices, initializing
@cindex initializing matrices

@deftypefun void gsl_matrix_set_all (gsl_matrix * @var{m}, double @var{x})
This function sets all the elements of the matrix @var{m} to the value
@var{x}.
@end deftypefun

@deftypefun void gsl_matrix_set_zero (gsl_matrix * @var{m})
This function sets all the elements of the matrix @var{m} to zero.
@end deftypefun

@deftypefun void gsl_matrix_set_identity (gsl_matrix * @var{m})
This function sets the elements of the matrix @var{m} to the
corresponding elements of the identity matrix, @math{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.
@end deftypefun

@node Reading and writing matrices
@subsection Reading and writing matrices

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

@deftypefun int gsl_matrix_fwrite (FILE * @var{stream}, const gsl_matrix * @var{m})
This function writes the elements of the matrix @var{m} to the stream
@var{stream} in binary format.  The return value is 0 for success and
@code{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.
@end deftypefun

@deftypefun int gsl_matrix_fread (FILE * @var{stream}, gsl_matrix * @var{m})
This function reads into the matrix @var{m} from the open stream
@var{stream} in binary format.  The matrix @var{m} must be preallocated
with the correct dimensions since the function uses the size of @var{m} to
determine how many bytes to read.  The return value is 0 for success and
@code{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.
@end deftypefun

@deftypefun int gsl_matrix_fprintf (FILE * @var{stream}, const gsl_matrix * @var{m}, const char * @var{format})
This function writes the elements of the matrix @var{m} line-by-line to
the stream @var{stream} using the format specifier @var{format}, which
should be one of the @code{%g}, @code{%e} or @code{%f} formats for
floating point numbers and @code{%d} for integers.  The function returns
0 for success and @code{GSL_EFAILED} if there was a problem writing to
the file.
@end deftypefun

@deftypefun int gsl_matrix_fscanf (FILE * @var{stream}, gsl_matrix * @var{m})
This function reads formatted data from the stream @var{stream} into the
matrix @var{m}.  The matrix @var{m} must be preallocated with the correct
dimensions since the function uses the size of @var{m} to determine how many
numbers to read.  The function returns 0 for success and
@code{GSL_EFAILED} if there was a problem reading from the file.
@end deftypefun

@node Matrix views
@subsection 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
@code{gsl_matrix_view} and a constant matrix view has the type
@code{gsl_matrix_const_view}.  In both cases the elements of the view
can by accessed using the @code{matrix} component of the view object.  A
pointer @code{gsl_matrix *} or @code{const gsl_matrix *} can be obtained
by taking the address of the @code{matrix} component with the @code{&}
operator.  In addition to matrix views it is also possible to create
vector views of a matrix, such as row or column views.

@deftypefun gsl_matrix_view gsl_matrix_submatrix (gsl_matrix * @var{m}, size_t @var{i}, size_t @var{j}, size_t @var{n1}, size_t @var{n2})
@deftypefunx gsl_matrix_const_view gsl_matrix_const_submatrix (const gsl_matrix * @var{m}, size_t @var{i}, size_t @var{j}, size_t @var{n1}, size_t @var{n2})
These functions return a matrix view of a submatrix of the matrix
@var{m}.  The upper-left element of the submatrix is the element
(@var{k1},@var{k2}) of the original matrix.  The submatrix has @var{n1}
rows and @var{n2} columns.  The physical number of columns in memory
given by @var{tda} is unchanged.  Mathematically, the
(@var{i},@var{j})-th element of the new matrix is given by,

@example
m'(i,j) = m->data[(k1*m->tda + k2) + i*m->tda + j]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n1-1} and the index @var{j}
runs from 0 to @code{n2-1}.

The @code{data} pointer of the returned matrix struct is set to null if
the combined parameters (@var{k1},@var{k2},@var{n1},@var{n2},@var{tda})
overrun the ends of the original matrix.

The new matrix view is only a view of the block underlying the existing
matrix, @var{m}.  The block containing the elements of @var{m} is not
owned by the new matrix view.  When the view goes out of scope the
original matrix @var{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 @code{gsl_matrix_const_submatrix} is equivalent to
@code{gsl_matrix_submatrix} but can be used for matrices which are
declared @code{const}.
@end deftypefun


@deftypefun gsl_matrix_view gsl_matrix_view_array (double * @var{base}, size_t @var{n1}, size_t @var{n2})
@deftypefunx gsl_matrix_const_view gsl_matrix_const_view_array (const double * @var{base}, size_t @var{n1}, size_t @var{n2})
These functions return a matrix view of the array @var{base}.  The
matrix has @var{n1} rows and @var{n2} columns.  The physical number of
columns in memory is also given by @var{n2}.  Mathematically, the
(@var{i},@var{j})-th element of the new matrix is given by,

@example
m'(i,j) = base[i*n2 + j]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n1-1} and the index @var{j}
runs from 0 to @code{n2-1}.

The new matrix is only a view of the array @var{base}.  When the view
goes out of scope the original array @var{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.

The function @code{gsl_matrix_const_view_array} is equivalent to
@code{gsl_matrix_view_array} but can be used for matrices which are
declared @code{const}.
@end deftypefun


@deftypefun gsl_matrix_view gsl_matrix_view_array_with_tda (double * @var{base}, size_t @var{n1}, size_t @var{n2}, size_t @var{tda})
@deftypefunx gsl_matrix_const_view gsl_matrix_const_view_array_with_tda (const double * @var{base}, size_t @var{n1}, size_t @var{n2}, size_t @var{tda})
These functions return a matrix view of the array @var{base} with a
physical number of columns @var{tda} which may differ from corresponding
the dimension of the matrix.  The matrix has @var{n1} rows and @var{n2}
columns, and the physical number of columns in memory is given by
@var{tda}.  Mathematically, the (@var{i},@var{j})-th element of the new
matrix is given by,

@example
m'(i,j) = base[i*tda + j]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n1-1} and the index @var{j}
runs from 0 to @code{n2-1}.

The new matrix is only a view of the array @var{base}.  When the view
goes out of scope the original array @var{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.

The function @code{gsl_matrix_const_view_array_with_tda} is equivalent
to @code{gsl_matrix_view_array_with_tda} but can be used for matrices
which are declared @code{const}.
@end deftypefun

@deftypefun gsl_matrix_view gsl_matrix_view_vector (gsl_vector * @var{v}, size_t @var{n1}, size_t @var{n2})
@deftypefunx gsl_matrix_const_view gsl_matrix_const_view_vector (const gsl_vector * @var{v}, size_t @var{n1}, size_t @var{n2})
These functions return a matrix view of the vector @var{v}.  The matrix
has @var{n1} rows and @var{n2} columns. The vector must have unit
stride. The physical number of columns in memory is also given by
@var{n2}.  Mathematically, the (@var{i},@var{j})-th element of the new
matrix is given by,

@example
m'(i,j) = v->data[i*n2 + j]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n1-1} and the index @var{j}
runs from 0 to @code{n2-1}.

The new matrix is only a view of the vector @var{v}.  When the view
goes out of scope the original vector @var{v} 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 view is still in use.

The function @code{gsl_matrix_const_view_vector} is equivalent to
@code{gsl_matrix_view_vector} but can be used for matrices which are
declared @code{const}.
@end deftypefun


@deftypefun gsl_matrix_view gsl_matrix_view_vector_with_tda (gsl_vector * @var{v}, size_t @var{n1}, size_t @var{n2}, size_t @var{tda})
@deftypefunx gsl_matrix_const_view gsl_matrix_const_view_vector_with_tda (const gsl_vector * @var{v}, size_t @var{n1}, size_t @var{n2}, size_t @var{tda})
These functions return a matrix view of the vector @var{v} with a
physical number of columns @var{tda} which may differ from the
corresponding matrix dimension.  The vector must have unit stride. The
matrix has @var{n1} rows and @var{n2} columns, and the physical number
of columns in memory is given by @var{tda}.  Mathematically, the
(@var{i},@var{j})-th element of the new matrix is given by,

@example
m'(i,j) = v->data[i*tda + j]
@end example
@noindent
where the index @var{i} runs from 0 to @code{n1-1} and the index @var{j}
runs from 0 to @code{n2-1}.

The new matrix is only a view of the vector @var{v}.  When the view
goes out of scope the original vector @var{v} 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 view is still in use.

The function @code{gsl_matrix_const_view_vector_with_tda} is equivalent
to @code{gsl_matrix_view_vector_with_tda} but can be used for matrices
which are declared @code{const}.
@end deftypefun


@comment @node Modifying matrix views
@comment @subsection Modifying matrix views
@comment 
@comment @deftypefun int gsl_matrix_view_from_matrix (gsl_matrix * @var{m}, gsl_matrix * @var{mm}, const size_t @var{k1}, const size_t @var{k2}, const size_t @var{n1}, const size_t @var{n2})
@comment This function modifies and existing matrix view @var{m} to form a new
@comment view of a matrix @var{mm}, starting from element (@var{k1},@var{k2}).
@comment The matrix view has @var{n1} rows and @var{n2} columns.  Any existing
@comment view in @var{m} will be lost as a result of this function.
@comment @end deftypefun
@comment 
@comment @deftypefun int gsl_matrix_view_from_vector (gsl_matrix * @var{m}, gsl_vector * @var{v}, const size_t @var{offset}, const size_t @var{n1}, const size_t @var{n2})
@comment This function modifies and existing matrix view @var{m} to form a new
@comment view of a vector @var{v}, starting from element @var{offset}.  The
@comment vector has @var{n1} rows and @var{n2} columns.  Any
@comment existing view in @var{m} will be lost as a result of this function.
@comment @end deftypefun
@comment 
@comment @deftypefun int gsl_matrix_view_from_array (gsl_matrix * @var{m}, double * @var{base}, const size_t @var{offset}, const size_t @var{n1}, const size_t @var{n2})
@comment This function modifies and existing matrix view @var{m} to form a new
@comment view of an array @var{base}, starting from element @var{offset}.  The
@comment matrix has @var{n1} rows and @var{n2} columns.  Any