This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.

START-INFO-DIR-ENTRY
* Octave: (octave).	Interactive language for numerical computations.
END-INFO-DIR-ENTRY

   Copyright (C) 1996, 1997 John W. Eaton.

   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.


File: octave,  Node: Rearranging Matrices,  Next: Special Utility Matrices,  Prev: Finding Elements and Checking Conditions,  Up: Matrix Manipulation

Rearranging Matrices
====================

 - Function File:  fliplr (X)
     Return a copy of X with the order of the columns reversed.  For
     example,

          fliplr ([1, 2; 3, 4])
               =>  2  1
                   4  3

 - Function File:  flipud (X)
     Return a copy of X with the order of the rows reversed.  For
     example,

          flipud ([1, 2; 3, 4])
               =>  3  4
                   1  2

 - Function File:  rot90 (X, N)
     Return a copy of X with the elements rotated counterclockwise in
     90-degree increments.  The second argument is optional, and
     specifies how many 90-degree rotations are to be applied (the
     default value is 1).  Negative values of N rotate the matrix in a
     clockwise direction.  For example,

          rot90 ([1, 2; 3, 4], -1)
               =>  3  1
                   4  2

     rotates the given matrix clockwise by 90 degrees.  The following
     are all equivalent statements:

          rot90 ([1, 2; 3, 4], -1)
          ==
          rot90 ([1, 2; 3, 4], 3)
          ==
          rot90 ([1, 2; 3, 4], 7)

 - Function File:  reshape (A, M, N)
     Return a matrix with M rows and N columns whose elements are taken
     from the matrix A.  To decide how to order the elements, Octave
     pretends that the elements of a matrix are stored in column-major
     order (like Fortran arrays are stored).

     For example,

          reshape ([1, 2, 3, 4], 2, 2)
               =>  1  3
                   2  4

     If the variable `do_fortran_indexing' is nonzero, the `reshape'
     function is equivalent to

          retval = zeros (m, n);
          retval (:) = a;

     but it is somewhat less cryptic to use `reshape' instead of the
     colon operator.  Note that the total number of elements in the
     original matrix must match the total number of elements in the new
     matrix.

 - Function File:  shift (X, B)
     If X is a vector, perform a circular shift of length B of the
     elements of X.

     If X is a matrix, do the same for each column of X.

 - Loadable Function: [S, I] = sort (X)
     Return a copy of X with the elements elements arranged in
     increasing order.  For matrices, `sort' orders the elements in each
     column.

     For example,

          sort ([1, 2; 2, 3; 3, 1])
               =>  1  1
                   2  2
                   3  3

     The `sort' function may also be used to produce a matrix
     containing the original row indices of the elements in the sorted
     matrix.  For example,

          [s, i] = sort ([1, 2; 2, 3; 3, 1])
               => s = 1  1
                      2  2
                      3  3
               => i = 1  3
                      2  1
                      3  2

   Since the `sort' function does not allow sort keys to be specified,
it can't be used to order the rows of a matrix according to the values
of the elements in various columns(1) in a single call.  Using the
second output, however, it is possible to sort all rows based on the
values in a given column.  Here's an example that sorts the rows of a
matrix based on the values in the second column.

     a = [1, 2; 2, 3; 3, 1];
     [s, i] = sort (a (:, 2));
     a (i, :)
          =>  3  1
              1  2
              2  3

 - Function File:  tril (A, K)
 - Function File:  triu (A, K)
     Return a new matrix formed by extracting extract the lower (`tril')
     or upper (`triu') triangular part of the matrix A, and setting all
     other elements to zero.  The second argument is optional, and
     specifies how many diagonals above or below the main diagonal
     should also be set to zero.

     The default value of K is zero, so that `triu' and `tril' normally
     include the main diagonal as part of the result matrix.

     If the value of K is negative, additional elements above (for
     `tril') or below (for `triu') the main diagonal are also selected.

     The absolute value of K must not be greater than the number of
     sub- or super-diagonals.

     For example,

          tril (ones (3), -1)
               =>  0  0  0
                   1  0  0
                   1  1  0

     and

          tril (ones (3), 1)
               =>  1  1  0
                   1  1  1
                   1  1  1

 - Function File:  vec (X)
     Return the vector obtained by stacking the columns of the matrix X
     one above the other.

 - Function File:  vech (X)
     Return the vector obtained by eliminating all supradiagonal
     elements of the square matrix X and stacking the result one column
     above the other.

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

   (1)  For example, to first sort based on the values in column 1, and
then, for any values that are repeated in column 1, sort based on the
values found in column 2, etc.


File: octave,  Node: Special Utility Matrices,  Next: Famous Matrices,  Prev: Rearranging Matrices,  Up: Matrix Manipulation

Special Utility Matrices
========================

 - Built-in Function:  eye (X)
 - Built-in Function:  eye (N, M)
     Return an identity matrix.  If invoked with a single scalar
     argument, `eye' returns a square matrix with the dimension
     specified.  If you supply two scalar arguments, `eye' takes them
     to be the number of rows and columns.  If given a vector with two
     elements, `eye' uses the values of the elements as the number of
     rows and columns, respectively.  For example,

          eye (3)
               =>  1  0  0
                   0  1  0
                   0  0  1

     The following expressions all produce the same result:

          eye (2)
          ==
          eye (2, 2)
          ==
          eye (size ([1, 2; 3, 4])

     For compatibility with MATLAB, calling `eye' with no arguments is
     equivalent to calling it with an argument of 1.

 - Built-in Function:  ones (X)
 - Built-in Function:  ones (N, M)
     Return a matrix whose elements are all 1.  The arguments are
     handled the same as the arguments for `eye'.

     If you need to create a matrix whose values are all the same, you
     should use an expression like

          val_matrix = val * ones (n, m)

 - Built-in Function:  zeros (X)
 - Built-in Function:  zeros (N, M)
     Return a matrix whose elements are all 0.  The arguments are
     handled the same as the arguments for `eye'.

 - Loadable Function:  rand (X)
 - Loadable Function:  rand (N, M)
 - Loadable Function:  rand (`"seed"', X)
     Return a matrix with random elements uniformly distributed on the
     interval (0, 1).  The arguments are handled the same as the
     arguments for `eye'.  In addition, you can set the seed for the
     random number generator using the form

          rand ("seed", X)

     where X is a scalar value.  If called as

          rand ("seed")

     `rand' returns the current value of the seed.

 - Loadable Function:  randn (X)
 - Loadable Function:  randn (N, M)
 - Loadable Function:  randn (`"seed"', X)
     Return a matrix with normally distributed random elements.  The
     arguments are handled the same as the arguments for `eye'.  In
     addition, you can set the seed for the random number generator
     using the form

          randn ("seed", X)

     where X is a scalar value.  If called as

          randn ("seed")

     `randn' returns the current value of the seed.

   The `rand' and `randn' functions use separate generators.  This
ensures that

     rand ("seed", 13);
     randn ("seed", 13);
     u = rand (100, 1);
     n = randn (100, 1);

and

     rand ("seed", 13);
     randn ("seed", 13);
     u = zeros (100, 1);
     n = zeros (100, 1);
     for i = 1:100
       u(i) = rand ();
       n(i) = randn ();
     end

produce equivalent results.

   Normally, `rand' and `randn' obtain their initial seeds from the
system clock, so that the sequence of random numbers is not the same
each time you run Octave.  If you really do need for to reproduce a
sequence of numbers exactly, you can set the seed to a specific value.

   If it is invoked without arguments, `rand' and `randn' return a
single element of a random sequence.

   The `rand' and `randn' functions use Fortran code from RANLIB, a
library of fortran routines for random number generation, compiled by
Barry W. Brown and James Lovato of the Department of Biomathematics at
The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030.

 - Built-in Function:  diag (V, K)
     Return a diagonal matrix with vector V on diagonal K.  The second
     argument is optional.  If it is positive, the vector is placed on
     the K-th super-diagonal.  If it is negative, it is placed on the
     -K-th sub-diagonal.  The default value of K is 0, and the vector
     is placed on the main diagonal.  For example,

          diag ([1, 2, 3], 1)
               =>  0  1  0  0
                   0  0  2  0
                   0  0  0  3
                   0  0  0  0

   The functions `linspace' and `logspace' make it very easy to create
vectors with evenly or logarithmically spaced elements.  *Note Ranges::.

 - Function File:  linspace (BASE, LIMIT, N)
     Return a row vector with N linearly spaced elements between BASE
     and LIMIT.  The number of elements, N, must be greater than 1.
     The BASE and LIMIT are always included in the range.  If BASE is
     greater than LIMIT, the elements are stored in decreasing order.
     If the number of points is not specified, a value of 100 is used.

     The `linspace' function always returns a row vector, regardless of
     the value of `prefer_column_vectors'.

 - Function File:  logspace (BASE, LIMIT, N)
     Similar to `linspace' except that the values are logarithmically
     spaced from 10^base to 10^limit.

     If LIMIT is equal to pi, the points are between 10^base and pi,
     *not* 10^base and 10^pi, in order to  be compatible with the
     corresponding MATLAB function.

 - Built-in Variable: treat_neg_dim_as_zero
     If the value of `treat_neg_dim_as_zero' is nonzero, expressions
     like

          eye (-1)

     produce an empty matrix (i.e., row and column dimensions are zero).
     Otherwise, an error message is printed and control is returned to
     the top level.  The default value is 0.


File: octave,  Node: Famous Matrices,  Prev: Special Utility Matrices,  Up: Matrix Manipulation

Famous Matrices
===============

   The following functions return famous matrix forms.

 - Function File:  hankel (C, R)
     Return the Hankel matrix constructed given the first column C, and
     (optionally) the last row R.  If the last element of C is not the
     same as the first element of R, the last element of C is used.  If
     the second argument is omitted, the last row is taken to be the
     same as the first column.

     A Hankel matrix formed from an m-vector C, and an n-vector R, has
     the elements

          H (i, j) = c (i+j-1),  i+j-1 <= m;
          H (i, j) = r (i+j-m),  otherwise

 - Function File:  hilb (N)
     Return the Hilbert matrix of order N.  The i, j element of a
     Hilbert matrix is defined as

          H (i, j) = 1 / (i + j - 1)

 - Function File:  invhilb (N)
     Return the inverse of a Hilbert matrix of order N.  This is exact.
     Compare with the numerical calculation of `inverse (hilb (n))',
     which suffers from the ill-conditioning of the Hilbert matrix, and
     the finite precision of your computer's floating point arithmetic.

 - Function File:  sylvester_matrix (K)
     Return the Sylvester matrix of order n = 2^k.

 - Function File:  toeplitz (C, R)
     Return the Toeplitz matrix constructed given the first column C,
     and (optionally) the first row R.  If the first element of C is
     not the same as the first element of R, the first element of C is
     used.  If the second argument is omitted, the first row is taken
     to be the same as the first column.

     A square Toeplitz matrix has the form

          c(0)  r(1)   r(2)  ...  r(n)
          c(1)  c(0)   r(1)      r(n-1)
          c(2)  c(1)   c(0)      r(n-2)
           .                       .
           .                       .
           .                       .
          
          c(n) c(n-1) c(n-2) ...  c(0)

 - Function File:  vander (C)
     Return the Vandermonde matrix whose next to last column is C.

     A Vandermonde matrix has the form

          c(0)^n ... c(0)^2  c(0)  1
          c(1)^n ... c(1)^2  c(1)  1
           .           .      .    .
           .           .      .    .
           .           .      .    .
          
          c(n)^n ... c(n)^2  c(n)  1


File: octave,  Node: Arithmetic,  Next: Linear Algebra,  Prev: Matrix Manipulation,  Up: Top

Arithmetic
**********

   Unless otherwise noted, all of the functions described in this
chapter will work for real and complex scalar or matrix arguments.

* Menu:

* Utility Functions::
* Complex Arithmetic::
* Trigonometry::
* Sums and Products::
* Special Functions::
* Mathematical Constants::


File: octave,  Node: Utility Functions,  Next: Complex Arithmetic,  Prev: Arithmetic,  Up: Arithmetic

Utility Functions
=================

   The following functions are available for working with complex
numbers.  Each expects a single argument.  They are called "mapping
functions" because when given a matrix argument, they apply the given
function to each element of the matrix.

 - Mapping Function:  ceil (X)
     Return the smallest integer not less than X.  If X is complex,
     return `ceil (real (X)) + ceil (imag (X)) * I'.

 - Mapping Function:  exp (X)
     Compute the exponential of X.  To compute the matrix exponential,
     see *Note Linear Algebra::.

 - Mapping Function:  fix (X)
     Truncate X toward zero.  If X is complex, return `fix (real (X)) +
     fix (imag (X)) * I'.

 - Mapping Function:  floor (X)
     Return the largest integer not greater than X.  If X is complex,
     return `floor (real (X)) + floor (imag (X)) * I'.

 - Mapping Function:  gcd (X, `...')
     Compute the greatest common divisor of the elements of X, or the
     list of all the arguments.  For example,

          gcd (a1, ..., ak)

     is the same as

          gcd ([a1, ..., ak])

     An optional second return value, V contains an integer vector such
     that

          g = v(1) * a(k) + ... + v(k) * a(k)

 - Mapping Function:  lcm (X, `...')
     Compute the least common multiple of the elements elements of X, or
     the list of all the arguments.  For example,

          lcm (a1, ..., ak)

     is the same as

          lcm ([a1, ..., ak]).

 - Mapping Function:  log (X)
     Compute the natural logarithm of X.  To compute the matrix
     logarithm, see *Note Linear Algebra::.

 - Mapping Function:  log10 (X)
     Compute the base-10 logarithm of X.

 - Mapping Function: Y = log2 (X)
 - Mapping Function: [F, E] log2 (X)
     Compute the base-2 logarithm of X.  With two outputs, returns F
     and E such that  1/2 <= abs(f) < 1 and x = f * 2^e.

 - Loadable Function:  max (X)
     For a vector argument, return the maximum value.  For a matrix
     argument, return the maximum value from each column, as a row
     vector.  Thus,

          max (max (X))

     returns the largest element of X.

     For complex arguments, the magnitude of the elements are used for
     comparison.

 - Loadable Function:  min (X)
     Like `max', but return the minimum value.

 - Function File:  nextpow2 (X)
     If X is a scalar, returns the first integer N such that  2^n >=
     abs (x).

     If X is a vector, return `nextpow2 (length (X))'.

 - Mapping Function:  pow2 (X)
 - Mapping Function:  pow2 (F, E)
     With one argument, computes  2 .^ x for each element of X.  With
     two arguments, returns  f .* (2 .^ e).

 - Mapping Function:  rem (X, Y)
     Return the remainder of `X / Y', computed using the expression

          x - y .* fix (x ./ y)

     An error message is printed if the dimensions of the arguments do
     not agree, or if either of the arguments is complex.

 - Mapping Function:  round (X)
     Return the integer nearest to X.  If X is complex, return `round
     (real (X)) + round (imag (X)) * I'.

 - Mapping Function:  sign (X)
     Compute the "signum" function, which is defined as

                     -1, x < 0;
          sign (x) =  0, x = 0;
                      1, x > 0.

     For complex arguments, `sign' returns `x ./ abs (X)'.

 - Mapping Function:  sqrt (X)
     Compute the square root of X.  If X is negative, a complex result
     is returned.  To compute the matrix square root, see *Note Linear
     Algebra::.

 - Mapping Function:  xor (X, Y)
     Return the `exclusive or' of the entries of X and Y.  For boolean
     expressions X and Y, `xor (X, Y)' is true if and only if X or Y is
     true, but not if both X and Y are true.


File: octave,  Node: Complex Arithmetic,  Next: Trigonometry,  Prev: Utility Functions,  Up: Arithmetic

Complex Arithmetic
==================

   The following functions are available for working with complex
numbers.  Each expects a single argument.  Given a matrix they work on
an element by element basis.  In the descriptions of the following
functions, Z is the complex number X + IY, where I is defined as `sqrt
(-1)'.

 - Mapping Function:  abs (Z)
     Compute the magnitude of Z, defined as |Z| = `sqrt (x^2 + y^2)'.

     For example,

          abs (3 + 4i)
               => 5

 - Mapping Function:  arg (Z)
 - Mapping Function:  angle (Z)
     Compute the argument of Z, defined as THETA = `atan (Y/X)'.

     in radians.

     For example,

          arg (3 + 4i)
               => 0.92730

 - Mapping Function:  conj (Z)
     Return the complex conjugate of Z, defined as `conj (Z)' = X - IY.

 - Mapping Function:  imag (Z)
     Return the imaginary part of Z as a real number.

 - Mapping Function:  real (Z)
     Return the real part of Z.


File: octave,  Node: Trigonometry,  Next: Sums and Products,  Prev: Complex Arithmetic,  Up: Arithmetic

Trigonometry
============

   Octave provides the following trigonometric functions:

 - Mapping Function:  sin (Z)
 - Mapping Function:  cos (Z)
 - Mapping Function:  tan (Z)
 - Mapping Function:  sec (Z)
 - Mapping Function:  csc (Z)
 - Mapping Function:  cot (Z)
     The ordinary trigonometric functions.

 - Mapping Function:  asin (Z)
 - Mapping Function:  acos (Z)
 - Mapping Function:  atan (Z)
 - Mapping Function:  asec (Z)
 - Mapping Function:  acsc (Z)
 - Mapping Function:  acot (Z)
     The ordinary inverse trigonometric functions.

 - Mapping Function:  sinh (Z)
 - Mapping Function:  cosh (Z)
 - Mapping Function:  tanh (Z)
 - Mapping Function:  sech (Z)
 - Mapping Function:  csch (Z)
 - Mapping Function:  coth (Z)
     Hyperbolic trigonometric functions.

 - Mapping Function:  asinh (Z)
 - Mapping Function:  acosh (Z)
 - Mapping Function:  atanh (Z)
 - Mapping Function:  asech (Z)
 - Mapping Function:  acsch (Z)
 - Mapping Function:  acoth (Z)
     Inverse hyperbolic trigonometric functions.

   Each of these functions expect a single argument.  For matrix
arguments, they work on an element by element basis.  For example,

     sin ([1, 2; 3, 4])
          =>  0.84147   0.90930
              0.14112  -0.75680

 - Mapping Function:  atan2 (Y, X)
     Return the arctangent of Y/X.  The signs of the arguments are used
     to determine the quadrant of the result, which is in the range
     `pi' to -`pi'.


File: octave,  Node: Sums and Products,  Next: Special Functions,  Prev: Trigonometry,  Up: Arithmetic

Sums and Products
=================

 - Built-in Function:  sum (X)
     For a vector argument, return the sum of all the elements.  For a
     matrix argument, return the sum of the elements in each column, as
     a row vector.  The sum of an empty matrix is 0 if it has no
     columns, or a vector of zeros if it has no rows (*note Empty
     Matrices::.).

 - Built-in Function:  prod (X)
     For a vector argument, return the product of all the elements.
     For a matrix argument, return the product of the elements in each
     column, as a row vector.  The product of an empty matrix is 1 if
     it has no columns, or a vector of ones if it has no rows (*note
     Empty Matrices::.).

 - Built-in Function:  cumsum (X)
     Return the cumulative sum of each column of X.  For example,

          cumsum ([1, 2; 3, 4])
               =>  1  2
                   4  6

 - Built-in Function:  cumprod (X)
     Return the cumulative product of each column of X.  For example,

          cumprod ([1, 2; 3, 4])
               =>  1  2
                   3  8

 - Built-in Function:  sumsq (X)
     For a vector argument, return the sum of the squares of all the
     elements.  For a matrix argument, return the sum of the squares of
     the elements in each column, as a row vector.


File: octave,  Node: Special Functions,  Next: Mathematical Constants,  Prev: Sums and Products,  Up: Arithmetic

Special Functions
=================

 - Mapping Function:  besseli (ALPHA, X)
 - Mapping Function:  besselj (ALPHA, X)
 - Mapping Function:  besselk (ALPHA, X)
 - Mapping Function:  bessely (ALPHA, X)
     Compute Bessel functions of the following types:

    `besselj'
          Bessel functions of the first kind.

    `bessely'
          Bessel functions of the second kind.

    `besseli'
          Modified Bessel functions of the first kind.

    `besselk'
          Modified Bessel functions of the second kind.

     The second argument, X, must be a real matrix, vector, or scalar.

     The first argument, ALPHA, must be greater than or equal to zero.
     If ALPHA is a range, it must have an increment equal to one.

     If ALPHA is a scalar, the result is the same size as X.

     If ALPHA is a range, X must be a vector or scalar, and the result
     is a matrix with `length(X)' rows and `length(ALPHA)' columns.

 - Mapping Function:  beta (A, B)
     Return the Beta function,

          beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).

 - Mapping Function:  betai (A, B, X)
     Return the incomplete Beta function,

                                              x
                                             /
          betai (a, b, x) = beta (a, b)^(-1) | t^(a-1) (1-t)^(b-1) dt.
                                             /
                                          t=0

     If x has more than one component, both A and B must be scalars.
     If X is a scalar, A and B must be of compatible dimensions.

 - Mapping Function:  bincoeff (N, K)
     Return the binomial coefficient of N and K, defined as

           /   \
           | n |    n (n-1) (n-2) ... (n-k+1)
           |   |  = -------------------------
           | k |               k!
           \   /

     For example,

          bincoeff (5, 2)
               => 10

 - Mapping Function:  erf (Z)
     Computes the error function,

                                   z
                                  /
          erf (z) = (2/sqrt (pi)) | e^(-t^2) dt
                                  /
                               t=0

 - Mapping Function:  erfc (Z)
     Computes the complementary error function, `1 - erf (Z)'.

 - Mapping Function:  erfinv (Z)
     Computes the inverse of the error function,

 - Mapping Function:  gamma (Z)
     Computes the Gamma function,

                      infinity
                      /
          gamma (z) = | t^(z-1) exp (-t) dt.
                      /
                   t=0

 - Mapping Function:  gammai (A, X)
     Computes the incomplete gamma function,

                                        x
                              1        /
          gammai (a, x) = ---------    | exp (-t) t^(a-1) dt
                          gamma (a)    /
                                    t=0

     If A is scalar, then `gammai (A, X)' is returned for each element
     of X and vice versa.

     If neither A nor X is scalar, the sizes of A and X must agree, and
     GAMMAI is applied element-by-element.

 - Mapping Function:  lgamma (A, X)
 - Mapping Function:  gammaln (A, X)
     Return the natural logarithm of the gamma function.

 - Function File:  cross (X, Y)
     Computes the vector cross product of the two 3-dimensional vectors
     X and Y.  For example,

          cross ([1,1,0], [0,1,1])
               => [ 1; -1; 1 ]

 - Function File:  commutation_matrix (M, N)
     Return the commutation matrix  K(m,n)  which is the unique  M*N by
     M*N  matrix such that  K(M,N) * vec (A) = vec (A')  for all  M by N
     matrices  A.

     If only one argument M is given,  K(m,m)  is returned.

     See Magnus and Neudecker (1988), Matrix differential calculus with
     applications in statistics and econometrics.

 - Function File:  duplication_matrix (N)
     Return the duplication matrix  D_N  which is the unique  N^2 by
     N*(N+1)/2  matrix such that  D_N \cdot vech (A) = vec (A)  for all
     symmetric  N by N  matrices  A.

     See Magnus and Neudecker (1988), Matrix differential calculus with
     applications in statistics and econometrics.


File: octave,  Node: Mathematical Constants,  Prev: Special Functions,  Up: Arithmetic

Mathematical Constants
======================

 - Built-in Variable: I
 - Built-in Variable: J
 - Built-in Variable: i
 - Built-in Variable: j
     A pure imaginary number, defined as   `sqrt (-1)'.  The `I' and
     `J' forms are true constants, and cannot be modified.  The `i' and
     `j' forms are like ordinary variables, and may be used for other
     purposes.  However, unlike other variables, they once again assume
     their special predefined values if they are cleared *Note Status
     of Variables::.

 - Built-in Variable: Inf
 - Built-in Variable: inf
     Infinity.  This is the result of an operation like 1/0, or an
     operation that results in a floating point overflow.

 - Built-in Variable: NaN
 - Built-in Variable: nan
     Not a number.  This is the result of an operation like 0/0, or
     `Inf - Inf', or any operation with a NaN.

 - Built-in Variable: pi
     The ratio of the circumference of a circle to its diameter.
     Internally, `pi' is computed as `4.0 * atan (1.0)'.

 - Built-in Variable: e
     The base of natural logarithms.  The constant  E  satisfies the
     equation  `log' (E) = 1.

 - Built-in Variable: eps
     The machine precision.  More precisely, `eps' is the largest
     relative spacing between any two adjacent numbers in the machine's
     floating point system.  This number is obviously system-dependent.
     On machines that support 64 bit IEEE floating point arithmetic,
     `eps' is approximately  2.2204e-16.

 - Built-in Variable: realmax
     The largest floating point number that is representable.  The
     actual value is system-dependent.  On machines that support 64 bit
     IEEE floating point arithmetic, `realmax' is approximately
     1.7977e+308

 - Built-in Variable: realmin
     The smallest floating point number that is representable.  The
     actual value is system-dependent.  On machines that support 64 bit
     IEEE floating point arithmetic, `realmin' is approximately
     2.2251e-308


File: octave,  Node: Linear Algebra,  Next: Nonlinear Equations,  Prev: Arithmetic,  Up: Top

Linear Algebra
**************

   This chapter documents the linear algebra functions of Octave.
Reference material for many of these functions may be found in Golub
and Van Loan, `Matrix Computations, 2nd Ed.', Johns Hopkins, 1989, and
in `LAPACK Users' Guide', SIAM, 1992.

* Menu:

* Basic Matrix Functions::
* Matrix Factorizations::
* Functions of a Matrix::


File: octave,  Node: Basic Matrix Functions,  Next: Matrix Factorizations,  Prev: Linear Algebra,  Up: Linear Algebra

Basic Matrix Functions
======================

 - Loadable Function: AA = balance (A, OPT)
 - Loadable Function: [DD, AA] = balance (A, OPT)
 - Loadable Function: [CC, DD, AA, BB] = balance (A, B, OPT)
     `[dd, aa] = balance (a)' returns `aa = dd \ a * dd'.  `aa' is a
     matrix whose row and column norms are roughly equal in magnitude,
     and `dd' = `p * d', where `p' is a permutation matrix and `d' is a
     diagonal matrix of powers of two.  This allows the equilibration
     to be computed without roundoff.  Results of eigenvalue
     calculation are typically improved by balancing first.

     `[cc, dd, aa, bb] = balance (a, b)' returns `aa = cc*a*dd' and `bb
     = cc*b*dd)', where `aa' and `bb' have non-zero elements of
     approximately the same magnitude and `cc' and `dd' are permuted
     diagonal matrices as in `dd' for the algebraic eigenvalue problem.

     The eigenvalue balancing option `opt' is selected as follows:

    `"N"', `"n"'
          No balancing; arguments copied, transformation(s) set to
          identity.

    `"P"', `"p"'
          Permute argument(s) to isolate eigenvalues where possible.

    `"S"', `"s"'
          Scale to improve accuracy of computed eigenvalues.

    `"B"', `"b"'
          Permute and scale, in that order. Rows/columns of a (and b)
          that are isolated by permutation are not scaled.  This is the
          default behavior.

     Algebraic eigenvalue balancing uses standard LAPACK routines.

     Generalized eigenvalue problem balancing uses Ward's algorithm
     (SIAM Journal on Scientific and Statistical Computing, 1981).

 - :  cond (A)
     Compute the (two-norm) condition number of a matrix. `cond (a)' is
     defined as `norm (a) * norm (inv (a))', and is computed via a
     singular value decomposition.

 - Loadable Function:  det (A)
     Compute the determinant of A using LINPACK.

 - Loadable Function: LAMBDA = eig (A)
 - Loadable Function: [V, LAMBDA] = eig (A)
     The eigenvalues (and eigenvectors) of a matrix are computed in a
     several step process which begins with a Hessenberg decomposition,
     followed by a Schur decomposition, from which the eigenvalues are
     apparent.  The eigenvectors, when desired, are computed by further
     manipulations of the Schur decomposition.

 - Loadable Function: G = givens (X, Y)
 - Loadable Function: [C, S] = givens (X, Y)
     Return a 2 by 2 orthogonal matrix `G = [C S; -S' C]' such that `G
     [X; Y] = [*; 0]' with X and Y scalars.

     For example,

          givens (1, 1)
               =>   0.70711   0.70711
                   -0.70711   0.70711

 - Loadable Function:  inv (A)
 - Loadable Function:  inverse (A)
     Compute the inverse of the square matrix A.

 - Function File:  norm (A, P)
     Compute the p-norm of the matrix A.  If the second argument is
     missing, `p = 2' is assumed.

     If A is a matrix:

    P = `1'
          1-norm, the largest column sum of A.

    P = `2'
          Largest singular value of A.

    P = `Inf'
          Infinity norm, the largest row sum of A.

    P = `"fro"'
          Frobenius norm of A, `sqrt (sum (diag (A' * A)))'.

     If A is a vector or a scalar:

    P = `Inf'
          `max (abs (A))'.

    P = `-Inf'
          `min (abs (A))'.

    other
          p-norm of A, `(sum (abs (A) .^ P)) ^ (1/P)'.

 - Function File:  null (A, TOL)
     Return an orthonormal basis of the null space of A.

     The dimension of the null space is taken as the number of singular
     values of A not greater than TOL.  If the argument TOL is missing,
     it is computed as

          max (size (A)) * max (svd (A)) * eps

 - Function File:  orth (A, TOL)
     Return an orthonormal basis of the range space of A.

     The dimension of the range space is taken as the number of singular
     values of A greater than TOL.  If the argument TOL is missing, it
     is computed as

          max (size (A)) * max (svd (A)) * eps

 - Function File:  pinv (X, TOL)
     Return the pseudoinverse of X.  Singular values less than TOL are
     ignored.

     If the second argument is omitted, it is assumed that

          tol = max (size (X)) * sigma_max (X) * eps,

     where `sigma_max (X)' is the maximal singular value of X.

 - Function File:  rank (A, TOL)
     Compute the rank of A, using the singular value decomposition.
     The rank is taken to be the number  of singular values of A that
     are greater than the specified tolerance TOL.  If the second
     argument is omitted, it is taken to be

          tol = max (size (A)) * sigma (1) * eps;

     where `eps' is machine precision and `sigma' is the largest
     singular value of A.

 - Function File:  trace (A)
     Compute the trace of A, `sum (diag (A))'.


File: octave,  Node: Matrix Factorizations,  Next: Functions of a Matrix,  Prev: Basic Matrix Functions,  Up: Linear Algebra

Matrix Factorizations
=====================

 - Loadable Function:  chol (A)
     Compute the Cholesky factor, R, of the symmetric positive definite
     matrix A, where

          r' * r = a.

 - Loadable Function: H = hess (A)
 - Loadable Function: [P, H] = hess (A)
     Compute the Hessenberg decomposition of the matrix A.

     The Hessenberg decomposition is usually used as the first step in
     an eigenvalue computation, but has other applications as well (see
     Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control,
     1979.  The Hessenberg decomposition is `p * h * p' = a' where `p'
     is a square unitary matrix (`p' * p = I', using complex-conjugate
     transposition) and `h' is upper Hessenberg (`i >= j+1 => h (i, j)
     = 0').

 - Loadable Function: [L, U, P] = lu (A)
     Compute the LU decomposition of A, using subroutines from LAPACK.
     The result is returned in a permuted form, according to the
     optional return value P.  For example, given the matrix `a = [1,
     2; 3, 4]',

          [l, u, p] = lu (a)

     returns

          l =
          
            1.00000  0.00000
            0.33333  1.00000
          
          u =
          
            3.00000  4.00000
            0.00000  0.66667
          
          p =
          
            0  1
            1  0

 - Loadable Function: [Q, R, P] = qr (A)
     Compute the QR factorization of A, using standard LAPACK
     subroutines.  For example, given the matrix `a = [1, 2; 3, 4]',

          [q, r] = qr (a)

     returns

          q =
          
            -0.31623  -0.94868
            -0.94868   0.31623
          
          r =
          
            -3.16228  -4.42719
             0.00000  -0.63246

     The `qr' factorization has applications in the solution of least
     squares problems

          `min norm(A x - b)'

     for overdetermined systems of equations (i.e., `a'  is a tall,
     thin matrix).  The QR factorization is `q * r = a' where `q' is an
     orthogonal matrix and `r' is upper triangular.

     The permuted QR factorization `[Q, R, P] = qr (A)' forms the QR
     factorization such that the diagonal entries of `r' are decreasing
     in magnitude order.  For example, given the matrix `a = [1, 2; 3,
     4]',

          [q, r, pi] = qr(a)

     returns

          q =
          
            -0.44721  -0.89443
            -0.89443   0.44721
          
          r =
          
            -4.47214  -3.13050
             0.00000   0.44721
          
          p =
          
             0  1
             1  0

     The permuted `qr' factorization `[q, r, p] = qr (a)' factorization
     allows the construction of an orthogonal basis of `span (a)'.

 - Loadable Function: S = schur (A)
 - Loadable Function: [U, S] = schur (A, OPT)
     The Schur decomposition is used to compute eigenvalues of a square
     matrix, and has applications in the solution of algebraic Riccati
     equations in control (see `are' and `dare').  `schur' always
     returns `s = u' * a * u' where `u'  is a unitary matrix (`u'* u'
     is identity) and `s' is upper triangular.  The eigenvalues of `a'
     (and `s') are the diagonal elements of `s' If the matrix `a' is
     real, then the real Schur decomposition is computed, in which the
     matrix `u' is orthogonal and `s' is block upper triangular with
     blocks of size at most `2 x 2' blocks along the diagonal.  The
     diagonal elements of `s' (or the eigenvalues of the `2 x 2'
     blocks, when appropriate) are the eigenvalues of `a' and `s'.

     The eigenvalues are optionally ordered along the diagonal
     according to the value of `opt'.  `opt = "a"' indicates that all
     eigenvalues with negative real parts should be moved to the leading
     block of `s' (used in `are'), `opt = "d"' indicates that all
     eigenvalues with magnitude less than one should be moved to the
     leading block of `s' (used in `dare'), and `opt = "u"', the
     default, indicates that no ordering of eigenvalues should occur.
     The leading `k' columns of `u' always span the `a'-invariant
     subspace corresponding to the `k' leading eigenvalues of `s'.

 - Loadable Function: S = svd (A)
 - Loadable Function: [U, S, V] = svd (A)
     Compute the singular value decomposition of A

          a = u * sigma * v'

     The function `svd' normally returns the vector of singular values.
     If asked for three return values, it computes U, S, and V.  For
     example,

          svd (hilb (3))

     returns

          ans =
          
            1.4083189
            0.1223271
            0.0026873

     and

          [u, s, v] = svd (hilb (3))

     returns

          u =
          
            -0.82704   0.54745   0.12766
            -0.45986  -0.52829  -0.71375
            -0.32330  -0.64901   0.68867
          
          s =
          
            1.40832  0.00000  0.00000
            0.00000  0.12233  0.00000
            0.00000  0.00000  0.00269
          
          v =
          
            -0.82704   0.54745   0.12766
            -0.45986  -0.52829  -0.71375
            -0.32330  -0.64901   0.68867

     If given a second argument, `svd' returns an economy-sized
     decomposition, eliminating the unnecessary rows or columns of U or
     V.


File: octave,  Node: Functions of a Matrix,  Prev: Matrix Factorizations,  Up: Linear Algebra

Functions of a Matrix
=====================

 - Loadable Function:  expm (A)
     Return the exponential of a matrix, defined as the infinite Taylor
     series

          expm(a) = I + a + a^2/2! + a^3/3! + ...

     The Taylor series is *not* the way to compute the matrix
     exponential; see Moler and Van Loan, `Nineteen Dubious Ways to
     Compute the Exponential of a Matrix', SIAM Review, 1978.  This
     routine uses Ward's diagonal Pade' approximation method with three
     step preconditioning (SIAM Journal on Numerical Analysis, 1977).
     Diagonal Pade'  approximations are rational polynomials of matrices

               -1
          D (a)   N (a)

     whose Taylor series matches the first `2q+1' terms of the Taylor
     series above; direct evaluation of the Taylor series (with the
     same preconditioning steps) may be desirable in lieu of the Pade'
     approximation when `Dq(a)' is ill-conditioned.

 - Loadable Function:  logm (A)
     Compute the matrix logarithm of the square matrix A.  Note that
     this is currently implemented in terms of an eigenvalue expansion
     and needs to be improved to be more robust.

 - Loadable Function:  sqrtm (A)
     Compute the matrix square root of the square matrix A.  Note that
     this is currently implemented in terms of an eigenvalue expansion
     and needs to be improved to be more robust.

 - Function File:  kron (A, B)
     Form the kronecker product of two matrices, defined block by block
     as

          x = [a(i, j) b]

     For example,

          kron (1:4, ones (3, 1))
               =>  1  2  3  4
                   1  2  3  4
                   1  2  3  4

 - Function File: [AA, BB, Q, Z] = qzhess (A, B)
     Compute the Hessenberg-triangular decomposition of the matrix
     pencil `(A, B)', returning `AA = Q * A * Z', `BB = Q * B * Z',
     with Q and Z orthogonal.  For example,

          [aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8])
               => aa = [ -3.02244, -4.41741;  0.92998,  0.69749 ]
               => bb = [ -8.60233, -9.99730;  0.00000, -0.23250 ]
               =>  q = [ -0.58124, -0.81373; -0.81373,  0.58124 ]
               =>  z = [ 1, 0; 0, 1 ]

     The Hessenberg-triangular decomposition is the first step in Moler
     and Stewart's QZ decomposition algorithm.

     Algorithm taken from Golub and Van Loan, `Matrix Computations, 2nd
     edition'.

 - Loadable Function:  qzval (A, B)
     Compute generalized eigenvalues of the matrix pencil `A - lambda
     B'.

     The arguments A and B must be real matrices.

 - Loadable Function: X = syl (A, B, C)
     Solve the Sylvester equation

          A X + X B + C = 0
     using standard LAPACK subroutines.  For example,

          syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12])
               => [ -0.50000, -0.66667; -0.66667, -0.50000 ]


File: octave,  Node: Nonlinear Equations,  Next: Quadrature,  Prev: Linear Algebra,  Up: Top

Nonlinear Equations
*******************

   Octave can solve sets of nonlinear equations of the form

     F (x) = 0

using the function `fsolve', which is based on the MINPACK subroutine
`hybrd'.

 - Loadable Function: [X, INFO] = fsolve (FCN, X0)
     Given FCN, the name of a function of the form `f (X)' and an
     initial starting point X0, `fsolve' solves the set of equations
     such that `f(X) == 0'.

 - Loadable Function:  fsolve_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `fsolve'.  Given one argument,
     `fsolve_options' returns the value of the corresponding option.  If
     no arguments are supplied, the names of all the available options
     and their current values are displayed.

   Here is a complete example.  To solve the set of equations

     -2x^2 + 3xy   + 4 sin(y) = 6
      3x^2 - 2xy^2 + 3 cos(x) = -4

you first need to write a function to compute the value of the given
function.  For example:

     function y = f (x)
       y(1) = -2*x(1)^2 + 3*x(1)*x(2)   + 4*sin(x(2)) - 6;
       y(2) =  3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4;
     endfunction

   Then, call `fsolve' with a specified initial condition to find the
roots of the system of equations.  For example, given the function `f'
defined above,

     [x, info] = fsolve ("f", [1; 2])

results in the solution

     x =
     
       0.57983
       2.54621
     
     info = 1

   A value of `info = 1' indicates that the solution has converged.

   The function `perror' may be used to print English messages
corresponding to the numeric error codes.  For example,

     perror ("fsolve", 1)
          -| solution converged to requested tolerance


File: octave,  Node: Quadrature,  Next: Differential Equations,  Prev: Nonlinear Equations,  Up: Top

Quadrature
**********

* Menu:

* Functions of One Variable::
* Orthogonal Collocation::


File: octave,  Node: Functions of One Variable,  Next: Orthogonal Collocation,  Prev: Quadrature,  Up: Quadrature

Functions of One Variable
=========================

 - Loadable Function: [V, IER, NFUN, ERR] = quad (F, A, B, TOL, SING)
     Integrate a nonlinear function of one variable using Quadpack.
     The first argument is the name of the  function to call to compute
     the value of the integrand.  It must have the form

          y = f (x)

     where Y and X are scalars.

     The second and third arguments are limits of integration.  Either
     or both may be infinite.

     The optional argument TOL is a vector that specifies the desired
     accuracy of the result.  The first element of the vector is the
     desired absolute tolerance, and the second element is the desired
     relative tolerance.  To choose a relative test only, set the
     absolute tolerance to zero.  To choose an absolute test only, set
     the relative tolerance to zero.

     The optional argument SING is a vector of values at which the
     integrand is known to be singular.

     The result of the integration is returned in V and IER contains an
     integer error code (0 indicates a successful integration).  The
     value of NFUN indicates how many function evaluations were
     required, and ERR contains an estimate of the error in the
     solution.

 - Loadable Function:  quad_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `quad'.  Given one argument,
     `quad_options' returns the value of the corresponding option.  If
     no arguments are supplied, the names of all the available options
     and their current values are displayed.

   Here is an example of using `quad' to integrate the function

       F(X) = X * sin (1/X) * sqrt (abs (1 - X))

from X = 0 to X = 3.

   This is a fairly difficult integration (plot the function over the
range of integration to see why).

   The first step is to define the function:

     function y = f (x)
       y = x .* sin (1 ./ x) .* sqrt (abs (1 - x));
     endfunction

   Note the use of the `dot' forms of the operators.  This is not
necessary for the call to `quad', but it makes it much easier to
generate a set of points for plotting (because it makes it possible to
call the function with a vector argument to produce a vector result).

   Then we simply call quad:

     [v, ier, nfun, err] = quad ("f", 0, 3)
          => 1.9819
          => 1
          => 5061
          => 1.1522e-07

   Although `quad' returns a nonzero value for IER, the result is
reasonably accurate (to see why, examine what happens to the result if
you move the lower bound to 0.1, then 0.01, then 0.001, etc.).


File: octave,  Node: Orthogonal Collocation,  Prev: Functions of One Variable,  Up: Quadrature

Orthogonal Collocation
======================

 - Loadable Function: [R, A, B, Q] = colloc (N, "left", "right")
     Compute derivative and integral weight matrices for orthogonal
     collocation using the subroutines given in J. Villadsen and M. L.
     Michelsen, `Solution of Differential Equation Models by Polynomial
     Approximation'.

   Here is an example of using `colloc' to generate weight matrices for
solving the second order differential equation U' - ALPHA * U" = 0 with
the boundary conditions U(0) = 0 and U(1) = 1.

   First, we can generate the weight matrices for N points (including
the endpoints of the interval), and incorporate the boundary conditions
in the right hand side (for a specific value of ALPHA).

     n = 7;
     alpha = 0.1;
     [r, a, b] = colloc (n-2, "left", "right");
     at = a(2:n-1,2:n-1);
     bt = b(2:n-1,2:n-1);
     rhs = alpha * b(2:n-1,n) - a(2:n-1,n);

   Then the solution at the roots R is

     u = [ 0; (at - alpha * bt) \ rhs; 1]
          => [ 0.00; 0.004; 0.01 0.00; 0.12; 0.62; 1.00 ]


File: octave,  Node: Differential Equations,  Next: Optimization,  Prev: Quadrature,  Up: Top

Differential Equations
**********************

   Octave has two built-in functions for solving differential equations.
Both are based on reliable ODE solvers written in Fortran.

* Menu:

* Ordinary Differential Equations::
* Differential-Algebraic Equations::


File: octave,  Node: Ordinary Differential Equations,  Next: Differential-Algebraic Equations,  Prev: Differential Equations,  Up: Differential Equations

Ordinary Differential Equations
===============================

   The function `lsode' can be used Solve ODEs of the form

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

 - Loadable Function:  lsode (FCN, X0, T, T_CRIT)
     Return a matrix of X as a function of T, given the initial state
     of the system X0.  Each row in the result matrix corresponds to
     one of the elements in the vector T.  The first element of T
     corresponds to the initial state X0, so that the first row of the
     output is X0.

     The first argument, FCN, is a string that names the function to
     call to compute the vector of right hand sides for the set of
     equations.  It must have the form

          XDOT = f (X, T)

     where XDOT and X are vectors and T is a scalar.

     The fourth argument is optional, and may be used to specify a set
     of times that the ODE solver should not integrate past.  It is
     useful for avoiding difficulties with singularities and points
     where there is a discontinuity in the derivative.

   Here is an example of solving a set of three differential equations
using `lsode'.  Given the function

     function xdot = f (x, t)
     
       xdot = zeros (3,1);
     
       xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \
                 - 8.375e-06*x(1)^2);
       xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27;
       xdot(3) = 0.161*(x(1) - x(3));
     
     endfunction

and the initial condition `x0 = [ 4; 1.1; 4 ]', the set of equations
can be integrated using the command

     t = linspace (0, 500, 1000);
     
     y = lsode ("f", x0, t);

   If you try this, you will see that the value of the result changes
dramatically between T = 0 and 5, and again around T = 305.  A more
efficient set of output points might be

     t = [0, logspace (-1, log10(303), 150), \
             logspace (log10(304), log10(500), 150)];

 - Loadable Function:  lsode_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `lsode'.  Given one argument,
     `lsode_options' returns the value of the corresponding option.  If
     no arguments are supplied, the names of all the available options
     and their current values are displayed.

   See Alan C. Hindmarsh, `ODEPACK, A Systematized Collection of ODE
Solvers', in Scientific Computing, R. S. Stepleman, editor, (1983) for
more information about the inner workings of `lsode'.

