vectors.texi

用于VC.net的gsl的lib库文件包

@comment @deftypefun {gsl_vector *} gsl_vector_alloc_from_vector (gsl_vector * @var{v}, size_t @var{offset}, size_t @var{n}, size_t @var{stride})
@comment This function creates a vector as a slice of another vector @var{v},
@comment returning a pointer to a newly initialized vector struct.  The start of
@comment the new vector is offset by @var{offset} elements from the start of the
@comment original vector.  The new vector has @var{n} elements, with a step-size
@comment of @var{stride} from one element to the next in the original vector.
@comment Mathematically, the @var{i}-th element of the new vector @var{v'} is
@comment given by,
@comment 
@comment @example
@comment v'(i) = v->data[(offset + i*stride)*v->stride]
@comment @end example
@comment @noindent
@comment where the index @var{i} runs from 0 to @code{n-1}.
@comment 
@comment A null pointer is returned if the combined parameters
@comment (@var{offset},@var{n},@var{stride}) overrun the end of the original
@comment vector or if insufficient memory is available store the new vector.
@comment 
@comment The new vector is only a view of the block underlying the original
@comment vector, @var{v}.  The block is not owned by the new vector.  When the new
@comment vector is deallocated the original vector @var{v} and its block will
@comment continue to exist.  The original memory can only be deallocated by
@comment freeing the original vector.  Of course, the original vector should not
@comment be deallocated while the new vector is still in use.
@comment @end deftypefun

@node Copying vectors
@subsection Copying vectors

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

@deftypefun int gsl_vector_memcpy (gsl_vector * @var{dest}, const gsl_vector * @var{src})
This function copies the elements of the vector @var{src} into the
vector @var{dest}.  The two vectors must have the same length.
@end deftypefun

@deftypefun int gsl_vector_swap (gsl_vector * @var{v}, gsl_vector * @var{w})
This function exchanges the elements of the vectors @var{v} and @var{w}
by copying.  The two vectors must have the same length.
@end deftypefun


@node Exchanging elements
@subsection Exchanging elements

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

@deftypefun int gsl_vector_swap_elements (gsl_vector * @var{v}, size_t @var{i}, size_t @var{j})
This function exchanges the @var{i}-th and @var{j}-th elements of the
vector @var{v} in-place.
@end deftypefun

@deftypefun int gsl_vector_reverse (gsl_vector * @var{v})
This function reverses the order of the elements of the vector @var{v}.
@end deftypefun


@node Vector operations
@subsection Vector operations

The following operations are only defined for real vectors.

@deftypefun int gsl_vector_add (gsl_vector * @var{a}, const gsl_vector * @var{b})
This function adds the elements of vector @var{b} to the elements of
vector @var{a}, @math{a'_i = a_i + b_i}. The two vectors must have the
same length.
@end deftypefun

@deftypefun int gsl_vector_sub (gsl_vector * @var{a}, const gsl_vector * @var{b})
This function subtracts the elements of vector @var{b} from the elements of
vector @var{a}, @math{a'_i = a_i - b_i}. The two vectors must have the
same length.
@end deftypefun

@deftypefun int gsl_vector_mul (gsl_vector * @var{a}, const gsl_vector * @var{b})
This function multiplies the elements of vector @var{a} by the elements of
vector @var{b}, @math{a'_i = a_i * b_i}. The two vectors must have the
same length.
@end deftypefun

@deftypefun int gsl_vector_div (gsl_vector * @var{a}, const gsl_vector * @var{b})
This function divides the elements of vector @var{a} by the elements of
vector @var{b}, @math{a'_i = a_i / b_i}. The two vectors must have the
same length.
@end deftypefun

@deftypefun int gsl_vector_scale (gsl_vector * @var{a}, const double @var{x})
This function multiplies the elements of vector @var{a} by the constant
factor @var{x}, @math{a'_i = x a_i}.
@end deftypefun

@deftypefun int gsl_vector_add_constant (gsl_vector * @var{a}, const double @var{x})
This function adds the constant value @var{x} to the elements of the
vector @var{a}, @math{a'_i = a_i + x}.
@end deftypefun

@node Finding maximum and minimum elements of vectors
@subsection Finding maximum and minimum elements of vectors

@deftypefun double gsl_vector_max (const gsl_vector * @var{v})
This function returns the maximum value in the vector @var{v}.
@end deftypefun

@deftypefun double gsl_vector_min (const gsl_vector * @var{v})
This function returns the minimum value in the vector @var{v}.
@end deftypefun

@deftypefun void gsl_vector_minmax (const gsl_vector * @var{v}, double * @var{min_out}, double * @var{max_out})
This function returns the minimum and maximum values in the vector
@var{v}, storing them in @var{min_out} and @var{max_out}.
@end deftypefun

@deftypefun size_t gsl_vector_max_index (const gsl_vector * @var{v})
This function returns the index of the maximum value in the vector @var{v}.
When there are several equal maximum elements then the lowest index is
returned.
@end deftypefun

@deftypefun size_t gsl_vector_min_index (const gsl_vector * @var{v})
This function returns the index of the minimum value in the vector @var{v}.
When there are several equal minimum elements then the lowest index is
returned.
@end deftypefun

@deftypefun void gsl_vector_minmax_index (const gsl_vector * @var{v}, size_t * @var{imin}, size_t * @var{imax})
This function returns the indices of the minimum and maximum values in
the vector @var{v}, storing them in @var{imin} and @var{imax}. When
there are several equal minimum or maximum elements then the lowest
indices are returned.
@end deftypefun

@node Vector properties
@subsection Vector properties

@deftypefun int gsl_vector_isnull (const gsl_vector * @var{v})
This function returns 1 if all the elements of the vector @var{v} are
zero, and 0 otherwise.
@end deftypefun

@node Example programs for vectors
@subsection Example programs for vectors

This program shows how to allocate, initialize and read from a vector
using the functions @code{gsl_vector_alloc}, @code{gsl_vector_set} and
@code{gsl_vector_get}.

@example
@verbatiminclude examples/vector.c
@end example
@comment
@noindent
Here is the output from the program.  The final loop attempts to read
outside the range of the vector @code{v}, and the error is trapped by
the range-checking code in @code{gsl_vector_get}.

@example
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)
@end example
@comment
@noindent
The next program shows how to write a vector to a file.

@example
@verbatiminclude examples/vectorw.c
@end example
@comment
@noindent
After running this program the file @file{test.dat} should contain the
elements of @code{v}, written using the format specifier
@code{%.5g}.  The vector could then be read back in using the function
@code{gsl_vector_fscanf (f, v)} as follows:

@example
@verbatiminclude examples/vectorr.c
@end example


@node Matrices
@section Matrices
@cindex matrices
@cindex physical dimension, matrices
@cindex trailing dimension, matrices
@cindex leading dimension, matrices

Matrices are defined by a @code{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 @code{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, @var{data}, a pointer to
the block owned by the matrix @var{block}, if any, and an ownership
flag, @var{owner}.  The physical dimension determines the memory layout
and can differ from the matrix dimension to allow the use of
submatrices.  The @code{gsl_matrix} structure is very simple and looks
like this,

@example
typedef struct
@{
  size_t size1;
  size_t size2;
  size_t tda;
  double * data;
  gsl_block * block;
  int owner;
@} gsl_matrix;
@end example
@comment
@noindent
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 @sc{fortran}
stores arrays in column-major order. The number of rows is @var{size1}.
The range of valid row indices runs from 0 to @code{size1-1}.  Similarly
@var{size2} is the number of columns.  The range of valid column indices
runs from 0 to @code{size2-1}.  The physical row dimension @var{tda}, or
@dfn{trailing dimension}, specifies the size of a row of the matrix as
laid out in memory.

For example, in the following matrix @var{size1} is 3, @var{size2} is 4,
and @var{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.

@example
@group
00 01 02 03 XX XX XX XX
10 11 12 13 XX XX XX XX
20 21 22 23 XX XX XX XX
@end group
@end example
@noindent
Each unused memory location is represented by ``@code{XX}''.  The
pointer @var{data} gives the location of the first element of the matrix
in memory.  The pointer @var{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 @var{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 @var{owner} field is
zero and any underlying block will not be freed.

The functions for allocating and accessing matrices are defined in
@file{gsl_matrix.h}

@menu
* Matrix allocation::           
* Accessing matrix elements::   
* Initializing matrix elements::  
* Reading and writing matrices::  
* Matrix views::                
* Creating row and column views::  
* Copying matrices::            
* Copying rows and columns::    
* Exchanging rows and columns::  
* Matrix operations::           
* Finding maximum and minimum elements of matrices::  
* Matrix properties::           
* Example programs for matrices::  
@end menu

@node Matrix allocation
@subsection Matrix allocation

The functions for allocating memory to a matrix follow the style of
@code{malloc} and @code{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
@code{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 @code{alloc}.

@deftypefun {gsl_matrix *} gsl_matrix_alloc (size_t @var{n1}, size_t @var{n2})
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