This is octave.info, produced by makeinfo version 4.8 from
/usr/obj/ports/octave-3.0.5/octave-3.0.5/doc/interpreter/octave.texi.

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

   Copyright (C) 1996, 1997, 1999, 2000, 2001, 2002, 2005, 2006, 2007
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.info,  Node: Information,  Next: Operators and Functions,  Prev: Creation,  Up: Basics

20.1.3 Finding out Information about Sparse Matrices
----------------------------------------------------

There are a number of functions that allow information concerning
sparse matrices to be obtained. The most basic of these is "issparse"
that identifies whether a particular Octave object is in fact a sparse
matrix.

   Another very basic function is "nnz" that returns the number of
non-zero entries there are in a sparse matrix, while the function
"nzmax" returns the amount of storage allocated to the sparse matrix.
Note that Octave tends to crop unused memory at the first opportunity
for sparse objects. There are some cases of user created sparse objects
where the value returned by "nzmaz" will not be the same as "nnz", but
in general they will give the same result. The function "spstats"
returns some basic statistics on the columns of a sparse matrix
including the number of elements, the mean and the variance of each
column.

 -- Loadable Function:  issparse (EXPR)
     Return 1 if the value of the expression EXPR is a sparse matrix.

 -- Built-in Function: SCALAR = nnz (A)
     Returns the number of non zero elements in A.

     *See also:* sparse.

 -- Function File:  nonzeros (S)
     Returns a vector of the non-zero values of the sparse matrix S.

 -- Built-in Function: SCALAR = nzmax (SM)
     Return the amount of storage allocated to the sparse matrix SM.
     Note that Octave tends to crop unused memory at the first
     opportunity for sparse objects. There are some cases of user
     created sparse objects where the value returned by "nzmaz" will
     not be the same as "nnz", but in general they will give the same
     result.

     *See also:* sparse, spalloc.

 -- Function File: [COUNT, MEAN, VAR] = spstats (S)
 -- Function File: [COUNT, MEAN, VAR] = spstats (S, J)
     Return the stats for the non-zero elements of the sparse matrix S.
     COUNT is the number of non-zeros in each column, MEAN is the mean
     of the non-zeros in each column, and VAR is the variance of the
     non-zeros in each column.

     Called with two input arguments, if S is the data and J is the bin
     number for the data, compute the stats for each bin.  In this
     case, bins can contain data values of zero, whereas with `spstats
     (S)' the zeros may disappear.

   When solving linear equations involving sparse matrices Octave
determines the means to solve the equation based on the type of the
matrix as discussed in *Note Sparse Linear Algebra::. Octave probes the
matrix type when the div (/) or ldiv (\) operator is first used with
the matrix and then caches the type. However the "matrix_type" function
can be used to determine the type of the sparse matrix prior to use of
the div or ldiv operators. For example

     a = tril (sprandn(1024, 1024, 0.02), -1) ...
         + speye(1024);
     matrix_type (a);
     ans = Lower

   show that Octave correctly determines the matrix type for lower
triangular matrices. "matrix_type" can also be used to force the type
of a matrix to be a particular type. For example

     a = matrix_type (tril (sprandn (1024, ...
        1024, 0.02), -1) + speye(1024), 'Lower');

   This allows the cost of determining the matrix type to be avoided.
However, incorrectly defining the matrix type will result in incorrect
results from solutions of linear equations, and so it is entirely the
responsibility of the user to correctly identify the matrix type

   There are several graphical means of finding out information about
sparse matrices. The first is the "spy" command, which displays the
structure of the non-zero elements of the matrix. *Note fig:spmatrix::,
for an example of the use of "spy".  More advanced graphical
information can be obtained with the "treeplot", "etreeplot" and
"gplot" commands.


            |  * *
            |  * * * *
            |    * *   * *
            |    *   *     * *
          5 -      *   *       * *
            |      *     *         * *
            |        *     *           * *
            |        *       *             *
            |          *       *
         10 -          *         *
            |            *         *
            |            *           *
            |              *           *
            |              *             *
         15 -                *             *
            |----------|---------|---------|
                       5        10        15

Figure 20.1: Structure of simple sparse matrix.

   One use of sparse matrices is in graph theory, where the
interconnections between nodes are represented as an adjacency matrix.
That is, if the i-th node in a graph is connected to the j-th node.
Then the ij-th node (and in the case of undirected graphs the ji-th
node) of the sparse adjacency matrix is non-zero. If each node is then
associated with a set of co-ordinates, then the "gplot" command can be
used to graphically display the interconnections between nodes.

   As a trivial example of the use of "gplot", consider the example

     A = sparse([2,6,1,3,2,4,3,5,4,6,1,5],
         [1,1,2,2,3,3,4,4,5,5,6,6],1,6,6);
     xy = [0,4,8,6,4,2;5,0,5,7,5,7]';
     gplot(A,xy)

   which creates an adjacency matrix `A' where node 1 is connected to
nodes 2 and 6, node 2 with nodes 1 and 3, etc. The co-ordinates of the
nodes are given in the n-by-2 matrix `xy'.

   The dependencies between the nodes of a Cholesky factorization can be
calculated in linear time without explicitly needing to calculate the
Cholesky factorization by the `etree' command. This command returns the
elimination tree of the matrix and can be displayed graphically by the
command `treeplot(etree(A))' if `A' is symmetric or
`treeplot(etree(A+A'))' otherwise.

 -- Function File:  spy (X)
 -- Function File:  spy (..., MARKERSIZE)
 -- Function File:  spy (..., LINESPEC)
     Plot the sparsity pattern of the sparse matrix X. If the argument
     MARKERSIZE is given as an scalar value, it is used to determine the
     point size in the plot. If the string LINESPEC is given it is
     passed to `plot' and determines the appearance of the plot.

     *See also:* plot.

 -- Loadable Function: P = etree (S)
 -- Loadable Function: P = etree (S, TYP)
 -- Loadable Function: [P, Q] = etree (S, TYP)
     Returns the elimination tree for the matrix S. By default S is
     assumed to be symmetric and the symmetric elimination tree is
     returned. The argument TYP controls whether a symmetric or column
     elimination tree is returned. Valid values of TYP are 'sym' or
     'col', for symmetric or column elimination tree respectively

     Called with a second argument, "etree" also returns the postorder
     permutations on the tree.

 -- Function File:  etreeplot (TREE)
 -- Function File:  etreeplot (TREE, NODE_STYLE, EDGE_STYLE)
     Plot the elimination tree of the matrix S or `S+S''  if S in
     non-symmetric.  The optional parameters LINE_STYLE and EDGE_STYLE
     define the output style.

     *See also:* treeplot, gplot.

 -- Function File:  gplot (A, XY)
 -- Function File:  gplot (A, XY, LINE_STYLE)
 -- Function File: [X, Y] = gplot (A, XY)
     Plot a graph defined by A and XY in the graph theory sense.  A is
     the adjacency matrix of the array to be plotted and XY is an
     N-by-2 matrix containing the coordinates of the nodes of the graph.

     The optional parameter LINE_STYLE defines the output style for the
     plot.  Called with no output arguments the graph is plotted
     directly.  Otherwise, return the coordinates of the plot in X and
     Y.

     *See also:* treeplot, etreeplot, spy.

 -- Function File:  treeplot (TREE)
 -- Function File:  treeplot (TREE, LINESTYLE, EDGESTYLE)
     Produces a graph of tree or forest. The first argument is vector of
     predecessors, optional parameters LINESTYLE and EDGESTYLE define
     the output style. The complexity of the algorithm is O(n) in terms
     of is time and memory requirements.

     *See also:* etreeplot, gplot.


File: octave.info,  Node: Operators and Functions,  Prev: Information,  Up: Basics

20.1.4 Basic Operators and Functions on Sparse Matrices
-------------------------------------------------------

* Menu:

* Functions:: Sparse Functions
* ReturnType:: The Return Types of Operators and Functions
* MathConsiderations:: Mathematical Considerations


File: octave.info,  Node: Functions,  Next: ReturnType,  Prev: Operators and Functions,  Up: Operators and Functions

20.1.4.1 Sparse Functions
.........................

An important consideration in the use of the sparse functions of Octave
is that many of the internal functions of Octave, such as "diag", can
not accept sparse matrices as an input. The sparse implementation in
Octave therefore uses the "dispatch" function to overload the normal
Octave functions with equivalent functions that work with sparse
matrices. However, at any time the sparse matrix specific version of
the function can be used by explicitly calling its function name.

   The table below lists all of the sparse functions of Octave.  Note
that the names of the specific sparse forms of the functions are
typically the same as the general versions with a "sp" prefix. In the
table below, and the rest of this article the specific sparse versions
of the functions are used.

Generate sparse matrices:
     "spalloc", "spdiags", "speye", "sprand",   "sprandn", "sprandsym"

Sparse matrix conversion:
     "full", "sparse", "spconvert", "spfind"

Manipulate sparse matrices
     "issparse", "nnz", "nonzeros", "nzmax",   "spfun", "spones", "spy"

Graph Theory:
     "etree", "etreeplot", "gplot",   "treeplot"

Sparse matrix reordering:
     "ccolamd", "colamd", "colperm", "csymamd",   "dmperm", "symamd",
     "randperm", "symrcm"

Linear algebra:
     "matrix_type", "spchol", "cpcholinv",   "spchol2inv", "spdet",
     "spinv", "spkron",   "splchol", "splu", "spqr", "normest",
     "condest",   "sprank"

Iterative techniques:
     "luinc", "pcg", "pcr"

Miscellaneous:
     "spparms", "symbfact", "spstats",   "spprod", "spcumsum", "spsum",
      "spsumsq", "spmin", "spmax", "spatan2",   "spdiag"

   In addition all of the standard Octave mapper functions (ie. basic
math functions that take a single argument) such as "abs", etc can
accept sparse matrices. The reader is referred to the documentation
supplied with these functions within Octave itself for further details.


File: octave.info,  Node: ReturnType,  Next: MathConsiderations,  Prev: Functions,  Up: Operators and Functions

20.1.4.2 The Return Types of Operators and Functions
....................................................

The two basic reasons to use sparse matrices are to reduce the memory
usage and to not have to do calculations on zero elements. The two are
closely related in that the computation time on a sparse matrix operator
or function is roughly linear with the number of non-zero elements.

   Therefore, there is a certain density of non-zero elements of a
matrix where it no longer makes sense to store it as a sparse matrix,
but rather as a full matrix. For this reason operators and functions
that have a high probability of returning a full matrix will always
return one. For example adding a scalar constant to a sparse matrix
will almost always make it a full matrix, and so the example

     speye(3) + 0
     =>   1  0  0
       0  1  0
       0  0  1

   returns a full matrix as can be seen.

   Additionally, if `sparse_auto_mutate' is true, all sparse functions
test the amount of memory occupied by the sparse matrix to see if the
amount of storage used is larger than the amount used by the full
equivalent. Therefore `speye (2) * 1' will return a full matrix as the
memory used is smaller for the full version than the sparse version.

   As all of the mixed operators and functions between full and sparse
matrices exist, in general this does not cause any problems. However,
one area where it does cause a problem is where a sparse matrix is
promoted to a full matrix, where subsequent operations would resparsify
the matrix. Such cases are rare, but can be artificially created, for
example `(fliplr(speye(3)) + speye(3)) - speye(3)' gives a full matrix
when it should give a sparse one. In general, where such cases occur,
they impose only a small memory penalty.

   There is however one known case where this behavior of Octave's
sparse matrices will cause a problem. That is in the handling of the
"diag" function. Whether "diag" returns a sparse or full matrix
depending on the type of its input arguments. So

      a = diag (sparse([1,2,3]), -1);

   should return a sparse matrix. To ensure this actually happens, the
"sparse" function, and other functions based on it like "speye", always
returns a sparse matrix, even if the memory used will be larger than
its full representation.

 -- Built-in Function: VAL = sparse_auto_mutate ()
 -- Built-in Function: OLD_VAL = sparse_auto_mutate (NEW_VAL)
     Query or set the internal variable that controls whether Octave
     will automatically mutate sparse matrices to real matrices to save
     memory.  For example,

          s = speye(3);
          sparse_auto_mutate (false)
          s (:, 1) = 1;
          typeinfo (s)
          => sparse matrix
          sparse_auto_mutate (true)
          s (1, :) = 1;
          typeinfo (s)
          => matrix

   Note that the `sparse_auto_mutate' option is incompatible with
MATLAB, and so it is off by default.


File: octave.info,  Node: MathConsiderations,  Prev: ReturnType,  Up: Operators and Functions

20.1.4.3 Mathematical Considerations
....................................

The attempt has been made to make sparse matrices behave in exactly the
same manner as there full counterparts. However, there are certain
differences and especially differences with other products sparse
implementations.

   Firstly, the "./" and ".^" operators must be used with care.
Consider what the examples

       s = speye (4);
       a1 = s .^ 2;
       a2 = s .^ s;
       a3 = s .^ -2;
       a4 = s ./ 2;
       a5 = 2 ./ s;
       a6 = s ./ s;

   will give. The first example of S raised to the power of 2 causes no
problems. However S raised element-wise to itself involves a large
number of terms `0 .^ 0' which is 1. There `S .^ S' is a full matrix.

   Likewise `S .^ -2' involves terms terms like `0 .^ -2' which is
infinity, and so `S .^ -2' is equally a full matrix.

   For the "./" operator `S ./ 2' has no problems, but `2 ./ S'
involves a large number of infinity terms as well and is equally a full
matrix. The case of `S ./ S' involves terms like `0 ./ 0' which is a
`NaN' and so this is equally a full matrix with the zero elements of S
filled with `NaN' values.

   The above behavior is consistent with full matrices, but is not
consistent with sparse implementations in other products.

   A particular problem of sparse matrices comes about due to the fact
that as the zeros are not stored, the sign-bit of these zeros is
equally not stored. In certain cases the sign-bit of zero is important.
For example

      a = 0 ./ [-1, 1; 1, -1];
      b = 1 ./ a
      => -Inf            Inf
          Inf           -Inf
      c = 1 ./ sparse (a)
      =>  Inf            Inf
          Inf            Inf

   To correct this behavior would mean that zero elements with a
negative sign-bit would need to be stored in the matrix to ensure that
their sign-bit was respected. This is not done at this time, for
reasons of efficiency, and so the user is warned that calculations
where the sign-bit of zero is important must not be done using sparse
matrices.

   In general any function or operator used on a sparse matrix will
result in a sparse matrix with the same or a larger number of non-zero
elements than the original matrix. This is particularly true for the
important case of sparse matrix factorizations. The usual way to
address this is to reorder the matrix, such that its factorization is
sparser than the factorization of the original matrix. That is the
factorization of `L * U = P * S * Q' has sparser terms `L' and `U' than
the equivalent factorization `L * U = S'.

   Several functions are available to reorder depending on the type of
the matrix to be factorized. If the matrix is symmetric
positive-definite, then "symamd" or "csymamd" should be used. Otherwise
"colamd" or "ccolamd" should be used. For completeness the reordering
functions "colperm" and "randperm" are also available.

   *Note fig:simplematrix::, for an example of the structure of a simple
positive definite matrix.


            |  * *
            |  * * * *
            |    * *   * *
            |    *   *     * *
          5 -      *   *       * *
            |      *     *         * *
            |        *     *           * *
            |        *       *             *
            |          *       *
         10 -          *         *
            |            *         *
            |            *           *
            |              *           *
            |              *             *
         15 -                *             *
            |----------|---------|---------|
                       5        10        15

Figure 20.2: Structure of simple sparse matrix.

   The standard Cholesky factorization of this matrix can be obtained
by the same command that would be used for a full matrix. This can be
visualized with the command `r = chol(A); spy(r);'.  The original
matrix had 43 non-zero terms, while this Cholesky factorization has 71,
with only half of the symmetric matrix being stored. This is a
significant level of fill in, and although not an issue for such a
small test case, can represents a large overhead in working with other
sparse matrices.

   The appropriate sparsity preserving permutation of the original
matrix is given by "symamd" and the factorization using this reordering
can be visualized using the command `q = symamd(A); r = chol(A(q,q));
spy(r)'. This gives 29 non-zero terms which is a significant
improvement.

   The Cholesky factorization itself can be used to determine the
appropriate sparsity preserving reordering of the matrix during the
factorization, In that case this might be obtained with three return
arguments as r`[r, p, q] = chol(A); spy(r)'.

   In the case of an asymmetric matrix, the appropriate sparsity
preserving permutation is "colamd" and the factorization using this
reordering can be visualized using the command `q = colamd(A); [l, u,
p] = lu(A(:,q)); spy(l+u)'.

   Finally, Octave implicitly reorders the matrix when using the div (/)
and ldiv (\) operators, and so no the user does not need to explicitly
reorder the matrix to maximize performance.

 -- Loadable Function: P = ccolamd (S)
 -- Loadable Function: P = ccolamd (S, KNOBS)
 -- Loadable Function: P = ccolamd (S, KNOBS, CMEMBER)
 -- Loadable Function: [P, STATS] = ccolamd (...)
     Constrained column approximate minimum degree permutation. `P =
     ccolamd (S)' returns the column approximate minimum degree
     permutation vector for the sparse matrix S. For a non-symmetric
     matrix S, `S (:, P)' tends to have sparser LU factors than S.
     `chol (S (:, P)' * S (:, P))' also tends to be sparser than `chol
     (S' * S)'. `P = ccolamd (S, 1)' optimizes the ordering for `lu (S
     (:, P))'.  The ordering is followed by a column elimination tree
     post-ordering.

     KNOBS is an optional one- to five-element input vector, with a
     default value of `[0 10 10 1 0]' if not present or empty.  Entries
     not present are set to their defaults.

    `KNOBS(1)'
          if nonzero, the ordering is optimized for `lu (S (:, p))'. It
          will be a poor ordering for `chol (S (:, P)' * S (:, P))'.
          This is the most important knob for ccolamd.

    `KNOB(2)'
          if S is m-by-n, rows with more than `max (16, KNOBS (2) *
          sqrt (n))' entries are ignored.

    `KNOB(3)'
          columns with more than `max (16, KNOBS (3) * sqrt (min (M,
          N)))' entries are ignored and ordered last in the output
          permutation (subject to the cmember constraints).

    `KNOB(4)'
          if nonzero, aggressive absorption is performed.

    `KNOB(5)'
          if nonzero, statistics and knobs are printed.


     CMEMBER is an optional vector of length n.  It defines the
     constraints on the column ordering.  If `CMEMBER (j) = C', then
     column J is in constraint set C (C must be in the range 1 to N).
     In the output permutation P, all columns in set 1 appear first,
     followed by all columns in set 2, and so on.  `CMEMBER =
     ones(1,n)' if not present or empty.  `ccolamd (S, [], 1 : N)'
     returns `1 : N'

     `P = ccolamd (S)' is about the same as `P = colamd (S)'. KNOBS and
     its default values differ. `colamd' always does aggressive
     absorption, and it finds an ordering suitable for both `lu (S (:,
     P))' and `chol (S (:, P)' * S (:, P))'; it cannot optimize its
     ordering for `lu (S (:, P))' to the extent that `ccolamd (S, 1)'
     can.

     STATS is an optional 20-element output vector that provides data
     about the ordering and the validity of the input matrix S. Ordering
     statistics are in `STATS (1 : 3)'. `STATS (1)' and `STATS (2)' are
     the number of dense or empty rows and columns ignored by CCOLAMD
     and `STATS (3)' is the number of garbage collections performed on
     the internal data structure used by CCOLAMD (roughly of size `2.2
     * nnz (S) + 4 * M + 7 * N' integers).

     `STATS (4 : 7)' provide information if CCOLAMD was able to
     continue. The matrix is OK if `STATS (4)' is zero, or 1 if
     invalid. `STATS (5)' is the rightmost column index that is
     unsorted or contains duplicate entries, or zero if no such column
     exists.  `STATS (6)' is the last seen duplicate or out-of-order row
     index in the column index given by `STATS (5)', or zero if no such
     row index exists. `STATS (7)' is the number of duplicate or
     out-of-order row indices. `STATS (8 : 20)' is always zero in the
     current version of CCOLAMD (reserved for future use).

     The authors of the code itself are S. Larimore, T. Davis (Uni of
     Florida) and S. Rajamanickam in collaboration with J. Bilbert and
     E. Ng. Supported by the National Science Foundation (DMS-9504974,
     DMS-9803599, CCR-0203270), and a grant from Sandia National Lab.
     See `http://www.cise.ufl.edu/research/sparse' for ccolamd,
     csymamd, amd, colamd, symamd, and other related orderings.

     *See also:* colamd, csymamd.

 -- Loadable Function: P = colamd (S)
 -- Loadable Function: P = colamd (S, KNOBS)
 -- Loadable Function: [P, STATS] = colamd (S)
 -- Loadable Function: [P, STATS] = colamd (S, KNOBS)
     Column approximate minimum degree permutation. `P = colamd (S)'
     returns the column approximate minimum degree permutation vector
     for the sparse matrix S. For a non-symmetric matrix S, `S (:,P)'
     tends to have sparser LU factors than S.  The Cholesky
     factorization of `S (:,P)' * S (:,P)' also tends to be sparser
     than that of `S' * S'.

     KNOBS is an optional one- to three-element input vector.  If S is
     m-by-n, then rows with more than `max(16,KNOBS(1)*sqrt(n))' entries
     are ignored. Columns with more than
     `max(16,knobs(2)*sqrt(min(m,n)))' entries are removed prior to
     ordering, and ordered last in the output permutation P. Only
     completely dense rows or columns are removed if `KNOBS (1)' and
     `KNOBS (2)' are < 0, respectively.  If `KNOBS (3)' is nonzero,
     STATS and KNOBS are printed.  The default is `KNOBS = [10 10 0]'.
     Note that KNOBS differs from earlier versions of colamd

     STATS is an optional 20-element output vector that provides data
     about the ordering and the validity of the input matrix S. Ordering
     statistics are in `STATS (1:3)'. `STATS (1)' and `STATS (2)' are
     the number of dense or empty rows and columns ignored by COLAMD
     and `STATS (3)' is the number of garbage collections performed on
     the internal data structure used by COLAMD (roughly of size `2.2 *
     nnz(S) + 4 * M + 7 * N' integers).

     Octave built-in functions are intended to generate valid sparse
     matrices, with no duplicate entries, with ascending row indices of
     the nonzeros in each column, with a non-negative number of entries
     in each column (!)  and so on.  If a matrix is invalid, then
     COLAMD may or may not be able to continue.  If there are duplicate
     entries (a row index appears two or more times in the same column)
     or if the row indices in a column are out of order, then COLAMD
     can correct these errors by ignoring the duplicate entries and
     sorting each column of its internal copy of the matrix S (the
     input matrix S is not repaired, however). If a matrix is invalid
     in other ways then COLAMD cannot continue, an error message is
     printed, and no output arguments (P or STATS) are returned.
     COLAMD is thus a simple way to check a sparse matrix to see if it's
     valid.

     `STATS (4:7)' provide information if COLAMD was able to continue.
     The matrix is OK if `STATS (4)' is zero, or 1 if invalid. `STATS
     (5)' is the rightmost column index that is unsorted or contains
     duplicate entries, or zero if no such column exists.  `STATS (6)'
     is the last seen duplicate or out-of-order row index in the column
     index given by `STATS (5)', or zero if no such row index exists.
     `STATS (7)' is the number of duplicate or out-of-order row
     indices. `STATS (8:20)' is always zero in the current version of
     COLAMD (reserved for future use).

     The ordering is followed by a column elimination tree
     post-ordering.

     The authors of the code itself are Stefan I. Larimore and Timothy
     A.  Davis (davis@cise.ufl.edu), University of Florida.  The
     algorithm was developed in collaboration with John Gilbert, Xerox
     PARC, and Esmond Ng, Oak Ridge National Laboratory. (see
     `http://www.cise.ufl.edu/research/sparse/colamd')

     *See also:* colperm, symamd.

 -- Function File: P = colperm (S)
     Returns the column permutations such that the columns of `S (:,
     P)' are ordered in terms of increase number of non-zero elements.
     If S is symmetric, then P is chosen such that `S (P, P)' orders
     the rows and columns with increasing number of non zeros elements.

 -- Loadable Function: P = csymamd (S)
 -- Loadable Function: P = csymamd (S, KNOBS)
 -- Loadable Function: P = csymamd (S, KNOBS, CMEMBER)
 -- Loadable Function: [P, STATS] = csymamd (...)
     For a symmetric positive definite matrix S, returns the permutation
     vector P such that `S(P,P)' tends to have a sparser Cholesky
     factor than S. Sometimes `csymamd' works well for symmetric
     indefinite matrices too. The matrix S is assumed to be symmetric;
     only the strictly lower triangular part is referenced.  S must be
     square. The ordering is followed by an elimination tree
     post-ordering.

     KNOBS is an optional one- to three-element input vector, with a
     default value of `[10 1 0]' if present or empty.  Entries not
     present are set to their defaults.

    `KNOBS(1)'
          If S is n-by-n, then rows and columns with more than
          `max(16,KNOBS(1)*sqrt(n))' entries are ignored, and ordered
          last in the output permutation (subject to the cmember
          constraints).

    `KNOBS(2)'
          If nonzero, aggressive absorption is performed.

    `KNOBS(3)'
          If nonzero, statistics and knobs are printed.


     CMEMBER is an optional vector of length n. It defines the
     constraints on the ordering. If `CMEMBER(j) = S', then row/column
     j is in constraint set C (C must be in the range 1 to n). In the
     output permutation P, rows/columns in set 1 appear first, followed
     by all rows/columns in set 2, and so on. `CMEMBER = ones(1,n)' if
     not present or empty. `csymamd(S,[],1:n)' returns `1:n'.

     `P = csymamd(S)' is about the same as `P = symamd(S)'. KNOBS and
     its default values differ.

     `STATS (4:7)' provide information if CCOLAMD was able to continue.
     The matrix is OK if `STATS (4)' is zero, or 1 if invalid. `STATS
     (5)' is the rightmost column index that is unsorted or contains
     duplicate entries, or zero if no such column exists.  `STATS (6)'
     is the last seen duplicate or out-of-order row index in the column
     index given by `STATS (5)', or zero if no such row index exists.
     `STATS (7)' is the number of duplicate or out-of-order row
     indices. `STATS (8:20)' is always zero in the current version of
     CCOLAMD (reserved for future use).

     The authors of the code itself are S. Larimore, T. Davis (Uni of
     Florida) and S. Rajamanickam in collaboration with J. Bilbert and
     E. Ng. Supported by the National Science Foundation (DMS-9504974,
     DMS-9803599, CCR-0203270), and a grant from Sandia National Lab.
     See `http://www.cise.ufl.edu/research/sparse' for ccolamd,
     csymamd, amd, colamd, symamd, and other related orderings.

     *See also:* symamd, ccolamd.

 -- Loadable Function: P = dmperm (S)
 -- Loadable Function: [P, Q, R, S] = dmperm (S)
     Perform a Dulmage-Mendelsohn permutation on the sparse matrix S.
     With a single output argument "dmperm" performs the row
     permutations P such that `S (P,:)' has no zero elements on the
     diagonal.

     Called with two or more output arguments, returns the row and
     column permutations, such that `S (P, Q)' is in block triangular
     form. The values of R and S define the boundaries of the blocks.
     If S is square then `R == S'.

     The method used is described in: A. Pothen & C.-J. Fan. Computing
     the block triangular form of a sparse matrix. ACM Trans. Math.
     Software, 16(4):303-324, 1990.

     *See also:* colamd, ccolamd.

 -- Loadable Function: P = symamd (S)
 -- Loadable Function: P = symamd (S, KNOBS)
 -- Loadable Function: [P, STATS] = symamd (S)
 -- Loadable Function: [P, STATS] = symamd (S, KNOBS)
     For a symmetric positive definite matrix S, returns the permutation
     vector p such that `S (P, P)' tends to have a sparser Cholesky
     factor than S. Sometimes SYMAMD works well for symmetric
     indefinite matrices too. The matrix S is assumed to be symmetric;
     only the strictly lower triangular part is referenced. S must be
     square.

     KNOBS is an optional one- to two-element input vector.  If S is
     n-by-n, then rows and columns with more than
     `max(16,KNOBS(1)*sqrt(n))' entries are removed prior to ordering,
     and ordered last in the output permutation P. No rows/columns are
     removed if `KNOBS(1) < 0'.  If `KNOBS (2)' is nonzero, `stats' and
     KNOBS are printed.  The default is `KNOBS = [10 0]'.  Note that
     KNOBS differs from earlier versions of symamd.

     STATS is an optional 20-element output vector that provides data
     about the ordering and the validity of the input matrix S. Ordering
     statistics are in `STATS (1:3)'. `STATS (1) = STATS (2)' is the
     number of dense or empty rows and columns ignored by SYMAMD and
     `STATS (3)' is the number of garbage collections performed on the
     internal data structure used by SYMAMD (roughly of size `8.4 * nnz
     (tril (S, -1)) + 9 * N' integers).

     Octave built-in functions are intended to generate valid sparse
     matrices, with no duplicate entries, with ascending row indices of
     the nonzeros in each column, with a non-negative number of entries
     in each column (!)  and so on.  If a matrix is invalid, then
     SYMAMD may or may not be able to continue.  If there are duplicate
     entries (a row index appears two or more times in the same column)
     or if the row indices in a column are out of order, then SYMAMD
     can correct these errors by ignoring the duplicate entries and
     sorting each column of its internal copy of the matrix S (the
     input matrix S is not repaired, however).  If a matrix is invalid
     in other ways then SYMAMD cannot continue, an error message is
     printed, and no output arguments (P or STATS) are returned.
     SYMAMD is thus a simple way to check a sparse matrix to see if
     it's valid.

     `STATS (4:7)' provide information if SYMAMD was able to continue.
     The matrix is OK if `STATS (4)' is zero, or 1 if invalid. `STATS
     (5)' is the rightmost column index that is unsorted or contains
     duplicate entries, or zero if no such column exists. `STATS (6)'
     is the last seen duplicate or out-of-order row index in the column
     index given by `STATS (5)', or zero if no such row index exists.
     `STATS (7)' is the number of duplicate or out-of-order row
     indices. `STATS (8:20)' is always zero in the current version of
     SYMAMD (reserved for future use).

     The ordering is followed by a column elimination tree
     post-ordering.

     The authors of the code itself are Stefan I. Larimore and Timothy
     A.  Davis (davis@cise.ufl.edu), University of Florida.  The
     algorithm was developed in collaboration with John Gilbert, Xerox
     PARC, and Esmond Ng, Oak Ridge National Laboratory. (see
     `http://www.cise.ufl.edu/research/sparse/colamd')

     *See also:* colperm, colamd.

 -- Loadable Function: P =  symrcm (S)
     Symmetric reverse Cuthill-McKee permutation of S.  Return a
     permutation vector P such that `S (P, P)' tends to have its
     diagonal elements closer to the diagonal than S.  This is a good
     preordering for LU or Cholesky factorization of matrices that come
     from 'long, skinny' problems.  It works for both symmetric and
     asymmetric S.

     The algorithm represents a heuristic approach to the NP-complete
     bandwidth minimization problem.  The implementation is based in the
     descriptions found in

     E. Cuthill, J. McKee: Reducing the Bandwidth of Sparse Symmetric
     Matrices. Proceedings of the 24th ACM National Conference, 157-172
     1969, Brandon Press, New Jersey.

     Alan George, Joseph W. H. Liu: Computer Solution of Large Sparse
     Positive Definite Systems, Prentice Hall Series in Computational
     Mathematics, ISBN 0-13-165274-5, 1981.


     *See also:* colperm, colamd, symamd.


File: octave.info,  Node: Sparse Linear Algebra,  Next: Iterative Techniques,  Prev: Basics,  Up: Sparse Matrices

20.2 Linear Algebra on Sparse Matrices
======================================

Octave includes a poly-morphic solver for sparse matrices, where the
exact solver used to factorize the matrix, depends on the properties of
the sparse matrix itself. Generally, the cost of determining the matrix
type is small relative to the cost of factorizing the matrix itself,
but in any case the matrix type is cached once it is calculated, so
that it is not re-determined each time it is used in a linear equation.

   The selection tree for how the linear equation is solve is

  1. If the matrix is diagonal, solve directly and goto 8

  2. If the matrix is a permuted diagonal, solve directly taking into
     account the permutations. Goto 8

  3. If the matrix is square, banded and if the band density is less
     than that given by `spparms ("bandden")' continue, else goto 4.

       a. If the matrix is tridiagonal and the right-hand side is not
          sparse continue, else goto 3b.

            1. If the matrix is hermitian, with a positive real
               diagonal, attempt       Cholesky factorization using
               LAPACK xPTSV.

            2. If the above failed or the matrix is not hermitian with
               a positive       real diagonal use Gaussian elimination
               with pivoting using       LAPACK xGTSV, and goto 8.

       b. If the matrix is hermitian with a positive real diagonal,
          attempt       Cholesky factorization using LAPACK xPBTRF.

       c. if the above failed or the matrix is not hermitian with a
          positive       real diagonal use Gaussian elimination with
          pivoting using       LAPACK xGBTRF, and goto 8.

  4. If the matrix is upper or lower triangular perform a sparse forward
     or backward substitution, and goto 8

  5. If the matrix is a upper triangular matrix with column permutations
     or lower triangular matrix with row permutations, perform a sparse
     forward or backward substitution, and goto 8

  6. If the matrix is square, hermitian with a real positive diagonal,
     attempt sparse Cholesky factorization using CHOLMOD.

  7. If the sparse Cholesky factorization failed or the matrix is not
     hermitian with a real positive diagonal, and the matrix is square,
     factorize using UMFPACK.

  8. If the matrix is not square, or any of the previous solvers flags
     a singular or near singular matrix, find a minimum norm solution
     using CXSPARSE(1).

   The band density is defined as the number of non-zero values in the
matrix divided by the number of non-zero values in the matrix. The
banded matrix solvers can be entirely disabled by using "spparms" to
set `bandden' to 1 (i.e. `spparms ("bandden", 1)').

   The QR solver factorizes the problem with a Dulmage-Mendhelsohn, to
separate the problem into blocks that can be treated as over-determined,
multiple well determined blocks, and a final over-determined block. For
matrices with blocks of strongly connected nodes this is a big win as
LU decomposition can be used for many blocks. It also significantly
improves the chance of finding a solution to over-determined problems
rather than just returning a vector of "NaN"'s.

   All of the solvers above, can calculate an estimate of the condition
number. This can be used to detect numerical stability problems in the
solution and force a minimum norm solution to be used. However, for
narrow banded, triangular or diagonal matrices, the cost of calculating
the condition number is significant, and can in fact exceed the cost of
factoring the matrix. Therefore the condition number is not calculated
in these cases, and Octave relies on simpler techniques to detect
singular matrices or the underlying LAPACK code in the case of banded
matrices.

   The user can force the type of the matrix with the `matrix_type'
function. This overcomes the cost of discovering the type of the matrix.
However, it should be noted incorrectly identifying the type of the
matrix will lead to unpredictable results, and so `matrix_type' should
be used with care.

 -- Function File: [N, C] = normest (A, TOL)
     Estimate the 2-norm of the matrix A using a power series analysis.
     This is typically used for large matrices, where the cost of
     calculating the `norm (A)' is prohibitive and an approximation to
     the 2-norm is acceptable.

     TOL is the tolerance to which the 2-norm is calculated. By default
     TOL is 1e-6. C returns the number of iterations needed for
     `normest' to converge.

 -- Function File: [EST, V] = condest (A, T)
 -- Function File: [EST, V] = condest (A, SOLVE, SOLVE_T, T)
 -- Function File: [EST, V] = condest (APPLY, APPLY_T, SOLVE, SOLVE_T,
          N, T)
     Estimate the 1-norm condition number of a matrix matrix A using T
     test vectors using a randomized 1-norm estimator.  If T exceeds 5,
     then only 5 test vectors are used.

     If the matrix is not explicit, e.g. when  estimating the condition
     number of A given an LU factorization, `condest' uses the
     following functions:

    APPLY
          `A*x' for a matrix `x' of size N by T.

    APPLY_T
          `A'*x' for a matrix `x' of size N by T.

    SOLVE
          `A \ b' for a matrix `b' of size N by T.

    SOLVE_T
          `A' \ b' for a matrix `b' of size N by T.

     The implicit version requires an explicit dimension N.

     `condest' uses a randomized algorithm to approximate the 1-norms.

     `condest' returns the 1-norm condition estimate EST and a vector V
     satisfying `norm (A*v, 1) == norm (A, 1) * norm (V, 1) / EST'.
     When EST is large, V is an approximate null vector.

     References:
        * Nicholas J. Higham and Françoise Tisseur, "A Block Algorithm
          for Matrix 1-Norm Estimation, with an Application to 1-Norm
          Pseudospectra." SIMAX vol 21, no 4, pp 1185-1201.
          `http://dx.doi.org/10.1137/S0895479899356080'

        * Nicholas J. Higham and Françoise Tisseur, "A Block Algorithm
          for Matrix 1-Norm Estimation, with an Application to 1-Norm
          Pseudospectra." `http://citeseer.ist.psu.edu/223007.html'


     *See also:* norm, cond, onenormest.

 -- Loadable Function: R = spchol (A)
 -- Loadable Function: [R, P] = spchol (A)
 -- Loadable Function: [R, P, Q] = spchol (A)
     Compute the Cholesky factor, R, of the symmetric positive definite
     sparse matrix A, where

          r' * r = a.

     If called with 2 or more outputs P is the 0 when R is positive
     definite and P is a positive integer otherwise.

     If called with 3 outputs then a sparsity preserving row/column
     permutation is applied to A prior to the factorization. That is R
     is the factorization of `A(Q,Q)' such that

          r' * r = q * a * q'.

     Note that `splchol' factorization is faster and uses less memory.

     *See also:* spcholinv, spchol2inv, splchol.

 -- Loadable Function:  spcholinv (A)
     Use the Cholesky factorization to compute the inverse of the
     sparse symmetric positive definite matrix A.

     *See also:* spchol, spchol2inv.

 -- Loadable Function:  spchol2inv (U)
     Invert a sparse symmetric, positive definite square matrix from its
     Cholesky decomposition, U.  Note that U should be an
     upper-triangular matrix with positive diagonal elements.
     `chol2inv (U)' provides `inv (U'*U)' but it is much faster than
     using `inv'.

     *See also:* spchol, spcholinv.

 -- Loadable Function: [D, RCOND] =  spdet (A)
     Compute the determinant of sparse matrix A using UMFPACK.  Return
     an estimate of the reciprocal condition number if requested.

 -- Loadable Function: [X, RCOND] =  spinv (A, Q)
     Compute the inverse of the sparse square matrix A.  Return an
     estimate of the reciprocal condition number if requested,
     otherwise warn of an ill-conditioned matrix if the reciprocal
     condition number is small.  This function takes advantage of the
     sparsity of the matrix to accelerate the calculation of the
     inverse.

     In general X will be a full matrix, and so if possible forming the
     inverse of a sparse matrix should be avoided. It is significantly
     more accurate and faster to do `Y = A \ B', rather than `Y = spinv
     (A) * B'.

 -- Loadable Function:  spkron (A, B)
     Form the kronecker product of two sparse matrices. This is defined
     block by block as

          x = [a(i, j) b]

     For example,

          kron(speye(3),spdiag([1,2,3]))
          =>
          Compressed Column Sparse (rows = 9, cols = 9, nnz = 9)

            (1, 1) ->  1
            (2, 2) ->  2
            (3, 3) ->  3
            (4, 4) ->  1
            (5, 5) ->  2
            (6, 6) ->  3
            (7, 7) ->  1
            (8, 8) ->  2
            (9, 9) ->  3

 -- Loadable Function: L = splchol (A)
 -- Loadable Function: [L, P] = splchol (A)
 -- Loadable Function: [L, P, Q] = splchol (A)
     Compute the Cholesky factor, L, of the symmetric positive definite
     sparse matrix A, where

          l * l' = a.

     If called with 2 or more outputs P is the 0 when L is positive
     definite and L is a positive integer otherwise.

     If called with 3 outputs that a sparsity preserving row/column
     permutation is applied to A prior to the factorization. That is L
     is the factorization of `A(Q,Q)' such that

          r * r' = a (q, q).

     Note that `splchol' factorization is faster and uses less memory
     than `spchol'. `splchol(A)' is equivalent to `spchol(A)''.

     *See also:* spcholinv, spchol2inv, splchol.

 -- Loadable Function: [L, U] = splu (A)
 -- Loadable Function: [L, U, P] = splu (A)
 -- Loadable Function: [L, U, P, Q] = splu (A)
 -- Loadable Function: [L, U, P, Q] = splu (..., THRES)
 -- Loadable Function: [L, U, P] = splu (..., Q)
     Compute the LU decomposition of the sparse matrix A, using
     subroutines from UMFPACK.  The result is returned in a permuted
     form, according to the optional return values P and Q.

     Called with two or three output arguments and a single input
     argument, "splu" is a replacement for "lu", and therefore the
     sparsity preserving column permutations Q are not performed.
     Called with a fourth output argument, the sparsity preserving
     column transformation Q is returned, such that `P * A * Q = L * U'.

     An additional input argument THRES, that defines the pivoting
     threshold can be given. Alternatively, the desired sparsity
     preserving column permutations Q can be passed. Note that Q is
     assumed to be fixed if there are fewer than four output arguments.
     Otherwise, the updated column permutations are returned as the
     fourth argument.

     With two output arguments, returns the permuted forms of the upper
     and lower triangular matrices, such that `A = L * U'.  With two or
     three output arguments, if a user-defined Q is given, then `U *
     Q'' is returned. The matrix is not required to be square.

     *See also:* sparse, spinv, colamd, symamd.

 -- Loadable Function:   spparms ()
 -- Loadable Function: VALS = spparms ()
 -- Loadable Function: [KEYS, VALS] = spparms ()
 -- Loadable Function: VAL = spparms (KEY)
 -- Loadable Function:   spparms (VALS)
 -- Loadable Function:   spparms ('defaults')
 -- Loadable Function:   spparms ('tight')
 -- Loadable Function:   spparms (KEY, VAL)
     Sets or displays the parameters used by the sparse solvers and
     factorization functions. The first four calls above get
     information about the current settings, while the others change
     the current settings. The parameters are stored as pairs of keys
     and values, where the values are all floats and the keys are one
     of the strings

        * spumoni Printing level of debugging information of the
          solvers (default 0)

        * ths_rel Included for compatibility. Not used. (default 1)

        * ths_abs Included for compatibility. Not used. (default 1)

        * exact_d Included for compatibility. Not used. (default 0)

        * supernd Included for compatibility. Not used. (default 3)

        * rreduce Included for compatibility. Not used. (default 3)

        * wh_frac Included for compatibility. Not used. (default 0.5)

        * autommd Flag whether the LU/QR and the '\' and '/' operators
          will automatically use the sparsity preserving mmd functions
          (default 1)

        * autoamd Flag whether the LU and the '\' and '/' operators
          will automatically use the sparsity preserving amd functions
          (default 1)

        * piv_tol The pivot tolerance of the UMFPACK solvers (default
          0.1)

        * bandden ?? (default 0.5)

        * umfpack Flag whether the UMFPACK or mmd solvers are used for
          the LU, '\' and '/' operations (default 1)

     The value of individual keys can be set with `spparms (KEY, VAL)'.
     The default values can be restored with the special keyword
     'defaults'. The special keyword 'tight' can be used to set the mmd
     solvers to attempt for a sparser solution at the potential cost of
     longer running time.

 -- Loadable Function: R = spqr (A)
 -- Loadable Function: R = spqr (A,0)
 -- Loadable Function: [C, R] = spqr (A,B)
 -- Loadable Function: [C, R] = spqr (A,B,0)
     Compute the sparse QR factorization of A, using CSPARSE.  As the
     matrix Q is in general a full matrix, this function returns the
     Q-less factorization R of A, such that `R = chol (A' * A)'.

     If the final argument is the scalar `0' and the number of rows is
     larger than the number of columns, then an economy factorization is
     returned. That is R will have only `size (A,1)' rows.

     If an additional matrix B is supplied, then `spqr' returns C,
     where `C = Q' * B'. This allows the least squares approximation of
     `A \ B' to be calculated as

          [C,R] = spqr (A,B)
          X = R \ C


     *See also:* spchol, qr.

 -- Loadable Function: P = sprank (S)
     Calculates the structural rank of a sparse matrix S. Note that
     only the structure of the matrix is used in this calculation based
     on a Dulmage-Mendelsohn to block triangular form. As such the
     numerical rank of the matrix S is bounded by `sprank (S) >= rank
     (S)'. Ignoring floating point errors `sprank (S) == rank (S)'.

     *See also:* dmperm.

 -- Loadable Function: [COUNT, H, PARENT, POST, R] = symbfact (S, TYP,
          MODE)
     Performs a symbolic factorization analysis on the sparse matrix S.
     Where

    S
          S is a complex or real sparse matrix.

    TYP
          Is the type of the factorization and can be one of

         `sym'
               Factorize S. This is the default.

         `col'
               Factorize `S' * S'.

         `row'
               Factorize `S * S''.

         `lo'
               Factorize `S''

    MODE
          The default is to return the Cholesky factorization for R,
          and if MODE is 'L', the conjugate transpose of the Cholesky
          factorization is returned. The conjugate transpose version is
          faster and uses less memory, but returns the same values for
          COUNT, H, PARENT and POST outputs.

     The output variables are

    COUNT
          The row counts of the Cholesky factorization as determined by
          TYP.

    H
          The height of the elimination tree.

    PARENT
          The elimination tree itself.

    POST
          A sparse boolean matrix whose structure is that of the
          Cholesky factorization as determined by TYP.

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

   (1) The CHOLMOD, UMFPACK and CXSPARSE packages were written by Tim
Davis and are available at http://www.cise.ufl.edu/research/sparse/


File: octave.info,  Node: Iterative Techniques,  Next: Real Life Example,  Prev: Sparse Linear Algebra,  Up: Sparse Matrices

20.3 Iterative Techniques applied to sparse matrices
====================================================

The left division `\' and right division `/' operators, discussed in
the previous section, use direct solvers to resolve a linear equation
of the form `X = A \ B' or `X = B / A'. Octave equally includes a
number of functions to solve sparse linear equations using iterative
techniques.

 -- Function File: X = pcg (A, B, TOL, MAXIT, M1, M2, X0, ...)
 -- Function File: [X, FLAG, RELRES, ITER, RESVEC, EIGEST] = pcg (...)
     Solves the linear system of equations `A * X = B' by means of the
     Preconditioned Conjugate Gradient iterative method. The input
     arguments are

        * A can be either a square (preferably sparse) matrix or a
          function handle, inline function or string containing the name
          of a function which computes `A * X'. In principle A should
          be symmetric and positive definite; if `pcg' finds A to not
          be positive definite, you will get a warning message and the
          FLAG output parameter will be set.

        * B is the right hand side vector.

        * TOL is the required relative tolerance for the residual error,
          `B - A * X'. The iteration stops if `norm (B - A * X) <= TOL
          * norm (B - A * X0)'. If TOL is empty or is omitted, the
          function sets `TOL = 1e-6' by default.

        * MAXIT is the maximum allowable number of iterations; if `[]'
          is supplied for `maxit', or `pcg' has less arguments, a
          default value equal to 20 is used.

        * M = M1 * M2 is the (left) preconditioning matrix, so that the
          iteration is (theoretically) equivalent to solving by `pcg'
          `P * X = M \ B', with `P = M \ A'.  Note that a proper choice
          of the preconditioner may dramatically improve the overall
          performance of the method. Instead of matrices M1 and M2, the
          user may pass two functions which return the results of
          applying the inverse of M1 and M2 to a vector (usually this
          is the preferred way of using the preconditioner).  If `[]'
          is supplied for M1, or M1 is omitted, no preconditioning is
          applied. If M2 is omitted, M = M1 will be used as
          preconditioner.

        * X0 is the initial guess. If X0 is empty or omitted, the
          function sets X0 to a zero vector by default.

     The arguments which follow X0 are treated as parameters, and
     passed in a proper way to any of the functions (A or M) which are
     passed to `pcg'. See the examples below for further details. The
     output arguments are

        * X is the computed approximation to the solution of `A * X =
          B'.

        * FLAG reports on the convergence. `FLAG = 0' means the
          solution converged and the tolerance criterion given by TOL
          is satisfied. `FLAG = 1' means that the MAXIT limit for the
          iteration count was reached. `FLAG = 3' reports that the
          (preconditioned) matrix was found not positive definite.

        * RELRES is the ratio of the final residual to its initial
          value, measured in the Euclidean norm.

        * ITER is the actual number of iterations performed.

        * RESVEC describes the convergence history of the method.
          `RESVEC (i,1)' is the Euclidean norm of the residual, and
          `RESVEC (i,2)' is the preconditioned residual norm, after the
          (I-1)-th iteration, `I = 1, 2, ..., ITER+1'. The
          preconditioned residual norm is defined as `norm (R) ^ 2 = R'
          * (M \ R)' where `R = B - A * X', see also the description of
          M. If EIGEST is not required, only `RESVEC (:,1)' is returned.

        * EIGEST returns the estimate for the smallest `EIGEST (1)' and
          largest `EIGEST (2)' eigenvalues of the preconditioned matrix
          `P = M \ A'. In particular, if no preconditioning is used,
          the estimates for the extreme eigenvalues of A are returned.
          `EIGEST (1)' is an overestimate and `EIGEST (2)' is an
          underestimate, so that `EIGEST (2) / EIGEST (1)' is a lower
          bound for `cond (P, 2)', which nevertheless in the limit
          should theoretically be equal to the actual value of the
          condition number.  The method which computes EIGEST works
          only for symmetric positive definite A and M, and the user is
          responsible for verifying this assumption.

     Let us consider a trivial problem with a diagonal matrix (we
     exploit the sparsity of A)

          	N = 10;
          	A = spdiag ([1:N]);
          	b = rand (N, 1);
               [L, U, P, Q] = luinc (A,1.e-3);

     EXAMPLE 1: Simplest use of `pcg'

            x = pcg(A,b)

     EXAMPLE 2: `pcg' with a function which computes `A * X'

            function y = applyA (x)
              y = [1:N]'.*x;
            endfunction

            x = pcg ("applyA", b)

     EXAMPLE 3: `pcg' with a preconditioner: L * U

          x=pcg(A,b,1.e-6,500,L*U);

     EXAMPLE 4: `pcg' with a preconditioner: L * U.  Faster than
     EXAMPLE 3 since lower and upper triangular matrices are easier to
     invert

          x=pcg(A,b,1.e-6,500,L,U);

     EXAMPLE 5: Preconditioned iteration, with full diagnostics. The
     preconditioner (quite strange, because even the original matrix A
     is trivial) is defined as a function

            function y = applyM(x)
              K = floor (length (x) - 2);
              y = x;
              y(1:K) = x(1:K)./[1:K]';
            endfunction

            [x, flag, relres, iter, resvec, eigest] = ...
                               pcg (A, b, [], [], "applyM");
            semilogy (1:iter+1, resvec);

     EXAMPLE 6: Finally, a preconditioner which depends on a parameter
     K.

            function y = applyM (x, varargin)
            K = varargin{1};
            y = x;
            y(1:K) = x(1:K)./[1:K]';
            endfunction

            [x, flag, relres, iter, resvec, eigest] = ...
                 pcg (A, b, [], [], "applyM", [], [], 3)

     REFERENCES

     	[1] C.T.Kelley, 'Iterative methods for linear and nonlinear
     equations', 	SIAM, 1995 (the base PCG algorithm)

     	[2] Y.Saad, 'Iterative methods for sparse linear systems', PWS 1996
     (condition number estimate from PCG) Revised version of this book
     is 	available online at
     http://www-users.cs.umn.edu/~saad/books.html


     *See also:* sparse, pcr.

 -- Function File: X = pcr (A, B, TOL, MAXIT, M, X0, ...)
 -- Function File: [X, FLAG, RELRES, ITER, RESVEC] = pcr (...)
     Solves the linear system of equations `A * X = B' by means of the
     Preconditioned Conjugate Residuals iterative method. The input
     arguments are

        * A can be either a square (preferably sparse) matrix or a
          function handle, inline function or string containing the name
          of a function which computes `A * X'. In principle A should
          be symmetric and non-singular; if `pcr' finds A to be
          numerically singular, you will get a warning message and the
          FLAG output parameter will be set.

        * B is the right hand side vector.

        * TOL is the required relative tolerance for the residual error,
          `B - A * X'. The iteration stops if `norm (B - A * X) <= TOL
          * norm (B - A * X0)'. If TOL is empty or is omitted, the
          function sets `TOL = 1e-6' by default.

        * MAXIT is the maximum allowable number of iterations; if `[]'
          is supplied for `maxit', or `pcr' has less arguments, a
          default value equal to 20 is used.

        * M is the (left) preconditioning matrix, so that the iteration
          is (theoretically) equivalent to solving by `pcr' `P * X = M
          \ B', with `P = M \ A'.  Note that a proper choice of the
          preconditioner may dramatically improve the overall
          performance of the method. Instead of matrix M, the user may
          pass a function which returns the results of applying the
          inverse of M to a vector (usually this is the preferred way
          of using the preconditioner). If `[]' is supplied for M, or M
          is omitted, no preconditioning is applied.

        * X0 is the initial guess. If X0 is empty or omitted, the
          function sets X0 to a zero vector by default.

     The arguments which follow X0 are treated as parameters, and
     passed in a proper way to any of the functions (A or M) which are
     passed to `pcr'. See the examples below for further details. The
     output arguments are

        * X is the computed approximation to the solution of `A * X =
          B'.

        * FLAG reports on the convergence. `FLAG = 0' means the
          solution converged and the tolerance criterion given by TOL
          is satisfied. `FLAG = 1' means that the MAXIT limit for the
          iteration count was reached. `FLAG = 3' reports t `pcr'
          breakdown, see [1] for details.

        * RELRES is the ratio of the final residual to its initial
          value, measured in the Euclidean norm.

        * ITER is the actual number of iterations performed.

        * RESVEC describes the convergence history of the method, so
          that `RESVEC (i)' contains the Euclidean norms of the
          residual after the (I-1)-th iteration, `I = 1,2, ..., ITER+1'.

     Let us consider a trivial problem with a diagonal matrix (we
     exploit the sparsity of A)

          	N = 10;
          	A = diag([1:N]); A = sparse(A);
          	b = rand(N,1);

     EXAMPLE 1: Simplest use of `pcr'

            x = pcr(A, b)

     EXAMPLE 2: `pcr' with a function which computes `A * X'.

            function y = applyA(x)
              y = [1:10]'.*x;
            endfunction

            x = pcr('applyA',b)

     EXAMPLE 3:  Preconditioned iteration, with full diagnostics. The
     preconditioner (quite strange, because even the original matrix A
     is trivial) is defined as a function

            function y = applyM(x)
              K = floor(length(x)-2);
              y = x;
              y(1:K) = x(1:K)./[1:K]';
            endfunction

            [x, flag, relres, iter, resvec] = ...
                               pcr(A, b, [], [], 'applyM')
            semilogy([1:iter+1], resvec);

     EXAMPLE 4: Finally, a preconditioner which depends on a parameter
     K.

            function y = applyM(x, varargin)
              K = varargin{1};
              y = x; y(1:K) = x(1:K)./[1:K]';
            endfunction

            [x, flag, relres, iter, resvec] = ...
                               pcr(A, b, [], [], 'applyM', [], 3)

     REFERENCES

     	[1] W. Hackbusch, "Iterative Solution of Large Sparse Systems of
     Equations", section 9.5.4; Springer, 1994


     *See also:* sparse, pcg.

   The speed with which an iterative solver converges to a solution can
be accelerated with the use of a pre-conditioning matrix M. In this
case the linear equation `M^-1 * X = M^-1 * A \ B' is solved instead.
Typical pre-conditioning matrices are partial factorizations of the
original matrix.

 -- Loadable Function: [L, U, P, Q] = luinc (A, '0')
 -- Loadable Function: [L, U, P, Q] = luinc (A, DROPTOL)
 -- Loadable Function: [L, U, P, Q] = luinc (A, OPTS)
     Produce the incomplete LU factorization of the sparse matrix A.
     Two types of incomplete factorization are possible, and the type
     is determined by the second argument to "luinc".

     Called with a second argument of '0', the zero-level incomplete LU
     factorization is produced. This creates a factorization of A where
     the position of the non-zero arguments correspond to the same
     positions as in the matrix A.

     Alternatively, the fill-in of the incomplete LU factorization can
     be controlled through the variable DROPTOL or the structure OPTS.
     The UMFPACK multifrontal factorization code by Tim A.  Davis is
     used for the incomplete LU factorization, (availability
     `http://www.cise.ufl.edu/research/sparse/umfpack/')

     DROPTOL determines the values below which the values in the LU
     factorization are dropped and replaced by zero. It must be a
     positive scalar, and any values in the factorization whose
     absolute value are less than this value are dropped, expect if
     leaving them increase the sparsity of the matrix. Setting DROPTOL
     to zero results in a complete LU factorization which is the
     default.

     OPTS is a structure containing one or more of the fields

    `droptol'
          The drop tolerance as above. If OPTS only contains `droptol'
          then this is equivalent to using the variable DROPTOL.

    `milu'
          A logical variable flagging whether to use the modified
          incomplete LU factorization. In the case that `milu' is true,
          the dropped values are subtracted from the diagonal of the
          matrix U of the factorization.  The default is `false'.

    `udiag'
          A logical variable that flags whether zero elements on the
          diagonal of U should be replaced with DROPTOL to attempt to
          avoid singular factors. The default is `false'.

    `thresh'
          Defines the pivot threshold in the interval [0,1]. Values
          outside that range are ignored.

     All other fields in OPTS are ignored. The outputs from "luinc" are
     the same as for "lu".

     *See also:* sparse, lu, cholinc.


File: octave.info,  Node: Real Life Example,  Prev: Iterative Techniques,  Up: Sparse Matrices

20.4 Real Life Example of the use of Sparse Matrices
====================================================

A common application for sparse matrices is in the solution of Finite
Element Models. Finite element models allow numerical solution of
partial differential equations that do not have closed form solutions,
typically because of the complex shape of the domain.

   In order to motivate this application, we consider the boundary value
Laplace equation. This system can model scalar potential fields, such
as heat or electrical potential. Given a medium Omega with boundary
dOmega . At all points on the dOmega the boundary conditions are known,
and we wish to calculate the potential in Omega . Boundary conditions
may specify the potential (Dirichlet boundary condition), its normal
derivative across the boundary (Neumann boundary condition), or a
weighted sum of the potential and its derivative (Cauchy boundary
condition).

   In a thermal model, we want to calculate the temperature in Omega
and know the boundary temperature (Dirichlet condition) or heat flux
(from which we can calculate the Neumann condition by dividing by the
thermal conductivity  at the boundary). Similarly, in an electrical
model, we want to calculate the voltage in Omega and know the boundary
voltage (Dirichlet) or current (Neumann condition after diving by the
electrical conductivity).  In an electrical model, it is common for
much of the boundary to be electrically isolated; this is a Neumann
boundary condition with the current equal to zero.

   The simplest finite element models will divide Omega into simplexes
(triangles in 2D, pyramids in 3D).

   The following example creates a simple rectangular 2D electrically
conductive medium with 10 V and 20 V imposed on opposite sides
(Dirichlet boundary conditions). All other edges are electrically
isolated.

        node_y= [1;1.2;1.5;1.8;2]*ones(1,11);
        node_x= ones(5,1)*[1,1.05,1.1,1.2, ...
                  1.3,1.5,1.7,1.8,1.9,1.95,2];
        nodes= [node_x(:), node_y(:)];

        [h,w]= size(node_x);
        elems= [];
        for idx= 1:w-1
          widx= (idx-1)*h;
          elems= [elems; ...
            widx+[(1:h-1);(2:h);h+(1:h-1)]'; ...
            widx+[(2:h);h+(2:h);h+(1:h-1)]' ];
        endfor

        E= size(elems,1); # No. of simplices
        N= size(nodes,1); # No. of vertices
        D= size(elems,2); # dimensions+1

   This creates a N-by-2 matrix `nodes' and a E-by-3 matrix `elems'
with values, which define finite element triangles:

       nodes(1:7,:)'
         1.00 1.00 1.00 1.00 1.00 1.05 1.05 ...
         1.00 1.20 1.50 1.80 2.00 1.00 1.20 ...

       elems(1:7,:)'
         1    2    3    4    2    3    4 ...
         2    3    4    5    7    8    9 ...
         6    7    8    9    6    7    8 ...

   Using a first order FEM, we approximate the electrical conductivity
distribution in Omega as constant on each simplex (represented by the
vector `conductivity').  Based on the finite element geometry, we first
calculate a system (or stiffness) matrix for each simplex (represented
as 3-by-3 elements on the diagonal of the element-wise system matrix
`SE'. Based on `SE' and a N-by-DE connectivity matrix `C', representing
the connections between simplices and vertices, the global connectivity
matrix `S' is calculated.

       # Element conductivity
       conductivity= [1*ones(1,16), ...
              2*ones(1,48), 1*ones(1,16)];

       # Connectivity matrix
       C = sparse ((1:D*E), reshape (elems', ...
              D*E, 1), 1, D*E, N);

       # Calculate system matrix
       Siidx = floor ([0:D*E-1]'/D) * D * ...
              ones(1,D) + ones(D*E,1)*(1:D) ;
       Sjidx = [1:D*E]'*ones(1,D);
       Sdata = zeros(D*E,D);
       dfact = factorial(D-1);
       for j=1:E
          a = inv([ones(D,1), ...
              nodes(elems(j,:), :)]);
          const = conductivity(j) * 2 / ...
              dfact / abs(det(a));
          Sdata(D*(j-1)+(1:D),:) = const * ...
              a(2:D,:)' * a(2:D,:);
       endfor
       # Element-wise system matrix
       SE= sparse(Siidx,Sjidx,Sdata);
       # Global system matrix
       S= C'* SE *C;

   The system matrix acts like the conductivity `S' in Ohm's law `S * V
= I'.  Based on the Dirichlet and Neumann boundary conditions, we are
able to solve for the voltages at each vertex `V'.

       # Dirichlet boundary conditions
       D_nodes=[1:5, 51:55];
       D_value=[10*ones(1,5), 20*ones(1,5)];

       V= zeros(N,1);
       V(D_nodes) = D_value;
       idx = 1:N; # vertices without Dirichlet
                  # boundary condns
       idx(D_nodes) = [];

       # Neumann boundary conditions. Note that
       # N_value must be normalized by the
       # boundary length and element conductivity
       N_nodes=[];
       N_value=[];

       Q = zeros(N,1);
       Q(N_nodes) = N_value;

       V(idx) = S(idx,idx) \ ( Q(idx) - ...
                 S(idx,D_nodes) * V(D_nodes));

   Finally, in order to display the solution, we show each solved
voltage value in the z-axis for each simplex vertex.

       elemx = elems(:,[1,2,3,1])';
       xelems = reshape (nodes(elemx, 1), 4, E);
       yelems = reshape (nodes(elemx, 2), 4, E);
       velems = reshape (V(elemx), 4, E);
       plot3 (xelems,yelems,velems,'k');
       print ('grid.eps');


File: octave.info,  Node: Numerical Integration,  Next: Differential Equations,  Prev: Sparse Matrices,  Up: Top

21 Numerical Integration
************************

Octave comes with several built-in functions for computing the integral
of a function numerically.  These functions all solve 1-dimensional
integration problems.

* Menu:

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


File: octave.info,  Node: Functions of One Variable,  Next: Functions of Multiple Variables,  Up: Numerical Integration

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

Octave supports three different algorithms for computing the integral
of a function f over the interval from a to b.  These are

`quad'
     Numerical integration based on Gaussian quadrature.

`quadl'
     Numerical integration using an adaptive Lobatto rule.

`trapz'
     Numerical integration using the trapezoidal method.

Besides these functions Octave also allows you to perform cumulative
numerical integration using the trapezoidal method through the
`cumtrapz' function.

 -- 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, the function
     handle or the inline 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.

     You can use the function `quad_options' to set optional parameters
     for `quad'.

     It should be noted that since `quad' is written in Fortran it
     cannot be called recursively.

 -- 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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance; may be zero for pure relative error test.

    `"relative tolerance"'
          Nonnegative relative tolerance.  If the absolute tolerance is
          zero, the relative tolerance must be greater than or equal to
          `max (50*eps, 0.5e-28)'.

   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.).

 -- Function File: Q = quadl (F, A, B)
 -- Function File: Q = quadl (F, A, B, TOL)
 -- Function File: Q = quadl (F, A, B, TOL, TRACE)
 -- Function File: Q = quadl (F, A, B, TOL, TRACE, P1, P2, ...)
     Numerically evaluate integral using adaptive Lobatto rule.  `quadl
     (F, A, B)' approximates the integral of `F(X)' to machine
     precision. F is either a function handle, inline function or
     string containing the name of the function to evaluate. The
     function F must return a vector of output values if given a vector
     of input values.

     If defined, TOL defines the relative tolerance to which to which
     to integrate `F(X)'. While if TRACE is defined, displays the left
     end point of the current interval, the interval length, and the
     partial integral.

     Additional arguments P1, etc, are passed directly to F.  To use
     default values for TOL and TRACE, one may pass empty matrices.

     Reference: W. Gander and W. Gautschi, 'Adaptive Quadrature -
     Revisited', BIT Vol. 40, No. 1, March 2000, pp. 84-101.
     `http://www.inf.ethz.ch/personal/gander/'


 -- Function File: Z = trapz (Y)
 -- Function File: Z = trapz (X, Y)
 -- Function File: Z = trapz (..., DIM)
     Numerical integration using trapezoidal method. `trapz (Y)'
     computes the integral of the Y along the first non singleton
     dimension. If the argument X is omitted a equally spaced vector is
     assumed. `trapz (X, Y)' evaluates the integral with respect to X.


     *See also:* cumtrapz.

 -- Function File: Z = cumtrapz (Y)
 -- Function File: Z = cumtrapz (X, Y)
 -- Function File: Z = cumtrapz (..., DIM)
     Cumulative numerical integration using trapezoidal method.
     `cumtrapz (Y)' computes the cumulative integral of the Y along the
     first non singleton dimension. If the argument X is omitted a
     equally spaced vector is assumed. `cumtrapz (X, Y)' evaluates the
     cumulative integral with respect to X.


     *See also:* trapz,cumsum.


File: octave.info,  Node: Orthogonal Collocation,  Prev: Functions of Multiple Variables,  Up: Numerical Integration

21.2 Orthogonal Collocation
===========================

 -- Loadable Function: [R, AMAT, BMAT, 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.info,  Node: Functions of Multiple Variables,  Next: Orthogonal Collocation,  Prev: Functions of One Variable,  Up: Numerical Integration

21.3 Functions of Multiple Variables
====================================

Octave does not have built-in functions for computing the integral of
functions of multiple variables.  It is however possible to compute the
integral of a function of multiple variables using the functions for
one-dimensional integrals.

   To illustrate how the integration can be performed, we will integrate
the function
     f(x, y) = sin(pi*x*y)*sqrt(x*y)
   for x and y between 0 and 1.

   The first approach creates a function that integrates f with respect
to x, and then integrates that function with respect to y.  Since
`quad' is written in Fortran it cannot be called recursively.  This
means that `quad' cannot integrate a function that calls `quad', and
hence cannot be used to perform the double integration.  It is however
possible with `quadl', which is what the following code does.

     function I = g(y)
       I = ones(1, length(y));
       for i = 1:length(y)
         f = @(x) sin(pi.*x.*y(i)).*sqrt(x.*y(i));
         I(i) = quadl(f, 0, 1);
       endfor
     endfunction

     I = quadl("g", 0, 1)
           => 0.30022

   The above mentioned approach works but is fairly slow, and that
problem increases exponentially with the dimensionality the problem.
Another possible solution is to use Orthogonal Collocation as described
in the previous section.  The integral of a function f(x,y) for x and y
between 0 and 1 can be approximated using n points by the sum over
`i=1:n' and `j=1:n' of `q(i)*q(j)*f(r(i),r(j))', where q and r is as
returned by `colloc(n)'.  The generalisation to more than two variables
is straight forward.  The following code computes the studied integral
using n=7 points.

     f = @(x,y) sin(pi*x*y').*sqrt(x*y');
     n = 7;
     [t, A, B, q] = colloc(n);
     I = q'*f(t,t)*q;
           => 0.30022

It should be noted that the number of points determines the quality of
the approximation.  If the integration needs to be performed between a
and b instead of 0 and 1, a change of variables is needed.


File: octave.info,  Node: Differential Equations,  Next: Optimization,  Prev: Numerical Integration,  Up: Top

22 Differential Equations
*************************

Octave has built-in functions for solving ordinary differential
equations, and differential-algebraic equations.  All solvers are based
on reliable ODE solvers written in Fortran.

* Menu:

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


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

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

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

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

 -- Loadable Function: [X, ISTATE, MSG] = lsode (FCN, X_0, T, T_CRIT)
     Solve the set of differential equations

          dx
          -- = f(x, t)
          dt

     with

          x(t_0) = x_0

     The solution is returned in the matrix X, with each row
     corresponding to an element of the vector T.  The first element of
     T should be t_0 and should correspond to the initial state of the
     system X_0, so that the first row of the output is X_0.

     The first argument, FCN, is a string, or cell array of strings,
     inline or function handles, that names the function to call to
     compute the vector of right hand sides for the set of equations.
     The function must have the form

          XDOT = f (X, T)

     in which XDOT and X are vectors and T is a scalar.

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a function
     to compute the Jacobian of f.  The Jacobian function must have the
     form

          JAC = j (X, T)

     in which JAC is the matrix of partial derivatives

                       | df_1  df_1       df_1 |
                       | ----  ----  ...  ---- |
                       | dx_1  dx_2       dx_N |
                       |                       |
                       | df_2  df_2       df_2 |
                       | ----  ----  ...  ---- |
                df_i   | dx_1  dx_2       dx_N |
          jac = ---- = |                       |
                dx_j   |  .    .     .    .    |
                       |  .    .      .   .    |
                       |  .    .       .  .    |
                       |                       |
                       | df_N  df_N       df_N |
                       | ----  ----  ...  ---- |
                       | dx_1  dx_2       dx_N |

     The second and third arguments specify the initial state of the
     system, x_0, and the initial value of the independent variable t_0.

     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.

     After a successful computation, the value of ISTATE will be 2
     (consistent with the Fortran version of LSODE).

     If the computation is not successful, ISTATE will be something
     other than 2 and MSG will contain additional information.

     You can use the function `lsode_options' to set optional
     parameters for `lsode'.

     *See also:* daspk, dassl, dasrt.

 -- 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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector.

    `"relative tolerance"'
          Relative tolerance parameter.  Unlike the absolute tolerance,
          this parameter may only be a scalar.

          The local error test applied at each integration step is

                 abs (local error in x(i)) <= ...
                     rtol * abs (y(i)) + atol(i)

    `"integration method"'
          A string specifying the method of integration to use to solve
          the ODE system.  Valid values are

         "adams"
         "non-stiff"
               No Jacobian used (even if it is available).

         "bdf"

         "stiff"
               Use stiff backward differentiation formula (BDF) method.
               If a function to compute the Jacobian is not supplied,
               `lsode' will compute a finite difference approximation
               of the Jacobian matrix.

    `"initial step size"'
          The step size to be attempted on the first step (default is
          determined automatically).

    `"maximum order"'
          Restrict the maximum order of the solution method.  If using
          the Adams method, this option must be between 1 and 12.
          Otherwise, it must be between 1 and 5, inclusive.

    `"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions  (default is not specified).

    `"minimum step size"'
          The minimum absolute step size allowed (default is 0).

    `"step limit"'
          Maximum number of steps allowed (default is 100000).

   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)];

   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'.


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

22.2 Differential-Algebraic Equations
=====================================

The function `daspk' can be used to solve DAEs of the form

     0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0

where x-dot is the derivative of x. The equation is solved using
Petzold's DAE solver DASPK.

 -- Loadable Function: [X, XDOT, ISTATE, MSG] = daspk (FCN, X_0,
          XDOT_0, T, T_CRIT)
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T.  The first element of T should be t_0 and correspond to
     the initial state of the system X_0 and its derivative XDOT_0, so
     that the first row of the output X is X_0 and the first row of the
     output XDOT is XDOT_0.

     The first argument, FCN, is a string or a two element cell array
     of strings, inline or function handle, that names the function, to
     call to compute the vector of residuals for the set of equations.
     It must have the form

          RES = f (X, XDOT, T)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a
     function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)

     The second and third arguments to `daspk' specify the initial
     condition of the states and their derivatives, and the fourth
     argument specifies a vector of output times at which the solution
     is desired, including the time corresponding to the initial
     condition.

     The set of initial states and derivatives are not strictly
     required to be consistent.  If they are not consistent, you must
     use the `daspk_options' function to provide additional information
     so that `daspk' can compute a consistent starting point.

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

     After a successful computation, the value of ISTATE will be
     greater than zero (consistent with the Fortran version of DASPK).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function `daspk_options' to set optional
     parameters for `daspk'.

     *See also:* dassl.

 -- Loadable Function:  daspk_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `daspk'.  Given one argument,
     `daspk_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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

    `"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is

                 abs (local error in x(i))
                      <= rtol(i) * abs (Y(i)) + atol(i)

    `"compute consistent initial condition"'
          Denoting the differential variables in the state vector by
          `Y_d' and the algebraic variables by `Y_a', `ddaspk' can solve
          one of two initialization problems:

            1. Given Y_d, calculate Y_a and Y'_d

            2. Given Y', calculate Y.

          In either case, initial values for the given components are
          input, and initial guesses for the unknown components must
          also be provided as input.  Set this option to 1 to solve the
          first problem, or 2 to solve the second (the default default
          is 0, so you must provide a set of initial conditions that
          are consistent).

          If this option is set to a nonzero value, you must also set
          the `"algebraic variables"' option to declare which variables
          in the problem are algebraic.

    `"use initial condition heuristics"'
          Set to a nonzero value to use the initial condition
          heuristics options described below.

    `"initial condition heuristics"'
          A vector of the following parameters that can be used to
          control the initial condition calculation.

         `MXNIT'
               Maximum number of Newton iterations (default is 5).

         `MXNJ'
               Maximum number of Jacobian evaluations (default is 6).

         `MXNH'
               Maximum number of values of the artificial stepsize
               parameter to be tried if the `"compute consistent
               initial condition"' option has been set to 1 (default is
               5).

               Note that the maximum total number of Newton iterations
               allowed is `MXNIT*MXNJ*MXNH' if the `"compute consistent
               initial condition"' option has been set to 1 and
               `MXNIT*MXNJ' if it is set to 2.

         `LSOFF'
               Set to a nonzero value to disable the linesearch
               algorithm (default is 0).

         `STPTOL'
               Minimum scaled step in linesearch algorithm (default is
               eps^(2/3)).

         `EPINIT'
               Swing factor in the Newton iteration convergence test.
               The test is applied to the residual vector,
               premultiplied by the approximate Jacobian.  For
               convergence, the weighted RMS norm of this vector
               (scaled by the error weights) must be less than
               `EPINIT*EPCON', where `EPCON' = 0.33 is the analogous
               test constant used in the time steps. The default is
               `EPINIT' = 0.01.

    `"print initial condition info"'
          Set this option to a nonzero value to display detailed
          information about the initial condition calculation (default
          is 0).

    `"exclude algebraic variables from error test"'
          Set to a nonzero value to exclude algebraic variables from
          the error test.  You must also set the `"algebraic
          variables"' option to declare which variables in the problem
          are algebraic (default is 0).

    `"algebraic variables"'
          A vector of the same length as the state vector.  A nonzero
          element indicates that the corresponding element of the state
          vector is an algebraic variable (i.e., its derivative does
          not appear explicitly in the equation set.

          This option is required by the `compute consistent initial
          condition"' and `"exclude algebraic variables from error
          test"' options.

    `"enforce inequality constraints"'
          Set to one of the following values to enforce the inequality
          constraints specified by the `"inequality constraint types"'
          option (default is 0).

            1. To have constraint checking only in the initial
               condition calculation.

            2. To enforce constraint checking during the integration.

            3. To enforce both options 1 and 2.

    `"inequality constraint types"'
          A vector of the same length as the state specifying the type
          of inequality constraint.  Each element of the vector
          corresponds to an element of the state and should be assigned
          one of the following codes

         -2
               Less than zero.

         -1
               Less than or equal to zero.

         0
               Not constrained.

         1
               Greater than or equal to zero.

         2
               Greater than zero.

          This option only has an effect if the `"enforce inequality
          constraints"' option is nonzero.

    `"initial step size"'
          Differential-algebraic problems may occasionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize
          (default is computed automatically).

    `"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive (default is 5).

    `"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions (default is not specified).

   Octave also includes DASSL, an earlier version of DASPK, and DASRT,
which can be used to solve DAEs with constraints (stopping conditions).

 -- Loadable Function: [X, XDOT, T_OUT, ISTAT, MSG] = dasrt (FCN [, G],
          X_0, XDOT_0, T [, T_CRIT])
     Solve the set of differential-algebraic equations

          0 = f (x, xdot, t)

     with

          x(t_0) = x_0, xdot(t_0) = xdot_0

     with functional stopping criteria (root solving).

     The solution is returned in the matrices X and XDOT, with each row
     in the result matrices corresponding to one of the elements in the
     vector T_OUT.  The first element of T should be t_0 and correspond
     to the initial state of the system X_0 and its derivative XDOT_0,
     so that the first row of the output X is X_0 and the first row of
     the output XDOT is XDOT_0.

     The vector T provides an upper limit on the length of the
     integration.  If the stopping condition is met, the vector T_OUT
     will be shorter than T, and the final element of T_OUT will be the
     point at which the stopping condition was met, and may not
     correspond to any element of the vector T.

     The first argument, FCN, is a string, or cell array of strings or
     inline or function handles, that names the function to call to
     compute the vector of residuals for the set of equations. It must
     have the form

          RES = f (X, XDOT, T)

     in which X, XDOT, and RES are vectors, and T is a scalar.

     If FCN is a two-element string array, or two element cell array,
     the first element names the function f described above, and the
     second element names a function to compute the modified Jacobian

                df       df
          jac = -- + c ------
                dx     d xdot

     The modified Jacobian function must have the form


          JAC = j (X, XDOT, T, C)

     The optional second argument names a function that defines the
     constraint functions whose roots are desired during the
     integration.  This function must have the form

          G_OUT = g (X, T)

     and return a vector of the constraint function values.  If the
     value of any of the constraint functions changes sign, DASRT will
     attempt to stop the integration at the point of the sign change.

     If the name of the constraint function is omitted, `dasrt' solves
     the same problem as `daspk' or `dassl'.

     Note that because of numerical errors in the constraint functions
     due to roundoff and integration error, DASRT may return false
     roots, or return the same root at two or more nearly equal values
     of T.  If such false roots are suspected, the user should consider
     smaller error tolerances or higher precision in the evaluation of
     the constraint functions.

     If a root of some constraint function defines the end of the
     problem, the input to DASRT should nevertheless allow integration
     to a point slightly past that root, so that DASRT can locate the
     root by interpolation.

     The third and fourth arguments to `dasrt' specify the initial
     condition of the states and their derivatives, and the fourth
     argument specifies a vector of output times at which the solution
     is desired, including the time corresponding to the initial
     condition.

     The set of initial states and derivatives are not strictly
     required to be consistent.  In practice, however, DASSL is not
     very good at determining a consistent set for you, so it is best
     if you ensure that the initial values result in the function
     evaluating to zero.

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

     After a successful computation, the value of ISTATE will be
     greater than zero (consistent with the Fortran version of DASSL).

     If the computation is not successful, the value of ISTATE will be
     less than zero and MSG will contain additional information.

     You can use the function `dasrt_options' to set optional
     parameters for `dasrt'.

     *See also:* daspk, dasrt, lsode.

 -- Loadable Function:  dasrt_options (OPT, VAL)
     When called with two arguments, this function allows you set
     options parameters for the function `dasrt'.  Given one argument,
     `dasrt_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.

     Options include

    `"absolute tolerance"'
          Absolute tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the relative tolerance must also be a vector of the same
          length.

    `"relative tolerance"'
          Relative tolerance.  May be either vector or scalar.  If a
          vector, it must match the dimension of the state vector, and
          the absolute tolerance must also be a vector of the same
          length.

          The local error test applied at each integration step is
                 abs (local error in x(i)) <= ...
                     rtol(i) * abs (Y(i)) + atol(i)

    `"initial step size"'
          Differential-algebraic problems may occasionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize.

    `"maximum order"'
          Restrict the maximum order of the solution method.  This
          option must be between 1 and 5, inclusive.

    `"maximum step size"'
          Setting the maximum stepsize will avoid passing over very
          large regions.

    `"step limit"'
          Maximum number of integration steps to attempt on a single
          call to the underlying Fortran code.

   See K. E. Brenan, et al., `Numerical Solution of Initial-Value
Problems in Differential-Algebraic Equations', North-Holland (1989) for
more information about the implementation of DASSL.


File: octave.info,  Node: Optimization,  Next: Statistics,  Prev: Differential Equations,  Up: Top

23 Optimization
***************

Octave comes with support for solving various kinds of optimization
problems. Specifically Octave can solve problems in Linear Programming,
Quadratic Programming, Nonlinear Programming, and Linear Least Squares
Minimization.

* Menu:

* Linear Programming::
* Quadratic Programming::
* Nonlinear Programming::
* Linear Least Squares::


File: octave.info,  Node: Linear Programming,  Next: Quadratic Programming,  Up: Optimization

23.1 Linear Programming
=======================

Octave can solve Linear Programming problems using the `glpk' function.
That is, Octave can solve

     min C'*x
   subject to the linear constraints A*x = b where x >= 0.

The `glpk' function also supports variations of this problem.

 -- Function File: [XOPT, FMIN, STATUS, EXTRA] = glpk (C, A, B, LB, UB,
          CTYPE, VARTYPE, SENSE, PARAM)
     Solve a linear program using the GNU GLPK library.  Given three
     arguments, `glpk' solves the following standard LP:

          min C'*x

     subject to

          A*x  = b
            x >= 0

     but may also solve problems of the form

          [ min | max ] C'*x

     subject to

          A*x [ "=" | "<=" | ">=" ] b
            x >= LB
            x <= UB

     Input arguments:

    C
          A column array containing the objective function coefficients.

    A
          A matrix containing the constraints coefficients.

    B
          A column array containing the right-hand side value for each
          constraint in the constraint matrix.

    LB
          An array containing the lower bound on each of the variables.
          If LB is not supplied, the default lower bound for the
          variables is zero.

    UB
          An array containing the upper bound on each of the variables.
          If UB is not supplied, the default upper bound is assumed to
          be infinite.

    CTYPE
          An array of characters containing the sense of each
          constraint in the constraint matrix.  Each element of the
          array may be one of the following values
         `"F"'
               A free (unbounded) constraint (the constraint is
               ignored).

         `"U"'
               An inequality constraint with an upper bound (`A(i,:)*x
               <= b(i)').

         `"S"'
               An equality constraint (`A(i,:)*x = b(i)').

         `"L"'
               An inequality with a lower bound (`A(i,:)*x >= b(i)').

         `"D"'
               An inequality constraint with both upper and lower bounds
               (`A(i,:)*x >= -b(i)' _and_ (`A(i,:)*x <= b(i)').

    VARTYPE
          A column array containing the types of the variables.
         `"C"'
               A continuous variable.

         `"I"'
               An integer variable.

    SENSE
          If SENSE is 1, the problem is a minimization.  If SENSE is
          -1, the problem is a maximization.  The default value is 1.

    PARAM
          A structure containing the following parameters used to
          define the behavior of solver.  Missing elements in the
          structure take on default values, so you only need to set the
          elements that you wish to change from the default.

          Integer parameters:

         `msglev (`LPX_K_MSGLEV', default: 1)'
               Level of messages output by solver routines:
              0
                    No output.

              1
                    Error messages only.

              2
                    Normal output .

              3
                    Full output (includes informational messages).

         `scale (`LPX_K_SCALE', default: 1)'
               Scaling option:
              0
                    No scaling.

              1
                    Equilibration scaling.

              2
                    Geometric mean scaling, then equilibration scaling.

         `dual	 (`LPX_K_DUAL', default: 0)'
               Dual simplex option:
              0
                    Do not use the dual simplex.

              1
                    If initial basic solution is dual feasible, use the
                    dual simplex.

         `price	 (`LPX_K_PRICE', default: 1)'
               Pricing option (for both primal and dual simplex):
              0
                    Textbook pricing.

              1
                    Steepest edge pricing.

         `round	 (`LPX_K_ROUND', default: 0)'
               Solution rounding option:
              0
                    Report all primal and dual values "as is".

              1
                    Replace tiny primal and dual values by exact zero.

         `itlim	 (`LPX_K_ITLIM', default: -1)'
               Simplex iterations limit.  If this value is positive, it
               is decreased by one each time when one simplex iteration
               has been performed, and reaching zero value signals the
               solver to stop the search.  Negative value means no
               iterations limit.

         `itcnt (`LPX_K_OUTFRQ', default: 200)'
               Output frequency, in iterations.  This parameter
               specifies how frequently the solver sends information
               about the solution to the standard output.

         `branch (`LPX_K_BRANCH', default: 2)'
               Branching heuristic option (for MIP only):
              0
                    Branch on the first variable.

              1
                    Branch on the last variable.

              2
                    Branch using a heuristic by Driebeck and Tomlin.

         `btrack (`LPX_K_BTRACK', default: 2)'
               Backtracking heuristic option (for MIP only):
              0
                    Depth first search.

              1
                    Breadth first search.

              2
                    Backtrack using the best projection heuristic.

         `presol (`LPX_K_PRESOL', default: 1)'
               If this flag is set, the routine lpx_simplex solves the
               problem using the built-in LP presolver.  Otherwise the
               LP presolver is not used.

         `lpsolver (default: 1)'
               Select which solver to use.  If the problem is a MIP
               problem this flag will be ignored.
              1
                    Revised simplex method.

              2
                    Interior point method.

         `save (default: 0)'
               If this parameter is nonzero, save a copy of the problem
               in CPLEX LP format to the file `"outpb.lp"'.  There is
               currently no way to change the name of the output file.

          Real parameters:

         `relax (`LPX_K_RELAX', default: 0.07)'
               Relaxation parameter used in the ratio test. If it is
               zero, the textbook ratio test is used. If it is non-zero
               (should be positive), Harris' two-pass ratio test is
               used. In the latter case on the first pass of the ratio
               test basic variables (in the case of primal simplex) or
               reduced costs of non-basic variables (in the case of
               dual simplex) are allowed to slightly violate their
               bounds, but not more than `relax*tolbnd' or `relax*toldj
               (thus, `relax' is a percentage of `tolbnd' or `toldj''.

         `tolbnd (`LPX_K_TOLBND', default: 10e-7)'
               Relative tolerance used to check if the current basic
               solution is primal feasible.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

         `toldj (`LPX_K_TOLDJ', default: 10e-7)'
               Absolute tolerance used to check if the current basic
               solution is dual feasible.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

         `tolpiv (`LPX_K_TOLPIV', default: 10e-9)'
               Relative tolerance used to choose eligible pivotal
               elements of the simplex table.  It is not recommended
               that you change this parameter unless you have a
               detailed understanding of its purpose.

         `objll (`LPX_K_OBJLL', default: -DBL_MAX)'
               Lower limit of the objective function.  If on the phase
               II the objective function reaches this limit and
               continues decreasing, the solver stops the search.  This
               parameter is used in the dual simplex method only.

         `objul (`LPX_K_OBJUL', default: +DBL_MAX)'
               Upper limit of the objective function. If on the phase
               II the objective function reaches this limit and
               continues increasing, the solver stops the search.  This
               parameter is used in the dual simplex only.

         `tmlim (`LPX_K_TMLIM', default: -1.0)'
               Searching time limit, in seconds. If this value is
               positive, it is decreased each time when one simplex
               iteration has been performed by the amount of time spent
               for the iteration, and reaching zero value signals the
               solver to stop the search.  Negative value means no time
               limit.

         `outdly (`LPX_K_OUTDLY', default: 0.0)'
               Output delay, in seconds. This parameter specifies how
               long the solver should delay sending information about
               the solution to the standard output. Non-positive value
               means no delay.

         `tolint (`LPX_K_TOLINT', default: 10e-5)'
               Relative tolerance used to check if the current basic
               solution is integer feasible.  It is not recommended
               that you change this parameter unless you have a
               detailed understanding of its purpose.

         `tolobj (`LPX_K_TOLOBJ', default: 10e-7)'
               Relative tolerance used to check if the value of the
               objective function is not better than in the best known
               integer feasible solution.  It is not recommended that
               you change this parameter unless you have a detailed
               understanding of its purpose.

     Output values:

    XOPT
          The optimizer (the value of the decision variables at the
          optimum).

    FOPT
          The optimum value of the objective function.

    STATUS
          Status of the optimization.

          Simplex Method:
         180 (`LPX_OPT')
               Solution is optimal.

         181 (`LPX_FEAS')
               Solution is feasible.

         182 (`LPX_INFEAS')
               Solution is infeasible.

         183 (`LPX_NOFEAS')
               Problem has no feasible solution.

         184 (`LPX_UNBND')
               Problem has no unbounded solution.

         185 (`LPX_UNDEF')
               Solution status is undefined.
          Interior Point Method:
         150 (`LPX_T_UNDEF')
               The interior point method is undefined.

         151 (`LPX_T_OPT')
               The interior point method is optimal.
          Mixed Integer Method:
         170 (`LPX_I_UNDEF')
               The status is undefined.

         171 (`LPX_I_OPT')
               The solution is integer optimal.

         172 (`LPX_I_FEAS')
               Solution integer feasible but its optimality has not
               been proven

         173 (`LPX_I_NOFEAS')
               No integer feasible solution.
          If an error occurs, STATUS will contain one of the following
          codes:

         204 (`LPX_E_FAULT')
               Unable to start the search.

         205 (`LPX_E_OBJLL')
               Objective function lower limit reached.

         206 (`LPX_E_OBJUL')
               Objective function upper limit reached.

         207 (`LPX_E_ITLIM')
               Iterations limit exhausted.

         208 (`LPX_E_TMLIM')
               Time limit exhausted.

         209 (`LPX_E_NOFEAS')
               No feasible solution.

         210 (`LPX_E_INSTAB')
               Numerical instability.

         211 (`LPX_E_SING')
               Problems with basis matrix.

         212 (`LPX_E_NOCONV')
               No convergence (interior).

         213 (`LPX_E_NOPFS')
               No primal feasible solution (LP presolver).

         214 (`LPX_E_NODFS')
               No dual feasible solution (LP presolver).

    EXTRA
          A data structure containing the following fields:
         `lambda'
               Dual variables.

         `redcosts'
               Reduced Costs.

         `time'
               Time (in seconds) used for solving LP/MIP problem.

         `mem'
               Memory (in bytes) used for solving LP/MIP problem (this
               is not available if the version of GLPK is 4.15 or
               later).

     Example:

          c = [10, 6, 4]';
          a = [ 1, 1, 1;
               10, 4, 5;
                2, 2, 6];
          b = [100, 600, 300]';
          lb = [0, 0, 0]';
          ub = [];
          ctype = "UUU";
          vartype = "CCC";
          s = -1;

          param.msglev = 1;
          param.itlim = 100;

          [xmin, fmin, status, extra] = ...
             glpk (c, a, b, lb, ub, ctype, vartype, s, param);


File: octave.info,  Node: Quadratic Programming,  Next: Nonlinear Programming,  Prev: Linear Programming,  Up: Optimization

23.2 Quadratic Programming
==========================

Octave can also solve Quadratic Programming problems, this is
     min 0.5 x'*H*x + x'*q
   subject to
          A*x = b
          lb <= x <= ub
          A_lb <= A_in*x <= A_ub

 -- Function File: [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B, LB, UB,
          A_LB, A_IN, A_UB)
     Solve the quadratic program

               min 0.5 x'*H*x + x'*q
                x

     subject to

               A*x = b
               lb <= x <= ub
               A_lb <= A_in*x <= A_ub

     using a null-space active-set method.

     Any bound (A, B, LB, UB, A_LB, A_UB) may be set to the empty
     matrix (`[]') if not present.  If the initial guess is feasible
     the algorithm is faster.

     The value INFO is a structure with the following fields:
    `solveiter'
          The number of iterations required to find the solution.

    `info'
          An integer indicating the status of the solution, as follows:
         0
               The problem is feasible and convex.  Global solution
               found.

         1
               The problem is not convex.  Local solution found.

         2
               The problem is not convex and unbounded.

         3
               Maximum number of iterations reached.

         6
               The problem is infeasible.


File: octave.info,  Node: Nonlinear Programming,  Next: Linear Least Squares,  Prev: Quadratic Programming,  Up: Optimization

23.3 Nonlinear Programming
==========================

Octave can also perform general nonlinear minimization using a
successive quadratic programming solver.

 -- Function File: [X, OBJ, INFO, ITER, NF, LAMBDA] = sqp (X, PHI, G,
          H, LB, UB, MAXITER, TOLERANCE)
     Solve the nonlinear program

               min phi (x)
                x

     subject to

               g(x)  = 0
               h(x) >= 0
               lb <= x <= ub

     using a successive quadratic programming method.

     The first argument is the initial guess for the vector X.

     The second argument is a function handle pointing to the objective
     function.  The objective function must be of the form

               y = phi (x)

     in which X is a vector and Y is a scalar.

     The second argument may also be a 2- or 3-element cell array of
     function handles.  The first element should point to the objective
     function, the second should point to a function that computes the
     gradient of the objective function, and the third should point to a
     function to compute the hessian of the objective function.  If the
     gradient function is not supplied, the gradient is computed by
     finite differences.  If the hessian function is not supplied, a
     BFGS update formula is used to approximate the hessian.

     If supplied, the gradient function must be of the form

          g = gradient (x)

     in which X is a vector and G is a vector.

     If supplied, the hessian function must be of the form

          h = hessian (x)

     in which X is a vector and H is a matrix.

     The third and fourth arguments are function handles pointing to
     functions that compute the equality constraints and the inequality
     constraints, respectively.

     If your problem does not have equality (or inequality) constraints,
     you may pass an empty matrix for CEF (or CIF).

     If supplied, the equality and inequality constraint functions must
     be of the form

          r = f (x)

     in which X is a vector and R is a vector.

     The third and fourth arguments may also be 2-element cell arrays of
     function handles.  The first element should point to the constraint
     function and the second should point to a function that computes
     the gradient of the constraint function:

                          [ d f(x)   d f(x)        d f(x) ]
              transpose ( [ ------   -----   ...   ------ ] )
                          [  dx_1     dx_2          dx_N  ]

     The fifth and sixth arguments are vectors containing lower and
     upper bounds on X. These must be consistent with equality and
     inequality constraints G and H. If the bounds are not specified,
     or are empty, they are set to -REALMAX and REALMAX by default.

     The seventh argument is max. number of iterations. If not
     specified, the default value is 100.

     The eighth argument is tolerance for stopping criteria. If not
     specified, the default value is EPS.

     Here is an example of calling `sqp':

          function r = g (x)
            r = [ sumsq(x)-10;
                  x(2)*x(3)-5*x(4)*x(5);
                  x(1)^3+x(2)^3+1 ];
          endfunction

          function obj = phi (x)
            obj = exp(prod(x)) - 0.5*(x(1)^3+x(2)^3+1)^2;
          endfunction

          x0 = [-1.8; 1.7; 1.9; -0.8; -0.8];

          [x, obj, info, iter, nf, lambda] = sqp (x0, @phi, @g, [])

          x =

            -1.71714
             1.59571
             1.82725
            -0.76364
            -0.76364

          obj = 0.053950
          info = 101
          iter = 8
          nf = 10
          lambda =

            -0.0401627
             0.0379578
            -0.0052227

     The value returned in INFO may be one of the following:
    101
          The algorithm terminated because the norm of the last step
          was less than `tol * norm (x))' (the value of tol is
          currently fixed at `sqrt (eps)'--edit `sqp.m' to modify this
          value.

    102
          The BFGS update failed.

    103
          The maximum number of iterations was reached (the maximum
          number of allowed iterations is currently fixed at 100--edit
          `sqp.m' to increase this value).


     *See also:* qp.


File: octave.info,  Node: Linear Least Squares,  Prev: Nonlinear Programming,  Up: Optimization

23.4 Linear Least Squares
=========================

Octave also supports linear least squares minimization.  That is,
Octave can find the parameter b such that the model y = x*b fits data
(x,y) as good as possible, assuming zero-mean Gaussian noise.  If the
noise is assumed to be isotropic the problem can be solved using the
`\' or `/' operators, or the `ols' function.  In the general case where
the noise is assumed to be anisotropic the `gls' is needed.

 -- Function File: [BETA, SIGMA, R] = ols (Y, X)
     Ordinary least squares estimation for the multivariate model y = x
     b + e with mean (e) = 0 and cov (vec (e)) = kron (s, I).   where y
     is a t by p matrix, x is a t by k matrix, b is a k by p matrix, and
     e is a t by p matrix.

     Each row of Y and X is an observation and each column a variable.

     The return values BETA, SIGMA, and R are defined as follows.

    BETA
          The OLS estimator for B, `BETA = pinv (X) * Y', where `pinv
          (X)' denotes the pseudoinverse of X.

    SIGMA
          The OLS estimator for the matrix S,

               SIGMA = (Y-X*BETA)'
                 * (Y-X*BETA)
                 / (T-rank(X))

    R
          The matrix of OLS residuals, `R = Y - X * BETA'.

 -- Function File: [BETA, V, R] = gls (Y, X, O)
     Generalized least squares estimation for the multivariate model y
     = x b + e with mean (e) = 0 and cov (vec (e)) = (s^2) o,  where y
     is a t by p matrix, x is a t by k matrix, b is a k by p matrix, e
     is a t by p matrix, and o is a t p by t p matrix.

     Each row of Y and X is an observation and each column a variable.
     The return values BETA, V, and R are defined as follows.

    BETA
          The GLS estimator for b.

    V
          The GLS estimator for s^2.

    R
          The matrix of GLS residuals, r = y - x beta.


File: octave.info,  Node: Statistics,  Next: Financial Functions,  Prev: Optimization,  Up: Top

24 Statistics
*************

Octave has support for various statistical methods.  This includes
basic descriptive statistics, statistical tests, random number
generation, and much more.

   The functions that analyze data all assume that multidimensional data
is arranged in a matrix where each row is an observation, and each
column is a variable.  So, the matrix defined by

     a = [ 0.9, 0.7;
           0.1, 0.1;
           0.5, 0.4 ];

contains three observations from a two-dimensional distribution.  While
this is the default data arrangement, most functions support different
arrangements.

   It should be noted that the statistics functions don't handle data
containing NaN, NA, or Inf.  Such values need to be handled explicitly.

* Menu:

* Descriptive Statistics::
* Basic Statistical Functions::
* Statistical Plots::
* Tests::
* Models::
* Distributions::
* Random Number Generation::


File: octave.info,  Node: Descriptive Statistics,  Next: Basic Statistical Functions,  Up: Statistics

24.1 Descriptive Statistics
===========================

Octave can compute various statistics such as the moments of a data set.

 -- Function File:  mean (X, DIM, OPT)
     If X is a vector, compute the mean of the elements of X

          mean (x) = SUM_i x(i) / N
     If X is a matrix, compute the mean for each column and return them
     in a row vector.

     With the optional argument OPT, the kind of mean computed can be
     selected.  The following options are recognized:

    `"a"'
          Compute the (ordinary) arithmetic mean.  This is the default.

    `"g"'
          Compute the geometric mean.

    `"h"'
          Compute the harmonic mean.

     If the optional argument DIM is supplied, work along dimension DIM.

     Both DIM and OPT are optional.  If both are supplied, either may
     appear first.

 -- Function File:  median (X, DIM)
     If X is a vector, compute the median value of the elements of X.
     If the elements of X are sorted, the median is defined as

                      x(ceil(N/2)),             N odd
          median(x) =
                      (x(N/2) + x((N/2)+1))/2,  N even
     If X is a matrix, compute the median value for each column
     and return them in a row vector. If the optional DIM argument is
     given, operate along this dimension.

     *See also:* std, mean.

 -- Function File: Q = quantile (X, P)
 -- Function File: Q = quantile (X, P, DIM)
 -- Function File: Q = quantile (X, P, DIM, METHOD )
     For a sample, X, calculate the quantiles, Q, corresponding to the
     cumulative probability values in P. All non-numeric values (NaNs)
     of X are ignored.

     If X is a matrix, compute the quantiles for each column and return
     them in a matrix, such that the i-th row of Q contains the P(i)th
     quantiles of each column of X.

     The optional argument DIM determines the dimension along which the
     percentiles are calculated. If DIM is omitted, and X is a vector
     or matrix, it defaults to 1 (column wise quantiles). In the
     instance that X is a N-d array, DIM defaults to the first
     dimension whose size greater than unity.

     The methods available to calculate sample quantiles are the nine
     methods used by R (http://www.r-project.org/). The default value
     is METHOD = 5.

     Discontinuous sample quantile methods 1, 2, and 3

       1. Method 1: Inverse of empirical distribution function.

       2. Method 2: Similar to method 1 but with averaging at
          discontinuities.

       3. Method 3: SAS definition: nearest even order statistic.

     Continuous sample quantile methods 4 through 9, where p(k) is the
     linear interpolation function respecting each methods'
     representative cdf.

       4. Method 4: p(k) = k / n. That is, linear interpolation of the
          empirical cdf.

       5. Method 5: p(k) = (k - 0.5) / n. That is a piecewise linear
          function where the knots are the values midway through the
          steps of the empirical cdf.

       6. Method 6: p(k) = k / (n + 1).

       7. Method 7: p(k) = (k - 1) / (n - 1).

       8. Method 8: p(k) = (k - 1/3) / (n + 1/3). The resulting
          quantile estimates are approximately median-unbiased
          regardless of the distribution of X.

       9. Method 9: p(k) = (k - 3/8) / (n + 1/4). The resulting
          quantile estimates are approximately unbiased for the
          expected order statistics if X is normally distributed.

     Hyndman and Fan (1996) recommend method 8.  Maxima, S, and R
     (versions prior to 2.0.0) use 7 as their default.  Minitab and SPSS
     use method 6.  Matlab uses method 5.

     References:

        * Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New
          S Language. Wadsworth & Brooks/Cole.

        * Hyndman, R. J. and Fan, Y. (1996) Sample quantiles in
          statistical packages, American Statistician, 50, 361-365.

        * R: A Language and Environment for Statistical Computing;
          `http://cran.r-project.org/doc/manuals/fullrefman.pdf'.

 -- Function File: Y = prctile (X, P)
 -- Function File: Q = prctile (X, P, DIM)
     For a sample X, compute the the quantiles, Y, corresponding to the
     cumulative probability values, P, in percent. All non-numeric
     values (NaNs) of X are ignored.

     If X is a matrix, compute the the percentiles for each column and
     return them in a matrix, such that the i-th row of Y contains the
     P(i)th percentiles of each column of X.

     The optional argument DIM determines the dimension along which the
     percentiles are calculated. If DIM is omitted, and X is a vector
     or matrix, it defaults to 1 (column wise quantiles). In the
     instance that X is a N-d array, DIM defaults to the first
     dimension whose size greater than unity.


 -- Function File:  meansq (X)
 -- Function File:  meansq (X, DIM)
     For vector arguments, return the mean square of the values.  For
     matrix arguments, return a row vector containing the mean square
     of each column. With the optional DIM argument, returns the mean
     squared of the values along this dimension.

 -- Function File:  std (X)
 -- Function File:  std (X, OPT)
 -- Function File:  std (X, OPT, DIM)
     If X is a vector, compute the standard deviation of the elements
     of X.

          std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
     If X is a matrix, compute the standard deviation for each
     column and return them in a row vector.

     The argument OPT determines the type of normalization to use.
     Valid values are

    0:
          normalizes with N-1, provides the square root of best
          unbiased estimator of   the variance [default]

    1:
          normalizes with N, this provides the square root of the
          second moment around   the mean

     The third argument DIM determines the dimension along which the
     standard deviation is calculated.

     *See also:* mean, median.

 -- Function File:  var (X)
     For vector arguments, return the (real) variance of the values.
     For matrix arguments, return a row vector containing the variance
     for each column.

     The argument OPT determines the type of normalization to use.
     Valid values are

    0:
          Normalizes with N-1, provides the best unbiased estimator of
          the variance [default].

    1:
          Normalizes with N, this provides the second moment around the
          mean.

     The third argument DIM determines the dimension along which the
     variance is calculated.

 -- Function File: [M, F, C] = mode (X, DIM)
     Count the most frequently appearing value. `mode' counts the
     frequency along the first non-singleton dimension and if two or
     more values have te same frequency returns the smallest of the two
     in M. The dimension along which to count can be specified by the
     DIM parameter.

     The variable F counts the frequency of each of the most frequently
     occurring elements. The cell array C contains all of the elements
     with the maximum frequency .

 -- Function File:  cov (X, Y)
     Compute covariance.

     If each row of X and Y is an observation and each column is a
     variable, the (I, J)-th entry of `cov (X, Y)' is the covariance
     between the I-th variable in X and the J-th variable in Y.  If
     called with one argument, compute `cov (X, X)'.

 -- Function File:  cor (X, Y)
     Compute correlation.

     The (I, J)-th entry of `cor (X, Y)' is the correlation between the
     I-th variable in X and the J-th variable in Y.

          corrcoef(x,y) = cov(x,y)/(std(x)*std(y))

     For matrices, each row is an observation and each column a
     variable; vectors are always observations and may be row or column
     vectors.

     `cor (X)' is equivalent to `cor (X, X)'.

     Note that the `corrcoef' function does the same as `cor'.

 -- Function File:  corrcoef (X, Y)
     Compute correlation.

     If each row of X and Y is an observation and each column is a
     variable, the (I, J)-th entry of `corrcoef (X, Y)' is the
     correlation between the I-th variable in X and the J-th variable
     in Y.

          corrcoef(x,y) = cov(x,y)/(std(x)*std(y))

     If called with one argument, compute `corrcoef (X, X)'.

 -- Function File:  kurtosis (X, DIM)
     If X is a vector of length N, return the kurtosis

          kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3

     of X.  If X is a matrix, return the kurtosis over the first
     non-singleton dimension. The optional argument DIM can be given to
     force the kurtosis to be given over that dimension.

 -- Function File:  skewness (X, DIM)
     If X is a vector of length n, return the skewness

          skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)

     of X.  If X is a matrix, return the skewness along the first
     non-singleton dimension of the matrix. If the optional DIM
     argument is given, operate along this dimension.

 -- Function File:  statistics (X)
     If X is a matrix, return a matrix with the minimum, first
     quartile, median, third quartile, maximum, mean, standard
     deviation, skewness and kurtosis of the columns of X as its
     columns.

     If X is a vector, calculate the statistics along the non-singleton
     dimension.

 -- Function File:  moment (X, P, OPT, DIM)
     If X is a vector, compute the P-th moment of X.

     If X is a matrix, return the row vector containing the P-th moment
     of each column.

     With the optional string opt, the kind of moment to be computed can
     be specified.  If opt contains `"c"' or `"a"', central and/or
     absolute moments are returned.  For example,

          moment (x, 3, "ac")

     computes the third central absolute moment of X.

     If the optional argument DIM is supplied, work along dimension DIM.


File: octave.info,  Node: Basic Statistical Functions,  Next: Statistical Plots,  Prev: Descriptive Statistics,  Up: Statistics

24.2 Basic Statistical Functions
================================

Octave also supports various helpful statistical functions.

 -- Function File:  mahalanobis (X, Y)
     Return the Mahalanobis' D-square distance between the multivariate
     samples X and Y, which must have the same number of components
     (columns), but may have a different number of observations (rows).

 -- Function File:  center (X)
 -- Function File:  center (X, DIM)
     If X is a vector, subtract its mean.  If X is a matrix, do the
     above for each column.  If the optional argument DIM is given,
     perform the above operation along this dimension

 -- Function File:  studentize (X, DIM)
     If X is a vector, subtract its mean and divide by its standard
     deviation.

     If X is a matrix, do the above along the first non-singleton
     dimension. If the optional argument DIM is given then operate
     along this dimension.

 -- Function File: C = nchoosek (N, K)
     Compute the binomial coefficient or all combinations of N.  If N
     is a scalar then, calculate the binomial coefficient of N and K,
     defined as

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

     If N is a vector generate all combinations of the elements of N,
     taken K at a time, one row per combination. The resulting C has
     size `[nchoosek (length (N), K), K]'.


     *See also:* bincoeff.

 -- Function File:  perms (V)
     Generate all permutations of V, one row per permutation. The
     result has size `factorial (N) * N', where N is the length of V.

     As an example, `perms([1, 2, 3])' returns the matrix
            1   2   3
            2   1   3
            1   3   2
            2   3   1
            3   1   2
            3   2   1

 -- Function File:  values (X)
     Return the different values in a column vector, arranged in
     ascending order.

     As an example, `values([1, 2, 3, 1])' returns the vector `[1, 2,
     3]'.

 -- Function File: [T, L_X] = table (X)
 -- Function File: [T, L_X, L_Y] = table (X, Y)
     Create a contingency table T from data vectors.  The L vectors are
     the corresponding levels.

     Currently, only 1- and 2-dimensional tables are supported.

 -- Function File:  spearman (X, Y)
     Compute Spearman's rank correlation coefficient RHO for each of
     the variables specified by the input arguments.

     For matrices, each row is an observation and each column a
     variable; vectors are always observations and may be row or column
     vectors.

     `spearman (X)' is equivalent to `spearman (X, X)'.

     For two data vectors X and Y, Spearman's RHO is the correlation of
     the ranks of X and Y.

     If X and Y are drawn from independent distributions, RHO has zero
     mean and variance `1 / (n - 1)', and is asymptotically normally
     distributed.

 -- Function File:  run_count (X, N)
     Count the upward runs along the first non-singleton dimension of X
     of length 1, 2, ..., N-1 and greater than or equal to N. If the
     optional argument DIM is given operate along this dimension

 -- Function File:  ranks (X, DIM)
     Return the ranks of X along the first non-singleton dimension
     adjust for ties. If the optional argument DIM is given, operate
     along this dimension.

 -- Function File:  range (X)
 -- Function File:  range (X, DIM)
     If X is a vector, return the range, i.e., the difference between
     the maximum and the minimum, of the input data.

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

     If the optional argument DIM is supplied, work along dimension DIM.

 -- Function File:  probit (P)
     For each component of P, return the probit (the quantile of the
     standard normal distribution) of P.

 -- Function File:  logit (P)
     For each component of P, return the logit of P defined as
          logit(P) = log (P / (1-P))

 -- Function File:  cloglog (X)
     Return the complementary log-log function of X, defined as

          cloglog(x) = - log (- log (X))

 -- Function File:  kendall (X, Y)
     Compute Kendall's TAU for each of the variables specified by the
     input arguments.

     For matrices, each row is an observation and each column a
     variable; vectors are always observations and may be row or column
     vectors.

     `kendall (X)' is equivalent to `kendall (X, X)'.

     For two data vectors X, Y of common length N, Kendall's TAU is the
     correlation of the signs of all rank differences of X and Y;
     i.e., if both X and Y have distinct entries, then

                   1
          tau = -------   SUM sign (q(i) - q(j)) * sign (r(i) - r(j))
                n (n-1)   i,j

     in which the Q(I) and R(I)  are the ranks of X and Y, respectively.

     If X and Y are drawn from independent distributions, Kendall's TAU
     is asymptotically normal with mean 0 and variance `(2 * (2N+5)) /
     (9 * N * (N-1))'.

 -- Function File:  iqr (X, DIM)
     If X is a vector, return the interquartile range, i.e., the
     difference between the upper and lower quartile, of the input data.

     If X is a matrix, do the above for first non singleton dimension
     of X. If the option DIM argument is given, then operate along this
     dimension.

 -- Function File:  cut (X, BREAKS)
     Create categorical data out of numerical or continuous data by
     cutting into intervals.

     If BREAKS is a scalar, the data is cut into that many equal-width
     intervals.  If BREAKS is a vector of break points, the category
     has `length (BREAKS) - 1' groups.

     The returned value is a vector of the same size as X telling which
     group each point in X belongs to.  Groups are labelled from 1 to
     the number of groups; points outside the range of BREAKS are
     labelled by `NaN'.


File: octave.info,  Node: Statistical Plots,  Next: Tests,  Prev: Basic Statistical Functions,  Up: Statistics

24.3 Statistical Plots
======================

Octave can create Quantile Plots (QQ-Plots), and Probability Plots
(PP-Plots).  These are simple graphical tests for determining if a data
set comes from a certain distribution.

   It is worth noticing that Octave can also show histograms of data
using the `hist' function as described in *Note Two-Dimensional Plots::.

 -- Function File: [Q, S] = qqplot (X, DIST, PARAMS)
     Perform a QQ-plot (quantile plot).

     If F is the CDF of the distribution DIST with parameters PARAMS
     and G its inverse, and X a sample vector of length N, the QQ-plot
     graphs ordinate S(I) = I-th largest element of x versus abscissa
     Q(If) = G((I - 0.5)/N).

     If the sample comes from F except for a transformation of location
     and scale, the pairs will approximately follow a straight line.

     The default for DIST is the standard normal distribution.  The
     optional argument PARAMS contains a list of parameters of DIST.
     For example, for a quantile plot of the uniform distribution on
     [2,4] and X, use

          qqplot (x, "uniform", 2, 4)

     DIST can be any string for which a function DIST_INV that
     calculates the inverse CDF of distribution DIST exists.

     If no output arguments are given, the data are plotted directly.

 -- Function File: [P, Y] = ppplot (X, DIST, PARAMS)
     Perform a PP-plot (probability plot).

     If F is the CDF of the distribution DIST with parameters PARAMS
     and X a sample vector of length N, the PP-plot graphs ordinate
     Y(I) = F (I-th largest element of X) versus abscissa P(I) = (I -
     0.5)/N.  If the sample comes from F, the pairs will approximately
     follow a straight line.

     The default for DIST is the standard normal distribution.  The
     optional argument PARAMS contains a list of parameters of DIST.
     For example, for a probability plot of the uniform distribution on
     [2,4] and X, use

          ppplot (x, "uniform", 2, 4)

     DIST can be any string for which a function DIST_CDF that
     calculates the CDF of distribution DIST exists.

     If no output arguments are given, the data are plotted directly.


File: octave.info,  Node: Tests,  Next: Models,  Prev: Statistical Plots,  Up: Statistics

24.4 Tests
==========

Octave can perform several different statistical tests.  The following
table summarizes the available tests.

*Hypothesis*                  *Test Functions*
Equal mean values             `anova', `hotelling_test2',
                              `t_test_2',        `welch_test',
                              `wilcoxon_test', `z_test_2'
Equal medians                 `kruskal_wallis_test', `sign_test'
Equal variances               `bartlett_test', `manova',
                              `var_test'
Equal distributions           `chisquare_test_homogeneity',
                              `kolmogorov_smirnov_test_2',
                              `u_test'
Equal marginal frequencies    `mcnemar_test'
Equal success probabilities   `prop_test_2'
Independent observations      `chisquare_test_independence',
                              `run_test'
Uncorrelated observations     `cor_test'
Given mean value              `hotelling_test', `t_test', `z_test'
Observations from given       `kolmogorov_smirnov_test'
distribution                  
Regression                    `f_test_regression',
                              `t_test_regression'

   The tests return a p-value that describes the outcome of the test.
Assuming that the test hypothesis is true, the p-value is the
probability of obtaining a worse result than the observed one.  So
large p-values corresponds to a successful test.  Usually a test
hypothesis is accepted if the p-value exceeds 0.05.

 -- Function File: [PVAL, F, DF_B, DF_W] = anova (Y, G)
     Perform a one-way analysis of variance (ANOVA).  The goal is to
     test whether the population means of data taken from K different
     groups are all equal.

     Data may be given in a single vector Y with groups specified by a
     corresponding vector of group labels G (e.g., numbers from 1 to
     K). This is the general form which does not impose any restriction
     on the number of data in each group or the group labels.

     If Y is a matrix and G is omitted, each column of Y is treated as
     a group.  This form is only appropriate for balanced ANOVA in
     which the numbers of samples from each group are all equal.

     Under the null of constant means, the statistic F follows an F
     distribution with DF_B and DF_W degrees of freedom.

     The p-value (1 minus the CDF of this distribution at F) is
     returned in PVAL.

     If no output argument is given, the standard one-way ANOVA table is
     printed.

 -- Function File: [PVAL, CHISQ, DF] = bartlett_test (X1, ...)
     Perform a Bartlett test for the homogeneity of variances in the
     data vectors X1, X2, ..., XK, where K > 1.

     Under the null of equal variances, the test statistic CHISQ
     approximately follows a chi-square distribution with DF degrees of
     freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, CHISQ, DF] = chisquare_test_homogeneity (X,
          Y, C)
     Given two samples X and Y, perform a chisquare test for
     homogeneity of the null hypothesis that X and Y come from the same
     distribution, based on the partition induced by the (strictly
     increasing) entries of C.

     For large samples, the test statistic CHISQ approximately follows a
     chisquare distribution with DF = `length (C)' degrees of freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, CHISQ, DF] = chisquare_test_independence (X)
     Perform a chi-square test for independence based on the contingency
     table X.  Under the null hypothesis of independence, CHISQ
     approximately has a chi-square distribution with DF degrees of
     freedom.

     The p-value (1 minus the CDF of this distribution at chisq) of the
     test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File:  cor_test (X, Y, ALT, METHOD)
     Test whether two samples X and Y come from uncorrelated
     populations.

     The optional argument string ALT describes the alternative
     hypothesis, and can be `"!="' or `"<>"' (non-zero), `">"' (greater
     than 0), or `"<"' (less than 0).  The default is the two-sided
     case.

     The optional argument string METHOD specifies on which correlation
     coefficient the test should be based.  If METHOD is `"pearson"'
     (default), the (usual) Pearson's product moment correlation
     coefficient is used.  In this case, the data should come from a
     bivariate normal distribution.  Otherwise, the other two methods
     offer nonparametric alternatives. If METHOD is `"kendall"', then
     Kendall's rank correlation tau is used.  If METHOD is
     `"spearman"', then Spearman's rank correlation rho is used.  Only
     the first character is necessary.

     The output is a structure with the following elements:

    PVAL
          The p-value of the test.

    STAT
          The value of the test statistic.

    DIST
          The distribution of the test statistic.

    PARAMS
          The parameters of the null distribution of the test statistic.

    ALTERNATIVE
          The alternative hypothesis.

    METHOD
          The method used for testing.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, F, DF_NUM, DF_DEN] = f_test_regression (Y, X,
          RR, R)
     Perform an F test for the null hypothesis rr * b = r in a classical
     normal regression model y = X * b + e.

     Under the null, the test statistic F follows an F distribution
     with DF_NUM and DF_DEN degrees of freedom.

     The p-value (1 minus the CDF of this distribution at F) is
     returned in PVAL.

     If not given explicitly, R = 0.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, TSQ] = hotelling_test (X, M)
     For a sample X from a multivariate normal distribution with unknown
     mean and covariance matrix, test the null hypothesis that `mean
     (X) == M'.

     Hotelling's T^2 is returned in TSQ.  Under the null, (n-p) T^2 /
     (p(n-1)) has an F distribution with p and n-p degrees of freedom,
     where n and p are the numbers of samples and variables,
     respectively.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, TSQ] = hotelling_test_2 (X, Y)
     For two samples X from multivariate normal distributions with the
     same number of variables (columns), unknown means and unknown
     equal covariance matrices, test the null hypothesis `mean (X) ==
     mean (Y)'.

     Hotelling's two-sample T^2 is returned in TSQ.  Under the null,

          (n_x+n_y-p-1) T^2 / (p(n_x+n_y-2))

     has an F distribution with p and n_x+n_y-p-1 degrees of freedom,
     where n_x and n_y are the sample sizes and p is the number of
     variables.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, KS] = kolmogorov_smirnov_test (X, DIST,
          PARAMS, ALT)
     Perform a Kolmogorov-Smirnov test of the null hypothesis that the
     sample X comes from the (continuous) distribution dist. I.e., if F
     and G are the CDFs corresponding to the sample and dist,
     respectively, then the null is that F == G.

     The optional argument PARAMS contains a list of parameters of
     DIST.  For example, to test whether a sample X comes from a
     uniform distribution on [2,4], use

          kolmogorov_smirnov_test(x, "uniform", 2, 4)

     DIST can be any string for which a function DIST_CDF that
     calculates the CDF of distribution DIST exists.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative F != G.  In this case, the test
     statistic KS follows a two-sided Kolmogorov-Smirnov distribution.
     If ALT is `">"', the one-sided alternative F > G is considered.
     Similarly for `"<"', the one-sided alternative F > G is
     considered.  In this case, the test statistic KS has a one-sided
     Kolmogorov-Smirnov distribution.  The default is the two-sided
     case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, KS, D] = kolmogorov_smirnov_test_2 (X, Y, ALT)
     Perform a 2-sample Kolmogorov-Smirnov test of the null hypothesis
     that the samples X and Y come from the same (continuous)
     distribution.  I.e., if F and G are the CDFs corresponding to the
     X and Y samples, respectively, then the null is that F == G.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative F != G.  In this case, the test
     statistic KS follows a two-sided Kolmogorov-Smirnov distribution.
     If ALT is `">"', the one-sided alternative F > G is considered.
     Similarly for `"<"', the one-sided alternative F < G is
     considered.  In this case, the test statistic KS has a one-sided
     Kolmogorov-Smirnov distribution.  The default is the two-sided
     case.

     The p-value of the test is returned in PVAL.

     The third returned value, D, is the test statistic, the maximum
     vertical distance between the two cumulative distribution
     functions.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, K, DF] = kruskal_wallis_test (X1, ...)
     Perform a Kruskal-Wallis one-factor "analysis of variance".

     Suppose a variable is observed for K > 1 different groups, and let
     X1, ..., XK be the corresponding data vectors.

     Under the null hypothesis that the ranks in the pooled sample are
     not affected by the group memberships, the test statistic K is
     approximately chi-square with DF = K - 1 degrees of freedom.

     If the data contains ties (some value appears more than once) K is
     divided by

     1 - SUMTIES / ( N^3 - N )

     where SUMTIES is the sum of T^2 - T over each group of ties where
     T is the number of ties in the group and N is the total number of
     values in the input data. For more info on this adjustment see
     "Use of Ranks in One-Criterion Variance Analysis" in Journal of
     the American Statistical Association, Vol. 47, No. 260 (Dec 1952)
     by William H. Kruskal and W. Allen Wallis.

     The p-value (1 minus the CDF of this distribution at K) is
     returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File:  manova (Y, G)
     Perform a one-way multivariate analysis of variance (MANOVA). The
     goal is to test whether the p-dimensional population means of data
     taken from K different groups are all equal.  All data are assumed
     drawn independently from p-dimensional normal distributions with
     the same covariance matrix.

     The data matrix is given by Y.  As usual, rows are observations
     and columns are variables.  The vector G specifies the
     corresponding group labels (e.g., numbers from 1 to K).

     The LR test statistic (Wilks' Lambda) and approximate p-values are
     computed and displayed.

 -- Function File: [PVAL, CHISQ, DF] = mcnemar_test (X)
     For a square contingency table X of data cross-classified on the
     row and column variables, McNemar's test can be used for testing
     the null hypothesis of symmetry of the classification
     probabilities.

     Under the null, CHISQ is approximately distributed as chisquare
     with DF degrees of freedom.

     The p-value (1 minus the CDF of this distribution at CHISQ) is
     returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = prop_test_2 (X1, N1, X2, N2, ALT)
     If X1 and N1 are the counts of successes and trials in one sample,
     and X2 and N2 those in a second one, test the null hypothesis that
     the success probabilities P1 and P2 are the same.  Under the null,
     the test statistic Z approximately follows a standard normal
     distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative P1 != P2.  If ALT is `">"', the
     one-sided alternative P1 > P2 is used.  Similarly for `"<"', the
     one-sided alternative P1 < P2 is used.  The default is the
     two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, CHISQ] = run_test (X)
     Perform a chi-square test with 6 degrees of freedom based on the
     upward runs in the columns of X.  Can be used to test whether X
     contains independent data.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value is displayed.

 -- Function File: [PVAL, B, N] = sign_test (X, Y, ALT)
     For two matched-pair samples X and Y, perform a sign test of the
     null hypothesis PROB (X > Y) == PROB (X < Y) == 1/2.  Under the
     null, the test statistic B roughly follows a binomial distribution
     with parameters `N = sum (X != Y)' and P = 1/2.

     With the optional argument `alt', the alternative of interest can
     be selected.  If ALT is `"!="' or `"<>"', the null hypothesis is
     tested against the two-sided alternative PROB (X < Y) != 1/2.  If
     ALT is `">"', the one-sided alternative PROB (X > Y) > 1/2 ("x is
     stochastically greater than y") is considered.  Similarly for
     `"<"', the one-sided alternative PROB (X > Y) < 1/2 ("x is
     stochastically less than y") is considered.  The default is the
     two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test (X, M, ALT)
     For a sample X from a normal distribution with unknown mean and
     variance, perform a t-test of the null hypothesis `mean (X) == M'.
     Under the null, the test statistic T follows a Student
     distribution with `DF = length (X) - 1' degrees of freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != M'.  If ALT is
     `">"', the one-sided alternative `mean (X) > M' is considered.
     Similarly for "<", the one-sided alternative `mean (X) < M' is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test_2 (X, Y, ALT)
     For two samples x and y from normal distributions with unknown
     means and unknown equal variances, perform a two-sample t-test of
     the null hypothesis of equal means.  Under the null, the test
     statistic T follows a Student distribution with DF degrees of
     freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != mean (Y)'.  If ALT
     is `">"', the one-sided alternative `mean (X) > mean (Y)' is used.
     Similarly for `"<"', the one-sided alternative `mean (X) < mean
     (Y)' is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = t_test_regression (Y, X, RR, R, ALT)
     Perform an t test for the null hypothesis `RR * B = R' in a
     classical normal regression model `Y = X * B + E'.  Under the
     null, the test statistic T follows a T distribution with DF
     degrees of freedom.

     If R is omitted, a value of 0 is assumed.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `RR * B != R'.  If ALT is `">"',
     the one-sided alternative `RR * B > R' is used.  Similarly for
     "<", the one-sided alternative `RR * B < R' is used.  The default
     is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = u_test (X, Y, ALT)
     For two samples X and Y, perform a Mann-Whitney U-test of the null
     hypothesis PROB (X > Y) == 1/2 == PROB (X < Y).  Under the null,
     the test statistic Z approximately follows a standard normal
     distribution.  Note that this test is equivalent to the Wilcoxon
     rank-sum test.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative PROB (X > Y) != 1/2.  If ALT is
     `">"', the one-sided alternative PROB (X > Y) > 1/2 is considered.
     Similarly for `"<"', the one-sided alternative PROB (X > Y) < 1/2
     is considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, F, DF_NUM, DF_DEN] = var_test (X, Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and unknown variances, perform an F-test of the null
     hypothesis of equal variances.  Under the null, the test statistic
     F follows an F-distribution with DF_NUM and DF_DEN degrees of
     freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `var (X) != var (Y)'.  If ALT is
     `">"', the one-sided alternative `var (X) > var (Y)' is used.
     Similarly for "<", the one-sided alternative `var (X) > var (Y)'
     is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, T, DF] = welch_test (X, Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and unknown and not necessarily equal variances, perform a
     Welch test of the null hypothesis of equal means.  Under the null,
     the test statistic T approximately follows a Student distribution
     with DF degrees of freedom.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != M'.  If ALT is
     `">"', the one-sided alternative mean(x) > M is considered.
     Similarly for `"<"', the one-sided alternative mean(x) < M is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = wilcoxon_test (X, Y, ALT)
     For two matched-pair sample vectors X and Y, perform a Wilcoxon
     signed-rank test of the null hypothesis PROB (X > Y) == 1/2.
     Under the null, the test statistic Z approximately follows a
     standard normal distribution when N > 25.

     *Warning*: This function assumes a normal distribution for Z and
     thus is invalid for N <= 25.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative PROB (X > Y) != 1/2.  If alt is
     `">"', the one-sided alternative PROB (X > Y) > 1/2 is considered.
     Similarly for `"<"', the one-sided alternative PROB (X > Y) < 1/2
     is considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed.

 -- Function File: [PVAL, Z] = z_test (X, M, V, ALT)
     Perform a Z-test of the null hypothesis `mean (X) == M' for a
     sample X from a normal distribution with unknown mean and known
     variance V.  Under the null, the test statistic Z follows a
     standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != M'.  If ALT is
     `">"', the one-sided alternative `mean (X) > M' is considered.
     Similarly for `"<"', the one-sided alternative `mean (X) < M' is
     considered.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed along with some information.

 -- Function File: [PVAL, Z] = z_test_2 (X, Y, V_X, V_Y, ALT)
     For two samples X and Y from normal distributions with unknown
     means and known variances V_X and V_Y, perform a Z-test of the
     hypothesis of equal means.  Under the null, the test statistic Z
     follows a standard normal distribution.

     With the optional argument string ALT, the alternative of interest
     can be selected.  If ALT is `"!="' or `"<>"', the null is tested
     against the two-sided alternative `mean (X) != mean (Y)'.  If alt
     is `">"', the one-sided alternative `mean (X) > mean (Y)' is used.
     Similarly for `"<"', the one-sided alternative `mean (X) < mean
     (Y)' is used.  The default is the two-sided case.

     The p-value of the test is returned in PVAL.

     If no output argument is given, the p-value of the test is
     displayed along with some information.


File: octave.info,  Node: Models,  Next: Distributions,  Prev: Tests,  Up: Statistics

24.5 Models
===========

 -- Function File: [THETA, BETA, DEV, DL, D2L, P] = logistic_regression
          (Y, X, PRINT, THETA, BETA)
     Perform ordinal logistic regression.

     Suppose Y takes values in K ordered categories, and let `gamma_i
     (X)' be the cumulative probability that Y falls in one of the
     first I categories given the covariate X.  Then

          [theta, beta] = logistic_regression (y, x)

     fits the model

          logit (gamma_i (x)) = theta_i - beta' * x,   i = 1...k-1

     The number of ordinal categories, K, is taken to be the number of
     distinct values of `round (Y)'.  If K equals 2, Y is binary and
     the model is ordinary logistic regression.  The matrix X is
     assumed to have full column rank.

     Given Y only, `theta = logistic_regression (y)' fits the model
     with baseline logit odds only.

     The full form is

          [theta, beta, dev, dl, d2l, gamma]
             = logistic_regression (y, x, print, theta, beta)

     in which all output arguments and all input arguments except Y are
     optional.

     Setting PRINT to 1 requests summary information about the fitted
     model to be displayed.  Setting PRINT to 2 requests information
     about convergence at each iteration.  Other values request no
     information to be displayed.  The input arguments THETA and BETA
     give initial estimates for THETA and BETA.

     The returned value DEV holds minus twice the log-likelihood.

     The returned values DL and D2L are the vector of first and the
     matrix of second derivatives of the log-likelihood with respect to
     THETA and BETA.

     P holds estimates for the conditional distribution of Y given X.


File: octave.info,  Node: Distributions,  Next: Random Number Generation,  Prev: Models,  Up: Statistics

24.6 Distributions
==================

Octave has functions for computing the Probability Density Function
(PDF), the Cumulative Distribution function (CDF), and the quantile
(the inverse of the CDF) of a large number of distributions.

   The following table summarizes the supported distributions (in
alphabetical order).

*Distribution*         *PDF*             *CDF*             *Quantile*
Beta Distribution      `betapdf'         `betacdf'         `betainv'
Binomial Distribution  `binopdf'         `binocdf'         `binoinv'
Cauchy Distribution    `cauchy_pdf'      `cauchy_cdf'      `cauchy_inv'
Chi-Square             `chi2pdf'         `chi2cdf'         `chi2inv'
Distribution                                               
Univariate Discrete    `discrete_pdf'    `discrete_cdf'    `discrete_inv'
Distribution                                               
Empirical Distribution `empirical_pdf'   `empirical_cdf'   `empirical_inv'
Exponential            `exppdf'          `expcdf'          `expinv'
Distribution                                               
F Distribution         `fpdf'            `fcdf'            `finv'
Gamma Distribution     `gampdf'          `gamcdf'          `gaminv'
Geometric Distribution `geopdf'          `geocdf'          `geoinv'
Hypergeometric         `hygepdf'         `hygecdf'         `hygeinv'
Distribution                                               
Kolmogorov Smirnov     _Not Available_   `kolmogorov_smirnov_cdf'_Not Available_
Distribution                                               
Laplace Distribution   `laplace_pdf'     `laplace_cdf'     `laplace_inv'
Logistic Distribution  `logistic_pdf'    `logistic_cdf'    `logistic_inv'
Log-Normal             `lognpdf'         `logncdf'         `logninv'
Distribution                                               
Pascal Distribution    `nbinpdf'         `nbincdf'         `nbininv'
Univariate Normal      `normpdf'         `normcdf'         `norminv'
Distribution                                               
Poisson Distribution   `poisspdf'        `poisscdf'        `poissinv'
t (Student)            `tpdf'            `tcdf'            `tinv'
Distribution                                               
Univariate Discrete    `unidpdf'         `unidcdf'         `unidinv'
Distribution                                               
Uniform Distribution   `unifpdf'         `unifcdf'         `unifinv'
Weibull Distribution   `wblpdf'          `wblcdf'          `wblinv'

 -- Function File:  betacdf (X, A, B)
     For each element of X, returns the CDF at X of the beta
     distribution with parameters A and B, i.e., PROB (beta (A, B) <=
     X).

 -- Function File:  betainv (X, A, B)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Beta distribution with parameters A and B.

 -- Function File:  betapdf (X, A, B)
     For each element of X, returns the PDF at X of the beta
     distribution with parameters A and B.

 -- Function File:  binocdf (X, N, P)
     For each element of X, compute the CDF at X of the binomial
     distribution with parameters N and P.

 -- Function File:  binoinv (X, N, P)
     For each element of X, compute the quantile at X of the binomial
     distribution with parameters N and P.

 -- Function File:  binopdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the binomial distribution with parameters N and P.

 -- Function File:  cauchy_cdf (X, LAMBDA, SIGMA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Cauchy distribution with location
     parameter LAMBDA and scale parameter SIGMA.  Default values are
     LAMBDA = 0, SIGMA = 1.

 -- Function File:  cauchy_inv (X, LAMBDA, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Cauchy distribution with location parameter
     LAMBDA and scale parameter SIGMA.  Default values are LAMBDA = 0,
     SIGMA = 1.

 -- Function File:  cauchy_pdf (X, LAMBDA, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the Cauchy distribution with location parameter
     LAMBDA and scale parameter SIGMA > 0.  Default values are LAMBDA =
     0, SIGMA = 1.

 -- Function File:  chi2cdf (X, N)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the chisquare distribution with N degrees
     of freedom.

 -- Function File:  chi2inv (X, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the chisquare distribution with N degrees of freedom.

 -- Function File:  chisquare_pdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the chisquare distribution with N degrees of freedom.

 -- Function File:  discrete_cdf (X, V, P)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of a univariate discrete distribution which
     assumes the values in V with probabilities P.

 -- Function File:  discrete_inv (X, V, P)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the univariate distribution which assumes the values
     in V with probabilities P.

 -- Function File:  discrete_pdf (X, V, P)
     For each element of X, compute the probability density function
     (PDF) at X of a univariate discrete distribution which assumes the
     values in V with probabilities P.

 -- Function File:  empirical_cdf (X, DATA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the empirical distribution obtained from
     the univariate sample DATA.

 -- Function File:  empirical_inv (X, DATA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File:  empirical_pdf (X, DATA)
     For each element of X, compute the probability density function
     (PDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File:  expcdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the exponential distribution with mean
     LAMBDA.

     The arguments can be of common size or scalar.

 -- Function File:  expinv (X, LAMBDA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the exponential distribution with mean LAMBDA.

 -- Function File:  exppdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) of the exponential distribution with mean LAMBDA.

 -- Function File:  fcdf (X, M, N)
     For each element of X, compute the CDF at X of the F distribution
     with M and N degrees of freedom, i.e., PROB (F (M, N) <= X).

 -- Function File:  finv (X, M, N)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the F distribution with parameters M and N.

 -- Function File:  fpdf (X, M, N)
     For each element of X, compute the probability density function
     (PDF) at X of the F distribution with M and N degrees of freedom.

 -- Function File:  gamcdf (X, A, B)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Gamma distribution with parameters A
     and B.

     *See also:* gamma, gammaln, gammainc, gampdf, gaminv, gamrnd.

 -- Function File:  gaminv (X, A, B)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Gamma distribution with parameters A and B.

     *See also:* gamma, gammaln, gammainc, gampdf, gamcdf, gamrnd.

 -- Function File:  gampdf (X, A, B)
     For each element of X, return the probability density function
     (PDF) at X of the Gamma distribution with parameters A and B.

     *See also:* gamma, gammaln, gammainc, gamcdf, gaminv, gamrnd.

 -- Function File:  geocdf (X, P)
     For each element of X, compute the CDF at X of the geometric
     distribution with parameter P.

 -- Function File:  geoinv (X, P)
     For each element of X, compute the quantile at X of the geometric
     distribution with parameter P.

 -- Function File:  geopdf (X, P)
     For each element of X, compute the probability density function
     (PDF) at X of the geometric distribution with parameter P.

 -- Function File:  hygecdf (X, T, M, N)
     Compute the cumulative distribution function (CDF) at X of the
     hypergeometric distribution with parameters T, M, and N.  This is
     the probability of obtaining not more than X marked items when
     randomly drawing a sample of size N without replacement from a
     population of total size T containing M marked items.

     The parameters T, M, and N must positive integers with M and N not
     greater than T.

 -- Function File:  hygeinv (X, T, M, N)
     For each element of X, compute the quantile at X of the
     hypergeometric distribution with parameters T, M, and N.

     The parameters T, M, and N must positive integers with M and N not
     greater than T.

 -- Function File:  hygepdf (X, T, M, N)
     Compute the probability density function (PDF) at X of the
     hypergeometric distribution with parameters T, M, and N. This is
     the probability of obtaining X marked items when randomly drawing
     a sample of size N without replacement from a population of total
     size T containing M marked items.

     The arguments must be of common size or scalar.

 -- Function File:  kolmogorov_smirnov_cdf (X, TOL)
     Return the CDF at X of the Kolmogorov-Smirnov distribution,
                   Inf
          Q(x) =   SUM    (-1)^k exp(-2 k^2 x^2)
                 k = -Inf

     for X > 0.

     The optional parameter TOL specifies the precision up to which the
     series should be evaluated;  the default is TOL = `eps'.

 -- Function File:  laplace_cdf (X)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Laplace distribution.

 -- Function File:  laplace_inv (X)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Laplace distribution.

 -- Function File:  laplace_pdf (X)
     For each element of X, compute the probability density function
     (PDF) at X of the Laplace distribution.

 -- Function File:  logistic_cdf (X)
     For each component of X, compute the CDF at X of the logistic
     distribution.

 -- Function File:  logistic_inv (X)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the logistic distribution.

 -- Function File:  logistic_pdf (X)
     For each component of X, compute the PDF at X of the logistic
     distribution.

 -- Function File:  logncdf (X, MU, SIGMA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the lognormal distribution with parameters
     MU and SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean MU and standard
     deviation SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File:  logninv (X, MU, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean `log (MU)' and
     variance SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File:  lognpdf (X, MU, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean MU and standard
     deviation SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File:  nbincdf (X, N, P)
     For each element of X, compute the CDF at x of the Pascal
     (negative binomial) distribution with parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  nbininv (X, N, P)
     For each element of X, compute the quantile at X of the Pascal
     (negative binomial) distribution with parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  nbinpdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the Pascal (negative binomial) distribution with
     parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  normcdf (X, M, S)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the normal distribution with mean M and
     standard deviation S.

     Default values are M = 0, S = 1.

 -- Function File:  norminv (X, M, S)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the normal distribution with mean M and standard
     deviation S.

     Default values are M = 0, S = 1.

 -- Function File:  normpdf (X, M, S)
     For each element of X, compute the probability density function
     (PDF) at X of the normal distribution with mean M and standard
     deviation S.

     Default values are M = 0, S = 1.

 -- Function File:  poisscdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Poisson distribution with parameter
     lambda.

 -- Function File:  poissinv (X, LAMBDA)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Poisson distribution with parameter LAMBDA.

 -- Function File:  poisspdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) at X of the poisson distribution with parameter LAMBDA.

 -- Function File:  tcdf (X, N)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the t (Student) distribution with N degrees
     of freedom, i.e., PROB (t(N) <= X).

 -- Function File:  tinv (X, N)
     For each probability value X, compute the the inverse of the
     cumulative distribution function (CDF) of the t (Student)
     distribution with degrees of freedom N.  This function is
     analagous to looking in a table for the t-value of a single-tailed
     distribution.

 -- Function File:  tpdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the T (Student) distribution with N degrees of
     freedom.

 -- Function File:  unidcdf (X, V)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of a univariate discrete distribution which
     assumes the values in V with equal probability.

 -- Function File:  unidinv (X, V)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the univariate discrete distribution which assumes the
     values in V with equal probability

 -- Function File:  unidpdf (X, V)
     For each element of X, compute the probability density function
     (PDF) at X of a univariate discrete distribution which assumes the
     values in V with equal probability.

 -- Function File:  unifcdf (X, A, B)
     Return the CDF at X of the uniform distribution on [A, B], i.e.,
     PROB (uniform (A, B) <= x).

     Default values are A = 0, B = 1.

 -- Function File:  unifinv (X, A, B)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the uniform distribution on [A, B].

     Default values are A = 0, B = 1.

 -- Function File:  unifpdf (X, A, B)
     For each element of X, compute the PDF at X of the uniform
     distribution on [A, B].

     Default values are A = 0, B = 1.

 -- Function File:  wblcdf (X, SCALE, SHAPE)
     Compute the cumulative distribution function (CDF) at X of the
     Weibull distribution with shape parameter SCALE and scale
     parameter SHAPE, which is

          1 - exp(-(x/shape)^scale)
     for X >= 0.

 -- Function File:  wblinv (X, SCALE, SHAPE)
     Compute the quantile (the inverse of the CDF) at X of the Weibull
     distribution with shape parameter SCALE and scale parameter SHAPE.

 -- Function File:  wblpdf (X, SCALE, SHAPE)
     Compute the probability density function (PDF) at X of the Weibull
     distribution with shape parameter SCALE and scale parameter SHAPE
     which is given by

             scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)

     for X > 0.


File: octave.info,  Node: Random Number Generation,  Prev: Distributions,  Up: Statistics

24.7 Random Number Generation
=============================

Octave can generate random numbers from a large number of distributions.
The random number generators are based on the random number generators
described in *Note Special Utility Matrices::.

   The following table summarizes the available random number generators
(in alphabetical order).

*Distribution*                *Function*
Beta Distribution             `betarnd'
Binomial Distribution         `binornd'
Cauchy Distribution           `cauchy_rnd'
Chi-Square Distribution       `chi2rnd'
Univariate Discrete           `discrete_rnd'
Distribution                  
Empirical Distribution        `empirical_rnd'
Exponential Distribution      `exprnd'
F Distribution                `frnd'
Gamma Distribution            `gamrnd'
Geometric Distribution        `geornd'
Hypergeometric Distribution   `hygernd'
Laplace Distribution          `laplace_rnd'
Logistic Distribution         `logistic_rnd'
Log-Normal Distribution       `lognrnd'
Pascal Distribution           `nbinrnd'
Univariate Normal             `normrnd'
Distribution                  
Poisson Distribution          `poissrnd'
t (Student) Distribution      `trnd'
Univariate Discrete           `unidrnd'
Distribution                  
Uniform Distribution          `unifrnd'
Weibull Distribution          `wblrnd'
Wiener Process                `wienrnd'

 -- Function File:  betarnd (A, B, R, C)
 -- Function File:  betarnd (A, B, SZ)
     Return an R by C or `size (SZ)' matrix of random samples from the
     Beta distribution with parameters A and B.  Both A and B must be
     scalar or of size R  by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  binornd (N, P, R, C)
 -- Function File:  binornd (N, P, SZ)
     Return an R by C  or a `size (SZ)' matrix of random samples from
     the binomial distribution with parameters N and P.  Both N and P
     must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of N and P.

 -- Function File:  cauchy_rnd (LAMBDA, SIGMA, R, C)
 -- Function File:  cauchy_rnd (LAMBDA, SIGMA, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the Cauchy distribution with parameters LAMBDA and SIGMA which
     must both be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of LAMBDA and SIGMA.

 -- Function File:  chi2rnd (N, R, C)
 -- Function File:  chi2rnd (N, SZ)
     Return an R by C  or a `size (SZ)' matrix of random samples from
     the chisquare distribution with N degrees of freedom.  N must be a
     scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the size
     of N.

 -- Function File:  discrete_rnd (N, V, P)
 -- Function File:  discrete_rnd (V, P, R, C)
 -- Function File:  discrete_rnd (V, P, SZ)
     Generate a row vector containing a random sample of size N from
     the univariate distribution which assumes the values in V with
     probabilities P. N must be a scalar.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  empirical_rnd (N, DATA)
 -- Function File:  empirical_rnd (DATA, R, C)
 -- Function File:  empirical_rnd (DATA, SZ)
     Generate a bootstrap sample of size N from the empirical
     distribution obtained from the univariate sample DATA.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  exprnd (LAMBDA, R, C)
 -- Function File:  exprnd (LAMBDA, SZ)
     Return an R by C matrix of random samples from the exponential
     distribution with mean LAMBDA, which must be a scalar or of size R
     by C. Or if SZ is a vector, create a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the size
     of LAMBDA.

 -- Function File:  frnd (M, N, R, C)
 -- Function File:  frnd (M, N, SZ)
     Return an R by C matrix of random samples from the F distribution
     with M and N degrees of freedom.  Both M and N must be scalar or
     of size R by C.  If SZ is a vector the random samples are in a
     matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of M and N.

 -- Function File:  gamrnd (A, B, R, C)
 -- Function File:  gamrnd (A, B, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the Gamma distribution with parameters A and B.  Both A and B must
     be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

     *See also:* gamma, gammaln, gammainc, gampdf, gamcdf, gaminv.

 -- Function File:  geornd (P, R, C)
 -- Function File:  geornd (P, SZ)
     Return an R by C matrix of random samples from the geometric
     distribution with parameter P, which must be a scalar or of size R
     by C.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  hygernd (T, M, N, R, C)
 -- Function File:  hygernd (T, M, N, SZ)
 -- Function File:  hygernd (T, M, N)
     Return an R by C matrix of random samples from the hypergeometric
     distribution with parameters T, M, and N.

     The parameters T, M, and N must positive integers with M and N not
     greater than T.

     The parameter SZ must be scalar or a vector of matrix dimensions.
     If SZ is scalar, then a SZ by SZ matrix of random samples is
     generated.

 -- Function File:  laplace_rnd (R, C)
 -- Function File:  laplace_rnd (SZ);
     Return an R by C matrix of random numbers from the Laplace
     distribution.  Or if SZ is a vector, create a matrix of SZ.

 -- Function File:  logistic_rnd (R, C)
 -- Function File:  logistic_rnd (SZ)
     Return an R by C matrix of random numbers from the logistic
     distribution. Or if SZ is a vector, create a matrix of SZ.

 -- Function File:  lognrnd (MU, SIGMA, R, C)
 -- Function File:  lognrnd (MU, SIGMA, SZ)
     Return an R by C matrix of random samples from the lognormal
     distribution with parameters MU and SIGMA. Both MU and SIGMA must
     be scalar or of size R by C.  Or if SZ is a vector, create a
     matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of MU and SIGMA.

 -- Function File:  nbinrnd (N, P, R, C)
 -- Function File:  nbinrnd (N, P, SZ)
     Return an R by C matrix of random samples from the Pascal
     (negative binomial) distribution with parameters N and P.  Both N
     and P must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of N and P. Or if SZ is a vector, create a matrix of
     size SZ.

 -- Function File:  normrnd (M, S, R, C)
 -- Function File:  normrnd (M, S, SZ)
     Return an R by C  or `size (SZ)' matrix of random samples from the
     normal distribution with parameters mean M and standard deviation
     S.  Both M and S must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of M and S.

 -- Function File:  poissrnd (LAMBDA, R, C)
     Return an R by C matrix of random samples from the Poisson
     distribution with parameter LAMBDA, which must be a scalar or of
     size R by C.

     If R and C are omitted, the size of the result matrix is the size
     of LAMBDA.

 -- Function File:  trnd (N, R, C)
 -- Function File:  trnd (N, SZ)
     Return an R by C matrix of random samples from the t (Student)
     distribution with N degrees of freedom.  N must be a scalar or of
     size R by C. Or if SZ is a vector create a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the size
     of N.

 -- Function File:  unidrnd (MX);
 -- Function File:  unidrnd (MX, V);
 -- Function File:  unidrnd (MX, M, N, ...);
     Return random values from discrete uniform distribution, with
     maximum value(s) given by the integer MX, which may be a scalar or
     multidimensional array.

     If MX is a scalar, the size of the result is specified by the
     vector V, or by the optional arguments M, N, ....  Otherwise, the
     size of the result is the same as the size of MX.

 -- Function File:  unifrnd (A, B, R, C)
 -- Function File:  unifrnd (A, B, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the uniform distribution on [A, B].  Both A and B must be scalar
     or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  wblrnd (SCALE, SHAPE, R, C)
 -- Function File:  wblrnd (SCALE, SHAPE, SZ)
     Return an R by C matrix of random samples from the Weibull
     distribution with parameters SCALE and SHAPE which must be scalar
     or of size R by C. Or if SZ is a vector return a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of ALPHA and SIGMA.

 -- Function File:  wienrnd (T, D, N)
     Return a simulated realization of the D-dimensional Wiener Process
     on the interval [0, T].  If D is omitted, D = 1 is used. The first
     column of the return matrix contains time, the remaining columns
     contain the Wiener process.

     The optional parameter N gives the number of summands used for
     simulating the process over an interval of length 1.  If N is
     omitted, N = 1000 is used.


File: octave.info,  Node: Financial Functions,  Next: Sets,  Prev: Statistics,  Up: Top

25 Financial Functions
**********************

 -- Function File:  fv (R, N, P, L, METHOD)
     Return the future value at the end of period N of an investment
     which consists of N payments of P in each period, assuming an
     interest rate R.

     The optional argument L may be used to specify an additional
     lump-sum payment.

     The optional argument METHOD may be used to specify whether the
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  fvl (R, N, L)
     Return the future value at the end of N periods of an initial lump
     sum investment L, given a per-period interest rate R.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  irr (P, I)
     Return the internal rate of return of a series of payments P from
     an initial investment I (i.e., the solution of `npv (r, p) = i'.
     If the second argument is omitted, a value of 0 is used.

     *See also:* npv, pv, rate.

 -- Function File:  nper (R, P, A, L, METHOD)
     Return the number of regular payments of P necessary to amortize A
     loan of amount A and interest R.

     The optional argument L may be used to specify an additional
     lump-sum payment of L made at the end of the amortization time.

     The optional argument METHOD may be used to specify whether
     payments are made at the end ("E", default) or at the beginning
     ("B") of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

     *See also:* pv, pmt, rate, npv.

 -- Function File:  npv (R, P, I)
     Returns the net present value of a series of irregular (i.e., not
     necessarily identical) payments P which occur at the ends of N
     consecutive periods.  R specifies the one-period interest rates and
     can either be a scalar (constant rates) or a vector of the same
     length as P.

     The optional argument I may be used to specify an initial
     investment.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

     *See also:* irr, pv.

 -- Function File:  pmt (R, N, A, L, METHOD)
     Return the amount of periodic payment necessary to amortize a loan
     of amount a with interest rate R in N periods.

     The optional argument L may be used to specify a terminal lump-sum
     payment.

     The optional argument METHOD may be used to specify whether
     payments are made at the end ("E", default) or at the beginning
     ("B") of each period.

     *See also:* pv, nper, rate.

 -- Function File:  pv (R, N, P, L, METHOD)
     Returns the present value of an investment that will pay off P for
     N consecutive periods, assuming an interest R.

     The optional argument L may be used to specify an additional
     lump-sum payment made at the end of N periods.

     The optional argument METHOD may be used to specify whether
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

     *See also:* pmt, nper, rate, npv.

 -- Function File:  pvl (R, N, P)
     Return the present value of an investment that will pay off P in
     one lump sum at the end of N periods, given the interest rate R.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  rate (N, P, V, L, METHOD)
     Return the rate of return on an investment of present value V which
     pays P in N consecutive periods.

     The optional argument L may be used to specify an additional
     lump-sum payment made at the end of N periods.

     The optional string argument METHOD may be used to specify whether
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     *See also:* pv, pmt, nper, npv.

 -- Function File:  vol (X, M, N)
     Return the volatility of each column of the input matrix X.  The
     number of data sets per period is given by M (e.g. the number of
     data per year if you want to compute the volatility per year).
     The optional parameter N gives the number of past periods used for
     computation, if it is omitted, a value of 1 is used.  If T is the
     number of rows of X, `vol' returns the volatility from `n*m' to T.


File: octave.info,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Financial Functions,  Up: Top

26 Sets
*******

Octave has a limited set of functions for managing sets of data, where a
set is defined as a collection of unique elements.  In Octave a set is
represented as a vector of numbers.

 -- Function File:  create_set (X)
 -- Function File:  create_set (X, "rows")
     Return a row vector containing the unique values in X, sorted in
     ascending order.  For example,

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

     If the optional second input argument is the string "rows" each
     row of the matrix X will be considered an element of set.  For
     example,
          create_set ([ 1, 2; 3, 4; 4, 2; 1, 2 ], "rows")
          =>  1   2
              3   4
              4   2


     *See also:* union, intersection, complement, unique.

 -- Function File:  unique (X)
     Return the unique elements of X, sorted in ascending order.  If X
     is a row vector, return a row vector, but if X is a column vector
     or a matrix return a column vector.

 -- Function File:  unique (A, 'rows')
     Return the unique rows of A, sorted in ascending order.

 -- Function File: [Y, I, J] =  unique (X)
     Return index vectors I and J such that `x(i)==y' and `y(j)==x'.

     Additionally, one of 'first' or 'last' can be given as an argument.
     'last' (default) specifies that the highest possible indices are
     returned in I, while 'first' means the lowest.

     *See also:* union, intersect, setdiff, setxor, ismember.

* Menu:

* Set Operations::


File: octave.info,  Node: Set Operations,  Up: Sets

26.1 Set Operations
===================

Octave supports the basic set operations.  That is, Octave can compute
the union, intersection, complement, and difference of two sets.
Octave can also supports the _Exclusive Or_ set operation, and
membership determination.  The functions for set operations all work in
pretty much the same way.  As an example, assume that `x' and `y'
contains two sets, then

     union(x, y)

computes the union of the two sets.

 -- Function File: [TF, A_IDX] = ismember (A, S)
 -- Function File: [TF, A_IDX] = ismember (A, S, "rows")
     Return a matrix TF the same shape as A which has 1 if `A(i,j)' is
     in S or 0 if it isn't. If a second output argument is requested,
     the indexes into S of the matching elements are also returned.

          a = [3, 10, 1];
          s = [0:9];
          [tf, a_idx] = residue (a, s);
          => tf = [1, 0, 1]
          => a_idx = [4, 0, 2]

     The inputs, A and S, may also be cell arrays.

          a = {'abc'};
          s = {'abc', 'def'};
          [tf, a_idx] = residue (a, s);
          => tf = [1, 0]
          => a_idx = [1, 0]

     With the optional third argument `"rows"', and matrices A and S
     with the same number of columns, compare rows in A with the rows
     in S.

          a = [1:3; 5:7; 4:6];
          s = [0:2; 1:3; 2:4; 3:5; 4:6];
          [tf, a_idx] = ismember(a, s, 'rows');
          => tf = logical ([1; 0; 1])
          => a_idx = [2; 0; 5];


     *See also:* unique, union, intersection, setxor, setdiff.

 -- Function File:  union (A, B)
 -- Function File:  union (A, B, "rows")
     Return the set of elements that are in either of the sets A and B.
     For example,

          union ([1, 2, 4], [2, 3, 5])
          => [1, 2, 3, 4, 5]

     If the optional third input argument is the string "rows" each row
     of the matrices A and B will be considered an element of sets.
     For example,
          union([1, 2; 2, 3], [1, 2; 3, 4], "rows")
          =>  1   2
              2   3
              3   4

 -- Function File: [C, IA, IB] = union (A, B)
     Return index vectors IA and IB such that `a==c(ia)' and `b==c(ib)'.


     *See also:* create_set, intersection, complement.

 -- Function File:  intersect (A, B)
 -- Function File: [C, IA, IB] = intersect (A, B)
     Return the elements in both A and B, sorted in ascending order. If
     A and B are both column vectors return a column vector, otherwise
     return a row vector.

     Return index vectors IA and IB such that `a(ia)==c' and `b(ib)==c'.



*See also:* unique, union, setxor, setdiff, ismember.

 -- Function File:  complement (X, Y)
     Return the elements of set Y that are not in set X.  For example,

          complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
          => 5


     *See also:* create_set, union, intersection.

 -- Function File:  setdiff (A, B)
 -- Function File:  setdiff (A, B, "rows")
 -- Function File: [C, I] =  setdiff (A, B)
     Return the elements in A that are not in B, sorted in ascending
     order.  If A and B are both column vectors return a column vector,
     otherwise return a row vector.

     Given the optional third argument `"rows"', return the rows in A
     that are not in B, sorted in ascending order by rows.

     If requested, return I such that `c = a(i)'.

     *See also:* unique, union, intersect, setxor, ismember.

 -- Function File:  setxor (A, B)
 -- Function File:  setxor (A, B, 'rows')
     Return the elements exclusive to A or B, sorted in ascending
     order. If A and B are both column vectors return a column vector,
     otherwise return a row vector.

 -- Function File: [C, IA, IB] = setxor (A, B)
     Return index vectors IA and IB such that `a==c(ia)' and `b==c(ib)'.


     *See also:* unique, union, intersect, setdiff, ismember.


File: octave.info,  Node: Polynomial Manipulations,  Next: Interpolation,  Prev: Sets,  Up: Top

27 Polynomial Manipulations
***************************

In Octave, a polynomial is represented by its coefficients (arranged in
descending order).  For example, a vector C of length N+1 corresponds
to the following polynomial of order  N

     p(x) = C(1) x^N + ... + C(N) x + C(N+1).

* Menu:

* Evaluating Polynomials::
* Finding Roots::
* Products of Polynomials::
* Derivatives and Integrals::
* Polynomial Interpolation::
* Miscellaneous Functions::


File: octave.info,  Node: Evaluating Polynomials,  Next: Finding Roots,  Up: Polynomial Manipulations

27.1 Evaluating Polynomials
===========================

The value of a polynomial represented by the vector C can be evaluated
at the point X very easily, as the following example shows.

     N = length(c)-1;
     val = dot( x.^(N:-1:0), c );

While the above example shows how easy it is to compute the value of a
polynomial, it isn't the most stable algorithm.  With larger polynomials
you should use more elegant algorithms, such as Horner's Method, which
is exactly what the Octave function `polyval' does.

   In the case where X is a square matrix, the polynomial given by C is
still well-defined.  As when X is a scalar the obvious implementation
is easily expressed in Octave, but also in this case more elegant
algorithms perform better.  The `polyvalm' function provides such an
algorithm.

 -- Function File: Y= polyval (P, X)
 -- Function File: Y= polyval (P, X, [], MU)
     Evaluate the polynomial at of the specified values for X. When MU
     is present evaluate the polynomial for (X-MU(1))/MU(2).  If X is a
     vector or matrix, the polynomial is evaluated for each of the
     elements of X.

 -- Function File: [Y, DY] = polyval (P, X, S)
 -- Function File: [Y, DY] = polyval (P, X, S, MU)
     In addition to evaluating the polynomial, the second output
     represents the prediction interval, Y +/- DY, which contains at
     least 50% of the future predictions. To calculate the prediction
     interval, the structured variable S, originating form `polyfit',
     must be present.

     *See also:* polyfit, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, polyinteg.

 -- Function File:  polyvalm (C, X)
     Evaluate a polynomial in the matrix sense.

     `polyvalm (C, X)' will evaluate the polynomial in the matrix
     sense, i.e. matrix multiplication is used instead of element by
     element multiplication as is used in polyval.

     The argument X must be a square matrix.

     *See also:* polyval, poly, roots, conv, deconv, residue, filter,
     polyderiv, and polyinteg.


File: octave.info,  Node: Finding Roots,  Next: Products of Polynomials,  Prev: Evaluating Polynomials,  Up: Polynomial Manipulations

27.2 Finding Roots
==================

Octave can find the roots of a given polynomial.  This is done by
computing the companion matrix of the polynomial (see the `compan'
function for a definition), and then finding its eigenvalues.

 -- Function File:  roots (V)
     For a vector V with N components, return the roots of the
     polynomial

          v(1) * z^(N-1) + ... + v(N-1) * z + v(N)

     As an example, the following code finds the roots of the quadratic
     polynomial
          p(x) = x^2 - 5.

          c = [1, 0, -5];
          roots(c)
          =>  2.2361
          => -2.2361
     Note that the true result is +/- sqrt(5) which is roughly +/-
     2.2361.

     *See also:* compan.

 -- Function File:  compan (C)
     Compute the companion matrix corresponding to polynomial
     coefficient vector C.

     The companion matrix is

               _                                                        _
              |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(N)/c(1)  -c(N+1)/c(1)  |
              |       1            0      ...       0             0      |
              |       0            1      ...       0             0      |
          A = |       .            .   .            .             .      |
              |       .            .       .        .             .      |
              |       .            .           .    .             .      |
              |_      0            0      ...       1             0     _|

     The eigenvalues of the companion matrix are equal to the roots of
     the polynomial.

     *See also:* poly, roots, residue, conv, deconv, polyval, polyderiv,
     polyinteg.


File: octave.info,  Node: Products of Polynomials,  Next: Derivatives and Integrals,  Prev: Finding Roots,  Up: Polynomial Manipulations

27.3 Products of Polynomials
============================

 -- Function File:  conv (A, B)
     Convolve two vectors.

     `y = conv (a, b)' returns a vector of length equal to `length (a)
     + length (b) - 1'.  If A and B are polynomial coefficient vectors,
     `conv' returns the coefficients of the product polynomial.

     *See also:* deconv, poly, roots, residue, polyval, polyderiv,
     polyinteg.

 -- Function File:  deconv (Y, A)
     Deconvolve two vectors.

     `[b, r] = deconv (y, a)' solves for B and R such that `y = conv
     (a, b) + r'.

     If Y and A are polynomial coefficient vectors, B will contain the
     coefficients of the polynomial quotient and R will be a remainder
     polynomial of lowest order.

     *See also:* conv, poly, roots, residue, polyval, polyderiv,
     polyinteg.

 -- Loadable Function: y = conv2 (A, B, SHAPE)
 -- Loadable Function: y = conv2 (V1, V2, M, SHAPE)
     Returns 2D convolution of A and B where the size of C is given by

    SHAPE= 'full'
          returns full 2-D convolution

    SHAPE= 'same'
          same size as a. 'central' part of convolution

    SHAPE= 'valid'
          only parts which do not include zero-padded edges

     By default SHAPE is 'full'. When the third argument is a matrix
     returns the convolution of the matrix M by the vector V1 in the
     column direction and by vector V2 in the row direction

 -- Function File: Q = polygcd (B, A, TOL)
     Find greatest common divisor of two polynomials.  This is
     equivalent to the polynomial found by multiplying together all the
     common roots.  Together with deconv, you can reduce a ratio of two
     polynomials.  Tolerance defaults to
          sqrt(eps).
      Note that this is an unstable algorithm, so don't try it on large
     polynomials.

     Example
          polygcd (poly(1:8), poly(3:12)) - poly(3:8)
          => [ 0, 0, 0, 0, 0, 0, 0 ]
          deconv (poly(1:8), polygcd (poly(1:8), poly(3:12))) ...
            - poly(1:2)
          => [ 0, 0, 0 ]


     *See also:* poly, polyinteg, polyderiv, polyreduce, roots, conv,
     deconv, residue, filter, polyval, and polyvalm.

 -- Function File: [R, P, K, E] = residue (B, A)
     Compute the partial fraction expansion for the quotient of the
     polynomials, B and A.

           B(s)    M       r(m)         N
           ---- = SUM -------------  + SUM k(i)*s^(N-i)
           A(s)   m=1 (s-p(m))^e(m)    i=1

     where M is the number of poles (the length of the R, P, and E),
     the K vector is a polynomial of order N-1 representing the direct
     contribution, and the E vector specifies the multiplicity of the
     mth residue's pole.

     For example,

          b = [1, 1, 1];
          a = [1, -5, 8, -4];
          [r, p, k, e] = residue (b, a);
          => r = [-2; 7; 3]
          => p = [2; 2; 1]
          => k = [](0x0)
          => e = [1; 2; 1]

     which represents the following partial fraction expansion

                  s^2 + s + 1       -2        7        3
             ------------------- = ----- + ------- + -----
             s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)

 -- Function File: [B, A] = residue (R, P, K)
 -- Function File: [B, A] = residue (R, P, K, E)
     Compute the reconstituted quotient of polynomials, B(s)/A(s), from
     the partial fraction expansion; represented by the residues,
     poles, and a direct polynomial specified by R, P and K, and the
     pole multiplicity E.

     If the multiplicity, E, is not explicitly specified the
     multiplicity is determined by the script mpoles.m.

     For example,

          r = [-2; 7; 3];
          p = [2; 2; 1];
          k = [1, 0];
          [b, a] = residue (r, p, k);
          => b = [1, -5, 9, -3, 1]
          => a = [1, -5, 8, -4]

          where mpoles.m is used to determine e = [1; 2; 1]

     Alternatively the multiplicity may be defined explicitly, for
     example,

          r = [7; 3; -2];
          p = [2; 1; 2];
          k = [1, 0];
          e = [2; 1; 1];
          [b, a] = residue (r, p, k, e);
          => b = [1, -5, 9, -3, 1]
          => a = [1, -5, 8, -4]

     which represents the following partial fraction expansion

              -2        7        3         s^4 - 5s^3 + 9s^2 - 3s + 1
             ----- + ------- + ----- + s = --------------------------
             (s-2)   (s-2)^2   (s-1)          s^3 - 5s^2 + 8s - 4


     *See also:* poly, roots, conv, deconv, mpoles, polyval, polyderiv,
     polyinteg.


File: octave.info,  Node: Derivatives and Integrals,  Next: Polynomial Interpolation,  Prev: Products of Polynomials,  Up: Polynomial Manipulations

27.4 Derivatives and Integrals
==============================

Octave comes with functions for computing the derivative and the
integral of a polynomial.  The functions `polyderiv' and `polyint' both
return new polynomials describing the result.  As an example we'll
compute the definite integral of p(x) = x^2 + 1 from 0 to 3.

     c = [1, 0, 1];
     integral = polyint(c);
     area = polyval(integral, 3) - polyval(integral, 0)
     => 12

 -- Function File:  polyderiv (C)
 -- Function File: [Q] = polyderiv (B, A)
 -- Function File: [Q, R] = polyderiv (B, A)
     Return the coefficients of the derivative of the polynomial whose
     coefficients are given by vector C.  If a pair of polynomials is
     given B and A, the derivative of the product is returned in Q, or
     the quotient numerator in Q and the quotient denominator in R.

     *See also:* poly, polyinteg, polyreduce, roots, conv, deconv,
     residue, filter, polygcd, polyval, polyvalm.

 -- Function File:  polyder (C)
 -- Function File: [Q] = polyder (B, A)
 -- Function File: [Q, R] = polyder (B, A)
     See polyderiv.

 -- Function File:  polyint (C, K)
     Return the coefficients of the integral of the polynomial whose
     coefficients are represented by the vector C. The variable K is
     the constant of integration, which by default is set to zero.

     *See also:* poly, polyderiv, polyreduce, roots, conv, deconv,
     residue, filter, polyval, and polyvalm.


File: octave.info,  Node: Polynomial Interpolation,  Next: Miscellaneous Functions,  Prev: Derivatives and Integrals,  Up: Polynomial Manipulations

27.5 Polynomial Interpolation
=============================

Octave comes with good support for various kinds of interpolation, most
of which are described in *Note Interpolation::.  One simple alternative
to the functions described in the aforementioned chapter, is to fit a
single polynomial to some given data points.  To avoid a highly
fluctuating polynomial, one most often wants to fit a low-order
polynomial to data.  This usually means that it is necessary to fit the
polynomial in a least-squares sense, which is what the `polyfit'
function does.

 -- Function File: [P, S, MU] = polyfit (X, Y, N)
     Return the coefficients of a polynomial P(X) of degree N that
     minimizes the least-squares-error of the fit.

     The polynomial coefficients are returned in a row vector.

     The second output is a structure containing the following fields:

    `R'
          Triangular factor R from the QR decomposition.

    `X'
          The Vandermonde matrix used to compute the polynomial
          coefficients.

    `df'
          The degrees of freedom.

    `normr'
          The norm of the residuals.

    `yf'
          The values of the polynomial for each value of X.

     The second output may be used by `polyval' to calculate the
     statistical error limits of the predicted values.

     When the third output, MU, is present the coefficients, P, are
     associated with a polynomial in XHAT = (X-MU(1))/MU(2).  Where
     MU(1) = mean (X), and MU(2) = std (X).  This linear transformation
     of X improves the numerical stability of the fit.

     *See also:* polyval, polyconf, residue.

   In situations where a single polynomial isn't good enough, a solution
is to use several polynomials pieced together.  The function `mkpp'
creates a piece-wise polynomial, `ppval' evaluates the function created
by `mkpp', and `unmkpp' returns detailed information about the function.

   The following example shows how to combine two linear functions and a
quadratic into one function.  Each of these functions is expressed on
adjoined intervals.

     x = [-2, -1, 1, 2];
     p = [ 0,  1, 0;
           1, -2, 1;
           0, -1, 1 ];
     pp = mkpp(x, p);
     xi = linspace(-2, 2, 50);
     yi = ppval(pp, xi);
     plot(xi, yi);

 -- Function File: YI = ppval (PP, XI)
     Evaluate piece-wise polynomial PP at the points XI.  If `PP.d' is
     a scalar greater than 1, or an array, then the returned value YI
     will be an array that is `d1, d1, ..., dk, length (XI)]'.

     *See also:* mkpp, unmkpp, spline.

 -- Function File: PP =  mkpp (X, P)
 -- Function File: PP =  mkpp (X, P, D)
     Construct a piece-wise polynomial structure from sample points X
     and coefficients P.  The ith row of P, `P (I,:)', contains the
     coefficients for the polynomial over the I-th interval, ordered
     from highest to lowest. There must be one row for each interval in
     X, so `rows (P) == length (X) - 1'.

     You can concatenate multiple polynomials of the same order over the
     same set of intervals using `P = [ P1; P2; ...; PD ]'.  In this
     case, `rows (P) == D * (length (X) - 1)'.

     D specifies the shape of the matrix P for all except the last
     dimension. If D is not specified it will be computed as `round
     (rows (P) / (length (X) - 1))' instead.


     *See also:* unmkpp, ppval, spline.

 -- Function File: [X, P, N, K, D] = unmkpp (PP)
     Extract the components of a piece-wise polynomial structure PP.
     These are as follows:

    X
          Samples points.

    P
          Polynomial coefficients for points in sample interval. `P (I,
          :)' contains the coefficients for the polynomial over
          interval I ordered from highest to lowest. If `D > 1', `P (R,
          I, :)' contains the coefficients for the r-th polynomial
          defined on interval I. However, this is stored as a 2-D array
          such that `C = reshape (P (:, J), N, D)' gives `C (I,  R)' is
          the j-th coefficient of the r-th polynomial over the i-th
          interval.

    N
          Number of polynomial pieces.

    K
          Order of the polynomial plus 1.

    D
          Number of polynomials defined for each interval.


     *See also:* mkpp, ppval, spline.


File: octave.info,  Node: Miscellaneous Functions,  Prev: Polynomial Interpolation,  Up: Polynomial Manipulations

27.6 Miscellaneous Functions
============================

 -- Function File:  poly (A)
     If A is a square N-by-N matrix, `poly (A)' is the row vector of
     the coefficients of `det (z * eye (N) - a)', the characteristic
     polynomial of A.  As an example we can use this to find the
     eigenvalues of A as the roots of `poly (A)'.
          roots(poly(eye(3)))
          => 1.00000 + 0.00000i
          => 1.00000 - 0.00000i
          => 1.00000 + 0.00000i
     In real-life examples you should, however, use the `eig' function
     for computing eigenvalues.

     If X is a vector, `poly (X)' is a vector of coefficients of the
     polynomial whose roots are the elements of X.  That is, of C is a
     polynomial, then the elements of `D = roots (poly (C))' are
     contained in C.  The vectors C and D are, however, not equal due
     to sorting and numerical errors.

     *See also:* eig, roots.

 -- Function File:  polyout (C, X)
     Write formatted polynomial
             c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
      and return it as a string or write it to the screen (if NARGOUT
     is zero).  X defaults to the string `"s"'.

     *See also:* polyval, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, and polyinteg.

 -- Function File:  polyreduce (C)
     Reduces a polynomial coefficient vector to a minimum number of
     terms by stripping off any leading zeros.

     *See also:* poly, roots, conv, deconv, residue, filter, polyval,
     polyvalm, polyderiv, polyinteg.


File: octave.info,  Node: Interpolation,  Next: Geometry,  Prev: Polynomial Manipulations,  Up: Top

28 Interpolation
****************

* Menu:

* One-dimensional Interpolation::
* Multi-dimensional Interpolation::


File: octave.info,  Node: One-dimensional Interpolation,  Next: Multi-dimensional Interpolation,  Up: Interpolation

28.1 One-dimensional Interpolation
==================================

Octave supports several methods for one-dimensional interpolation, most
of which are described in this section.  *Note Polynomial
Interpolation:: and *Note Interpolation on Scattered Data:: describes
further methods.

 -- Function File: YI = interp1 (X, Y, XI)
 -- Function File: YI = interp1 (..., METHOD)
 -- Function File: YI = interp1 (..., EXTRAP)
 -- Function File: PP = interp1 (..., 'pp')
     One-dimensional interpolation. Interpolate Y, defined at the
     points X, at the points XI. The sample points X must be strictly
     monotonic. If Y is an array, treat the columns of Y separately.

     Method is one of:

    'nearest'
          Return the nearest neighbour.

    'linear'
          Linear interpolation from nearest neighbours

    'pchip'
          Piece-wise cubic hermite interpolating polynomial

    'cubic'
          Cubic interpolation from four nearest neighbours

    'spline'
          Cubic spline interpolation-smooth first and second derivatives
          throughout the curve

     Appending '*' to the start of the above method forces `interp1' to
     assume that X is uniformly spaced, and only `X (1)' and `X (2)'
     are referenced. This is usually faster, and is never slower. The
     default method is 'linear'.

     If EXTRAP is the string 'extrap', then extrapolate values beyond
     the endpoints.  If EXTRAP is a number, replace values beyond the
     endpoints with that number.  If EXTRAP is missing, assume NA.

     If the string argument 'pp' is specified, then XI should not be
     supplied and `interp1' returns the piece-wise polynomial that can
     later be used with `ppval' to evaluate the interpolation.  There
     is an equivalence, such that `ppval (interp1 (X, Y, METHOD, 'pp'),
     XI) == interp1 (X, Y, XI, METHOD, 'extrap')'.

     An example of the use of `interp1' is

             xf=[0:0.05:10]; yf = sin(2*pi*xf/5);
             xp=[0:10];      yp = sin(2*pi*xp/5);
             lin=interp1(xp,yp,xf);
             spl=interp1(xp,yp,xf,'spline');
             cub=interp1(xp,yp,xf,'cubic');
             near=interp1(xp,yp,xf,'nearest');
             plot(xf,yf,"r",xf,lin,"g",xf,spl,"b", ...
                  xf,cub,"c",xf,near,"m",xp,yp,"r*");
             legend ("original","linear","spline","cubic","nearest")


     *See also:* interpft.

   There are some important differences between the various
interpolation methods. The 'spline' method enforces that both the first
and second derivatives of the interpolated values have a continuous
derivative, whereas the other methods do not. This means that the
results of the 'spline' method are generally smoother. If the function
to be interpolated is in fact smooth, then 'spline' will give excellent
results. However, if the function to be evaluated is in some manner
discontinuous, then 'pchip' interpolation might give better results.

   This can be demonstrated by the code

     t = -2:2;
     dt = 1;
     ti =-2:0.025:2;
     dti = 0.025;
     y = sign(t);
     ys = interp1(t,y,ti,'spline');
     yp = interp1(t,y,ti,'pchip');
     ddys = diff(diff(ys)./dti)./dti;
     ddyp = diff(diff(yp)./dti)./dti;
     figure(1);
     plot (ti, ys,'r-', ti, yp,'g-');
     legend('spline','pchip',4);
     figure(2);
     plot (ti, ddys,'r+', ti, ddyp,'g*');
     legend('spline','pchip');

   Fourier interpolation, is a resampling technique where a signal is
converted to the frequency domain, padded with zeros and then
reconverted to the time domain.

 -- Function File:  interpft (X, N)
 -- Function File:  interpft (X, N, DIM)
     Fourier interpolation. If X is a vector, then X is resampled with
     N points. The data in X is assumed to be equispaced. If X is an
     array, then operate along each column of the array separately. If
     DIM is specified, then interpolate along the dimension DIM.

     `interpft' assumes that the interpolated function is periodic, and
     so assumptions are made about the end points of the interpolation.


     *See also:* interp1.

   There are two significant limitations on Fourier interpolation.
Firstly, the function signal is assumed to be periodic, and so non
periodic signals will be poorly represented at the edges. Secondly,
both the signal and its interpolation are required to be sampled at
equispaced points. An example of the use of `interpft' is

     t = 0 : 0.3 : pi; dt = t(2)-t(1);
     n = length (t); k = 100;
     ti = t(1) + [0 : k-1]*dt*n/k;
     y = sin (4*t + 0.3) .* cos (3*t - 0.1);
     yp = sin (4*ti + 0.3) .* cos (3*ti - 0.1);
     plot (ti, yp, 'g', ti, interp1(t, y, ti, 'spline'), 'b', ...
           ti, interpft (y, k), 'c', t, y, 'r+');
     legend ('sin(4t+0.3)cos(3t-0.1','spline','interpft','data');

   which demonstrates the poor behavior of Fourier interpolation for non
periodic functions.

   In additional the support function `spline' and `lookup' that
underlie the `interp1' function can be called directly.

 -- Function File: PP =  spline (X, Y)
 -- Function File: YI =  spline (X, Y, XI)
     Returns the cubic spline interpolation of Y at the point X. Called
     with two arguments the piece-wise polynomial PP that may later be
     used with `ppval' to evaluate the polynomial at specific points.

     The variable X must be a vector of length N, and Y can be either a
     vector or array. In the case where Y is a vector, it can have a
     length of either N or `N + 2'.  If the length of Y is N, then the
     'not-a-knot' end condition is used. If the length of Y is `N + 2',
     then the first and last values of the vector Y are the first
     derivative of the cubic spline at the end-points.

     If Y is an array, then the size of Y must have the form `[S1, S2,
     ..., SK, N]' or `[S1, S2, ..., SK, N + 2]'.  The array is then
     reshaped internally to a matrix where to leading dimension is
     given by `S1 * S2 * ... * SK' and each row this matrix is then
     treated separately. Note that this is exactly the opposite
     treatment than `interp1' and is done for compatibility.

     Called with a third input argument, `spline' evaluates the
     piece-wise spline at the points XI. There is an equivalence
     between `ppval (spline (X, Y), XI)' and `spline (X, Y, XI)'.


     *See also:* ppval, mkpp, unmkpp.

   The `lookup' is used by other interpolation function to identify the
points of the original data that are closest to the current point of
interest.

 -- Function File: IDX = lookup (TABLE, Y)
     Lookup values in a sorted table.  Usually used as a prelude to
     interpolation.

     If table is strictly increasing and `idx = lookup (table, y)', then
     `table(idx(i)) <= y(i) < table(idx(i+1))' for all `y(i)' within
     the table.  If `y(i)' is before the table, then `idx(i)' is 0. If
     `y(i)' is after the table then `idx(i)' is `table(n)'.

     If the table is strictly decreasing, then the tests are reversed.
     There are no guarantees for tables which are non-monotonic or are
     not strictly monotonic.

     To get an index value which lies within an interval of the table,
     use:

          idx = lookup (table(2:length(table)-1), y) + 1

     This expression puts values before the table into the first
     interval, and values after the table into the last interval.


File: octave.info,  Node: Multi-dimensional Interpolation,  Prev: One-dimensional Interpolation,  Up: Interpolation

28.2 Multi-dimensional Interpolation
====================================

There are three multi-dimensional interpolation functions in Octave,
with similar capabilities.  Methods using Delaunay tessellation are
described in *Note Interpolation on Scattered Data::.

 -- Function File: ZI= interp2 (X, Y, Z, XI, YI)
 -- Function File: ZI= interp2 (Z, XI, YI)
 -- Function File: ZI= interp2 (Z, N)
 -- Function File: ZI= interp2 (..., METHOD)
 -- Function File: ZI= interp2 (..., METHOD, EXTRAPVAL)
     Two-dimensional interpolation. X, Y and Z describe a surface
     function. If X and Y are vectors their length must correspondent
     to the size of Z. X and YY must be monotonic. If they are matrices
     they  must have the `meshgrid' format.

    `interp2 (X, Y, Z, XI, YI, ...)'
          Returns a matrix corresponding to the points described by the
          matrices  XI, YI.

          If the last argument is a string, the interpolation method can
          be specified. The method can be 'linear', 'nearest' or
          'cubic'.  If it is omitted 'linear' interpolation  is assumed.

    `interp2 (Z, XI, YI)'
          Assumes `X = 1:rows (Z)' and `Y = 1:columns (Z)'

    `interp2 (Z, N)'
          Interleaves the Matrix Z n-times. If N is omitted a value of
          `N = 1' is assumed.

     The variable METHOD defines the method to use for the
     interpolation. It can take one of the values

    'nearest'
          Return the nearest neighbor.

    'linear'
          Linear interpolation from nearest neighbors.

    'pchip'
          Piece-wise cubic hermite interpolating polynomial (not
          implemented yet).

    'cubic'
          Cubic interpolation from four nearest neighbors.

    'spline'
          Cubic spline interpolation-smooth first and second derivatives
          throughout the curve.

     If a scalar value EXTRAPVAL is defined as the final value, then
     values outside the mesh as set to this value. Note that in this
     case METHOD must be defined as well. If EXTRAPVAL is not defined
     then NA is assumed.


     *See also:* interp1.

 -- Function File: VI = interp3 (X, Y,Z, V, XI, YI, ZI)
 -- Function File: VI = interp3 (V, XI, YI, ZI)
 -- Function File: VI = interp3 (V, M)
 -- Function File: VI = interp3 (V)
 -- Function File: VI = interp3 (..., METHOD)
 -- Function File: VI = interp3 (..., METHOD, EXTRAPVAL)
     Perform 3-dimensional interpolation. Each element of then
     3-dimensional array V represents a value at a location given by
     the parameters X, Y, and Z. The parameters X, X, and Z are either
     3-dimensional arrays of the same size as the array V in the
     'meshgrid' format or vectors. The parameters XI, etc respect a
     similar format to X, etc, and they represent the points at which
     the array VI is interpolated.

     If X, Y, Z are omitted, they are assumed to be `x = 1 : size (V,
     2)', `y = 1 : size (V, 1)' and `z = 1 : size (V, 3)'. If M is
     specified, then the interpolation adds a point half way between
     each of the interpolation points. This process is performed M
     times. If only V is specified, then M is assumed to be `1'.

     Method is one of:

    'nearest'
          Return the nearest neighbour.

    'linear'
          Linear interpolation from nearest neighbours.

    'cubic'
          Cubic interpolation from four nearest neighbours (not
          implemented yet).

    'spline'
          Cubic spline interpolation-smooth first and second derivatives
          throughout the curve.

     The default method is 'linear'.

     If EXTRAP is the string 'extrap', then extrapolate values beyond
     the endpoints.  If EXTRAP is a number, replace values beyond the
     endpoints with that number.  If EXTRAP is missing, assume NA.

     *See also:* interp1, interp2, spline, meshgrid.

 -- Function File: VI = interpn (X1, X2, ..., V, Y1, Y2, ...)
 -- Function File: VI = interpn (V, Y1, Y2, ...)
 -- Function File: VI = interpn (V, M)
 -- Function File: VI = interpn (V)
 -- Function File: VI = interpn (..., METHOD)
 -- Function File: VI = interpn (..., METHOD, EXTRAPVAL)
     Perform N-dimensional interpolation, where N is at least two.
     Each element of then N-dimensional array V represents a value at a
     location given by the parameters X1, X2, ..., XN.  The parameters
     X1, X2, ..., XN are either N-dimensional arrays of the same size
     as the array V in the 'ndgrid' format or vectors. The parameters
     Y1, etc respect a similar format to X1, etc, and they represent
     the points at which the array VI is interpolated.

     If X1, ..., XN are omitted, they are assumed to be `x1 = 1 : size
     (V, 1)', etc. If M is specified, then the interpolation adds a
     point half way between each of the interpolation points. This
     process is performed M times. If only V is specified, then M is
     assumed to be `1'.

     Method is one of:

    'nearest'
          Return the nearest neighbour.

    'linear'
          Linear interpolation from nearest neighbours.

    'cubic'
          Cubic interpolation from four nearest neighbours (not
          implemented yet).

    'spline'
          Cubic spline interpolation-smooth first and second derivatives
          throughout the curve.

     The default method is 'linear'.

     If EXTRAPVAL is the scalar value, use it to replace the values
     beyond the endpoints with that number. If EXTRAPVAL is missing,
     assume NA.

     *See also:* interp1, interp2, spline, ndgrid.

   A significant difference between `interpn' and the other two
multidimensional interpolation functions is the fashion in which the
dimensions are treated. For `interp2' and `interp3', the 'y' axis is
considered to be the columns of the matrix, whereas the 'x' axis
corresponds to the rows of the array. As Octave indexes arrays in
column major order, the first dimension of any array is the columns, and
so `interpn' effectively reverses the 'x' and 'y' dimensions.  Consider
the example

     x = y = z = -1:1;
     f = @(x,y,z) x.^2 - y - z.^2;
     [xx, yy, zz] = meshgrid (x, y, z);
     v = f (xx,yy,zz);
     xi = yi = zi = -1:0.1:1;
     [xxi, yyi, zzi] = meshgrid (xi, yi, zi);
     vi = interp3(x, y, z, v, xxi, yyi, zzi, 'spline');
     [xxi, yyi, zzi] = ndgrid (xi, yi, zi);
     vi2 = interpn(x, y, z, v, xxi, yyi, zzi, 'spline');
     mesh (zi, yi, squeeze (vi2(1,:,:)));

where `vi' and `vi2' are identical. The reversal of the dimensions is
treated in the `meshgrid' and `ndgrid' functions respectively.

   In additional the support function `bicubic' that underlies the
cubic interpolation of `interp2' function can be called directly.

 -- Function File: ZI= bicubic (X, Y, Z, XI, YI, EXTRAPVAL)
     Return a matrix ZI corresponding to the bicubic interpolations at
     XI and YI of the data supplied as X, Y and Z. Points outside the
     grid are set to EXTRAPVAL

     See `http://wiki.woodpecker.org.cn/moin/Octave/Bicubic' for
     further information.

     *See also:* interp2.


File: octave.info,  Node: Geometry,  Next: Control Theory,  Prev: Interpolation,  Up: Top

29 Geometry
***********

Much of geometry code in Octave is based on the QHull (1). Some of the
documentation for Qhull, particularly for the options that can be
passed to `delaunay', `voronoi' and `convhull', etc, is relevant to
Octave users.

* Menu:

* Delaunay Triangulation::
* Voronoi Diagrams::
* Convex Hull::
* Interpolation on Scattered Data::

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

   (1) Barber, C.B., Dobkin, D.P., and Huhdanpaa, H.T., "The Quickhull
algorithm for convex hulls," ACM Trans. on Mathematical Software,
22(4):469-483, Dec 1996, `http://www.qhull.org'


File: octave.info,  Node: Delaunay Triangulation,  Next: Voronoi Diagrams,  Up: Geometry

29.1 Delaunay Triangulation
===========================

The Delaunay triangulation is constructed from a set of circum-circles.
These circum-circles are chosen so that there are at least three of the
points in the set to triangulation on the circumference of the
circum-circle. None of the points in the set of points falls within any
of the circum-circles.

   In general there are only three points on the circumference of any
circum-circle. However, in some cases, and in particular for the case
of a regular grid, 4 or more points can be on a single circum-circle.
In this case the Delaunay triangulation is not unique.

 -- Function File: TRI= delaunay (X, Y)
 -- Function File: TRI= delaunay (X, Y, OPT)
     The return matrix of size [n, 3] contains a set triangles which are
     described by the indices to the data point x and y vector.  The
     triangulation satisfies the Delaunay circumcircle criterion.  No
     other data point is in the circumcircle of the defining triangle.

     A third optional argument, which must be a string, contains extra
     options passed to the underlying qhull command.  See the
     documentation for the Qhull library for details.

          x = rand (1, 10);
          y = rand (size (x));
          T = delaunay (x, y);
          X = [x(T(:,1)); x(T(:,2)); x(T(:,3)); x(T(:,1))];
          Y = [y(T(:,1)); y(T(:,2)); y(T(:,3)); y(T(:,1))];
          axis ([0,1,0,1]);
          plot (X, Y, "b", x, y, "r*");


     *See also:* voronoi, delaunay3, delaunayn.

   The 3- and N-dimensional extension of the Delaunay triangulation are
given by `delaunay3' and `delaunayn' respectively.  `delaunay3' returns
a set of tetrahedra that satisfy the Delaunay circum-circle criteria.
Similarly, `delaunayn' returns the N-dimensional simplex satisfying the
Delaunay circum-circle criteria.  The N-dimensional extension of a
triangulation is called a tessellation.

 -- Function File: T = delaunay3 (X, Y, Z)
 -- Function File: T = delaunay3 (X, Y, Z, OPT)
     A matrix of size [n, 4] is returned. Each row contains a set of
     tetrahedron which are described by the indices to the data point
     vectors (x,y,z).

     A fourth optional argument, which must be a string or cell array
     of strings, contains extra options passed to the underlying qhull
     command.  See the documentation for the Qhull library for details.

     *See also:* delaunay,delaunayn.

 -- Function File: T = delaunayn (P)
 -- Function File: T = delaunayn (P, OPT)
     Form the Delaunay triangulation for a set of points.  The Delaunay
     triangulation is a tessellation of the convex hull of the points
     such that no n-sphere defined by the n-triangles contains any
     other points from the set.  The input matrix P of size `[n, dim]'
     contains N points in a space of dimension dim. The return matrix T
     has the size `[m, dim+1]'.  It contains for each row a set of
     indices to the points, which describes a simplex of dimension dim.
     For example, a 2d simplex is a triangle and 3d simplex is a
     tetrahedron.

     Extra options for the underlying Qhull command can be specified by
     the second argument. This argument is a cell array of strings. The
     default options depend on the dimension of the input:

        * 2D and 3D: OPT = `{"Qt", "Qbb", "Qc"}'

        * 4D and higher: OPT = `{"Qt", "Qbb", "Qc", "Qz"}'

     If OPT is [], then the default arguments are used. If OPT is
     `{""}', then none of the default arguments are used by Qhull.  See
     the Qhull documentation for the available options.

     All options can also be specified as single string, for example
     `"Qt Qbb Qc Qz"'.


   An example of a Delaunay triangulation of a set of points is

     rand ("state", 2);
     x = rand (10, 1);
     y = rand (10, 1);
     T = delaunay (x, y);
     X = [ x(T(:,1)); x(T(:,2)); x(T(:,3)); x(T(:,1)) ];
     Y = [ y(T(:,1)); y(T(:,2)); y(T(:,3)); y(T(:,1)) ];
     axis ([0, 1, 0, 1]);
     plot(X, Y, "b", x, y, "r*");

* Menu:

* Plotting the Triangulation::
* Identifying points in Triangulation::


File: octave.info,  Node: Plotting the Triangulation,  Next: Identifying points in Triangulation,  Up: Delaunay Triangulation

29.1.1 Plotting the Triangulation
---------------------------------

Octave has the functions `triplot' and `trimesh' to plot the Delaunay
triangulation of a 2-dimensional set of points.

 -- Function File:  triplot (TRI, X, Y)
 -- Function File:  triplot (TRI, X, Y, LINESPEC)
 -- Function File: H =  triplot (...)
     Plot a triangular mesh in 2D. The variable TRI is the triangular
     meshing of the points `(X, Y)' which is returned from `delaunay'.
     If given, the LINESPEC determines the properties to use for the
     lines. The output argument H is the graphic handle to the plot.

     *See also:* plot, trimesh, delaunay.

 -- Function File:  trimesh (TRI, X, Y, Z)
 -- Function File: H =  trimesh (...)
     Plot a triangular mesh in 3D. The variable TRI is the triangular
     meshing of the points `(X, Y)' which is returned from `delaunay'.
     The variable Z is value at the point `(X, Y)'. The output argument
     H is the graphic handle to the plot.

     *See also:* triplot, delaunay3.

   The difference between `triplot' and `trimesh' is that the former
only plots the 2-dimensional triangulation itself, whereas the second
plots the value of some function `f (X, Y)'.  An example of the use of
the `triplot' function is

     rand ("state", 2)
     x = rand (20, 1);
     y = rand (20, 1);
     tri = delaunay (x, y);
     triplot (tri, x, y);

   that plot the Delaunay triangulation of a set of random points in
2-dimensions.


File: octave.info,  Node: Identifying points in Triangulation,  Prev: Plotting the Triangulation,  Up: Delaunay Triangulation

29.1.2 Identifying points in Triangulation
------------------------------------------

It is often necessary to identify whether a particular point in the
N-dimensional space is within the Delaunay tessellation of a set of
points in this N-dimensional space, and if so which N-Simplex contains
the point and which point in the tessellation is closest to the desired
point.  The functions `tsearch' and `dsearch' perform this function in
a triangulation, and `tsearchn' and `dsearchn' in an N-dimensional
tessellation.

   To identify whether a particular point represented by a vector P
falls within one of the simplices of an N-Simplex, we can write the
Cartesian coordinates of the point in a parametric form with respect to
the N-Simplex.  This parametric form is called the Barycentric
Coordinates of the point.  If the points defining the N-Simplex are
given by `N + 1' vectors T(I,:), then the Barycentric coordinates
defining the point P is given by

     P = sum (BETA(1:N+1) * T(1:N+1),:)

where there are `N + 1' values `BETA(I)' that together as a vector
represent the Barycentric coordinates of the point P.  To ensure a
unique solution for the values of `BETA(I)' an additional criteria of

     sum (BETA(1:N+1)) == 1

is imposed, and we can therefore write the above as

     P - T(end, :) = BETA(1:end-1) * (T(1:end-1, :)
           - ones(N, 1) * T(end, :)

Solving for BETA we can then write

     BETA(1:end-1) = (P - T(end, :)) / (T(1:end-1, :)
           - ones(N, 1) * T(end, :))
     BETA(end) = sum(BETA(1:end-1))

which gives the formula for the conversion of the Cartesian coordinates
of the point P to the Barycentric coordinates BETA.  An important
property of the Barycentric coordinates is that for all points in the
N-Simplex

     0 <= BETA(I) <= 1

Therefore, the test in `tsearch' and `tsearchn' essentially only needs
to express each point in terms of the Barycentric coordinates of each
of the simplices of the N-Simplex and test the values of BETA. This is
exactly the implementation used in `tsearchn'. `tsearch' is optimized
for 2-dimensions and the Barycentric coordinates are not explicitly
formed.

 -- Loadable Function: IDX = tsearch (X, Y, T, XI, YI)
     Searches for the enclosing Delaunay convex hull. For `T = delaunay
     (X, Y)', finds the index in T containing the points `(XI, YI)'.
     For points outside the convex hull, IDX is NaN.

     *See also:* delaunay, delaunayn.

 -- Function File: [IDX, P] = tsearchn (X, T, XI)
     Searches for the enclosing Delaunay convex hull. For `T =
     delaunayn (X)', finds the index in T containing the points XI. For
     points outside the convex hull, IDX is NaN.  If requested
     `tsearchn' also returns the barycentric coordinates P of the
     enclosing triangles.

     *See also:* delaunay, delaunayn.

   An example of the use of `tsearch' can be seen with the simple
triangulation

     X = [-1; -1; 1; 1];
     Y = [-1; 1; -1; 1];
     TRI = [1, 2, 3; 2, 3, 1];

consisting of two triangles defined by TRI. We can then identify which
triangle a point falls in like

     tsearch (X, Y, TRI, -0.5, -0.5)
     => 1
     tsearch (X, Y, TRI, 0.5, 0.5)
     => 2

and we can confirm that a point doesn't lie within one of the triangles
like

     tsearch (X, Y, TRI, 2, 2)
     => NaN

   The `dsearch' and `dsearchn' find the closest point in a
tessellation to the desired point. The desired point does not
necessarily have to be in the tessellation, and even if it the returned
point of the tessellation does not have to be one of the vertexes of the
N-simplex within which the desired point is found.

 -- Function File: IDX = dsearch (X, Y, TRI, XI, YI)
 -- Function File: IDX = dsearch (X, Y, TRI, XI, YI, S)
     Returns the index IDX or the closest point in `X, Y)' to the
     elements `[XI(:), YI(:)]'. The variable S is accepted but ignored
     for compatibility.

     *See also:* dsearchn, tsearch.

 -- Function File: IDX = dsearchn (X, TRI, XI)
 -- Function File: IDX = dsearchn (X, TRI, XI, OUTVAL)
 -- Function File: IDX = dsearchn (X, XI)
 -- Function File: [IDX, D] = dsearchn (...)
     Returns the index IDX or the closest point in X to the elements
     XI. If OUTVAL is supplied, then the values of XI that are not
     contained within one of the simplicies TRI are set to OUTVAL.
     Generally, TRI is returned from `delaunayn (X)'.

     *See also:* dsearch, tsearch.

   An example of the use of `dsearch', using the above values of X, Y
and TRI is

     dsearch (X, Y, TRI, -2, -2)
     => 1

   If you wish the points that are outside the tessellation to be
flagged, then `dsearchn' can be used as

     dsearchn ([X, Y], TRI, [-2, -2], NaN)
     => NaN
     dsearchn ([X, Y], TRI, [-0.5, -0.5], NaN)
     => 1

where the point outside the tessellation are then flagged with `NaN'.


File: octave.info,  Node: Voronoi Diagrams,  Next: Convex Hull,  Prev: Delaunay Triangulation,  Up: Geometry

29.2 Voronoi Diagrams
=====================

A Voronoi diagram or Voronoi tessellation of a set of points S in an
N-dimensional space, is the tessellation of the N-dimensional space
such that all points in `V(P)', a partitions of the tessellation where
P is a member of S, are closer to P than any other point in S.  The
Voronoi diagram is related to the Delaunay triangulation of a set of
points, in that the vertexes of the Voronoi tessellation are the
center's of the circum-circles of the simplicies of the Delaunay
tessellation.

 -- Function File:  voronoi (X, Y)
 -- Function File:  voronoi (X, Y, "plotstyle")
 -- Function File:  voronoi (X, Y, "plotstyle", OPTIONS)
 -- Function File: [VX, VY] = voronoi (...)
     plots voronoi diagram of points `(X, Y)'.  The voronoi facets with
     points at infinity are not drawn.  [VX, VY] = voronoi(...) returns
     the vertices instead plotting the diagram. plot (VX, VY) shows the
     voronoi diagram.

     A fourth optional argument, which must be a string, contains extra
     options passed to the underlying qhull command.  See the
     documentation for the Qhull library for details.

            x = rand (10, 1);
            y = rand (size (x));
            h = convhull (x, y);
            [vx, vy] = voronoi (x, y);
            plot (vx, vy, "-b", x, y, "o", x(h), y(h), "-g")
            legend ("", "points", "hull");


     *See also:* voronoin, delaunay, convhull.

 -- Function File: [C, F] = voronoin (PTS)
 -- Function File: [C, F] = voronoin (PTS, OPTIONS)
     computes n- dimensional voronoi facets.  The input matrix PTS of
     size [n, dim] contains n points of dimension dim.  C contains the
     points of the voronoi facets. The list F contains for each facet
     the indices of the voronoi points.

     A second optional argument, which must be a string, contains extra
     options passed to the underlying qhull command.  See the
     documentation for the Qhull library for details.

     *See also:* voronoin, delaunay, convhull.

   An example of the use of `voronoi' is

     rand("state",9);
     x = rand(10,1);
     y = rand(10,1);
     tri = delaunay (x, y);
     [vx, vy] = voronoi (x, y, tri);
     triplot (tri, x, y, "b");
     hold on;
     plot (vx, vy, "r");

   Additional information about the size of the facets of a Voronoi
diagram, and which points of a set of points is in a polygon can be had
with the `polyarea' and `inpolygon' functions respectively.

 -- Function File:  polyarea (X, Y)
 -- Function File:  polyarea (X, Y, DIM)
     Determines area of a polygon by triangle method. The variables X
     and Y define the vertex pairs, and must therefore have the same
     shape. They can be either vectors or arrays. If they are arrays
     then the columns of X and Y are treated separately and an area
     returned for each.

     If the optional DIM argument is given, then `polyarea' works along
     this dimension of the arrays X and Y.


   An example of the use of `polyarea' might be

     rand ("state", 2);
     x = rand (10, 1);
     y = rand (10, 1);
     [c, f] = voronoin ([x, y]);
     af = zeros (size(f));
     for i = 1 : length (f)
       af(i) = polyarea (c (f {i, :}, 1), c (f {i, :}, 2));
     endfor

   Facets of the Voronoi diagram with a vertex at infinity have
infinity area.

 -- Function File: [IN, ON] =  inpolygon (X, Y, XV, XY)
     For a polygon defined by `(XV, YV)' points, determine if the
     points `(X, Y)' are inside or outside the polygon.  The variables
     X, Y, must have the same dimension. The optional output ON gives
     the points that are on the polygon.


   An example of the use of `inpolygon' might be

     randn ("state", 2);
     x = randn (100, 1);
     y = randn (100, 1);
     vx = cos (pi * [-1 : 0.1: 1]);
     vy = sin (pi * [-1 : 0.1 : 1]);
     in = inpolygon (x, y, vx, vy);
     plot(vx, vy, x(in), y(in), "r+", x(!in), y(!in), "bo");
     axis ([-2, 2, -2, 2]);


File: octave.info,  Node: Convex Hull,  Next: Interpolation on Scattered Data,  Prev: Voronoi Diagrams,  Up: Geometry

29.3 Convex Hull
================

The convex hull of a set of points is the minimum convex envelope
containing all of the points. Octave has the functions `convhull' and
`convhulln' to calculate the convex hull of 2-dimensional and
N-dimensional sets of points.

 -- Function File: H = convhull (X, Y)
 -- Function File: H = convhull (X, Y, OPT)
     Returns the index vector to the points of the enclosing convex
     hull.  The data points are defined by the x and y vectors.

     A third optional argument, which must be a string, contains extra
     options passed to the underlying qhull command.  See the
     documentation for the Qhull library for details.


     *See also:* delaunay, convhulln.

 -- Loadable Function: H = convhulln (P)
 -- Loadable Function: H = convhulln (P, OPT)
     Returns an index vector to the points of the enclosing convex hull.
     The input matrix of size [n, dim] contains n points of dimension
     dim.

     If a second optional argument is given, it must be a string or
     cell array of strings containing options for the underlying qhull
     command.  (See the Qhull documentation for the available options.)
     The default options are "s Qci Tcv".


     *See also:* convhull, delaunayn.

   An example of the use of `convhull' is

     x = -3:0.05:3;
     y = abs (sin (x));
     k = convhull (x, y);
     plot (x(k), y(k), "r-", x, y, "b+");
     axis ([-3.05, 3.05, -0.05, 1.05]);


File: octave.info,  Node: Interpolation on Scattered Data,  Prev: Convex Hull,  Up: Geometry

29.4 Interpolation on Scattered Data
====================================

An important use of the Delaunay tessellation is that it can be used to
interpolate from scattered data to an arbitrary set of points. To do
this the N-simplex of the known set of points is calculated with
`delaunay', `delaunay3' or `delaunayn'. Then the simplicies in to which
the desired points are found are identified. Finally the vertices of
the simplicies are used to interpolate to the desired points. The
functions that perform this interpolation are `griddata', `griddata3'
and `griddatan'.

 -- Function File: ZI = griddata (X, Y, Z, XI, YI, METHOD)
 -- Function File: [XI, YI, ZI] = griddata (X, Y, Z, XI, YI, METHOD)
     Generate a regular mesh from irregular data using interpolation.
     The function is defined by `Z = f (X, Y)'.  The interpolation
     points are all `(XI, YI)'.  If XI, YI are vectors then they are
     made into a 2D mesh.

     The interpolation method can be `"nearest"', `"cubic"' or
     `"linear"'.  If method is omitted it defaults to `"linear"'.

     *See also:* delaunay.

 -- Function File: VI = griddata3 (X, Y, Z, V XI, YI, ZI, METHOD,
          OPTIONS)
     Generate a regular mesh from irregular data using interpolation.
     The function is defined by `Y = f (X,Y,Z)'.  The interpolation
     points are all XI.

     The interpolation method can be `"nearest"' or `"linear"'.  If
     method is omitted it defaults to `"linear"'.

     *See also:* griddata, delaunayn.

 -- Function File: YI = griddatan (X, Y, XI, METHOD, OPTIONS)
     Generate a regular mesh from irregular data using interpolation.
     The function is defined by `Y = f (X)'.  The interpolation points
     are all XI.

     The interpolation method can be `"nearest"' or `"linear"'.  If
     method is omitted it defaults to `"linear"'.

     *See also:* griddata, delaunayn.

   An example of the use of the `griddata' function is

     rand("state",1);
     x=2*rand(1000,1)-1;
     y=2*rand(size(x))-1;
     z=sin(2*(x.^2+y.^2));
     [xx,yy]=meshgrid(linspace(-1,1,32));
     griddata(x,y,z,xx,yy);


File: octave.info,  Node: Control Theory,  Next: Signal Processing,  Prev: Geometry,  Up: Top

30 Control Theory
*****************

The Octave Control Systems Toolbox (OCST) was initially developed by
Dr. A. Scottedward Hodel <a.s.hodel@eng.auburn.edu> with the assistance
of his students
   * R. Bruce Tenison <btenison@dibbs.net>,

   * David C. Clem,

   * John E. Ingram <John.Ingram@sea.siemans.com>, and

   * Kristi McGowan.
   This development was supported in part by NASA's Marshall Space
Flight Center as part of an in-house CACSD environment.  Additional
important contributions were made by Dr. Kai Mueller
<mueller@ifr.ing.tu-bs.de> and Jose Daniel Munoz Frias (`place.m').

   An on-line menu-driven tutorial is available via `DEMOcontrol';
beginning OCST users should start with this program.

 -- Function File:  DEMOcontrol
     Octave Control Systems Toolbox demo/tutorial program.  The demo
     allows the user to select among several categories of OCST
     function:
          octave:1> DEMOcontrol
          Octave Controls System Toolbox Demo

            [ 1] System representation
            [ 2] Block diagram manipulations
            [ 3] Frequency response functions
            [ 4] State space analysis functions
            [ 5] Root locus functions
            [ 6] LQG/H2/Hinfinity functions
            [ 7] End
     Command examples are interactively run for users to observe
     the use of OCST functions.

     *See also:* Demo Programs: bddemo.m, frdemo.m, analdemo.m,
     moddmeo.m, rldemo.m.

* Menu:

* sysstruct::
* sysinterface::
* sysdisp::
* blockdiag::
* numerical::
* sysprop::
* systime::
* sysfreq::
* cacsd::
* misc::


File: octave.info,  Node: sysstruct,  Next: sysinterface,  Up: Control Theory

30.1 System Data Structure
==========================

* Menu:

* sysstructvars::
* sysstructtf::
* sysstructzp::
* sysstructss::

   The OCST stores all dynamic systems in a single data structure
format that can represent continuous systems, discrete-systems, and
mixed (hybrid) systems in state-space form, and can also represent
purely continuous/discrete systems in either transfer function or
pole-zero form. In order to provide more flexibility in treatment of
discrete/hybrid systems, the OCST also keeps a record of which system
outputs are sampled.

   Octave structures are accessed with a syntax much like that used by
the C programming language.  For consistency in use of the data
structure used in the OCST, it is recommended that the system structure
access m-files be used (*note sysinterface::).  Some elements of the
data structure are absent depending on the internal system
representation(s) used.  More than one system representation can be
used for SISO systems; the OCST m-files ensure that all representations
used are consistent with one another.

 -- Function File:  sysrepdemo
     Tutorial for the use of the system data structure functions.


File: octave.info,  Node: sysstructvars,  Next: sysstructtf,  Up: sysstruct

30.1.1 Variables common to all OCST system formats
--------------------------------------------------

The data structure elements (and variable types) common to all  system
representations are listed below; examples of the initialization and
use of the system data structures are given in subsequent sections and
in the online demo `DEMOcontrol'.
N
NZ
     The respective number of continuous and discrete states in the
     system (scalar)

INNAME
OUTNAME
     list of name(s) of the system input, output signal(s). (list of
     strings)

SYS
     System status vector.  (vector)

     This vector indicates both what representation was used to
     initialize the system data structure (called the primary system
     type) and which other representations are currently up-to-date
     with the primary system type (*note structaccess::).

     The value of the first element of the vector indicates the primary
     system type.

    0
          for tf form (initialized with `tf2sys' or `fir2sys')

    1
          for zp form (initialized with `zp2sys')

    2
          for ss form (initialized with `ss2sys')

     The next three elements are boolean flags that indicate whether
     tf, zp, or ss, respectively, are "up to date" (whether it is safe
     to use the variables associated with these representations).
     These flags are changed when calls are made to the `sysupdate'
     command.

TSAM
     Discrete time sampling period  (nonnegative scalar).   TSAM is set
     to 0 for continuous time systems.

YD
     Discrete-time output list (vector)

     indicates which outputs are discrete time (i.e.,     produced by
     D/A converters) and which are continuous time.      yd(ii) = 0 if
     output ii is continuous, = 1 if discrete.

   The remaining variables of the  system data structure are only
present if the corresponding entry of the `sys' vector is true (=1).


File: octave.info,  Node: sysstructtf,  Next: sysstructzp,  Prev: sysstructvars,  Up: sysstruct

30.1.2 `tf' format variables
----------------------------

NUM
     numerator coefficients   (vector)

DEN
     denominator coefficients   (vector)



File: octave.info,  Node: sysstructzp,  Next: sysstructss,  Prev: sysstructtf,  Up: sysstruct

30.1.3 `zp' format variables
----------------------------

ZER
     system zeros   (vector)

POL
     system poles    (vector)

K
     leading coefficient   (scalar)



File: octave.info,  Node: sysstructss,  Prev: sysstructzp,  Up: sysstruct

30.1.4 `ss' format variables
----------------------------

A
B
C
D
     The usual state-space matrices. If a system has both
     continuous and discrete states, they are sorted so that
     continuous states come first, then discrete states

     *Note* some functions (e.g., `bode', `hinfsyn') will not accept
     systems with both discrete and continuous states/outputs

STNAME
     names of system states   (list of strings)



File: octave.info,  Node: sysinterface,  Next: sysdisp,  Prev: sysstruct,  Up: Control Theory

30.2 System Construction and Interface Functions
================================================

Construction and manipulations of the OCST system data structure (*note
sysstruct::) requires attention to many details in order to ensure that
data structure contents remain consistent.  Users are strongly
encouraged to use the system interface functions in this section.
Functions for the formatted display in of system data structures are
given in *Note sysdisp::.

* Menu:

* fir2sys::
* ss2sys::
* tf2sys::
* zp2sys::
* structaccess::


File: octave.info,  Node: fir2sys,  Next: ss2sys,  Up: sysinterface

30.2.1 Finite impulse response system interface functions
---------------------------------------------------------

 -- Function File:  fir2sys (NUM, TSAM, INNAME, OUTNAME)
     construct a system data structure from FIR description

     *Inputs*
    NUM
          vector of coefficients [c0, c1, ..., cn] of the SISO FIR
          transfer function C(z) = c0 + c1*z^(-1) + c2*z^(-2) + ... +
          cn*z^(-n)

    TSAM
          sampling time (default: 1)

    INNAME
          name of input signal;  may be a string or a list with a
          single entry.

    OUTNAME
          name of output signal; may be a string or a list with a
          single entry.

     *Output*
    SYS
          system data structure

     *Example*
          octave:1> sys = fir2sys([1 -1 2 4],0.342,\
          > "A/D input","filter output");
          octave:2> sysout(sys)
          Input(s)
                  1: A/D input

          Output(s):
                  1: filter output (discrete)

          Sampling interval: 0.342
          transfer function form:
          1*z^3 - 1*z^2 + 2*z^1 + 4
          -------------------------
          1*z^3 + 0*z^2 + 0*z^1 + 0

 -- Function File: [C, TSAM, INPUT, OUTPUT] = sys2fir (SYS)
     Extract FIR data from system data structure; see `fir2sys' for
     parameter descriptions.

     *See also:* fir2sys.


File: octave.info,  Node: ss2sys,  Next: tf2sys,  Prev: fir2sys,  Up: sysinterface

30.2.2 State space system interface functions
---------------------------------------------

 -- Function File: OUTSYS = ss (A, B, C, D, TSAM, N, NZ, STNAME,
          INNAME, OUTNAME, OUTLIST)
     Create system structure from state-space data.   May be continuous,
     discrete, or mixed (sampled data)

     *Inputs*
    A
    B
    C
    D
          usual state space matrices.

          default: D = zero matrix

    TSAM
          sampling rate.  Default: tsam = 0 (continuous system)

    N
    NZ
          number of continuous, discrete states in the system

          If TSAM is 0, n = `rows'(A), nz = 0.

          If TSAM is greater than zero, n = 0, nz = `rows'(A)

          see below for system partitioning

    STNAME
          cell array of strings of state signal names

          default (STNAME=[] on input): `x_n' for continuous states,
          `xd_n' for discrete states

    INNAME
          cell array of strings of input signal names

          default (INNAME = [] on input): `u_n'

    OUTNAME
          cell array of strings of output signal names

          default (OUTNAME = [] on input): `y_n'

    OUTLIST
          list of indices of outputs y that are sampled

          If TSAM is 0, outlist = [].

          If TSAM is greater than 0, outlist = 1:`rows'(C).

     Unlike states, discrete/continuous outputs may appear in any order.

     `sys2ss' returns a vector YD where YD(OUTLIST) = 1; all other
     entries of YD are 0.

     *Output*
    OUTSYS
          system data structure

     *System partitioning*

     Suppose for simplicity that outlist specified that the first
     several outputs were continuous and the remaining outputs were
     discrete.  Then the system is partitioned as
          x = [ xc ]  (n x 1)
              [ xd ]  (nz x 1 discrete states)
          a = [ acc acd ]  b = [ bc ]
              [ adc add ]      [ bd ]
          c = [ ccc ccd ]  d = [ dc ]
              [ cdc cdd ]      [ dd ]

              (cdc = c(outlist,1:n), etc.)
     with dynamic equations: d/dt xc(t)     = acc*xc(t)      +
     acd*xd(k*tsam) + bc*u(t)

     xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)

     yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)

     yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)

     *Signal partitions*
                  | continuous      | discrete               |
          ----------------------------------------------------
          states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
          ----------------------------------------------------
          outputs | outname(cout,:) | outname(outlist,:)     |
          ----------------------------------------------------
     where cout is the list of in 1:`rows'(P) that are not
     contained in outlist. (Discrete/continuous outputs may be entered
     in any order desired by the user.)

     *Example*
          octave:1> a = [1 2 3; 4 5 6; 7 8 10];
          octave:2> b = [0 0 ; 0 1 ; 1 0];
          octave:3> c = eye (3);
          octave:4> sys = ss (a, b, c, [], 0, 3, 0, ...
          >                   {"volts", "amps", "joules"});
          octave:5> sysout(sys);
          Input(s)
                  1: u_1
                  2: u_2

          Output(s):
                  1: y_1
                  2: y_2
                  3: y_3

          state-space form:
          3 continuous states, 0 discrete states
          State(s):
                  1: volts
                  2: amps
                  3: joules

          A matrix: 3 x 3
             1   2   3
             4   5   6
             7   8  10
          B matrix: 3 x 2
            0  0
            0  1
            1  0
          C matrix: 3 x 3
            1  0  0
            0  1  0
            0  0  1
          D matrix: 3 x 3
            0  0
            0  0
            0  0
     Notice that the D matrix is constructed  by default to the correct
     dimensions.  Default input and output signals names were assigned
     since none were given.

 -- Function File:  ss2sys (A, B, C, D, TSAM, N, NZ, STNAME, INNAME,
          OUTNAME, OUTLIST)
     Create system structure from state-space data.   May be continuous,
     discrete, or mixed (sampled data)

     *Inputs*
    A
    B
    C
    D
          usual state space matrices.

          default: D = zero matrix

    TSAM
          sampling rate.  Default: tsam = 0 (continuous system)

    N
    NZ
          number of continuous, discrete states in the system

          If TSAM is 0, n = `rows'(A), nz = 0.

          If TSAM is greater than zero, n = 0, nz = `rows'(A)

          see below for system partitioning

    STNAME
          cell array of strings of state signal names

          default (STNAME=[] on input): `x_n' for continuous states,
          `xd_n' for discrete states

    INNAME
          cell array of strings of input signal names

          default (INNAME = [] on input): `u_n'

    OUTNAME
          cell array of strings of input signal names

          default (OUTNAME = [] on input): `y_n'

    OUTLIST
          list of indices of outputs y that are sampled

          If TSAM is 0, outlist = [].

          If TSAM is greater than 0, outlist = 1:`rows'(C).

     Unlike states, discrete/continuous outputs may appear in any order.

     `sys2ss' returns a vector YD where YD(OUTLIST) = 1; all other
     entries of YD are 0.

     *Outputs* OUTSYS = system data structure

     *System partitioning*

     Suppose for simplicity that outlist specified that the first
     several outputs were continuous and the remaining outputs were
     discrete.  Then the system is partitioned as
          x = [ xc ]  (n x 1)
              [ xd ]  (nz x 1 discrete states)
          a = [ acc acd ]  b = [ bc ]
              [ adc add ]      [ bd ]
          c = [ ccc ccd ]  d = [ dc ]
              [ cdc cdd ]      [ dd ]

              (cdc = c(outlist,1:n), etc.)
     with dynamic equations: d/dt xc(t)     = acc*xc(t)      +
     acd*xd(k*tsam) + bc*u(t)

     xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)

     yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)

     yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)

     *Signal partitions*
                  | continuous      | discrete               |
          ----------------------------------------------------
          states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
          ----------------------------------------------------
          outputs | outname(cout,:) | outname(outlist,:)     |
          ----------------------------------------------------
     where cout is the list of in 1:`rows'(P) that are not
     contained in outlist. (Discrete/continuous outputs may be entered
     in any order desired by the user.)

     *Example*
          octave:1> a = [1 2 3; 4 5 6; 7 8 10];
          octave:2> b = [0 0 ; 0 1 ; 1 0];
          octave:3> c = eye (3);
          octave:4> sys = ss (a, b, c, [], 0, 3, 0,
          >                   {"volts", "amps", "joules"});
          octave:5> sysout(sys);
          Input(s)
                  1: u_1
                  2: u_2

          Output(s):
                  1: y_1
                  2: y_2
                  3: y_3

          state-space form:
          3 continuous states, 0 discrete states
          State(s):
                  1: volts
                  2: amps
                  3: joules

          A matrix: 3 x 3
             1   2   3
             4   5   6
             7   8  10
          B matrix: 3 x 2
            0  0
            0  1
            1  0
          C matrix: 3 x 3
            1  0  0
            0  1  0
            0  0  1
          D matrix: 3 x 3
            0  0
            0  0
            0  0
     Notice that the D matrix is constructed  by default to the correct
     dimensions.  Default input and output signals names were assigned
     since none were given.

 -- Function File: [A, B, C, D, TSAM, N, NZ, STNAME, INNAME, OUTNAME,
YD] = sys2ss (SYS)
     Extract state space representation from system data structure.

     *Input*
    SYS
          System data structure.

     *Outputs*
    A
    B
    C
    D
          State space matrices for SYS.

    TSAM
          Sampling time of SYS (0 if continuous).

    N
    NZ
          Number of continuous, discrete states (discrete states come
          last in state vector X).

    STNAME
    INNAME
    OUTNAME
          Signal names (lists of strings);  names of states, inputs,
          and outputs, respectively.

    YD
          Binary vector; YD(II) is 1 if output Y(II) is discrete
          (sampled); otherwise  YD(II) is 0.

     A warning massage is printed if the system is a mixed continuous
     and discrete system.

     *Example*
          octave:1> sys=tf2sys([1 2],[3 4 5]);
          octave:2> [a,b,c,d] = sys2ss(sys)
          a =
             0.00000   1.00000
            -1.66667  -1.33333
          b =
            0
            1
          c = 0.66667  0.33333
          d = 0


File: octave.info,  Node: tf2sys,  Next: zp2sys,  Prev: ss2sys,  Up: sysinterface

30.2.3 Transfer function system interface functions
---------------------------------------------------

 -- Function File:  tf (NUM, DEN, TSAM, INNAME, OUTNAME)
     build system data structure from transfer function format data

     *Inputs*
    NUM
    DEN
          coefficients of numerator/denominator polynomials

    TSAM
          sampling interval. default: 0 (continuous time)

    INNAME
    OUTNAME
          input/output signal names; may be a string or cell array with
          a single string entry.

     *Outputs* SYS = system data structure

     *Example*
          octave:1> sys=tf([2 1],[1 2 1],0.1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1 (discrete)
          Sampling interval: 0.1
          transfer function form:
          2*z^1 + 1
          -----------------
          1*z^2 + 2*z^1 + 1

 -- Function File:  tf2sys (NUM, DEN, TSAM, INNAME, OUTNAME)
     Build system data structure from transfer function format data.

     *Inputs*
    NUM
    DEN
          Coefficients of numerator/denominator polynomials.

    TSAM
          Sampling interval; default: 0 (continuous time).

    INNAME
    OUTNAME
          Input/output signal names; may be a string or cell array with
          a single string entry.

     *Output*
    SYS
          System data structure.

     *Example*
          octave:1> sys=tf2sys([2 1],[1 2 1],0.1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1 (discrete)
          Sampling interval: 0.1
          transfer function form:
          2*z^1 + 1
          -----------------
          1*z^2 + 2*z^1 + 1

 -- Function File: [NUM, DEN, TSAM, INNAME, OUTNAME] = sys2tf (SYS)
     Extract transfer function data from a system data structure.

     See `tf' for parameter descriptions.

     *Example*
          octave:1> sys=ss([1 -2; -1.1,-2.1],[0;1],[1 1]);
          octave:2> [num,den] = sys2tf(sys)
          num = 1.0000  -3.0000
          den = 1.0000   1.1000  -4.3000


File: octave.info,  Node: zp2sys,  Next: structaccess,  Prev: tf2sys,  Up: sysinterface

30.2.4 Zero-pole system interface functions
-------------------------------------------

 -- Function File:  zp (ZER, POL, K, TSAM, INNAME, OUTNAME)
     Create system data structure from zero-pole data.

     *Inputs*
    ZER
          vector of system zeros

    POL
          vector of system poles

    K
          scalar leading coefficient

    TSAM
          sampling period. default: 0 (continuous system)

    INNAME
    OUTNAME
          input/output signal names (lists of strings)

     *Outputs* sys: system data structure

     *Example*
          octave:1> sys=zp([1 -1],[-2 -2 0],1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          zero-pole form:
          1 (s - 1) (s + 1)
          -----------------
          s (s + 2) (s + 2)

 -- Function File:  zp2sys (ZER, POL, K, TSAM, INNAME, OUTNAME)
     Create system data structure from zero-pole data.

     *Inputs*
    ZER
          Vector of system zeros.

    POL
          Vector of system poles.

    K
          Scalar leading coefficient.

    TSAM
          Sampling period; default: 0 (continuous system).

    INNAME
    OUTNAME
          Input/output signal names (lists of strings).

     *Output*
    SYS
          System data structure.

     *Example*
          octave:1> sys=zp2sys([1 -1],[-2 -2 0],1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          zero-pole form:
          1 (s - 1) (s + 1)
          -----------------
          s (s + 2) (s + 2)

 -- Function File: [ZER, POL, K, TSAM, INNAME, OUTNAME] = sys2zp (SYS)
     Extract zero/pole/leading coefficient information from a system
     data structure.

     See `zp' for parameter descriptions.

     *Example*
          octave:1> sys=ss([1 -2; -1.1,-2.1],[0;1],[1 1]);
          octave:2> [zer,pol,k] = sys2zp(sys)
          zer = 3.0000
          pol =
            -2.6953
             1.5953
          k = 1


File: octave.info,  Node: structaccess,  Prev: zp2sys,  Up: sysinterface

30.2.5 Data structure access functions
--------------------------------------

 -- Function File:  syschnames (SYS, OPT, LIST, NAMES)
     Superseded by `syssetsignals'.

 -- Function File:  syschtsam (SYS, TSAM)
     This function changes the sampling time (tsam) of the system.
     Exits with an error if sys is purely continuous time.

 -- Function File: [N, NZ, M, P, YD] = sysdimensions (SYS, OPT)
     return the number of states, inputs, and/or outputs in the system
     SYS.

     *Inputs*
    SYS
          system data structure

    OPT
          String indicating which dimensions are desired.  Values:
         `"all"'
               (default) return all parameters as specified under
               Outputs below.

         `"cst"'
               return N= number of continuous states

         `"dst"'
               return N= number of discrete states

         `"in"'
               return N= number of inputs

         `"out"'
               return N= number of outputs

     *Outputs*
    N
          number of continuous states (or individual requested
          dimension as specified by OPT).

    NZ
          number of discrete states

    M
          number of system inputs

    P
          number of system outputs

    YD
          binary vector; YD(II) is nonzero if output II is discrete.
          yd(ii) = 0 if output II is continuous


     *See also:* sysgetsignals, sysgettsam.

 -- Function File: [STNAME, INNAME, OUTNAME, YD] = sysgetsignals (SYS)
 -- Function File: SIGLIST = sysgetsignals (SYS, SIGID)
 -- Function File: SIGNAME = sysgetsignals (SYS, SIGID, SIGNUM, STRFLG)
     Get signal names from a system

     *Inputs*
    SYS
          system data structure for the state space system

    SIGID
          signal id.  String.  Must be one of
         `"in"'
               input signals

         `"out"'
               output signals

         `"st"'
               stage signals

         `"yd"'
               value of logical vector YD

    SIGNUM
          index(indices) or name(s) or signals; see `sysidx'

    STRFLG
          flag to return a string instead of a cell array;  Values:
         `0'
               (default) return a cell array (even if signum specifies
               an individual signal)

         `1'
               return a string.  Exits with an error if signum does not
               specify an individual signal.


     *Outputs*
    *If SIGID is not specified:

         STNAME
         INNAME
         OUTNAME
               signal names (cell array of strings);  names of states,
               inputs, and outputs, respectively.

         YD
               binary vector; YD(II) is nonzero if output II is
               discrete.

    *If SIGID is specified but SIGNUM is not specified:

         `sigid="in"'
               SIGLIST is set to the cell array of input names.

         `sigid="out"'
               SIGLIST is set to the cell array of output names.

         `sigid="st"'
               SIGLIST is set to the cell array of state names.

               stage signals

         `sigid="yd"'
               SIGLIST is set to logical vector indicating discrete
               outputs; SIGLIST(II) = 0 indicates that output II is
               continuous (unsampled), otherwise it is discrete.


    *If the first three input arguments are specified:
          SIGNAME is a cell array of the specified signal names (SIGID
          is `"in"', `"out"', or `"st"'), or else the logical flag
          indicating whether output(s) SIGNUM is(are) discrete
          (SIGVAL=1) or continuous (SIGVAL=0).

     *Examples* (From `sysrepdemo')
          octave> sys=ss(rand(4),rand(4,2),rand(3,4));
          octave># get all signal names
          octave> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys)
          Ast =
          (
            [1] = x_1
            [2] = x_2
            [3] = x_3
            [4] = x_4
          )
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          Aout =
          (
            [1] = y_1
            [2] = y_2
            [3] = y_3
          )
          Ayd =

            0  0  0
          octave> # get only input signal names:
          octave> Ain = sysgetsignals(sys,"in")
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          octave> # get name of output 2 (in cell array):
          octave> Aout = sysgetsignals(sys,"out",2)
          Aout =
          (
            [1] = y_2
          )
          octave> # get name of output 2 (as string):
          octave> Aout = sysgetsignals(sys,"out",2,1)
          Aout = y_2

 -- Function File:  sysgettype (SYS)
     return the initial system type of the system

     *Input*
    SYS
          System data structure.

     *Output*
    SYSTYPE
          String indicating how the structure was initially
          constructed. Values: `"ss"', `"zp"', or `"tf"'.

     FIR initialized systems return `systype="tf"'.

 -- Function File:  syssetsignals (SYS, OPT, NAMES, SIG_IDX)
     change the names of selected inputs, outputs and states.

     *Inputs*
    SYS
          System data structure.

    OPT
          Change default name (output).

         `"out"'
               Change selected output names.

         `"in"'
               Change selected input names.

         `"st"'
               Change selected state names.

         `"yd"'
               Change selected outputs from discrete to continuous or
               from continuous to discrete.

    NAMES

         `opt = "out", "in", "st"'
               string or string array containing desired signal names
               or values.

         `opt = "yd"'
               To desired output continuous/discrete flag.  Set name to
               0 for continuous, or 1 for discrete.

    SIG_IDX
          indices or names of outputs, yd, inputs, or states whose
          respective names/values should be changed.

          Default: replace entire cell array of names/entire yd vector.

     *Outputs*
    RETSYS
          SYS with appropriate signal names changed (or YD values,
          where appropriate).

     *Example*
          octave:1> sys=ss ([1 2; 3 4],[5;6],[7 8]);
          octave:2> sys = syssetsignals (sys, "st",
          >                              str2mat("Posx","Velx"));
          octave:3> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          state-space form:
          2 continuous states, 0 discrete states
          State(s):
                  1: Posx
                  2: Velx
          A matrix: 2 x 2
            1  2
            3  4
          B matrix: 2 x 1
            5
            6
          C matrix: 1 x 2
            7  8
          D matrix: 1 x 1
          0

 -- Function File:  sysupdate (SYS, OPT)
     Update the internal representation of a system.

     *Inputs*
    SYS:
          system data structure

    OPT
          string:
         `"tf"'
               update transfer function form

         `"zp"'
               update zero-pole form

         `"ss"'
               update state space form

         `"all"'
               all of the above

     *Outputs*
    RETSYS
          Contains union of data in sys and requested data.  If
          requested data in SYS is already up to date then RETSYS=SYS.

     Conversion to `tf' or `zp' exits with an error if the system is
     mixed continuous/digital.

     *See also:* tf, ss, zp, sysout, sys2ss, sys2tf, sys2zp.

 -- Function File: [SYSTYPE, NOUT, NIN, NCSTATES, NDSTATES] = minfo
          (INMAT)
     Determines the type of system matrix.  INMAT can be a varying, a
     system, a constant, and an empty matrix.

     *Outputs*
    SYSTYPE
          Can be one of: varying, system, constant, and empty.

    NOUT
          The number of outputs of the system.

    NIN
          The number of inputs of the system.

    NCSTATES
          The number of continuous states of the system.

    NDSTATES
          The number of discrete states of the system.

 -- Function File:  sysgettsam (SYS)
     Return the sampling time of the system SYS.


File: octave.info,  Node: sysdisp,  Next: blockdiag,  Prev: sysinterface,  Up: Control Theory

30.3 System display functions
=============================

 -- Function File:  sysout (SYS, OPT)
     print out a system data structure in desired format
    SYS
          system data structure

    OPT
          Display option
         `[]'
               primary system form (default)

         `"ss"'
               state space form

         `"tf"'
               transfer function form

         `"zp"'
               zero-pole form

         `"all"'
               all of the above

 -- Function File:  tfout (NUM, DENOM, X)
     Print formatted transfer function n(s)/d(s) to the screen.  X
     defaults to the string `"s"'

     *See also:* polyval, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, polyinteg, polyout.

 -- Function File:  zpout (ZER, POL, K, X)
     print formatted zero-pole form to the screen.  X defaults to the
     string `"s"'

     *See also:* polyval, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, polyinteg, polyout.


File: octave.info,  Node: blockdiag,  Next: numerical,  Prev: sysdisp,  Up: Control Theory

30.4 Block Diagram Manipulations
================================

*Note systime::.

   Unless otherwise noted, all parameters (input,output) are system
data structures.

 -- Function File:  bddemo (INPUTS)
     Octave Controls toolbox demo: Block Diagram Manipulations demo.

 -- Function File:  buildssic (CLST, ULST, OLST, ILST, S1, S2, S3, S4,
          S5, S6, S7, S8)
     Form an arbitrary complex (open or closed loop) system in
     state-space form from several systems. `buildssic' can easily
     (despite its cryptic syntax) integrate transfer functions from a
     complex block diagram into a single system with one call.  This
     function is especially useful for building open loop
     interconnections for H-infinity and H-2 designs or for closing
     loops with these controllers.

     Although this function is general purpose, the use of `sysgroup'
     `sysmult', `sysconnect' and the like is recommended for standard
     operations since they can handle mixed discrete and continuous
     systems and also the names of inputs, outputs, and states.

     The parameters consist of 4 lists that describe the connections
     outputs and inputs and up to 8 systems S1-S8.  Format of the lists:
    CLST
          connection list, describes the input signal of each system.
          The maximum number of rows of Clst is equal to the sum of all
          inputs of s1-s8.

          Example: `[1 2 -1; 2 1 0]' means that:  new input 1 is old
          input 1 + output 2 - output 1, and new input 2 is old input 2
          + output 1. The order of rows is arbitrary.

    ULST
          if not empty the old inputs in vector ULST will be appended
          to the outputs. You need this if you want to "pull out" the
          input of a system. Elements are input numbers of S1-S8.

    OLST
          output list, specifies the outputs of the resulting systems.
          Elements are output numbers of S1-S8.  The numbers are
          allowed to be negative and may appear in any order. An empty
          matrix means all outputs.

    ILST
          input list, specifies the inputs of the resulting systems.
          Elements are input numbers of S1-S8.  The numbers are allowed
          to be negative and may appear in any order. An empty matrix
          means all inputs.

     Example:  Very simple closed loop system.
          w        e  +-----+   u  +-----+
           --->o--*-->|  K  |--*-->|  G  |--*---> y
               ^  |   +-----+  |   +-----+  |
             - |  |            |            |
               |  |            +----------------> u
               |  |                         |
               |  +-------------------------|---> e
               |                            |
               +----------------------------+

     The closed loop system GW can be obtained by
          GW = buildssic([1 2; 2 -1], 2, [1 2 3], 2, G, K);

    CLST
          1st row: connect input 1 (G) with output 2 (K).

          2nd row: connect input 2 (K) with negative output 1 (G).

    ULST
          Append input of 2 (K) to the number of outputs.

    OLST
          Outputs are output of 1 (G), 2 (K) and appended output 3
          (from ULST).

    ILST
          The only input is 2 (K).

     Here is a real example:
                                   +----+
              -------------------->| W1 |---> v1
          z   |                    +----+
          ----|-------------+
              |             |
              |    +---+    v      +----+
              *--->| G |--->O--*-->| W2 |---> v2
              |    +---+       |   +----+
              |                |
              |                v
             u                  y

          min || GW   ||
                   vz   infty

     The closed loop system GW from [z, u]' to [v1, v2, y]' can be
     obtained by (all SISO systems):
          GW = buildssic([1, 4; 2, 4; 3, 1], 3, [2, 3, 5],
                         [3, 4], G, W1, W2, One);
     where "One" is a unity gain (auxiliary) function with order 0.
     (e.g. `One = ugain(1);')

 -- Function File: SYS = jet707 ()
     Creates a linearized state-space model of a Boeing 707-321 aircraft
     at V=80 m/s (M = 0.26, GA0 = -3 deg, ALPHA0 = 4 deg, KAPPA = 50
     deg).

     System inputs: (1) thrust and (2) elevator angle.

     System outputs:  (1) airspeed and (2) pitch angle.

     *Reference*: R. Brockhaus: `Flugregelung' (Flight Control),
     Springer, 1994.

     *See also:* ord2.

 -- Function File:  ord2 (NFREQ, DAMP, GAIN)
     Creates a continuous 2nd order system with parameters:

     *Inputs*
    NFREQ
          natural frequency [Hz]. (not in rad/s)

    DAMP
          damping coefficient

    GAIN
          dc-gain This is steady state value only for damp > 0.  gain
          is assumed to be 1.0 if omitted.

     *Output*
    OUTSYS
          system data structure has representation with w = 2 * pi *
          nfreq:
                   /                                        \
                   | / -2w*damp -w \  / w \                 |
               G = | |             |, |   |, [ 0  gain ], 0 |
                   | \   w       0 /  \ 0 /                 |
                   \                                        /
*See also* `jet707' (MIMO example, Boeing 707-321
     aircraft model)

 -- Function File:  sysadd (GSYS, HSYS)
     returns SYS = GSYS + HSYS.
        * Exits with an error if GSYS and HSYS are not compatibly
          dimensioned.

        * Prints a warning message is system states have identical
          names; duplicate names are given a suffix to make them unique.

        * SYS input/output names are taken from GSYS.

                    ________
               ----|  gsys  |---
          u   |    ----------  +|
          -----                (_)----> y
              |     ________   +|
               ----|  hsys  |---
                    --------

 -- Function File: SYS = sysappend (SYST, B, C, D, OUTNAME, INNAME, YD)
     appends new inputs and/or outputs to a system

     *Inputs*
    SYST
          system data structure

    B
          matrix to be appended to sys "B" matrix (empty if none)

    C
          matrix to be appended to sys "C" matrix (empty if none)

    D
          revised sys d matrix (can be passed as [] if the revised d is
          all zeros)

    OUTNAME
          list of names for new outputs

    INNAME
          list of names for new inputs

    YD
          binary vector; yd(ii)=0 indicates a continuous output;
          yd(ii)=1 indicates a discrete output.

     *Outputs*
    SYS
                  sys.b := [syst.b , b]
                  sys.c := [syst.c  ]
                           [ c     ]
                  sys.d := [syst.d | D12 ]
                           [ D21   | D22 ]
          where D12, D21, and D22 are the appropriate dimensioned
          blocks of the input parameter D.
             * The leading block D11 of D is ignored.

             * If INNAME and OUTNAME are not given as arguments,
               the new inputs and outputs are be assigned default names.

             * YD is a binary vector of length rows(c) that indicates
                 continuous/sampled outputs.  Default value for YD is:
                  - SYS is continuous or mixed YD = `zeros(1,rows(c))'

                  - SYS is discrete YD = `ones(1,rows(c))'

 -- Function File: CLSYS = sysconnect (SYS, OUT_IDX, IN_IDX, ORDER, TOL)
     Close the loop from specified outputs to respective specified
     inputs

     *Inputs*
    SYS
          System data structure.

    OUT_IDX
    IN_IDX
          Names or indices of signals to connect (see `sysidx').  The
          output specified by out_idx(ii) is connected to the input
          specified by in_idx(ii).

    ORDER
          logical flag (default = 0)
         `0'
               Leave inputs and outputs in their original order.

         `1'
               Permute inputs and outputs to the order shown in the
               diagram below.

    TOL
          Tolerance for singularities in algebraic loops, default:
          200`eps'.

     *Outputs*
    CLSYS
          Resulting closed loop system.

     *Method*

     `sysconnect' internally permutes selected inputs, outputs as shown
     below, closes the loop, and then permutes inputs and outputs back
     to their original order
                           --------------------
           u_1       ----->|                  |----> y_1
                           |        sys       |
                   old u_2 |                  |
          u_2* ---->(+)--->|                  |----->y_2
          (in_idx)   ^     --------------------    | (out_idx)
                     |                             |
                     -------------------------------
     The input that has the summing junction added to it has an *
     added to the end  of the input name.

 -- Function File: [CSYS, ACD, CCD] = syscont (SYS)
     Extract the purely continuous subsystem of an input system.

     *Input*
    SYS
          system data structure.

     *Outputs*
    CSYS
          is the purely continuous input/output connections of SYS

    ACD
    CCD
          connections from discrete states to continuous states,
          discrete states to continuous outputs, respectively.

          If no continuous path exists, CSYS will be empty.

 -- Function File: [DSYS, ADC, CDC] = sysdisc (SYS)
     *Input*
    SYS
          System data structure.

     *Outputs*
    DSYS
          Purely discrete portion of sys (returned empty if there is no
          purely discrete path from inputs to outputs).

    ADC
    CDC
          Connections from continuous states to discrete states and
          discrete outputs, respectively.

 -- Function File: RETSYS = sysdup (ASYS, OUT_IDX, IN_IDX)
     Duplicate specified input/output connections of a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX
    IN_IDX
          indices or names of desired signals (see `sigidx').
          duplicates are made of `y(out_idx(ii))' and `u(in_idx(ii))'.

     *Output*
    RETSYS
          Resulting closed loop system: duplicated i/o names are
          appended with a `"+"' suffix.

     *Method*

     `sysdup' creates copies of selected inputs and outputs as shown
     below.  U1, Y1 is the set of original inputs/outputs, and U2, Y2
     is the set of duplicated inputs/outputs in the order specified in
     IN_IDX, OUT_IDX, respectively
                    ____________________
          u1  ----->|                  |----> y1
                    |       asys       |
          u2 ------>|                  |----->y2
          (in_idx)  -------------------- (out_idx)

 -- Function File: SYS = sysgroup (ASYS, BSYS)
     Combines two systems into a single system.

     *Inputs*
    ASYS
    BSYS
          System data structures.

     *Output*
    SYS
          sys = block diag(asys,bsys)

                   __________________
                   |    ________    |
          u1 ----->|--> | asys |--->|----> y1
                   |    --------    |
                   |    ________    |
          u2 ----->|--> | bsys |--->|----> y2
                   |    --------    |
                   ------------------
                        Ksys
     The function also rearranges the internal state-space
     realization of SYS so that the continuous states come first and
     the discrete states come last.  If there are duplicate names, the
     second name has a unique suffix appended on to the end of the name.

 -- Function File: SYS = sysmult (ASYS, BSYS)
     Compute sys = Asys*Bsys (series connection):
          u   ----------     ----------
          --->|  Bsys  |---->|  Asys  |--->
              ----------     ----------
     A warning occurs if there is direct feed-through from an input
     or a continuous state of BSYS, through a discrete output of BSYS,
     to a continuous state or output in ASYS (system data structure
     does not recognize discrete inputs).

 -- Function File: RETSYS = sysprune (ASYS, OUT_IDX, IN_IDX)
     Extract specified inputs/outputs from a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX
    IN_IDX
          Indices or signal names of the outputs and inputs to be kept
          in the returned system; remaining connections are "pruned"
          off.  May select as [] (empty matrix) to specify all
          outputs/inputs.

               retsys = sysprune (Asys, [1:3,4], "u_1");
               retsys = sysprune (Asys, {"tx", "ty", "tz"}, 4);


     *Output*
    RETSYS
          Resulting system.

                     ____________________
          u1 ------->|                  |----> y1
           (in_idx)  |       Asys       | (out_idx)
          u2 ------->|                  |----| y2
            (deleted)-------------------- (deleted)

 -- Function File: PV = sysreorder (VLEN, LIST)
     *Inputs*
    VLEN
          Vector length.

    LIST
          A subset of `[1:vlen]'.

     *Output*
    PV
          A permutation vector to order elements of `[1:vlen]' in
          `list' to the end of a vector.

     Used internally by `sysconnect' to permute vector elements to their
     desired locations.

 -- Function File: RETSYS = sysscale (SYS, OUTSCALE, INSCALE, OUTNAME,
          INNAME)
     scale inputs/outputs of a system.

     *Inputs*
    SYS
          Structured system.

    OUTSCALE
    INSCALE
          Constant matrices of appropriate dimension.

    OUTNAME
    INNAME
          Lists of strings with the names of respectively outputs and
          inputs.

     *Output*
    RETSYS
          resulting open loop system:
                     -----------    -------    -----------
               u --->| inscale |--->| sys |--->| outscale |---> y
                     -----------    -------    -----------
     If the input names and output names (each a list of strings)
     are not given and the scaling matrices are not square, then
     default names will be given to the inputs and/or outputs.

     A warning message is printed if outscale attempts to add continuous
     system outputs to discrete system outputs; otherwise YD is set
     appropriately in the returned value of SYS.

 -- Function File: SYS = syssub (GSYS, HSYS)
     Return sys = Gsys - Hsys.

     *Method*

     GSYS and HSYS are connected in parallel.  The input vector is
     connected to both systems; the outputs are subtracted.  Returned
     system names are those of GSYS.
                   +--------+
              +--->|  Gsys  |---+
              |    +--------+   |
              |                +|
          u --+                (_)--> y
              |                -|
              |    +--------+   |
              +--->|  Hsys  |---+
                   +--------+

 -- Function File:  ugain (N)
     Creates a system with unity gain, no states.  This trivial system
     is sometimes needed to create arbitrary complex systems from
     simple systems with `buildssic'.  Watch out if you are forming
     sampled systems since `ugain' does not contain a sampling period.

     *See also:* hinfdemo, jet707.

 -- Function File: W = wgt1o (VL, VH, FC)
     State space description of a first order weighting function.

     Weighting function are needed by the H-2/H-infinity design
     procedure.  These functions are part of the augmented plant P (see
     `hinfdemo' for an application example).

     *Inputs*
    VL
          Gain at low frequencies.

    VH
          Gain at high frequencies.

    FC
          Corner frequency (in Hz, *not* in rad/sec)

     *Output*
    W
          Weighting function, given in form of a system data structure.

 -- Function File: KSYS = parallel (ASYS, BSYS)
     Forms the parallel connection of two systems.

                       --------------------
                       |      --------    |
              u  ----->|----> | asys |--->|----> y1
                  |    |      --------    |
                  |    |      --------    |
                  |--->|----> | bsys |--->|----> y2
                       |      --------    |
                       --------------------
                            ksys

 -- Function File: [RETSYS, NC, NO] = sysmin (SYS, FLG)
     Returns a minimal (or reduced order) system

     *Inputs*
    SYS
          System data structure

    FLG
          When equal to 0 (default value), returns minimal system, in
          which state names are lost; when equal to 1, returns system
          with physical states removed that are either uncontrollable or
          unobservable (cannot reduce further without discarding
          physical meaning of states).
     *Outputs*
    RETSYS
          Returned system.

    NC
          Number of controllable states in the returned system.

    NO
          Number of observable states in the returned system.

    CFLG
          `is_controllable(retsys)'.

    OFLG
          `is_observable(retsys)'.

