This is octave.info, produced by makeinfo version 6.5 from octave.texi.

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

Copyright © 1996-2020 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: Mathematical Considerations,  Prev: Return Types of Operators and Functions,  Up: Operators and Functions

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

   First, 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 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 nonzero
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
“amd”, “colamd” or “ccolamd” should be used.  For completeness the
reordering functions “colperm” and “randperm” are also available.

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

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

Figure 22.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);’.  *Note Figure
22.3: fig:simplechol.  The original matrix had 43 nonzero 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 nonzero 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, p, q] = chol (A); spy (r)’.

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

Figure 22.3: Structure of the unpermuted Cholesky factorization of the
above matrix.

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

Figure 22.4: Structure of the permuted Cholesky factorization of the
above matrix.

   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.

 -- : P = amd (S)
 -- : P = amd (S, OPTS)

     Return the approximate minimum degree permutation of a matrix.

     This is a permutation such that the Cholesky factorization of ‘S
     (P, P)’ tends to be sparser than the Cholesky factorization of S
     itself.  ‘amd’ is typically faster than ‘symamd’ but serves a
     similar purpose.

     The optional parameter OPTS is a structure that controls the
     behavior of ‘amd’.  The fields of the structure are

     OPTS.dense
          Determines what ‘amd’ considers to be a dense row or column of
          the input matrix.  Rows or columns with more than ‘max (16,
          (dense * sqrt (N)))’ entries, where N is the order of the
          matrix S, are ignored by ‘amd’ during the calculation of the
          permutation.  The value of dense must be a positive scalar and
          the default value is 10.0

     OPTS.aggressive
          If this value is a nonzero scalar, then ‘amd’ performs
          aggressive absorption.  The default is not to perform
          aggressive absorption.

     The author of the code itself is Timothy A. Davis (see
     <http://faculty.cse.tamu.edu/davis/suitesparse.html>).

     See also: *note symamd: XREFsymamd, *note colamd: XREFcolamd.

 -- : P = ccolamd (S)
 -- : P = ccolamd (S, KNOBS)
 -- : P = ccolamd (S, KNOBS, CMEMBER)
 -- : [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 1-element to 5-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.

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

     ‘KNOBS(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).

     ‘KNOBS(4)’
          if nonzero, aggressive absorption is performed.

     ‘KNOBS(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 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://faculty.cse.tamu.edu/davis/suitesparse.html> for ccolamd,
     csymamd, amd, colamd, symamd, and other related orderings.

     See also: *note colamd: XREFcolamd, *note csymamd: XREFcsymamd.

 -- : P = colamd (S)
 -- : P = colamd (S, KNOBS)
 -- : [P, STATS] = colamd (S)
 -- : [P, STATS] = colamd (S, KNOBS)

     Compute the 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.  The algorithm was developed in collaboration with John
     Gilbert, Xerox PARC, and Esmond Ng, Oak Ridge National Laboratory.
     (see <http://faculty.cse.tamu.edu/davis/suitesparse.html>)

     See also: *note colperm: XREFcolperm, *note symamd: XREFsymamd,
     *note ccolamd: XREFccolamd.

 -- : P = colperm (S)
     Return the column permutations such that the columns of ‘S (:, P)’
     are ordered in terms of increasing number of nonzero elements.

     If S is symmetric, then P is chosen such that ‘S (P, P)’ orders the
     rows and columns with increasing number of nonzeros elements.

 -- : P = csymamd (S)
 -- : P = csymamd (S, KNOBS)
 -- : P = csymamd (S, KNOBS, CMEMBER)
 -- : [P, STATS] = csymamd (...)

     For a symmetric positive definite matrix S, return 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 1-element to 3-element input vector, with a
     default value of ‘[10 1 0]’.  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 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://faculty.cse.tamu.edu/davis/suitesparse.html> for ccolamd,
     colamd, csymamd, amd, colamd, symamd, and other related orderings.

     See also: *note symamd: XREFsymamd, *note ccolamd: XREFccolamd.

 -- : P = dmperm (S)
 -- : [P, Q, R, S] = dmperm (S)

     Perform a Dulmage-Mendelsohn permutation of 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: *note colamd: XREFcolamd, *note ccolamd: XREFccolamd.

 -- : P = symamd (S)
 -- : P = symamd (S, KNOBS)
 -- : [P, STATS] = symamd (S)
 -- : [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.  The algorithm was developed in collaboration with John
     Gilbert, Xerox PARC, and Esmond Ng, Oak Ridge National Laboratory.
     (see <http://faculty.cse.tamu.edu/davis/suitesparse.html>)

     See also: *note colperm: XREFcolperm, *note colamd: XREFcolamd.

 -- : P = symrcm (S)
     Return the symmetric reverse Cuthill-McKee permutation of S.

     P is a permutation vector 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.

     A. George, J.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: *note colperm: XREFcolperm, *note colamd: XREFcolamd,
     *note symamd: XREFsymamd.


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

22.2 Linear Algebra on Sparse Matrices
======================================

Octave includes a polymorphic 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 an 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, solve, and perform one refinement iteration 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 nonzero values in the
band divided by the total number of values in the full band.  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-Mendelsohn
decomposition, 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 that identifying the type of the
matrix incorrectly will lead to unpredictable results, and so
‘matrix_type’ should be used with care.

 -- : NEST = normest (A)
 -- : NEST = normest (A, TOL)
 -- : [NEST, ITER] = normest (...)
     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 ‘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.

     The optional output ITER returns the number of iterations that were
     required for ‘normest’ to converge.

     See also: *note normest1: XREFnormest1, *note norm: XREFnorm, *note
     cond: XREFcond, *note condest: XREFcondest.

 -- : NEST = normest1 (A)
 -- : NEST = normest1 (A, T)
 -- : NEST = normest1 (A, T, X0)
 -- : NEST = normest1 (AFUN, T, X0, P1, P2, ...)
 -- : [NEST, V] = normest1 (A, ...)
 -- : [NEST, V, W] = normest1 (A, ...)
 -- : [NEST, V, W, ITER] = normest1 (A, ...)
     Estimate the 1-norm of the matrix A using a block algorithm.

     ‘normest1’ is best for large sparse matrices where only an estimate
     of the norm is required.  For small to medium sized matrices,
     consider using ‘norm (A, 1)’.  In addition, ‘normest1’ can be used
     for the estimate of the 1-norm of a linear operator A when
     matrix-vector products ‘A * X’ and ‘A' * X’ can be cheaply
     computed.  In this case, instead of the matrix A, a function ‘AFUN
     (FLAG, X)’ is used; it must return:

        • the dimension N of A, if FLAG is "dim"

        • true if A is a real operator, if FLAG is "real"

        • the result ‘A * X’, if FLAG is "notransp"

        • the result ‘A' * X’, if FLAG is "transp"

     A typical case is A defined by ‘B ^ M’, in which the result ‘A * X’
     can be computed without even forming explicitly ‘B ^ M’ by:

          Y = X;
          for I = 1:M
            Y = B * Y;
          endfor

     The parameters P1, P2, ... are arguments of ‘AFUN (FLAG, X, P1, P2,
     ...)’.

     The default value for T is 2.  The algorithm requires matrix-matrix
     products with sizes N x N and N x T.

     The initial matrix X0 should have columns of unit 1-norm.  The
     default initial matrix X0 has the first column ‘ones (N, 1) / N’
     and, if T > 1, the remaining columns with random elements ‘-1 / N’,
     ‘1 / N’, divided by N.

     On output, NEST is the desired estimate, V and W are vectors such
     that ‘W = A * V’, with ‘norm (W, 1)’ = ‘C * norm (V, 1)’.  ITER
     contains in ‘ITER(1)’ the number of iterations (the maximum is
     hardcoded to 5) and in ‘ITER(2)’ the total number of products ‘A *
     X’ or ‘A' * X’ performed by the algorithm.

     Algorithm Note: ‘normest1’ uses random numbers during evaluation.
     Therefore, if consistent results are required, the "state" of the
     random generator should be fixed before invoking ‘normest1’.

     Reference: N. J. Higham and F. Tisseur, ‘A block algorithm for
     matrix 1-norm estimation, with and application to 1-norm
     pseudospectra’, SIAM J. Matrix Anal.  Appl., pp.  1185–1201, Vol
     21, No.  4, 2000.

     See also: *note normest: XREFnormest, *note norm: XREFnorm, *note
     cond: XREFcond, *note condest: XREFcondest.

 -- : CEST = condest (A)
 -- : CEST = condest (A, T)
 -- : CEST = condest (A, SOLVEFUN, T, P1, P2, ...)
 -- : CEST = condest (AFCN, SOLVEFUN, T, P1, P2, ...)
 -- : [CEST, V] = condest (...)

     Estimate the 1-norm condition number of a square matrix A using T
     test vectors and a randomized 1-norm estimator.

     The optional input T specifies the number of test vectors (default
     5).

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

        − AFCN which must return

             • the dimension N of A, if FLAG is "dim"

             • true if A is a real operator, if FLAG is "real"

             • the result ‘A * X’, if FLAG is "notransp"

             • the result ‘A' * X’, if FLAG is "transp"

        − SOLVEFUN which must return

             • the dimension N of A, if FLAG is "dim"

             • true if A is a real operator, if FLAG is "real"

             • the result ‘A \ X’, if FLAG is "notransp"

             • the result ‘A' \ X’, if FLAG is "transp"

     The parameters P1, P2, ... are arguments of ‘AFCN (FLAG, X, P1, P2,
     ...)’ and ‘SOLVEFCN (FLAG, X, P1, P2, ...)’.

     The principal output is the 1-norm condition number estimate CEST.

     The optional second output is an approximate null vector when CEST
     is large; it satisfies the equation ‘norm (A*v, 1) == norm (A, 1) *
     norm (V, 1) / EST’.

     Algorithm Note: ‘condest’ uses a randomized algorithm to
     approximate the 1-norms.  Therefore, if consistent results are
     required, the "state" of the random generator should be fixed
     before invoking ‘condest’.

     References:

        • N.J. Higham and F. Tisseur, ‘A Block Algorithm for Matrix
          1-Norm Estimation, with an Application to 1-Norm
          Pseudospectra’.  SIMAX vol 21, no 4, pp 1185–1201.
          <https://dx.doi.org/10.1137/S0895479899356080>

        • N.J. Higham and F. Tisseur, ‘A Block Algorithm for Matrix
          1-Norm Estimation, with an Application to 1-Norm
          Pseudospectra’.  <https://citeseer.ist.psu.edu/223007.html>

     See also: *note cond: XREFcond, *note norm: XREFnorm, *note
     normest1: XREFnormest1, *note normest: XREFnormest.

 -- : spparms ()
 -- : VALS = spparms ()
 -- : [KEYS, VALS] = spparms ()
 -- : VAL = spparms (KEY)
 -- : spparms (VALS)
 -- : spparms ("default")
 -- : spparms ("tight")
 -- : spparms (KEY, VAL)
     Query or set 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 following 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)

     ‘sym_tol’
          The pivot tolerance of the UMFPACK symmetric solvers (default
          0.001)

     ‘bandden’
          The density of nonzero elements in a banded matrix before it
          is treated by the LAPACK banded solvers (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
     "default".  The special keyword "tight" can be used to set the mmd
     solvers to attempt a sparser solution at the potential cost of
     longer running time.

     See also: *note chol: XREFchol, *note colamd: XREFcolamd, *note lu:
     XREFlu, *note qr: XREFqr, *note symamd: XREFsymamd.

 -- : P = sprank (S)

     Calculate the structural rank of the sparse matrix S.

     Note that only the structure of the matrix is used in this
     calculation based on a Dulmage-Mendelsohn permutation 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: *note dmperm: XREFdmperm.

 -- : [COUNT, H, PARENT, POST, R] = symbfact (S)
 -- : [...] = symbfact (S, TYP)
 -- : [...] = symbfact (S, TYP, MODE)

     Perform a symbolic factorization analysis of the sparse matrix S.

     The input variables are

     S
          S is a real or complex sparse matrix.

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

          "sym" (default)
               Factorize S.  Assumes S is symmetric and uses the upper
               triangular portion of the matrix.

          "col"
               Factorize S’ * S.

          "row"
               Factorize S * S’.

          "lo"
               Factorize S’.  Assumes S is symmetric and uses the lower
               triangular portion of the matrix.

     MODE
          When MODE is unspecified return the Cholesky factorization for
          R.  If MODE is "lower" or "L" then return the conjugate
          transpose R’ which is a lower triangular factor.  The
          conjugate transpose version is faster and uses less memory,
          but still returns the same values for all other outputs:
          COUNT, H, PARENT, and POST.

     The output variables are:

     COUNT
          The row counts of the Cholesky factorization as determined by
          TYP.  The computational difficulty of performing the true
          factorization using ‘chol’ is ‘sum (COUNT .^ 2)’.

     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.

     See also: *note chol: XREFchol, *note etree: XREFetree, *note
     treelayout: XREFtreelayout.

   For non square matrices, the user can also utilize the ‘spaugment’
function to find a least squares solution to a linear equation.

 -- : S = spaugment (A, C)
     Create the augmented matrix of A.

     This is given by

          [C * eye(M, M), A;
                      A', zeros(N, N)]

     This is related to the least squares solution of ‘A \ B’, by

          S * [ R / C; x] = [ B, zeros(N, columns(B)) ]

     where R is the residual error

          R = B - A * X

     As the matrix S is symmetric indefinite it can be factorized with
     ‘lu’, and the minimum norm solution can therefore be found without
     the need for a ‘qr’ factorization.  As the residual error will be
     ‘zeros (M, M)’ for underdetermined problems, and example can be

          m = 11; n = 10; mn = max (m, n);
          A = spdiags ([ones(mn,1), 10*ones(mn,1), -ones(mn,1)],
                       [-1, 0, 1], m, n);
          x0 = A \ ones (m,1);
          s = spaugment (A);
          [L, U, P, Q] = lu (s);
          x1 = Q * (U \ (L \ (P  * [ones(m,1); zeros(n,1)])));
          x1 = x1(end - n + 1 : end);

     To find the solution of an overdetermined problem needs an estimate
     of the residual error R and so it is more complex to formulate a
     minimum norm solution using the ‘spaugment’ function.

     In general the left division operator is more stable and faster
     than using the ‘spaugment’ function.

     See also: *note mldivide: XREFmldivide.

   Finally, the function ‘eigs’ can be used to calculate a limited
number of eigenvalues and eigenvectors based on a selection criteria and
likewise for ‘svds’ which calculates a limited number of singular values
and vectors.

 -- : D = eigs (A)
 -- : D = eigs (A, K)
 -- : D = eigs (A, K, SIGMA)
 -- : D = eigs (A, K, SIGMA, OPTS)
 -- : D = eigs (A, B)
 -- : D = eigs (A, B, K)
 -- : D = eigs (A, B, K, SIGMA)
 -- : D = eigs (A, B, K, SIGMA, OPTS)
 -- : D = eigs (AF, N)
 -- : D = eigs (AF, N, B)
 -- : D = eigs (AF, N, K)
 -- : D = eigs (AF, N, B, K)
 -- : D = eigs (AF, N, K, SIGMA)
 -- : D = eigs (AF, N, B, K, SIGMA)
 -- : D = eigs (AF, N, K, SIGMA, OPTS)
 -- : D = eigs (AF, N, B, K, SIGMA, OPTS)
 -- : [V, D] = eigs (A, ...)
 -- : [V, D] = eigs (AF, N, ...)
 -- : [V, D, FLAG] = eigs (A, ...)
 -- : [V, D, FLAG] = eigs (AF, N, ...)
     Calculate a limited number of eigenvalues and eigenvectors of A,
     based on a selection criteria.

     The number of eigenvalues and eigenvectors to calculate is given by
     K and defaults to 6.

     By default, ‘eigs’ solve the equation ‘A * v = lambda * v’, where
     ‘lambda’ is a scalar representing one of the eigenvalues, and ‘v’
     is the corresponding eigenvector.  If given the positive definite
     matrix B then ‘eigs’ solves the general eigenvalue equation ‘A * v
     = lambda * B * v’.

     The argument SIGMA determines which eigenvalues are returned.
     SIGMA can be either a scalar or a string.  When SIGMA is a scalar,
     the K eigenvalues closest to SIGMA are returned.  If SIGMA is a
     string, it must have one of the following values.

     "lm"
          Largest Magnitude (default).

     "sm"
          Smallest Magnitude.

     "la"
          Largest Algebraic (valid only for real symmetric problems).

     "sa"
          Smallest Algebraic (valid only for real symmetric problems).

     "be"
          Both Ends, with one more from the high-end if K is odd (valid
          only for real symmetric problems).

     "lr"
          Largest Real part (valid only for complex or unsymmetric
          problems).

     "sr"
          Smallest Real part (valid only for complex or unsymmetric
          problems).

     "li"
          Largest Imaginary part (valid only for complex or unsymmetric
          problems).

     "si"
          Smallest Imaginary part (valid only for complex or unsymmetric
          problems).

     If OPTS is given, it is a structure defining possible options that
     ‘eigs’ should use.  The fields of the OPTS structure are:

     ‘issym’
          If AF is given, then flags whether the function AF defines a
          symmetric problem.  It is ignored if A is given.  The default
          is false.

     ‘isreal’
          If AF is given, then flags whether the function AF defines a
          real problem.  It is ignored if A is given.  The default is
          true.

     ‘tol’
          Defines the required convergence tolerance, calculated as ‘tol
          * norm (A)’.  The default is ‘eps’.

     ‘maxit’
          The maximum number of iterations.  The default is 300.

     ‘p’
          The number of Lanzcos basis vectors to use.  More vectors will
          result in faster convergence, but a greater use of memory.
          The optimal value of ‘p’ is problem dependent and should be in
          the range ‘K + 1’ to N.  The default value is ‘2 * K’.

     ‘v0’
          The starting vector for the algorithm.  An initial vector
          close to the final vector will speed up convergence.  The
          default is for ARPACK to randomly generate a starting vector.
          If specified, ‘v0’ must be an N-by-1 vector where ‘N = rows
          (A)’

     ‘disp’
          The level of diagnostic printout (0|1|2).  If ‘disp’ is 0 then
          diagnostics are disabled.  The default value is 0.

     ‘cholB’
          Flag if ‘chol (B)’ is passed rather than B.  The default is
          false.

     ‘permB’
          The permutation vector of the Cholesky factorization of B if
          ‘cholB’ is true.  It is obtained by ‘[R, ~, permB] = chol (B,
          "vector")’.  The default is ‘1:N’.

     It is also possible to represent A by a function denoted AF.  AF
     must be followed by a scalar argument N defining the length of the
     vector argument accepted by AF.  AF can be a function handle, an
     inline function, or a string.  When AF is a string it holds the
     name of the function to use.

     AF is a function of the form ‘y = af (x)’ where the required return
     value of AF is determined by the value of SIGMA.  The four possible
     forms are

     ‘A * x’
          if SIGMA is not given or is a string other than "sm".

     ‘A \ x’
          if SIGMA is 0 or "sm".

     ‘(A - sigma * I) \ x’
          for the standard eigenvalue problem, where ‘I’ is the identity
          matrix of the same size as A.

     ‘(A - sigma * B) \ x’
          for the general eigenvalue problem.

     The return arguments of ‘eigs’ depend on the number of return
     arguments requested.  With a single return argument, a vector D of
     length K is returned containing the K eigenvalues that have been
     found.  With two return arguments, V is a N-by-K matrix whose
     columns are the K eigenvectors corresponding to the returned
     eigenvalues.  The eigenvalues themselves are returned in D in the
     form of a N-by-K matrix, where the elements on the diagonal are the
     eigenvalues.

     Given a third return argument FLAG, ‘eigs’ returns the status of
     the convergence.  If FLAG is 0 then all eigenvalues have converged.
     Any other value indicates a failure to converge.

     This function is based on the ARPACK package, written by R.
     Lehoucq, K. Maschhoff, D. Sorensen, and C. Yang.  For more
     information see <http://www.caam.rice.edu/software/ARPACK/>.

     See also: *note eig: XREFeig, *note svds: XREFsvds.

 -- : S = svds (A)
 -- : S = svds (A, K)
 -- : S = svds (A, K, SIGMA)
 -- : S = svds (A, K, SIGMA, OPTS)
 -- : [U, S, V] = svds (...)
 -- : [U, S, V, FLAG] = svds (...)

     Find a few singular values of the matrix A.

     The singular values are calculated using

          [M, N] = size (A);
          S = eigs ([sparse(M, M), A;
                               A', sparse(N, N)])

     The eigenvalues returned by ‘eigs’ correspond to the singular
     values of A.  The number of singular values to calculate is given
     by K and defaults to 6.

     The argument SIGMA specifies which singular values to find.  When
     SIGMA is the string ’L’, the default, the largest singular values
     of A are found.  Otherwise, SIGMA must be a real scalar and the
     singular values closest to SIGMA are found.  As a corollary, ‘SIGMA
     = 0’ finds the smallest singular values.  Note that for relatively
     small values of SIGMA, there is a chance that the requested number
     of singular values will not be found.  In that case SIGMA should be
     increased.

     OPTS is a structure defining options that ‘svds’ will pass to
     ‘eigs’.  The possible fields of this structure are documented in
     ‘eigs’.  By default, ‘svds’ sets the following three fields:

     ‘tol’
          The required convergence tolerance for the singular values.
          The default value is 1e-10.  ‘eigs’ is passed ‘TOL / sqrt(2)’.

     ‘maxit’
          The maximum number of iterations.  The default is 300.

     ‘disp’
          The level of diagnostic printout (0|1|2).  If ‘disp’ is 0 then
          diagnostics are disabled.  The default value is 0.

     If more than one output is requested then ‘svds’ will return an
     approximation of the singular value decomposition of A

          A_approx = U*S*V'

     where A_approx is a matrix of size A but only rank K.

     FLAG returns 0 if the algorithm has successfully converged, and 1
     otherwise.  The test for convergence is

          norm (A*V - U*S, 1) <= TOL * norm (A, 1)

     ‘svds’ is best for finding only a few singular values from a large
     sparse matrix.  Otherwise, ‘svd (full (A))’ will likely be more
     efficient.

     See also: *note svd: XREFsvd, *note eigs: XREFeigs.

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

   (1) The CHOLMOD, UMFPACK and CXSPARSE packages were written by Tim
Davis and are available at
<http://faculty.cse.tamu.edu/davis/suitesparse.html>


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

22.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 also includes a number of
functions to solve sparse linear equations using iterative techniques.

 -- : X = pcg (A, B, TOL, MAXIT, M1, M2, X0, ...)
 -- : X = pcg (A, B, TOL, MAXIT, M, [], X0, ...)
 -- : [X, FLAG, RELRES, ITER, RESVEC, EIGEST] = pcg (A, B, ...)

     Solve the linear system of equations ‘A * X = B’ by means of the
     Preconditioned Conjugate Gradient iterative method.

     The input arguments are:

        • A is the matrix of the linear system and it must be square.  A
          can be passed as a matrix, function handle, or inline function
          ‘Afun’ such that ‘Afun(x) = A * x’.  Additional parameters to
          ‘Afun’ may be passed after X0.

          A has to be Hermitian and Positive Definite (HPD).  If ‘pcg’
          detects A not to be positive definite, a warning is printed
          and the FLAG output is 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)’.  If TOL is omitted or
          empty, then a tolerance of 1e-6 is used.

        • MAXIT is the maximum allowed number of iterations; if MAXIT is
          omitted or empty then a value of 20 is used.

        • M is a HPD preconditioning matrix.  For any decomposition ‘M =
          P1 * P2’ such that ‘inv (P1) * A * inv (P2)’ is HPD, the
          conjugate gradient method is formally applied to the linear
          system ‘inv (P1) * A * inv (P2) * Y = inv (P1) * B’, with ‘X =
          inv (P2) * Y’ (split preconditioning).  In practice, at each
          iteration of the conjugate gradient method a linear system
          with matrix M is solved with ‘mldivide’.  If a particular
          factorization ‘M = M1 * M2’ is available (for instance, an
          incomplete Cholesky factorization of A), the two matrices M1
          and M2 can be passed and the relative linear systems are
          solved with the ‘mldivide’ operator.  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.  If M1 is
          omitted or empty ‘[]’, then no preconditioning is applied.  If
          no factorization of M is available, M2 can be omitted or left
          [], and the input variable M1 can be used to pass the
          preconditioner M.

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

     The arguments which follow X0 are treated as parameters, and passed
     in an appropriate manner to any of the functions (A or M1 or M2)
     that have been given 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’.  If the algorithm did not converge, then X is the
          iteration which has the minimum residual.

        • FLAG reports on the convergence:

             • 0: The algorithm converged to within the prescribed
               tolerance.

             • 1: The algorithm did not converge and it reached the
               maximum number of iterations.

             • 2: The preconditioner matrix is singular.

             • 3: The algorithm stagnated, i.e., the absolute value of
               the difference between the current iteration X and the
               previous is less than ‘EPS * norm (X,2)’.

             • 4: The algorithm detects that the input (preconditioned)
               matrix is not HPD.

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

        • ITER indicates the iteration of X which it was computed.
          Since the output X corresponds to the minimal residual
          solution, the total number of iterations that the method
          performed is given by ‘length(resvec) - 1’.

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

     Let us consider a trivial problem with a tridiagonal matrix

          n = 10;
          A = toeplitz (sparse ([1, 1], [1, 2], [2, 1], 1, n));
          b = A * ones (n, 1);
          M1 = ichol (A); # in this tridiagonal case it corresponds to chol (A)'
          M2 = M1';
          M = M1 * M2;
          Afun = @(x) A * x;
          Mfun = @(x) M \ x;
          M1fun = @(x) M1 \ x;
          M2fun = @(x) M2 \ x;

     EXAMPLE 1: Simplest use of ‘pcg’

          x = pcg (A, b)

     EXAMPLE 2: ‘pcg’ with a function which computes ‘A * X’

          x = pcg (Afun, b)

     EXAMPLE 3: ‘pcg’ with a preconditioner matrix M

          x = pcg (A, b, 1e-06, 100, M)

     EXAMPLE 4: ‘pcg’ with a function as preconditioner

          x = pcg (Afun, b, 1e-6, 100, Mfun)

     EXAMPLE 5: ‘pcg’ with preconditioner matrices M1 and M2

          x = pcg (A, b, 1e-6, 100, M1, M2)

     EXAMPLE 6: ‘pcg’ with functions as preconditioners

          x = pcg (Afun, b, 1e-6, 100, M1fun, M2fun)

     EXAMPLE 7: ‘pcg’ with as input a function requiring an argument

            function y = Ap (A, x, p) # compute A^p * x
               y = x;
               for i = 1:p
                 y = A * y;
               endfor
            endfunction
          Apfun = @(x, p) Ap (A, x, p);
          x = pcg (Apfun, b, [], [], [], [], [], 2);

     EXAMPLE 8: explicit example to show that ‘pcg’ uses a split
     preconditioner

          M1 = ichol (A + 0.1 * eye (n)); # factorization of A perturbed
          M2 = M1';
          M = M1 * M2;

          ## reference solution computed by pcg after two iterations
          [x_ref, fl] = pcg (A, b, [], 2, M)

          ## split preconditioning
          [y, fl] = pcg ((M1 \ A) / M2, M1 \ b, [], 2)
          x = M2 \ y # compare x and x_ref


     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
          <https://www-users.cs.umn.edu/~saad/books.html>

     See also: *note sparse: XREFsparse, *note pcr: XREFpcr, *note
     gmres: XREFgmres, *note bicg: XREFbicg, *note bicgstab:
     XREFbicgstab, *note cgs: XREFcgs.

 -- : X = pcr (A, B, TOL, MAXIT, M, X0, ...)
 -- : [X, FLAG, RELRES, ITER, RESVEC] = pcr (...)

     Solve 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 a ‘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 = sparse (diag (1:n));
          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 = apply_a (x)
            y = [1:10]' .* x;
          endfunction

          x = pcr ("apply_a", 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 = apply_m (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, [], [], "apply_m")
          semilogy ([1:iter+1], resvec);

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

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

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

     References:

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

     See also: *note sparse: XREFsparse, *note pcg: XREFpcg.

   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.

 -- : L = ichol (A)
 -- : L = ichol (A, OPTS)

     Compute the incomplete Cholesky factorization of the sparse square
     matrix A.

     By default, ‘ichol’ uses only the lower triangle of A and produces
     a lower triangular factor L such that L*L’ approximates A.

     The factor given by this routine may be useful as a preconditioner
     for a system of linear equations being solved by iterative methods
     such as PCG (Preconditioned Conjugate Gradient).

     The factorization may be modified by passing options in a structure
     OPTS.  The option name is a field of the structure and the setting
     is the value of field.  Names and specifiers are case sensitive.

     type
          Type of factorization.

          "nofill" (default)
               Incomplete Cholesky factorization with no fill-in
               (IC(0)).

          "ict"
               Incomplete Cholesky factorization with threshold dropping
               (ICT).

     diagcomp
          A non-negative scalar ALPHA for incomplete Cholesky
          factorization of ‘A + ALPHA * diag (diag (A))’ instead of A.
          This can be useful when A is not positive definite.  The
          default value is 0.

     droptol
          A non-negative scalar specifying the drop tolerance for
          factorization if performing ICT.  The default value is 0 which
          produces the complete Cholesky factorization.

          Non-diagonal entries of L are set to 0 unless

          ‘abs (L(i,j)) >= droptol * norm (A(j:end, j), 1)’.

     michol
          Modified incomplete Cholesky factorization:

          "off" (default)
               Row and column sums are not necessarily preserved.

          "on"
               The diagonal of L is modified so that row (and column)
               sums are preserved even when elements have been dropped
               during the factorization.  The relationship preserved is:
               ‘A * e = L * L' * e’, where e is a vector of ones.

     shape

          "lower" (default)
               Use only the lower triangle of A and return a lower
               triangular factor L such that L*L’ approximates A.

          "upper"
               Use only the upper triangle of A and return an upper
               triangular factor U such that ‘U'*U’ approximates A.

     EXAMPLES

     The following problem demonstrates how to factorize a sample
     symmetric positive definite matrix with the full Cholesky
     decomposition and with the incomplete one.

          A = [ 0.37, -0.05,  -0.05,  -0.07;
               -0.05,  0.116,  0.0,   -0.05;
               -0.05,  0.0,    0.116, -0.05;
               -0.07, -0.05,  -0.05,   0.202];
          A = sparse (A);
          nnz (tril (A))
          ans =  9
          L = chol (A, "lower");
          nnz (L)
          ans =  10
          norm (A - L * L', "fro") / norm (A, "fro")
          ans =  1.1993e-16
          opts.type = "nofill";
          L = ichol (A, opts);
          nnz (L)
          ans =  9
          norm (A - L * L', "fro") / norm (A, "fro")
          ans =  0.019736

     Another example for decomposition is a finite difference matrix
     used to solve a boundary value problem on the unit square.

          nx = 400; ny = 200;
          hx = 1 / (nx + 1); hy = 1 / (ny + 1);
          Dxx = spdiags ([ones(nx, 1), -2*ones(nx, 1), ones(nx, 1)],
                         [-1 0 1 ], nx, nx) / (hx ^ 2);
          Dyy = spdiags ([ones(ny, 1), -2*ones(ny, 1), ones(ny, 1)],
                         [-1 0 1 ], ny, ny) / (hy ^ 2);
          A = -kron (Dxx, speye (ny)) - kron (speye (nx), Dyy);
          nnz (tril (A))
          ans =  239400
          opts.type = "nofill";
          L = ichol (A, opts);
          nnz (tril (A))
          ans =  239400
          norm (A - L * L', "fro") / norm (A, "fro")
          ans =  0.062327

     References for implemented algorithms:

     [1] Y. Saad.  "Preconditioning Techniques."  ‘Iterative Methods for
     Sparse Linear Systems’, PWS Publishing Company, 1996.

     [2] M. Jones, P. Plassmann: ‘An Improved Incomplete Cholesky
     Factorization’, 1992.

     See also: *note chol: XREFchol, *note ilu: XREFilu, *note pcg:
     XREFpcg.

 -- : ilu (A)
 -- : ilu (A, OPTS)
 -- : [L, U] = ilu (...)
 -- : [L, U, P] = ilu (...)

     Compute the incomplete LU factorization of the sparse square matrix
     A.

     ‘ilu’ returns a unit lower triangular matrix L, an upper triangular
     matrix U, and optionally a permutation matrix P, such that ‘L*U’
     approximates ‘P*A’.

     The factors given by this routine may be useful as preconditioners
     for a system of linear equations being solved by iterative methods
     such as BICG (BiConjugate Gradients) or GMRES (Generalized Minimum
     Residual Method).

     The factorization may be modified by passing options in a structure
     OPTS.  The option name is a field of the structure and the setting
     is the value of field.  Names and specifiers are case sensitive.

     ‘type’
          Type of factorization.

          "nofill" (default)
               ILU factorization with no fill-in (ILU(0)).

               Additional supported options: ‘milu’.

          "crout"
               Crout version of ILU factorization (ILUC).

               Additional supported options: ‘milu’, ‘droptol’.

          "ilutp"
               ILU factorization with threshold and pivoting.

               Additional supported options: ‘milu’, ‘droptol’, ‘udiag’,
               ‘thresh’.

     ‘droptol’
          A non-negative scalar specifying the drop tolerance for
          factorization.  The default value is 0 which produces the
          complete LU factorization.

          Non-diagonal entries of U are set to 0 unless

          ‘abs (U(i,j)) >= droptol * norm (A(:,j))’.

          Non-diagonal entries of L are set to 0 unless

          ‘abs (L(i,j)) >= droptol * norm (A(:,j))/U(j,j)’.

     ‘milu’
          Modified incomplete LU factorization:

          "row"
               Row-sum modified incomplete LU factorization.  The
               factorization preserves row sums: ‘A * e = L * U * e’,
               where e is a vector of ones.

          "col"
               Column-sum modified incomplete LU factorization.  The
               factorization preserves column sums: ‘e' * A = e' * L *
               U’.

          "off" (default)
               Row and column sums are not necessarily preserved.

     ‘udiag’
          If true, any zeros on the diagonal of the upper triangular
          factor are replaced by the local drop tolerance ‘droptol *
          norm (A(:,j))/U(j,j)’.  The default is false.

     ‘thresh’
          Pivot threshold for factorization.  It can range between 0
          (diagonal pivoting) and 1 (default), where the maximum
          magnitude entry in the column is chosen to be the pivot.

     If ‘ilu’ is called with just one output, the returned matrix is ‘L
     + U - speye (size (A))’, where L is unit lower triangular and U is
     upper triangular.

     With two outputs, ‘ilu’ returns a unit lower triangular matrix L
     and an upper triangular matrix U.  For OPTS.type == "ilutp", one of
     the factors is permuted based on the value of OPTS.milu.  When
     OPTS.milu == "row", U is a column permuted upper triangular factor.
     Otherwise, L is a row-permuted unit lower triangular factor.

     If there are three named outputs and OPTS.milu != "row", P is
     returned such that L and U are incomplete factors of ‘P*A’.  When
     OPTS.milu == "row", P is returned such that L and U are incomplete
     factors of ‘A*P’.

     EXAMPLES

          A = gallery ("neumann", 1600) + speye (1600);
          opts.type = "nofill";
          nnz (A)
          ans = 7840

          nnz (lu (A))
          ans = 126478

          nnz (ilu (A, opts))
          ans = 7840

     This shows that A has 7,840 nonzeros, the complete LU factorization
     has 126,478 nonzeros, and the incomplete LU factorization, with 0
     level of fill-in, has 7,840 nonzeros, the same amount as A.  Taken
     from: <https://www.mathworks.com/help/matlab/ref/ilu.html>

          A = gallery ("wathen", 10, 10);
          b = sum (A, 2);
          tol = 1e-8;
          maxit = 50;
          opts.type = "crout";
          opts.droptol = 1e-4;
          [L, U] = ilu (A, opts);
          x = bicg (A, b, tol, maxit, L, U);
          norm (A * x - b, inf)

     This example uses ILU as preconditioner for a random FEM-Matrix,
     which has a large condition number.  Without L and U BICG would not
     converge.

     See also: *note lu: XREFlu, *note ichol: XREFichol, *note bicg:
     XREFbicg, *note gmres: XREFgmres.


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

22.4 Real Life Example using 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 2-D 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

23 Numerical Integration
************************

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

* Menu:

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


File: octave.info,  Node: Functions of One Variable,  Next: Orthogonal Collocation,  Up: Numerical Integration

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

Octave supports five different adaptive quadrature 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.

‘quadv’
     Numerical integration using an adaptive vectorized Simpson’s rule.

‘quadl’
     Numerical integration using an adaptive Lobatto rule.

‘quadgk’
     Numerical integration using an adaptive Gauss-Konrod rule.

‘quadcc’
     Numerical integration using adaptive Clenshaw-Curtis rules.

     In addition, the following functions are also provided:

‘integral’
     A compatibility wrapper function that will choose between ‘quadv’
     and ‘quadgk’ depending on the integrand and options chosen.

‘trapz, cumtrapz’
     Numerical integration of data using the trapezoidal method.

The best quadrature algorithm to use depends on the integrand.  If you
have empirical data, rather than a function, the choice is ‘trapz’ or
‘cumtrapz’.  If you are uncertain about the characteristics of the
integrand, ‘quadcc’ will be the most robust as it can handle
discontinuities, singularities, oscillatory functions, and infinite
intervals.  When the integrand is smooth ‘quadgk’ may be the fastest of
the algorithms.

     Function    Characteristics
----------------------------------------------------------------------------
     quad        Low accuracy with nonsmooth integrands
     quadv       Medium accuracy with smooth integrands
     quadl       Medium accuracy with smooth integrands.  Slower than
                 quadgk.
     quadgk      Medium accuracy (1e-6 – 1e-9) with smooth integrands.
                 Handles oscillatory functions and infinite bounds
     quadcc      Low to High accuracy with nonsmooth/smooth integrands
                 Handles oscillatory functions, singularities, and
                 infinite bounds

   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 ‘quad’ integrator, but is required by the other
integrators.  In any case, it makes it much easier to generate a set of
points for plotting because it is possible to call the function with a
vector argument to produce a vector result.

   The second step is to call quad with the limits of integration:

     [q, 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.).

   The function "f" can be the string name of a function, a function
handle, or an inline function.  These options make it quite easy to do
integration without having to fully define a function in an m-file.  For
example:

     # Verify integral (x^3) = x^4/4
     f = inline ("x.^3");
     quadgk (f, 0, 1)
          ⇒ 0.25000

     # Verify gamma function = (n-1)! for n = 4
     f = @(x) x.^3 .* exp (-x);
     quadcc (f, 0, Inf)
          ⇒ 6.0000

 -- : Q = quad (F, A, B)
 -- : Q = quad (F, A, B, TOL)
 -- : Q = quad (F, A, B, TOL, SING)
 -- : [Q, IER, NFUN, ERR] = quad (...)
     Numerically evaluate the integral of F from A to B using Fortran
     routines from QUADPACK.

     F is a function handle, inline function, or a string containing the
     name of the function to evaluate.  The function must have the form
     ‘y = f (x)’ where Y and X are scalars.

     A and B are the lower and upper 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.  Both tolerances default to ‘sqrt
     (eps)’ or approximately 1.5e-8.

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

     IER contains an integer error code (0 indicates a successful
     integration).

     NFUN indicates the number of function evaluations that were made.

     ERR contains an estimate of the error in the solution.

     The function ‘quad_options’ can set other optional parameters for
     ‘quad’.

     Note: because ‘quad’ is written in Fortran it cannot be called
     recursively.  This prevents its use in integrating over more than
     one variable by routines ‘dblquad’ and ‘triplequad’.

     See also: *note quad_options: XREFquad_options, *note quadv:
     XREFquadv, *note quadl: XREFquadl, *note quadgk: XREFquadgk, *note
     quadcc: XREFquadcc, *note trapz: XREFtrapz, *note dblquad:
     XREFdblquad, *note triplequad: XREFtriplequad.

 -- : quad_options ()
 -- : val = quad_options (OPT)
 -- : quad_options (OPT, VAL)
     Query or set options for the function ‘quad’.

     When called with no arguments, the names of all available options
     and their current values are displayed.

     Given one argument, return the value of the option OPT.

     When called with two arguments, ‘quad_options’ sets the option OPT
     to value VAL.

     Options include

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

     "relative tolerance"
          Non-negative relative tolerance.  If the absolute tolerance is
          zero, the relative tolerance must be greater than or equal to
          ‘max (50*eps, 0.5e-28)’.

     "single precision absolute tolerance"
          Absolute tolerance for single precision; may be zero for pure
          relative error test.

     "single precision relative tolerance"
          Non-negative relative tolerance for single precision.  If the
          absolute tolerance is zero, the relative tolerance must be
          greater than or equal to ‘max (50*eps, 0.5e-28)’.

 -- : Q = quadv (F, A, B)
 -- : Q = quadv (F, A, B, TOL)
 -- : Q = quadv (F, A, B, TOL, TRACE)
 -- : Q = quadv (F, A, B, TOL, TRACE, P1, P2, ...)
 -- : [Q, NFUN] = quadv (...)

     Numerically evaluate the integral of F from A to B using an
     adaptive Simpson’s rule.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  ‘quadv’ is a vectorized version
     of ‘quad’ and the function defined by F must accept a scalar or
     vector as input and return a scalar, vector, or array as output.

     A and B are the lower and upper limits of integration.  Both limits
     must be finite.

     The optional argument TOL defines the absolute tolerance used to
     stop the adaptation procedure.  The default value is 1e-6.

     The algorithm used by ‘quadv’ involves recursively subdividing the
     integration interval and applying Simpson’s rule on each
     subinterval.  If TRACE is true then after computing each of these
     partial integrals display: (1) the total number of function
     evaluations, (2) the left end of the subinterval, (3) the length of
     the subinterval, (4) the approximation of the integral over the
     subinterval.

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

     The result of the integration is returned in Q.

     The optional output NFUN indicates the total number of function
     evaluations performed.

     Note: ‘quadv’ is written in Octave’s scripting language and can be
     used recursively in ‘dblquad’ and ‘triplequad’, unlike the ‘quad’
     function.

     See also: *note quad: XREFquad, *note quadl: XREFquadl, *note
     quadgk: XREFquadgk, *note quadcc: XREFquadcc, *note trapz:
     XREFtrapz, *note dblquad: XREFdblquad, *note triplequad:
     XREFtriplequad, *note integral: XREFintegral, *note integral2:
     XREFintegral2, *note integral3: XREFintegral3.

 -- : Q = quadl (F, A, B)
 -- : Q = quadl (F, A, B, TOL)
 -- : Q = quadl (F, A, B, TOL, TRACE)
 -- : Q = quadl (F, A, B, TOL, TRACE, P1, P2, ...)
 -- : [Q, NFUN] = quadl (...)

     Numerically evaluate the integral of F from A to B using an
     adaptive Lobatto rule.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be
     vectorized and return a vector of output values when given a vector
     of input values.

     A and B are the lower and upper limits of integration.  Both limits
     must be finite.

     The optional argument TOL defines the absolute tolerance with which
     to perform the integration.  The default value is 1e-6.

     The algorithm used by ‘quadl’ involves recursively subdividing the
     integration interval.  If TRACE is defined then for each
     subinterval display: (1) the total number of function evaluations,
     (2) the left end of the subinterval, (3) the length of the
     subinterval, (4) the approximation of the integral over the
     subinterval.

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

     The result of the integration is returned in Q.

     The optional output NFUN indicates the total number of function
     evaluations performed.

     Reference: W. Gander and W. Gautschi, ‘Adaptive Quadrature -
     Revisited’, BIT Vol.  40, No.  1, March 2000, pp.  84–101.
     <https://www.inf.ethz.ch/personal/gander/>

     See also: *note quad: XREFquad, *note quadv: XREFquadv, *note
     quadgk: XREFquadgk, *note quadcc: XREFquadcc, *note trapz:
     XREFtrapz, *note dblquad: XREFdblquad, *note triplequad:
     XREFtriplequad, *note integral: XREFintegral, *note integral2:
     XREFintegral2, *note integral3: XREFintegral3.

 -- : Q = quadgk (F, A, B)
 -- : Q = quadgk (F, A, B, ABSTOL)
 -- : Q = quadgk (F, A, B, ABSTOL, TRACE)
 -- : Q = quadgk (F, A, B, PROP, VAL, ...)
 -- : [Q, ERR] = quadgk (...)

     Numerically evaluate the integral of F from A to B using adaptive
     Gauss-Konrod quadrature.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be
     vectorized and return a vector of output values when given a vector
     of input values.

     A and B are the lower and upper limits of integration.  Either or
     both limits may be infinite or contain weak end singularities.
     Variable transformation will be used to treat any infinite
     intervals and weaken the singularities.  For example:

          quadgk (@(x) 1 ./ (sqrt (x) .* (x + 1)), 0, Inf)

     Note that the formulation of the integrand uses the
     element-by-element operator ‘./’ and all user functions to ‘quadgk’
     should do the same.

     The optional argument TOL defines the absolute tolerance used to
     stop the integration procedure.  The default value is 1e-10 (1e-5
     for single).

     The algorithm used by ‘quadgk’ involves subdividing the integration
     interval and evaluating each subinterval.  If TRACE is true then
     after computing each of these partial integrals display: (1) the
     number of subintervals at this step, (2) the current estimate of
     the error ERR, (3) the current estimate for the integral Q.

     Alternatively, properties of ‘quadgk’ can be passed to the function
     as pairs "PROP", VAL.  Valid properties are

     ‘AbsTol’
          Define the absolute error tolerance for the quadrature.  The
          default absolute tolerance is 1e-10 (1e-5 for single).

     ‘RelTol’
          Define the relative error tolerance for the quadrature.  The
          default relative tolerance is 1e-6 (1e-4 for single).

     ‘MaxIntervalCount’
          ‘quadgk’ initially subdivides the interval on which to perform
          the quadrature into 10 intervals.  Subintervals that have an
          unacceptable error are subdivided and re-evaluated.  If the
          number of subintervals exceeds 650 subintervals at any point
          then a poor convergence is signaled and the current estimate
          of the integral is returned.  The property "MaxIntervalCount"
          can be used to alter the number of subintervals that can exist
          before exiting.

     ‘WayPoints’
          Discontinuities in the first derivative of the function to
          integrate can be flagged with the "WayPoints" property.  This
          forces the ends of a subinterval to fall on the breakpoints of
          the function and can result in significantly improved
          estimation of the error in the integral, faster computation,
          or both.  For example,

               quadgk (@(x) abs (1 - x.^2), 0, 2, "Waypoints", 1)

          signals the breakpoint in the integrand at ‘X = 1’.

     ‘Trace’
          If logically true ‘quadgk’ prints information on the
          convergence of the quadrature at each iteration.

     If any of A, B, or WAYPOINTS is complex then the quadrature is
     treated as a contour integral along a piecewise continuous path
     defined by the above.  In this case the integral is assumed to have
     no edge singularities.  For example,

          quadgk (@(z) log (z), 1+1i, 1+1i, "WayPoints",
                  [1-1i, -1,-1i, -1+1i])

     integrates ‘log (z)’ along the square defined by ‘[1+1i, 1-1i,
     -1-1i, -1+1i]’.

     The result of the integration is returned in Q.

     ERR is an approximate bound on the error in the integral ‘abs (Q -
     I)’, where I is the exact value of the integral.

     Reference: L.F. Shampine, ‘"Vectorized adaptive quadrature in
     MATLAB"’, Journal of Computational and Applied Mathematics, pp.
     131–140, Vol 211, Issue 2, Feb 2008.

     See also: *note quad: XREFquad, *note quadv: XREFquadv, *note
     quadl: XREFquadl, *note quadcc: XREFquadcc, *note trapz: XREFtrapz,
     *note dblquad: XREFdblquad, *note triplequad: XREFtriplequad, *note
     integral: XREFintegral, *note integral2: XREFintegral2, *note
     integral3: XREFintegral3.

 -- : Q = quadcc (F, A, B)
 -- : Q = quadcc (F, A, B, TOL)
 -- : Q = quadcc (F, A, B, TOL, SING)
 -- : [Q, ERR, NR_POINTS] = quadcc (...)
     Numerically evaluate the integral of F from A to B using
     doubly-adaptive Clenshaw-Curtis quadrature.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be
     vectorized and must return a vector of output values if given a
     vector of input values.  For example,

          f = @(x) x .* sin (1./x) .* sqrt (abs (1 - x));

     which uses the element-by-element “dot” form for all operators.

     A and B are the lower and upper limits of integration.  Either or
     both limits may be infinite.  ‘quadcc’ handles an infinite limit by
     substituting the variable of integration with ‘x = tan (pi/2*u)’.

     The optional argument TOL is a 1- or 2-element 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
     default absolute tolerance is 1e-10 (1e-5 for single), and the
     default relative tolerance is 1e-6 (1e-4 for single).

     The optional argument SING contains a list of points where the
     integrand has known singularities, or discontinuities in any of its
     derivatives, inside the integration interval.  For the example
     above, which has a discontinuity at x=1, the call to ‘quadcc’ would
     be as follows

          int = quadcc (f, a, b, [], [ 1 ]);

     The result of the integration is returned in Q.

     ERR is an estimate of the absolute integration error.

     NR_POINTS is the number of points at which the integrand was
     evaluated.

     If the adaptive integration did not converge, the value of ERR will
     be larger than the requested tolerance.  Therefore, it is
     recommended to verify this value for difficult integrands.

     ‘quadcc’ is capable of dealing with non-numeric values of the
     integrand such as ‘NaN’ or ‘Inf’.  If the integral diverges, and
     ‘quadcc’ detects this, then a warning is issued and ‘Inf’ or ‘-Inf’
     is returned.

     Note: ‘quadcc’ is a general purpose quadrature algorithm and, as
     such, may be less efficient for a smooth or otherwise well-behaved
     integrand than other methods such as ‘quadgk’.

     The algorithm uses Clenshaw-Curtis quadrature rules of increasing
     degree in each interval and bisects the interval if either the
     function does not appear to be smooth or a rule of maximum degree
     has been reached.  The error estimate is computed from the L2-norm
     of the difference between two successive interpolations of the
     integrand over the nodes of the respective quadrature rules.

     Implementation Note: For Octave versions ≤ 4.2, ‘quadcc’ accepted a
     single tolerance argument which specified the relative tolerance.
     For versions 4.4 and 5, ‘quadcc’ will issue a warning when called
     with a single tolerance argument indicating that the meaning of
     this input has changed from relative tolerance to absolute
     tolerance.  The warning ID for this message is
     "Octave:quadcc:RelTol-conversion".  The warning may be disabled
     with ‘warning ("off", "Octave:quadcc:RelTol-conversion")’.

     Reference: P. Gonnet, ‘Increasing the Reliability of Adaptive
     Quadrature Using Explicit Interpolants’, ACM Transactions on
     Mathematical Software, Vol.  37, Issue 3, Article No.  3, 2010.

     See also: *note quad: XREFquad, *note quadv: XREFquadv, *note
     quadl: XREFquadl, *note quadgk: XREFquadgk, *note trapz: XREFtrapz,
     *note dblquad: XREFdblquad, *note triplequad: XREFtriplequad.

 -- : Q = integral (F, A, B)
 -- : Q = integral (F, A, B, PROP, VAL, ...)

     Numerically evaluate the integral of F from A to B using adaptive
     quadrature.

     ‘integral’ is a wrapper for ‘quadcc’ (general scalar integrands),
     ‘quadgk’ (integrals with specified integration paths), and ‘quadv’
     (array-valued integrands) that is intended to provide MATLAB
     compatibility.  More control of the numerical integration may be
     achievable by calling the various quadrature functions directly.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be
     vectorized and return a vector of output values when given a vector
     of input values.

     A and B are the lower and upper limits of integration.  Either or
     both limits may be infinite or contain weak end singularities.  If
     either or both limits are complex, ‘integral’ will perform a
     straight line path integral.  Alternatively, a complex domain path
     can be specified using the "Waypoints" option (see below).

     Additional optional parameters can be specified using "PROPERTY",
     VALUE pairs.  Valid properties are:

     ‘Waypoints’
          Specifies points to be used in defining subintervals of the
          quadrature algorithm, or if A, B, or WAYPOINTS are complex
          then the quadrature is calculated as a contour integral along
          a piecewise continuous path.  For more detail see ‘quadgk’.

     ‘ArrayValued’
          ‘integral’ expects F to return a scalar value unless
          ARRAYVALUED is specified as true.  This option will cause
          ‘integral’ to perform the integration over the entire array
          and return Q with the same dimensions as returned by F.  For
          more detail see ‘quadv’.

     ‘AbsTol’
          Define the absolute error tolerance for the quadrature.  The
          default absolute tolerance is 1e-10 (1e-5 for single).

     ‘RelTol’
          Define the relative error tolerance for the quadrature.  The
          default relative tolerance is 1e-6 (1e-4 for single).

     Adaptive quadrature is used to minimize the estimate of error until
     the following is satisfied:

            ERROR <= max (ABSTOL, RELTOL*|Q|).

     Known MATLAB incompatibilities:

       1. If tolerances are left unspecified, and any integration limits
          or waypoints are of type ‘single’, then Octave’s integral
          functions automatically reduce the default absolute and
          relative error tolerances as specified above.  If tighter
          tolerances are desired they must be specified.  MATLAB leaves
          the tighter tolerances appropriate for ‘double’ inputs in
          place regardless of the class of the integration limits.

       2. As a consequence of using ‘quadcc’, ‘quadgk’, and ‘quadv’,
          certain option combinations are not supported.  Currently,
          "ArrayValued" cannot be combined with "RelTol" or "Waypoints".

     See also: *note integral2: XREFintegral2, *note integral3:
     XREFintegral3, *note quad: XREFquad, *note quadgk: XREFquadgk,
     *note quadv: XREFquadv, *note quadl: XREFquadl, *note quadcc:
     XREFquadcc, *note trapz: XREFtrapz, *note dblquad: XREFdblquad,
     *note triplequad: XREFtriplequad.

   Sometimes one does not have the function, but only the raw (x, y)
points from which to perform an integration.  This can occur when
collecting data in an experiment.  The ‘trapz’ function can integrate
these values as shown in the following example where "data" has been
collected on the cosine function over the range [0, pi/2).

     x = 0:0.1:pi/2;  # Uniformly spaced points
     y = cos (x);
     trapz (x, y)
          ⇒ 0.99666

   The answer is reasonably close to the exact value of 1.  Ordinary
quadrature is sensitive to the characteristics of the integrand.
Empirical integration depends not just on the integrand, but also on the
particular points chosen to represent the function.  Repeating the
example above with the sine function over the range [0, pi/2) produces
far inferior results.

     x = 0:0.1:pi/2;  # Uniformly spaced points
     y = sin (x);
     trapz (x, y)
          ⇒ 0.92849

   However, a slightly different choice of data points can change the
result significantly.  The same integration, with the same number of
points, but spaced differently produces a more accurate answer.

     x = linspace (0, pi/2, 16);  # Uniformly spaced, but including endpoint
     y = sin (x);
     trapz (x, y)
          ⇒ 0.99909

   In general there may be no way of knowing the best distribution of
points ahead of time.  Or the points may come from an experiment where
there is no freedom to select the best distribution.  In any case, one
must remain aware of this issue when using ‘trapz’.

 -- : Q = trapz (Y)
 -- : Q = trapz (X, Y)
 -- : Q = trapz (..., DIM)

     Numerically evaluate the integral of points Y using the trapezoidal
     method.

     ‘trapz (Y)’ computes the integral of Y along the first
     non-singleton dimension.  When the argument X is omitted an equally
     spaced X vector with unit spacing (1) is assumed.  ‘trapz (X, Y)’
     evaluates the integral with respect to the spacing in X and the
     values in Y.  This is useful if the points in Y have been sampled
     unevenly.

     If the optional DIM argument is given, operate along this
     dimension.

     Application Note: If X is not specified then unit spacing will be
     used.  To scale the integral to the correct value you must multiply
     by the actual spacing value (deltaX). As an example, the integral
     of x^3 over the range [0, 1] is x^4/4 or 0.25.  The following code
     uses ‘trapz’ to calculate the integral in three different ways.

          x = 0:0.1:1;
          y = x.^3;
          ## No scaling
          q = trapz (y)
            ⇒ q = 2.5250
          ## Approximation to integral by scaling
          q * 0.1
            ⇒ 0.25250
          ## Same result by specifying X
          trapz (x, y)
            ⇒ 0.25250

     See also: *note cumtrapz: XREFcumtrapz.

 -- : Q = cumtrapz (Y)
 -- : Q = cumtrapz (X, Y)
 -- : Q = cumtrapz (..., DIM)
     Cumulative numerical integration of points Y using the trapezoidal
     method.

     ‘cumtrapz (Y)’ computes the cumulative integral of Y along the
     first non-singleton dimension.  Where ‘trapz’ reports only the
     overall integral sum, ‘cumtrapz’ reports the current partial sum
     value at each point of Y.

     When the argument X is omitted an equally spaced X vector with unit
     spacing (1) is assumed.  ‘cumtrapz (X, Y)’ evaluates the integral
     with respect to the spacing in X and the values in Y.  This is
     useful if the points in Y have been sampled unevenly.

     If the optional DIM argument is given, operate along this
     dimension.

     Application Note: If X is not specified then unit spacing will be
     used.  To scale the integral to the correct value you must multiply
     by the actual spacing value (deltaX).

     See also: *note trapz: XREFtrapz, *note cumsum: XREFcumsum.


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

23.2 Orthogonal Collocation
===========================

 -- : [R, AMAT, BMAT, Q] = colloc (N, "left", "right")
     Compute derivative and integral weight matrices for orthogonal
     collocation.

     Reference: J. Villadsen, 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,  Prev: Orthogonal Collocation,  Up: Numerical Integration

23.3 Functions of Multiple Variables
====================================

Octave includes several functions for computing the integral of
functions of multiple variables.  This procedure can generally be
performed by creating a function that integrates f with respect to x,
and then integrates that function with respect to y.  This procedure can
be performed manually using the following example which integrates the
function:

     f(x, y) = sin(pi*x*y) * sqrt(x*y)

   for x and y between 0 and 1.

   Using ‘quadgk’ in the example below, a double integration can be
performed.  (Note that any of the 1-D quadrature functions can be used
in this fashion except for ‘quad’ since it is written in Fortran and
cannot be called recursively.)

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

     I = quadgk ("g", 0, 1)
           ⇒ 0.30022

   The algorithm above is implemented in the function ‘dblquad’ for
integrals over two variables.  The 3-D equivalent of this process is
implemented in ‘triplequad’ for integrals over three variables.  As an
example, the result above can be replicated with a call to ‘dblquad’ as
shown below.

     I = dblquad (@(x, y) sin (pi*x.*y) .* sqrt (x.*y), 0, 1, 0, 1)
           ⇒ 0.30022

 -- : dblquad (F, XA, XB, YA, YB)
 -- : dblquad (F, XA, XB, YA, YB, TOL)
 -- : dblquad (F, XA, XB, YA, YB, TOL, QUADF)
 -- : dblquad (F, XA, XB, YA, YB, TOL, QUADF, ...)
     Numerically evaluate the double integral of F.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must have the
     form z = f(x,y) where X is a vector and Y is a scalar.  It should
     return a vector of the same length and orientation as X.

     XA, YA and XB, YB are the lower and upper limits of integration for
     x and y respectively.  The underlying integrator determines whether
     infinite bounds are accepted.

     The optional argument TOL defines the absolute tolerance used to
     integrate each sub-integral.  The default value is 1e-6.

     The optional argument QUADF specifies which underlying integrator
     function to use.  Any choice but ‘quad’ is available and the
     default is ‘quadcc’.

     Additional arguments, are passed directly to F.  To use the default
     value for TOL or QUADF one may pass ’:’ or an empty matrix ([]).

     See also: *note integral2: XREFintegral2, *note integral3:
     XREFintegral3, *note triplequad: XREFtriplequad, *note quad:
     XREFquad, *note quadv: XREFquadv, *note quadl: XREFquadl, *note
     quadgk: XREFquadgk, *note quadcc: XREFquadcc, *note trapz:
     XREFtrapz.

 -- : triplequad (F, XA, XB, YA, YB, ZA, ZB)
 -- : triplequad (F, XA, XB, YA, YB, ZA, ZB, TOL)
 -- : triplequad (F, XA, XB, YA, YB, ZA, ZB, TOL, QUADF)
 -- : triplequad (F, XA, XB, YA, YB, ZA, ZB, TOL, QUADF, ...)
     Numerically evaluate the triple integral of F.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must have the
     form w = f(x,y,z) where either X or Y is a vector and the remaining
     inputs are scalars.  It should return a vector of the same length
     and orientation as X or Y.

     XA, YA, ZA and XB, YB, ZB are the lower and upper limits of
     integration for x, y, and z respectively.  The underlying
     integrator determines whether infinite bounds are accepted.

     The optional argument TOL defines the absolute tolerance used to
     integrate each sub-integral.  The default value is 1e-6.

     The optional argument QUADF specifies which underlying integrator
     function to use.  Any choice but ‘quad’ is available and the
     default is ‘quadcc’.

     Additional arguments, are passed directly to F.  To use the default
     value for TOL or QUADF one may pass ’:’ or an empty matrix ([]).

     See also: *note integral3: XREFintegral3, *note integral2:
     XREFintegral2, *note dblquad: XREFdblquad, *note quad: XREFquad,
     *note quadv: XREFquadv, *note quadl: XREFquadl, *note quadgk:
     XREFquadgk, *note quadcc: XREFquadcc, *note trapz: XREFtrapz.

   The recursive algorithm for quadrature presented above is referred to
as "iterated".  A separate 2-D integration method is implemented in the
function ‘quad2d’.  This function performs a "tiled" integration by
subdividing the integration domain into rectangular regions and
performing separate integrations over those domains.  The domains are
further subdivided in areas requiring refinement to reach the desired
numerical accuracy.  For certain functions this method can be faster
than the 2-D iteration used in the other functions above.

 -- : Q = quad2d (F, XA, XB, YA, YB)
 -- : Q = quad2d (F, XA, XB, YA, YB, PROP, VAL, ...)
 -- : [Q, ERR, ITER] = quad2d (...)

     Numerically evaluate the two-dimensional integral of F using
     adaptive quadrature over the two-dimensional domain defined by XA,
     XB, YA, YB using tiled integration.  Additionally, YA and YB may be
     scalar functions of X, allowing for the integration over
     non-rectangular domains.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be of the
     form z = f(x,y) where X is a vector and Y is a scalar.  It should
     return a vector of the same length and orientation as X.

     Additional optional parameters can be specified using "PROPERTY",
     VALUE pairs.  Valid properties are:

     ‘AbsTol’
          Define the absolute error tolerance for the quadrature.  The
          default value is 1e-10 (1e-5 for single).

     ‘RelTol’
          Define the relative error tolerance for the quadrature.  The
          default value is 1e-6 (1e-4 for single).

     ‘MaxFunEvals’
          The maximum number of function calls to the vectorized
          function F.  The default value is 5000.

     ‘Singular’
          Enable/disable transforms to weaken singularities on the edge
          of the integration domain.  The default value is TRUE.

     ‘Vectorized’
          Option to disable vectorized integration, forcing Octave to
          use only scalar inputs when calling the integrand.  The
          default value is FALSE.

     ‘FailurePlot’
          If ‘quad2d’ fails to converge to the desired error tolerance
          before MaxFunEvals is reached, a plot of the areas that still
          need refinement is created.  The default value is FALSE.

     Adaptive quadrature is used to minimize the estimate of error until
     the following is satisfied:

                  ERROR <= max (ABSTOL, RELTOL*|Q|)

     The optional output ERR is an approximate bound on the error in the
     integral ‘abs (Q - I)’, where I is the exact value of the integral.
     The optional output ITER is the number of vectorized function calls
     to the function F that were used.

     Example 1 : integrate a rectangular region in x-y plane

          F = @(X,Y) 2*ones (size (X));
          Q = quad2d (F, 0, 1, 0, 1)
            ⇒ Q =  2

     The result is a volume, which for this constant-value integrand, is
     just ‘LENGTH * WIDTH * HEIGHT’.

     Example 2 : integrate a triangular region in x-y plane

          F = @(X,Y) 2*ones (size (X));
          YMAX = @(X) 1 - X;
          Q = quad2d (F, 0, 1, 0, YMAX)
            ⇒ Q =  1

     The result is a volume, which for this constant-value integrand, is
     the Triangle Area x Height or ‘1/2 * BASE * WIDTH * HEIGHT’.

     Programming Notes: If there are singularities within the
     integration region it is best to split the integral and place the
     singularities on the boundary.

     Known MATLAB incompatibility: If tolerances are left unspecified,
     and any integration limits are of type ‘single’, then Octave’s
     integral functions automatically reduce the default absolute and
     relative error tolerances as specified above.  If tighter
     tolerances are desired they must be specified.  MATLAB leaves the
     tighter tolerances appropriate for ‘double’ inputs in place
     regardless of the class of the integration limits.

     Reference: L.F. Shampine, ‘MATLAB program for quadrature in 2D’,
     Applied Mathematics and Computation, pp.  266–274, Vol 1, 2008.

     See also: *note integral2: XREFintegral2, *note dblquad:
     XREFdblquad, *note integral: XREFintegral, *note quad: XREFquad,
     *note quadgk: XREFquadgk, *note quadv: XREFquadv, *note quadl:
     XREFquadl, *note quadcc: XREFquadcc, *note trapz: XREFtrapz, *note
     integral3: XREFintegral3, *note triplequad: XREFtriplequad.

   Finally, the functions ‘integral2’ and ‘integral3’ are provided as
general 2-D and 3-D integration functions.  They will auto-select
between iterated and tiled integration methods and, unlike ‘dblquad’ and
‘triplequad’, will work with non-rectangular integration domains.

 -- : Q = integral2 (F, XA, XB, YA, YB)
 -- : Q = integral2 (F, XA, XB, YA, YB, PROP, VAL, ...)
 -- : [Q, ERR] = integral2 (...)

     Numerically evaluate the two-dimensional integral of F using
     adaptive quadrature over the two-dimensional domain defined by XA,
     XB, YA, YB (scalars may be finite or infinite).  Additionally, YA
     and YB may be scalar functions of X, allowing for integration over
     non-rectangular domains.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be of the
     form z = f(x,y) where X is a vector and Y is a scalar.  It should
     return a vector of the same length and orientation as X.

     Additional optional parameters can be specified using "PROPERTY",
     VALUE pairs.  Valid properties are:

     ‘AbsTol’
          Define the absolute error tolerance for the quadrature.  The
          default value is 1e-10 (1e-5 for single).

     ‘RelTol’
          Define the relative error tolerance for the quadrature.  The
          default value is 1e-6 (1e-4 for single).

     ‘Method’
          Specify the two-dimensional integration method to be used,
          with valid options being "auto" (default), "tiled", or
          "iterated".  When using "auto", Octave will choose the "tiled"
          method unless any of the integration limits are infinite.

     ‘Vectorized’
          Enable or disable vectorized integration.  A value of ‘false’
          forces Octave to use only scalar inputs when calling the
          integrand, which enables integrands f(x,y) that have not been
          vectorized and only accept X and Y as scalars to be used.  The
          default value is ‘true’.

     Adaptive quadrature is used to minimize the estimate of error until
     the following is satisfied:

                  ERROR <= max (ABSTOL, RELTOL*|Q|)

     ERR is an approximate bound on the error in the integral ‘abs (Q -
     I)’, where I is the exact value of the integral.

     Example 1 : integrate a rectangular region in x-y plane

          F = @(X,Y) 2*ones (size (X));
          Q = integral2 (F, 0, 1, 0, 1)
            ⇒ Q =  2

     The result is a volume, which for this constant-value integrand, is
     just ‘LENGTH * WIDTH * HEIGHT’.

     Example 2 : integrate a triangular region in x-y plane

          F = @(X,Y) 2*ones (size (X));
          YMAX = @(X) 1 - X;
          Q = integral2 (F, 0, 1, 0, YMAX)
            ⇒ Q =  1

     The result is a volume, which for this constant-value integrand, is
     the Triangle Area x Height or ‘1/2 * BASE * WIDTH * HEIGHT’.

     Programming Notes: If there are singularities within the
     integration region it is best to split the integral and place the
     singularities on the boundary.

     Known MATLAB incompatibility: If tolerances are left unspecified,
     and any integration limits are of type ‘single’, then Octave’s
     integral functions automatically reduce the default absolute and
     relative error tolerances as specified above.  If tighter
     tolerances are desired they must be specified.  MATLAB leaves the
     tighter tolerances appropriate for ‘double’ inputs in place
     regardless of the class of the integration limits.

     Reference: L.F. Shampine, ‘MATLAB program for quadrature in 2D’,
     Applied Mathematics and Computation, pp.  266–274, Vol 1, 2008.

     See also: *note quad2d: XREFquad2d, *note dblquad: XREFdblquad,
     *note integral: XREFintegral, *note quad: XREFquad, *note quadgk:
     XREFquadgk, *note quadv: XREFquadv, *note quadl: XREFquadl, *note
     quadcc: XREFquadcc, *note trapz: XREFtrapz, *note integral3:
     XREFintegral3, *note triplequad: XREFtriplequad.

 -- : Q = integral3 (F, XA, XB, YA, YB, ZA, ZB)
 -- : Q = integral3 (F, XA, XB, YA, YB, ZA, ZB, PROP, VAL, ...)

     Numerically evaluate the three-dimensional integral of F using
     adaptive quadrature over the three-dimensional domain defined by
     XA, XB, YA, YB, ZA, ZB (scalars may be finite or infinite).
     Additionally, YA and YB may be scalar functions of X and ZA, and ZB
     maybe be scalar functions of X and Y, allowing for integration over
     non-rectangular domains.

     F is a function handle, inline function, or string containing the
     name of the function to evaluate.  The function F must be of the
     form z = f(x,y) where X is a vector and Y is a scalar.  It should
     return a vector of the same length and orientation as X.

     Additional optional parameters can be specified using "PROPERTY",
     VALUE pairs.  Valid properties are:

     ‘AbsTol’
          Define the absolute error tolerance for the quadrature.  The
          default value is 1e-10 (1e-5 for single).

     ‘RelTol’
          Define the relative error tolerance for the quadrature.  The
          default value is 1e-6 (1e-4 for single).

     ‘Method’
          Specify the two-dimensional integration method to be used,
          with valid options being "auto" (default), "tiled", or
          "iterated".  When using "auto", Octave will choose the "tiled"
          method unless any of the integration limits are infinite.

     ‘Vectorized’
          Enable or disable vectorized integration.  A value of ‘false’
          forces Octave to use only scalar inputs when calling the
          integrand, which enables integrands f(x,y) that have not been
          vectorized and only accept X and Y as scalars to be used.  The
          default value is ‘true’.

     Adaptive quadrature is used to minimize the estimate of error until
     the following is satisfied:

                  ERROR <= max (ABSTOL, RELTOL*|Q|)

     ERR is an approximate bound on the error in the integral ‘abs (Q -
     I)’, where I is the exact value of the integral.

     Example 1 : integrate over a rectangular volume

          F = @(X,Y,Z) ones (size (X));
          Q = integral3 (F, 0, 1, 0, 1, 0, 1)
            ⇒ Q =  1.00000

     For this constant-value integrand, the result is a volume which is
     just ‘LENGTH * WIDTH * HEIGHT’.

     Example 2 : integrate over a spherical volume

          F = @(X,Y) ones (size (X));
          YMAX = @(X) sqrt (1 - X.^2);
          ZMAX = @(X,Y) sqrt (1 - X.^2 - Y.^2);
          Q = integral3 (F, 0, 1, 0, YMAX, 0, ZMAX)
            ⇒ Q =  0.52360

     For this constant-value integrand, the result is a volume which is
     1/8th of a unit sphere or ‘1/8 * 4/3 * pi’.

     Programming Notes: If there are singularities within the
     integration region it is best to split the integral and place the
     singularities on the boundary.

     Known MATLAB incompatibility: If tolerances are left unspecified,
     and any integration limits are of type ‘single’, then Octave’s
     integral functions automatically reduce the default absolute and
     relative error tolerances as specified above.  If tighter
     tolerances are desired they must be specified.  MATLAB leaves the
     tighter tolerances appropriate for ‘double’ inputs in place
     regardless of the class of the integration limits.

     Reference: L.F. Shampine, ‘MATLAB program for quadrature in 2D’,
     Applied Mathematics and Computation, pp.  266–274, Vol 1, 2008.

     See also: *note triplequad: XREFtriplequad, *note integral:
     XREFintegral, *note quad: XREFquad, *note quadgk: XREFquadgk, *note
     quadv: XREFquadv, *note quadl: XREFquadl, *note quadcc: XREFquadcc,
     *note trapz: XREFtrapz, *note integral2: XREFintegral2, *note
     quad2d: XREFquad2d, *note dblquad: XREFdblquad.

   The above integrations can be fairly slow, and that problem increases
exponentially with the dimensionality of the integral.  Another possible
solution for 2-D integration is to use Orthogonal Collocation as
described in the previous section (*note Orthogonal Collocation::).  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 generalization to more than two variables is straight forward.  The
following code computes the studied integral using n=8 points.

     f = @(x,y) sin (pi*x*y') .* sqrt (x*y');
     n = 8;
     [t, ~, ~, 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, then a change of variables is needed.


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

24 Differential Equations
*************************

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

* Menu:

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


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

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

 -- : [X, ISTATE, MSG] = lsode (FCN, X_0, T)
 -- : [X, ISTATE, MSG] = lsode (FCN, X_0, T, T_CRIT)
     Ordinary Differential Equation (ODE) solver.

     The set of differential equations to solve is

          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, inline, or function handle
     that names the function f 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 or a two-element cell array of
     strings, inline functions, or function handles, 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 argument specifies the initial state of the system x_0.
     The third argument is a vector, T, specifying the time values for
     which a solution is sought.

     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: *note daspk: XREFdaspk, *note dassl: XREFdassl, *note
     dasrt: XREFdasrt.

 -- : lsode_options ()
 -- : val = lsode_options (OPT)
 -- : lsode_options (OPT, VAL)
     Query or set options for the function ‘lsode’.

     When called with no arguments, the names of all available options
     and their current values are displayed.

     Given one argument, return the value of the option OPT.

     When called with two arguments, ‘lsode_options’ sets the option OPT
     to value VAL.

     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

     ## oregonator differential equation
     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’.

   An m-file for the differential equation used above is included with
the Octave distribution in the examples directory under the name
‘oregonator.m’.

* Menu:

* Matlab-compatible solvers::


File: octave.info,  Node: Matlab-compatible solvers,  Up: Ordinary Differential Equations

24.1.1 Matlab-compatible solvers
--------------------------------

Octave also provides a set of solvers for initial value problems for
Ordinary Differential Equations that have a MATLAB-compatible interface.
The options for this class of methods are set using the functions.

   • ‘odeset’

   • ‘odeget’

   Currently implemented solvers are:

   • Runge-Kutta methods

        • ‘ode23’ integrates a system of non-stiff ordinary differential
          equations (ODEs) or index-1 differential-algebraic equations
          (DAEs).  It uses the third-order Bogacki-Shampine method and
          adapts the local step size in order to satisfy a
          user-specified tolerance.  The solver requires three function
          evaluations per integration step.

        • ‘ode45’ integrates a system of non-stiff ODEs (or index-1
          DAEs) using the high-order, variable-step Dormand-Prince
          method.  It requires six function evaluations per integration
          step, but may take larger steps on smooth problems than
          ‘ode23’: potentially offering improved efficiency at smaller
          tolerances.

   • Linear multistep methods

        • ‘ode15s’ integrates a system of stiff ODEs (or index-1 DAEs)
          using a variable step, variable order method based on Backward
          Difference Formulas (BDF).

        • ‘ode15i’ integrates a system of fully-implicit ODEs (or
          index-1 DAEs) using the same variable step, variable order
          method as ‘ode15s’.  The function ‘decic’ can be used to
          compute consistent initial conditions.

 -- : [T, Y] = ode45 (FUN, TRANGE, INIT)
 -- : [T, Y] = ode45 (FUN, TRANGE, INIT, ODE_OPT)
 -- : [T, Y, TE, YE, IE] = ode45 (...)
 -- : SOLUTION = ode45 (...)
 -- : ode45 (...)

     Solve a set of non-stiff Ordinary Differential Equations (non-stiff
     ODEs) with the well known explicit Dormand-Prince method of order
     4.

     FUN is a function handle, inline function, or string containing the
     name of the function that defines the ODE: ‘y' = f(t,y)’.  The
     function must accept two inputs where the first is time T and the
     second is a column vector of unknowns Y.

     TRANGE specifies the time interval over which the ODE will be
     evaluated.  Typically, it is a two-element vector specifying the
     initial and final times (‘[tinit, tfinal]’).  If there are more
     than two elements then the solution will also be evaluated at these
     intermediate time instances.

     By default, ‘ode45’ uses an adaptive timestep with the
     ‘integrate_adaptive’ algorithm.  The tolerance for the timestep
     computation may be changed by using the options "RelTol" and
     "AbsTol".

     INIT contains the initial value for the unknowns.  If it is a row
     vector then the solution Y will be a matrix in which each column is
     the solution for the corresponding initial value in INIT.

     The optional fourth argument ODE_OPT specifies non-default options
     to the ODE solver.  It is a structure generated by ‘odeset’.

     The function typically returns two outputs.  Variable T is a column
     vector and contains the times where the solution was found.  The
     output Y is a matrix in which each column refers to a different
     unknown of the problem and each row corresponds to a time in T.

     The output can also be returned as a structure SOLUTION which has a
     field X containing a row vector of times where the solution was
     evaluated and a field Y containing the solution matrix such that
     each column corresponds to a time in X.  Use
     ‘fieldnames (SOLUTION)’ to see the other fields and additional
     information returned.

     If no output arguments are requested, and no ‘OutputFcn’ is
     specified in ODE_OPT, then the ‘OutputFcn’ is set to ‘odeplot’ and
     the results of the solver are plotted immediately.

     If using the "Events" option then three additional outputs may be
     returned.  TE holds the time when an Event function returned a
     zero.  YE holds the value of the solution at time TE.  IE contains
     an index indicating which Event function was triggered in the case
     of multiple Event functions.

     Example: Solve the Van der Pol equation

          fvdp = @(T,Y) [Y(2); (1 - Y(1)^2) * Y(2) - Y(1)];
          [T,Y] = ode45 (fvdp, [0, 20], [2, 0]);

     See also: *note odeset: XREFodeset, *note odeget: XREFodeget, *note
     ode23: XREFode23, *note ode15s: XREFode15s.

 -- : [T, Y] = ode23 (FUN, TRANGE, INIT)
 -- : [T, Y] = ode23 (FUN, TRANGE, INIT, ODE_OPT)
 -- : [T, Y, TE, YE, IE] = ode23 (...)
 -- : SOLUTION = ode23 (...)
 -- : ode23 (...)

     Solve a set of non-stiff Ordinary Differential Equations (non-stiff
     ODEs) with the well known explicit Bogacki-Shampine method of order
     3.

     FUN is a function handle, inline function, or string containing the
     name of the function that defines the ODE: ‘y' = f(t,y)’.  The
     function must accept two inputs where the first is time T and the
     second is a column vector of unknowns Y.

     TRANGE specifies the time interval over which the ODE will be
     evaluated.  Typically, it is a two-element vector specifying the
     initial and final times (‘[tinit, tfinal]’).  If there are more
     than two elements then the solution will also be evaluated at these
     intermediate time instances.

     By default, ‘ode23’ uses an adaptive timestep with the
     ‘integrate_adaptive’ algorithm.  The tolerance for the timestep
     computation may be changed by using the options "RelTol" and
     "AbsTol".

     INIT contains the initial value for the unknowns.  If it is a row
     vector then the solution Y will be a matrix in which each column is
     the solution for the corresponding initial value in INIT.

     The optional fourth argument ODE_OPT specifies non-default options
     to the ODE solver.  It is a structure generated by ‘odeset’.

     The function typically returns two outputs.  Variable T is a column
     vector and contains the times where the solution was found.  The
     output Y is a matrix in which each column refers to a different
     unknown of the problem and each row corresponds to a time in T.

     The output can also be returned as a structure SOLUTION which has a
     field X containing a row vector of times where the solution was
     evaluated and a field Y containing the solution matrix such that
     each column corresponds to a time in X.  Use
     ‘fieldnames (SOLUTION)’ to see the other fields and additional
     information returned.

     If no output arguments are requested, and no ‘OutputFcn’ is
     specified in ODE_OPT, then the ‘OutputFcn’ is set to ‘odeplot’ and
     the results of the solver are plotted immediately.

     If using the "Events" option then three additional outputs may be
     returned.  TE holds the time when an Event function returned a
     zero.  YE holds the value of the solution at time TE.  IE contains
     an index indicating which Event function was triggered in the case
     of multiple Event functions.

     Example: Solve the Van der Pol equation

          fvdp = @(T,Y) [Y(2); (1 - Y(1)^2) * Y(2) - Y(1)];
          [T,Y] = ode23 (fvdp, [0, 20], [2, 0]);

     Reference: For the definition of this method see
     <https://en.wikipedia.org/wiki/List_of_Runge%E2%80%93Kutta_methods>.

     See also: *note odeset: XREFodeset, *note odeget: XREFodeget, *note
     ode45: XREFode45, *note ode15s: XREFode15s.

 -- : [T, Y] = ode15s (FUN, TRANGE, Y0)
 -- : [T, Y] = ode15s (FUN, TRANGE, Y0, ODE_OPT)
 -- : [T, Y, TE, YE, IE] = ode15s (...)
 -- : SOLUTION = ode15s (...)
 -- : ode15s (...)
     Solve a set of stiff Ordinary Differential Equations (ODEs) or
     stiff semi-explicit index 1 Differential Algebraic Equations
     (DAEs).

     ‘ode15s’ uses a variable step, variable order BDF (Backward
     Differentiation Formula) method that ranges from order 1 to 5.

     FUN is a function handle, inline function, or string containing the
     name of the function that defines the ODE: ‘y' = f(t,y)’.  The
     function must accept two inputs where the first is time T and the
     second is a column vector of unknowns Y.

     TRANGE specifies the time interval over which the ODE will be
     evaluated.  Typically, it is a two-element vector specifying the
     initial and final times (‘[tinit, tfinal]’).  If there are more
     than two elements then the solution will also be evaluated at these
     intermediate time instances.

     INIT contains the initial value for the unknowns.  If it is a row
     vector then the solution Y will be a matrix in which each column is
     the solution for the corresponding initial value in INIT.

     The optional fourth argument ODE_OPT specifies non-default options
     to the ODE solver.  It is a structure generated by ‘odeset’.

     The function typically returns two outputs.  Variable T is a column
     vector and contains the times where the solution was found.  The
     output Y is a matrix in which each column refers to a different
     unknown of the problem and each row corresponds to a time in T.

     The output can also be returned as a structure SOLUTION which has a
     field X containing a row vector of times where the solution was
     evaluated and a field Y containing the solution matrix such that
     each column corresponds to a time in X.  Use
     ‘fieldnames (SOLUTION)’ to see the other fields and additional
     information returned.

     If no output arguments are requested, and no ‘OutputFcn’ is
     specified in ODE_OPT, then the ‘OutputFcn’ is set to ‘odeplot’ and
     the results of the solver are plotted immediately.

     If using the "Events" option then three additional outputs may be
     returned.  TE holds the time when an Event function returned a
     zero.  YE holds the value of the solution at time TE.  IE contains
     an index indicating which Event function was triggered in the case
     of multiple Event functions.

     Example: Solve Robertson’s equations:

          function r = robertson_dae (T, Y)
            r = [ -0.04*Y(1) + 1e4*Y(2)*Y(3)
                   0.04*Y(1) - 1e4*Y(2)*Y(3) - 3e7*Y(2)^2
          Y(1) + Y(2) + Y(3) - 1 ];
          endfunction
          opt = odeset ("Mass", [1 0 0; 0 1 0; 0 0 0], "MStateDependence", "none");
          [T,Y] = ode15s (@robertson_dae, [0, 1e3], [1; 0; 0], opt);

     See also: *note decic: XREFdecic, *note odeset: XREFodeset, *note
     odeget: XREFodeget, *note ode23: XREFode23, *note ode45: XREFode45.

 -- : [T, Y] = ode15i (FUN, TRANGE, Y0, YP0)
 -- : [T, Y] = ode15i (FUN, TRANGE, Y0, YP0, ODE_OPT)
 -- : [T, Y, TE, YE, IE] = ode15i (...)
 -- : SOLUTION = ode15i (...)
 -- : ode15i (...)
     Solve a set of fully-implicit Ordinary Differential Equations
     (ODEs) or index 1 Differential Algebraic Equations (DAEs).

     ‘ode15i’ uses a variable step, variable order BDF (Backward
     Differentiation Formula) method that ranges from order 1 to 5.

     FUN is a function handle, inline function, or string containing the
     name of the function that defines the ODE: ‘0 = f(t,y,yp)’.  The
     function must accept three inputs where the first is time T, the
     second is the function value Y (a column vector), and the third is
     the derivative value YP (a column vector).

     TRANGE specifies the time interval over which the ODE will be
     evaluated.  Typically, it is a two-element vector specifying the
     initial and final times (‘[tinit, tfinal]’).  If there are more
     than two elements then the solution will also be evaluated at these
     intermediate time instances.

     Y0 and YP0 contain the initial values for the unknowns Y and YP.
     If they are row vectors then the solution Y will be a matrix in
     which each column is the solution for the corresponding initial
     value in Y0 and YP0.

     Y0 and YP0 must be consistent initial conditions, meaning that
     ‘f(t,y0,yp0) = 0’ is satisfied.  The function ‘decic’ may be used
     to compute consistent initial conditions given initial guesses.

     The optional fifth argument ODE_OPT specifies non-default options
     to the ODE solver.  It is a structure generated by ‘odeset’.

     The function typically returns two outputs.  Variable T is a column
     vector and contains the times where the solution was found.  The
     output Y is a matrix in which each column refers to a different
     unknown of the problem and each row corresponds to a time in T.

     The output can also be returned as a structure SOLUTION which has a
     field X containing a row vector of times where the solution was
     evaluated and a field Y containing the solution matrix such that
     each column corresponds to a time in X.  Use
     ‘fieldnames (SOLUTION)’ to see the other fields and additional
     information returned.

     If no output arguments are requested, and no ‘OutputFcn’ is
     specified in ODE_OPT, then the ‘OutputFcn’ is set to ‘odeplot’ and
     the results of the solver are plotted immediately.

     If using the "Events" option then three additional outputs may be
     returned.  TE holds the time when an Event function returned a
     zero.  YE holds the value of the solution at time TE.  IE contains
     an index indicating which Event function was triggered in the case
     of multiple Event functions.

     Example: Solve Robertson’s equations:

          function r = robertson_dae (T, Y, YP)
            r = [ -(YP(1) + 0.04*Y(1) - 1e4*Y(2)*Y(3))
                  -(YP(2) - 0.04*Y(1) + 1e4*Y(2)*Y(3) + 3e7*Y(2)^2)
          Y(1) + Y(2) + Y(3) - 1 ];
          endfunction
          [T,Y] = ode15i (@robertson_dae, [0, 1e3], [1; 0; 0], [-1e-4; 1e-4; 0]);

     See also: *note decic: XREFdecic, *note odeset: XREFodeset, *note
     odeget: XREFodeget.

 -- : [Y0_NEW, YP0_NEW] = decic (FUN, T0, Y0, FIXED_Y0, YP0, FIXED_YP0)
 -- : [Y0_NEW, YP0_NEW] = decic (FUN, T0, Y0, FIXED_Y0, YP0, FIXED_YP0,
          OPTIONS)
 -- : [Y0_NEW, YP0_NEW, RESNORM] = decic (...)

     Compute consistent implicit ODE initial conditions Y0_NEW and
     YP0_NEW given initial guesses Y0 and YP0.

     A maximum of ‘length (Y0)’ components between FIXED_Y0 and
     FIXED_YP0 may be chosen as fixed values.

     FUN is a function handle.  The function must accept three inputs
     where the first is time T, the second is a column vector of
     unknowns Y, and the third is a column vector of unknowns YP.

     T0 is the initial time such that ‘FUN(T0, Y0_NEW, YP0_NEW) = 0’,
     specified as a scalar.

     Y0 is a vector used as the initial guess for Y.

     FIXED_Y0 is a vector which specifies the components of Y0 to hold
     fixed.  Choose a maximum of ‘length (Y0)’ components between
     FIXED_Y0 and FIXED_YP0 as fixed values.  Set FIXED_Y0(i) component
     to 1 if you want to fix the value of Y0(i).  Set FIXED_Y0(i)
     component to 0 if you want to allow the value of Y0(i) to change.

     YP0 is a vector used as the initial guess for YP.

     FIXED_YP0 is a vector which specifies the components of YP0 to hold
     fixed.  Choose a maximum of ‘length (YP0)’ components between
     FIXED_Y0 and FIXED_YP0 as fixed values.  Set FIXED_YP0(i) component
     to 1 if you want to fix the value of YP0(i).  Set FIXED_YP0(i)
     component to 0 if you want to allow the value of YP0(i) to change.

     The optional seventh argument OPTIONS is a structure array.  Use
     ‘odeset’ to generate this structure.  The relevant options are
     ‘RelTol’ and ‘AbsTol’ which specify the error thresholds used to
     compute the initial conditions.

     The function typically returns two outputs.  Variable Y0_NEW is a
     column vector and contains the consistent initial value of Y.  The
     output YP0_NEW is a column vector and contains the consistent
     initial value of YP.

     The optional third output RESNORM is the norm of the vector of
     residuals.  If RESNORM is small, ‘decic’ has successfully computed
     the initial conditions.  If the value of RESNORM is large, use
     ‘RelTol’ and ‘AbsTol’ to adjust it.

     Example: Compute initial conditions for Robertson’s equations:

          function r = robertson_dae (T, Y, YP)
            r = [ -(YP(1) + 0.04*Y(1) - 1e4*Y(2)*Y(3))
                  -(YP(2) - 0.04*Y(1) + 1e4*Y(2)*Y(3) + 3e7*Y(2)^2)
          Y(1) + Y(2) + Y(3) - 1 ];
          endfunction
          [Y0_NEW,YP0_NEW] = decic (@robertson_dae, 0, [1; 0; 0], [1; 1; 0],
          [-1e-4; 1; 0], [0; 0; 0]);

     See also: *note ode15i: XREFode15i, *note odeset: XREFodeset.

 -- : ODESTRUCT = odeset ()
 -- : ODESTRUCT = odeset ("FIELD1", VALUE1, "FIELD2", VALUE2, ...)
 -- : ODESTRUCT = odeset (OLDSTRUCT, "FIELD1", VALUE1, "FIELD2", VALUE2,
          ...)
 -- : ODESTRUCT = odeset (OLDSTRUCT, NEWSTRUCT)
 -- : odeset ()

     Create or modify an ODE options structure.

     When called with no input argument and one output argument, return
     a new ODE options structure that contains all possible fields
     initialized to their default values.  If no output argument is
     requested, display a list of the common ODE solver options along
     with their default value.

     If called with name-value input argument pairs "FIELD1", "VALUE1",
     "FIELD2", "VALUE2", ... return a new ODE options structure with all
     the most common option fields initialized, *and* set the values of
     the fields "FIELD1", "FIELD2", ... to the values VALUE1, VALUE2,
     ....

     If called with an input structure OLDSTRUCT then overwrite the
     values of the options "FIELD1", "FIELD2", ... with new values
     VALUE1, VALUE2, ... and return the modified structure.

     When called with two input ODE options structures OLDSTRUCT and
     NEWSTRUCT overwrite all values from the structure OLDSTRUCT with
     new values from the structure NEWSTRUCT.  Empty values in NEWSTRUCT
     will not overwrite values in OLDSTRUCT.

     The most commonly used ODE options, which are always assigned a
     value by ‘odeset’, are the following:

     ‘AbsTol’: positive scalar | vector, def. ‘1e-6’
          Absolute error tolerance.

     ‘BDF’: {"off"} | "on"
          Use BDF formulas in implicit multistep methods.  _Note_: This
          option is not yet implemented.

     ‘Events’: function_handle
          Event function.  An event function must have the form ‘[value,
          isterminal, direction] = my_events_f (t, y)’

     ‘InitialSlope’: vector
          Consistent initial slope vector for DAE solvers.

     ‘InitialStep’: positive scalar
          Initial time step size.

     ‘Jacobian’: matrix | function_handle
          Jacobian matrix, specified as a constant matrix or a function
          of time and state.

     ‘JConstant’: {"off"} | "on"
          Specify whether the Jacobian is a constant matrix or depends
          on the state.

     ‘JPattern’: sparse matrix
          If the Jacobian matrix is sparse and non-constant but
          maintains a constant sparsity pattern, specify the sparsity
          pattern.

     ‘Mass’: matrix | function_handle
          Mass matrix, specified as a constant matrix or a function of
          time and state.

     ‘MassSingular’: {"maybe"} | "yes" | "on"
          Specify whether the mass matrix is singular.

     ‘MaxOrder’: {5} | 4 | 3 | 2 | 1
          Maximum order of formula.

     ‘MaxStep’: positive scalar
          Maximum time step value.

     ‘MStateDependence’: {"weak"} | "none" | "strong"
          Specify whether the mass matrix depends on the state or only
          on time.

     ‘MvPattern’: sparse matrix
          If the mass matrix is sparse and non-constant but maintains a
          constant sparsity pattern, specify the sparsity pattern.
          _Note_: This option is not yet implemented.

     ‘NonNegative’: scalar | vector
          Specify elements of the state vector that are expected to
          remain non-negative during the simulation.

     ‘NormControl’: {"off"} | "on"
          Control error relative to the 2-norm of the solution, rather
          than its absolute value.

     ‘OutputFcn’: function_handle
          Function to monitor the state during the simulation.  For the
          form of the function to use see ‘odeplot’.

     ‘OutputSel’: scalar | vector
          Indices of elements of the state vector to be passed to the
          output monitoring function.

     ‘Refine’: positive scalar
          Specify whether output should be returned only at the end of
          each time step or also at intermediate time instances.  The
          value should be a scalar indicating the number of equally
          spaced time points to use within each timestep at which to
          return output.  _Note_: This option is not yet implemented.

     ‘RelTol’: positive scalar
          Relative error tolerance.

     ‘Stats’: {"off"} | "on"
          Print solver statistics after simulation.

     ‘Vectorized’: {"off"} | "on"
          Specify whether ‘odefun’ can be passed multiple values of the
          state at once.

     Field names that are not in the above list are also accepted and
     added to the result structure.

     See also: *note odeget: XREFodeget.

 -- : VAL = odeget (ODE_OPT, FIELD)
 -- : VAL = odeget (ODE_OPT, FIELD, DEFAULT)

     Query the value of the property FIELD in the ODE options structure
     ODE_OPT.

     If called with two input arguments and the first input argument
     ODE_OPT is an ODE option structure and the second input argument
     FIELD is a string specifying an option name, then return the option
     value VAL corresponding to FIELD from ODE_OPT.

     If called with an optional third input argument, and FIELD is not
     set in the structure ODE_OPT, then return the default value DEFAULT
     instead.

     See also: *note odeset: XREFodeset.

 -- : STOP_SOLVE = odeplot (T, Y, FLAG)

     Open a new figure window and plot the solution of an ode problem at
     each time step during the integration.

     The types and values of the input parameters T and Y depend on the
     input FLAG that is of type string.  Valid values of FLAG are:

     ‘"init"’
          The input T must be a column vector of length 2 with the first
          and last time step (‘[TFIRST TLAST]’.  The input Y contains
          the initial conditions for the ode problem (Y0).

     ‘""’
          The input T must be a scalar double specifying the time for
          which the solution in input Y was calculated.

     ‘"done"’
          The inputs should be empty, but are ignored if they are
          present.

     ‘odeplot’ always returns false, i.e., don’t stop the ode solver.

     Example: solve an anonymous implementation of the "Van der Pol"
     equation and display the results while solving.

          fvdp = @(t,y) [y(2); (1 - y(1)^2) * y(2) - y(1)];

          opt = odeset ("OutputFcn", @odeplot, "RelTol", 1e-6);
          sol = ode45 (fvdp, [0 20], [2 0], opt);

     Background Information: This function is called by an ode solver
     function if it was specified in the "OutputFcn" property of an
     options structure created with ‘odeset’.  The ode solver will
     initially call the function with the syntax ‘odeplot ([TFIRST,
     TLAST], Y0, "init")’.  The function initializes internal variables,
     creates a new figure window, and sets the x limits of the plot.
     Subsequently, at each time step during the integration the ode
     solver calls ‘odeplot (T, Y, [])’.  At the end of the solution the
     ode solver calls ‘odeplot ([], [], "done")’ so that odeplot can
     perform any clean-up actions required.

     See also: *note odeset: XREFodeset, *note odeget: XREFodeget, *note
     ode23: XREFode23, *note ode45: XREFode45.


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

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

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

     ‘daspk’ solves the set of 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, inline, or function handle
     that names the function f 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 a two-element cell array of
     strings, inline functions, or function handles, 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: *note dassl: XREFdassl.

 -- : daspk_options ()
 -- : val = daspk_options (OPT)
 -- : daspk_options (OPT, VAL)
     Query or set options for the function ‘daspk’.

     When called with no arguments, the names of all available options
     and their current values are displayed.

     Given one argument, return the value of the option OPT.

     When called with two arguments, ‘daspk_options’ sets the option OPT
     to value VAL.

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

 -- : [X, XDOT, ISTATE, MSG] = dassl (FCN, X_0, XDOT_0, T, T_CRIT)
     Solve a set of differential-algebraic equations.

     ‘dassl’ solves the set of 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, inline, or function handle
     that names the function f 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 a two-element cell array of
     strings, inline functions, or function handles, 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 ‘dassl’ 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 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 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 ‘dassl_options’ to set optional parameters
     for ‘dassl’.

     See also: *note daspk: XREFdaspk, *note dasrt: XREFdasrt, *note
     lsode: XREFlsode.

 -- : dassl_options ()
 -- : val = dassl_options (OPT)
 -- : dassl_options (OPT, VAL)
     Query or set options for the function ‘dassl’.

     When called with no arguments, the names of all available options
     and their current values are displayed.

     Given one argument, return the value of the option OPT.

     When called with two arguments, ‘dassl_options’ sets the option OPT
     to value VAL.

     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"
          If nonzero, ‘dassl’ will attempt to compute a consistent set
          of initial conditions.  This is generally not reliable, so it
          is best to provide a consistent set and leave this option set
          to zero.

     "enforce nonnegativity constraints"
          If you know that the solutions to your equations will always
          be non-negative, it may help to set this parameter to a
          nonzero value.  However, it is probably best to try leaving
          this option set to zero first, and only setting it to a
          nonzero value if that doesn’t work very well.

     "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 (default is not specified).

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

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

     ‘dasrt’ solves the set of 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, inline, or function handle
     that names the function f 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 a two-element cell array of
     strings, inline functions, or function handles, 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 round-off 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: *note dasrt_options: XREFdasrt_options, *note daspk:
     XREFdaspk, *note dasrt: XREFdasrt, *note lsode: XREFlsode.

 -- : dasrt_options ()
 -- : val = dasrt_options (OPT)
 -- : dasrt_options (OPT, VAL)
     Query or set options for the function ‘dasrt’.

     When called with no arguments, the names of all available options
     and their current values are displayed.

     Given one argument, return the value of the option OPT.

     When called with two arguments, ‘dasrt_options’ sets the option OPT
     to value VAL.

     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

25 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

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

 -- : [XOPT, FMIN, ERRNUM, 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 (default: 1)’
               Level of messages output by solver routines:

               0 (‘GLP_MSG_OFF’)
                    No output.

               1 (‘GLP_MSG_ERR’)
                    Error and warning messages only.

               2 (‘GLP_MSG_ON’)
                    Normal output.

               3 (‘GLP_MSG_ALL’)
                    Full output (includes informational messages).

          ‘scale (default: 16)’
               Scaling option.  The values can be combined with the
               bitwise OR operator and may be the following:

               1 (‘GLP_SF_GM’)
                    Geometric mean scaling.

               16 (‘GLP_SF_EQ’)
                    Equilibration scaling.

               32 (‘GLP_SF_2N’)
                    Round scale factors to power of two.

               64 (‘GLP_SF_SKIP’)
                    Skip if problem is well scaled.

               Alternatively, a value of 128 (‘GLP_SF_AUTO’) may be also
               specified, in which case the routine chooses the scaling
               options automatically.

          ‘dual (default: 1)’
               Simplex method option:

               1 (‘GLP_PRIMAL’)
                    Use two-phase primal simplex.

               2 (‘GLP_DUALP’)
                    Use two-phase dual simplex, and if it fails, switch
                    to the primal simplex.

               3 (‘GLP_DUAL’)
                    Use two-phase dual simplex.

          ‘price (default: 34)’
               Pricing option (for both primal and dual simplex):

               17 (‘GLP_PT_STD’)
                    Textbook pricing.

               34 (‘GLP_PT_PSE’)
                    Steepest edge pricing.

          ‘itlim (default: intmax)’
               Simplex iterations limit.  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.

          ‘outfrq (default: 200)’
               Output frequency, in iterations.  This parameter
               specifies how frequently the solver sends information
               about the solution to the standard output.

          ‘branch (default: 4)’
               Branching technique option (for MIP only):

               1 (‘GLP_BR_FFV’)
                    First fractional variable.

               2 (‘GLP_BR_LFV’)
                    Last fractional variable.

               3 (‘GLP_BR_MFV’)
                    Most fractional variable.

               4 (‘GLP_BR_DTH’)
                    Heuristic by Driebeck and Tomlin.

               5 (‘GLP_BR_PCH’)
                    Hybrid pseudocost heuristic.

          ‘btrack (default: 4)’
               Backtracking technique option (for MIP only):

               1 (‘GLP_BT_DFS’)
                    Depth first search.

               2 (‘GLP_BT_BFS’)
                    Breadth first search.

               3 (‘GLP_BT_BLB’)
                    Best local bound.

               4 (‘GLP_BT_BPH’)
                    Best projection heuristic.

          ‘presol (default: 1)’
               If this flag is set, the simplex solver uses 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.

          ‘rtest (default: 34)’
               Ratio test technique:

               17 (‘GLP_RT_STD’)
                    Standard ("textbook").

               34 (‘GLP_RT_HAR’)
                    Harris’ two-pass ratio test.

          ‘tmlim (default: intmax)’
               Searching time limit, in milliseconds.

          ‘outdly (default: 0)’
               Output delay, in seconds.  This parameter specifies how
               long the solver should delay sending information about
               the solution to the standard output.

          ‘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:

          ‘tolbnd (default: 1e-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 (default: 1e-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 (default: 1e-10)’
               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 (default: -DBL_MAX)’
               Lower limit of the objective function.  If 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 (default: +DBL_MAX)’
               Upper limit of the objective function.  If the objective
               function reaches this limit and continues increasing, the
               solver stops the search.  This parameter is used in the
               dual simplex only.

          ‘tolint (default: 1e-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 (default: 1e-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.

     ERRNUM
          Error code.

          0
               No error.

          1 (‘GLP_EBADB’)
               Invalid basis.

          2 (‘GLP_ESING’)
               Singular matrix.

          3 (‘GLP_ECOND’)
               Ill-conditioned matrix.

          4 (‘GLP_EBOUND’)
               Invalid bounds.

          5 (‘GLP_EFAIL’)
               Solver failed.

          6 (‘GLP_EOBJLL’)
               Objective function lower limit reached.

          7 (‘GLP_EOBJUL’)
               Objective function upper limit reached.

          8 (‘GLP_EITLIM’)
               Iterations limit exhausted.

          9 (‘GLP_ETMLIM’)
               Time limit exhausted.

          10 (‘GLP_ENOPFS’)
               No primal feasible solution.

          11 (‘GLP_ENODFS’)
               No dual feasible solution.

          12 (‘GLP_EROOT’)
               Root LP optimum not provided.

          13 (‘GLP_ESTOP’)
               Search terminated by application.

          14 (‘GLP_EMIPGAP’)
               Relative MIP gap tolerance reached.

          15 (‘GLP_ENOFEAS’)
               No primal/dual feasible solution.

          16 (‘GLP_ENOCVG’)
               No convergence.

          17 (‘GLP_EINSTAB’)
               Numerical instability.

          18 (‘GLP_EDATA’)
               Invalid data.

          19 (‘GLP_ERANGE’)
               Result out of range.

     EXTRA
          A data structure containing the following fields:

          ‘lambda’
               Dual variables.

          ‘redcosts’
               Reduced Costs.

          ‘time’
               Time (in seconds) used for solving LP/MIP problem.

          ‘status’
               Status of the optimization.

               1 (‘GLP_UNDEF’)
                    Solution status is undefined.

               2 (‘GLP_FEAS’)
                    Solution is feasible.

               3 (‘GLP_INFEAS’)
                    Solution is infeasible.

               4 (‘GLP_NOFEAS’)
                    Problem has no feasible solution.

               5 (‘GLP_OPT’)
                    Solution is optimal.

               6 (‘GLP_UNBND’)
                    Problem has no unbounded solution.

     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

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

 -- : [X, OBJ, INFO, LAMBDA] = qp (X0, H)
 -- : [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q)
 -- : [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B)
 -- : [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B, LB, UB)
 -- : [X, OBJ, INFO, LAMBDA] = qp (X0, H, Q, A, B, LB, UB, A_LB, A_IN,
          A_UB)
 -- : [X, OBJ, INFO, LAMBDA] = qp (..., OPTIONS)
     Solve a quadratic program (QP).

     Solve the quadratic program defined by

          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_IN, A_LB, A_UB) may be set to the empty
     matrix (‘[]’) if not present.  The constraints A and A_IN are
     matrices with each row representing a single constraint.  The other
     bounds are scalars or vectors depending on the number of
     constraints.  The algorithm is faster if the initial guess is
     feasible.

     OPTIONS
          An optional structure containing the following parameter(s)
          used to define the behavior of the 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.

          ‘MaxIter (default: 200)’
               Maximum number of iterations.

     INFO
          Structure containing run-time information about the algorithm.
          The following fields are defined:

          ‘solveiter’
               The number of iterations required to find the solution.

          ‘info’
               An integer indicating the status of the solution.

               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.

 -- : X = pqpnonneg (C, D)
 -- : X = pqpnonneg (C, D, X0)
 -- : X = pqpnonneg (C, D, X0, OPTIONS)
 -- : [X, MINVAL] = pqpnonneg (...)
 -- : [X, MINVAL, EXITFLAG] = pqpnonneg (...)
 -- : [X, MINVAL, EXITFLAG, OUTPUT] = pqpnonneg (...)
 -- : [X, MINVAL, EXITFLAG, OUTPUT, LAMBDA] = pqpnonneg (...)

     Minimize ‘1/2*X'*C*X + D'*X’ subject to ‘X >= 0’.

     C and D must be real matrices, and C must be symmetric and positive
     definite.

     X0 is an optional initial guess for the solution X.

     OPTIONS is an options structure to change the behavior of the
     algorithm (*note optimset: XREFoptimset.).  ‘pqpnonneg’ recognizes
     one option: "MaxIter".

     Outputs:

     X
          The solution matrix

     MINVAL
          The minimum attained model value, ‘1/2*XMIN'*C*XMIN + D'*XMIN’

     EXITFLAG
          An indicator of convergence.  0 indicates that the iteration
          count was exceeded, and therefore convergence was not reached;
          >0 indicates that the algorithm converged.  (The algorithm is
          stable and will converge given enough iterations.)

     OUTPUT
          A structure with two fields:

             • "algorithm": The algorithm used ("nnls")

             • "iterations": The number of iterations taken.

     LAMBDA
          Undocumented output

     See also: *note lsqnonneg: XREFlsqnonneg, *note qp: XREFqp, *note
     optimset: XREFoptimset.


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

25.3 Nonlinear Programming
==========================

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

 -- : [X, OBJ, INFO, ITER, NF, LAMBDA] = sqp (X0, PHI)
 -- : [...] = sqp (X0, PHI, G)
 -- : [...] = sqp (X0, PHI, G, H)
 -- : [...] = sqp (X0, PHI, G, H, LB, UB)
 -- : [...] = sqp (X0, PHI, G, H, LB, UB, MAXITER)
 -- : [...] = sqp (X0, PHI, G, H, LB, UB, MAXITER, TOL)
     Minimize an objective function using sequential quadratic
     programming (SQP).

     Solve the nonlinear program

          min phi (x)
           x

     subject to

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

     using a sequential quadratic programming method.

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

     The second argument is a function handle pointing to the objective
     function PHI.  The objective function must accept one vector
     argument and return 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 that computes 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.

     When supplied, the gradient function ‘PHI{2}’ must accept one
     vector argument and return a vector.  When supplied, the Hessian
     function ‘PHI{3}’ must accept one vector argument and return a
     matrix.

     The third and fourth arguments G and H are function handles
     pointing to functions that compute the equality constraints and the
     inequality constraints, respectively.  If the problem does not have
     equality (or inequality) constraints, then use an empty matrix ([])
     for G (or H).  When supplied, these equality and inequality
     constraint functions must accept one vector argument and return 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, LB and UB, contain lower and upper
     bounds on X.  These must be consistent with the equality and
     inequality constraints G and H.  If the arguments are vectors then
     X(i) is bound by LB(i) and UB(i).  A bound can also be a scalar in
     which case all elements of X will share the same bound.  If only
     one bound (lb, ub) is specified then the other will default to
     (-REALMAX, +REALMAX).

     The seventh argument MAXITER specifies the maximum number of
     iterations.  The default value is 100.

     The eighth argument TOL specifies the tolerance for the stopping
     criteria.  The default value is ‘sqrt (eps)’.

     The value returned in INFO may be one of the following:

     101
          The algorithm terminated normally.  All constraints meet the
          specified tolerance.

     102
          The BFGS update failed.

     103
          The maximum number of iterations was reached.

     104
          The stepsize has become too small, i.e., delta X, is less than
          ‘TOL * norm (x)’.

     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

     See also: *note qp: XREFqp.


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

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

 -- : [BETA, SIGMA, R] = ols (Y, X)
     Ordinary least squares (OLS) estimation.

     OLS applies to the multivariate model Y = X*B + E 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 is a p-variate observation in which each column
     represents a variable.  Likewise, the rows of X represent k-variate
     observations or possibly designed values.  Furthermore, the
     collection of observations X must be of adequate rank, k, otherwise
     B cannot be uniquely estimated.

     The observation errors, E, are assumed to originate from an
     underlying p-variate distribution with zero mean and p-by-p
     covariance matrix S, both constant conditioned on X.  Furthermore,
     the matrix S is constant with respect to each observation such that
     ‘mean (E) = 0’ and ‘cov (vec (E)) = kron (S, I)’.  (For cases that
     don’t meet this criteria, such as autocorrelated errors, see
     generalized least squares, gls, for more efficient estimations.)

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

     BETA
          The OLS estimator for matrix B.  BETA is calculated directly
          via ‘inv (X'*X) * X' * Y’ if the matrix ‘X'*X’ is of full
          rank.  Otherwise, ‘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’.

     See also: *note gls: XREFgls, *note pinv: XREFpinv.

 -- : [BETA, V, R] = gls (Y, X, O)
     Generalized least squares (GLS) model.

     Perform a generalized least squares estimation for the multivariate
     model Y = X*B + E 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 is a p-variate observation in which each column
     represents a variable.  Likewise, the rows of X represent k-variate
     observations or possibly designed values.  Furthermore, the
     collection of observations X must be of adequate rank, k, otherwise
     B cannot be uniquely estimated.

     The observation errors, E, are assumed to originate from an
     underlying p-variate distribution with zero mean but possibly
     heteroscedastic observations.  That is, in general, ‘mean (E) = 0’
     and ‘cov (vec (E)) = (s^2)*O’ in which s is a scalar and O is a
     t*p-by-t*p matrix.

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

     BETA
          The GLS estimator for matrix B.

     V
          The GLS estimator for scalar s^2.

     R
          The matrix of GLS residuals, R = Y - X*BETA.

     See also: *note ols: XREFols.

 -- : X = lsqnonneg (C, D)
 -- : X = lsqnonneg (C, D, X0)
 -- : X = lsqnonneg (C, D, X0, OPTIONS)
 -- : [X, RESNORM] = lsqnonneg (...)
 -- : [X, RESNORM, RESIDUAL] = lsqnonneg (...)
 -- : [X, RESNORM, RESIDUAL, EXITFLAG] = lsqnonneg (...)
 -- : [X, RESNORM, RESIDUAL, EXITFLAG, OUTPUT] = lsqnonneg (...)
 -- : [X, RESNORM, RESIDUAL, EXITFLAG, OUTPUT, LAMBDA] = lsqnonneg (...)

     Minimize ‘norm (C*X - D)’ subject to ‘X >= 0’.

     C and D must be real matrices.

     X0 is an optional initial guess for the solution X.

     OPTIONS is an options structure to change the behavior of the
     algorithm (*note optimset: XREFoptimset.).  ‘lsqnonneg’ recognizes
     these options: "MaxIter", "TolX".

     Outputs:

     RESNORM
          The squared 2-norm of the residual: ‘norm (C*X-D)^2’

     RESIDUAL
          The residual: ‘D-C*X’

     EXITFLAG
          An indicator of convergence.  0 indicates that the iteration
          count was exceeded, and therefore convergence was not reached;
          >0 indicates that the algorithm converged.  (The algorithm is
          stable and will converge given enough iterations.)

     OUTPUT
          A structure with two fields:

             • "algorithm": The algorithm used ("nnls")

             • "iterations": The number of iterations taken.

     LAMBDA
          Undocumented output

     See also: *note pqpnonneg: XREFpqpnonneg, *note lscov: XREFlscov,
     *note optimset: XREFoptimset.

 -- : X = lscov (A, B)
 -- : X = lscov (A, B, V)
 -- : X = lscov (A, B, V, ALG)
 -- : [X, STDX, MSE, S] = lscov (...)

     Compute a generalized linear least squares fit.

     Estimate X under the model B = AX + W, where the noise W is assumed
     to follow a normal distribution with covariance matrix {\sigma^2}
     V.

     If the size of the coefficient matrix A is n-by-p, the size of the
     vector/array of constant terms B must be n-by-k.

     The optional input argument V may be an n-element vector of
     positive weights (inverse variances), or an n-by-n symmetric
     positive semi-definite matrix representing the covariance of B.  If
     V is not supplied, the ordinary least squares solution is returned.

     The ALG input argument, a guidance on solution method to use, is
     currently ignored.

     Besides the least-squares estimate matrix X (p-by-k), the function
     also returns STDX (p-by-k), the error standard deviation of
     estimated X; MSE (k-by-1), the estimated data error covariance
     scale factors (\sigma^2); and S (p-by-p, or p-by-p-by-k if k > 1),
     the error covariance of X.

     Reference: Golub and Van Loan (1996), ‘Matrix Computations (3rd
     Ed.)’, Johns Hopkins, Section 5.6.3

     See also: *note ols: XREFols, *note gls: XREFgls, *note lsqnonneg:
     XREFlsqnonneg.

 -- : optimset ()
 -- : OPTIONS = optimset ()
 -- : OPTIONS = optimset (PAR, VAL, ...)
 -- : OPTIONS = optimset (OLD, PAR, VAL, ...)
 -- : OPTIONS = optimset (OLD, NEW)
     Create options structure for optimization functions.

     When called without any input or output arguments, ‘optimset’
     prints a list of all valid optimization parameters.

     When called with one output and no inputs, return an options
     structure with all valid option parameters initialized to ‘[]’.

     When called with a list of parameter/value pairs, return an options
     structure with only the named parameters initialized.

     When the first input is an existing options structure OLD, the
     values are updated from either the PAR/VAL list or from the options
     structure NEW.

     Valid parameters are:

     AutoScaling

     ComplexEqn

     Display
          Request verbose display of results from optimizations.  Values
          are:

          "off" [default]
               No display.

          "iter"
               Display intermediate results for every loop iteration.

          "final"
               Display the result of the final loop iteration.

          "notify"
               Display the result of the final loop iteration if the
               function has failed to converge.

     FinDiffType

     FunValCheck
          When enabled, display an error if the objective function
          returns an invalid value (a complex number, NaN, or Inf).
          Must be set to "on" or "off" [default].  Note: the functions
          ‘fzero’ and ‘fminbnd’ correctly handle Inf values and only
          complex values or NaN will cause an error in this case.

     GradObj
          When set to "on", the function to be minimized must return a
          second argument which is the gradient, or first derivative, of
          the function at the point X.  If set to "off" [default], the
          gradient is computed via finite differences.

     Jacobian
          When set to "on", the function to be minimized must return a
          second argument which is the Jacobian, or first derivative, of
          the function at the point X.  If set to "off" [default], the
          Jacobian is computed via finite differences.

     MaxFunEvals
          Maximum number of function evaluations before optimization
          stops.  Must be a positive integer.

     MaxIter
          Maximum number of algorithm iterations before optimization
          stops.  Must be a positive integer.

     OutputFcn
          A user-defined function executed once per algorithm iteration.

     TolFun
          Termination criterion for the function output.  If the
          difference in the calculated objective function between one
          algorithm iteration and the next is less than ‘TolFun’ the
          optimization stops.  Must be a positive scalar.

     TolX
          Termination criterion for the function input.  If the
          difference in X, the current search point, between one
          algorithm iteration and the next is less than ‘TolX’ the
          optimization stops.  Must be a positive scalar.

     TypicalX

     Updating

     See also: *note optimget: XREFoptimget.

 -- : optimget (OPTIONS, PARNAME)
 -- : optimget (OPTIONS, PARNAME, DEFAULT)
     Return the specific option PARNAME from the optimization options
     structure OPTIONS created by ‘optimset’.

     If PARNAME is not defined then return DEFAULT if supplied,
     otherwise return an empty matrix.

     See also: *note optimset: XREFoptimset.


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

26 Statistics
*************

Octave has support for various statistical methods.  The emphasis is on
basic descriptive statistics, but the Octave Forge statistics package
includes probability distributions, statistical tests, random number
generation, and much more.

   The functions that analyze data all assume that multi-dimensional
data is arranged in a matrix where each row is an observation, and each
column is a variable.  Thus, 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 test for data
containing NaN, NA, or Inf.  These values need to be detected and dealt
with explicitly.  See *note isnan: XREFisnan, *note isna: XREFisna,
*note isinf: XREFisinf, *note isfinite: XREFisfinite.

* Menu:

* Descriptive Statistics::
* Statistics on Sliding Windows of Data::
* Basic Statistical Functions::
* Correlation and Regression Analysis::
* Distributions::
* Random Number Generation::


File: octave.info,  Node: Descriptive Statistics,  Next: Statistics on Sliding Windows of Data,  Up: Statistics

26.1 Descriptive Statistics
===========================

One principal goal of descriptive statistics is to represent the essence
of a large data set concisely.  Octave provides the mean, median, and
mode functions which all summarize a data set with just a single number
corresponding to the central tendency of the data.

 -- : mean (X)
 -- : mean (X, DIM)
 -- : mean (X, OPT)
 -- : mean (X, DIM, OPT)
 -- : mean (..., OUTTYPE)
     Compute the mean of the elements of the vector X.

     The mean is defined as

          mean (X) = SUM_i X(i) / N

     where N is the length of the X vector.

     If X is a matrix, compute the mean for each column and return them
     in a row vector.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional argument OPT selects the type of mean to compute.  The
     following options are recognized:

     "a"
          Compute the (ordinary) arithmetic mean.  [default]

     "g"
          Compute the geometric mean.

     "h"
          Compute the harmonic mean.

     The optional argument OUTTYPE selects the data type of the output
     value.  The following options are recognized:

     "default"
          Output will be of class double unless X is of class single, in
          which case the output will also be single.

     "double"
          Output will be of class double.

     "native"
          Output will be the same class as X unless X is of class
          logical in which case it returns of class double.

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

     See also: *note median: XREFmedian, *note mode: XREFmode.

 -- : median (X)
 -- : median (X, DIM)
     Compute the median value of the elements of the vector X.

     When the elements of X are sorted, say ‘S = sort (X)’, the median
     is defined as

                       |  S(ceil(N/2))           N odd
          median (X) = |
                       | (S(N/2) + S(N/2+1))/2   N even

     If X is of a discrete type such as integer or logical, then the
     case of even N rounds up (or toward ‘true’).

     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: *note mean: XREFmean, *note mode: XREFmode.

 -- : mode (X)
 -- : mode (X, DIM)
 -- : [M, F, C] = mode (...)
     Compute the most frequently occurring value in a dataset (mode).

     ‘mode’ determines the frequency of values along the first
     non-singleton dimension and returns the value with the highest
     frequency.  If two, or more, values have the same frequency ‘mode’
     returns the smallest.

     If the optional argument DIM is given, operate along this
     dimension.

     The return variable F is the number of occurrences of the mode in
     the dataset.

     The cell array C contains all of the elements with the maximum
     frequency.

     See also: *note mean: XREFmean, *note median: XREFmedian.

   Using just one number, such as the mean, to represent an entire data
set may not give an accurate picture of the data.  One way to
characterize the fit is to measure the dispersion of the data.  Octave
provides several functions for measuring dispersion.

 -- : [S, L] = bounds (X)
 -- : [S, L] = bounds (X, DIM)
 -- : [S, L] = bounds (..., "nanflag")
     Return the smallest and largest values of the input data X.

     If X is a vector, the bounds are calculated over the elements of X.
     If X is a matrix, the bounds are calculated for each column.  For a
     multi-dimensional array, the bounds are calculated over the first
     non-singleton dimension.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional argument "nanflag" defaults to "omitnan" which does
     not include NaN values in the result.  If the argument "includenan"
     is given, and there is a NaN present, then the result for both
     smallest (S) and largest (L) elements will be NaN.

     The bounds are a quickly computed measure of the dispersion of a
     data set, but are less accurate than ‘iqr’ if there are outlying
     data points.

     See also: *note range: XREFrange, *note iqr: XREFiqr, *note mad:
     XREFmad, *note std: XREFstd.

 -- : range (X)
 -- : range (X, DIM)
     Return the range, i.e., the difference between the maximum and the
     minimum of the input data.

     If X is a vector, the range is calculated over the elements of X.
     If X is a matrix, the range is calculated over each column of X.

     If the optional argument DIM is given, operate along this
     dimension.

     The range is a quickly computed measure of the dispersion of a data
     set, but is less accurate than ‘iqr’ if there are outlying data
     points.

     See also: *note bounds: XREFbounds, *note iqr: XREFiqr, *note mad:
     XREFmad, *note std: XREFstd.

 -- : iqr (X)
 -- : iqr (X, DIM)
     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 optional argument DIM is given, operate along this
     dimension.

     As a measure of dispersion, the interquartile range is less
     affected by outliers than either ‘range’ or ‘std’.

     See also: *note bounds: XREFbounds, *note mad: XREFmad, *note
     range: XREFrange, *note std: XREFstd.

 -- : mad (X)
 -- : mad (X, OPT)
 -- : mad (X, OPT, DIM)
     Compute the mean or median absolute deviation of the elements of X.

     The mean absolute deviation is defined as

          MAD = mean (abs (X - mean (X)))

     The median absolute deviation is defined as

          MAD = median (abs (X - median (X)))

     If X is a matrix, compute ‘mad’ for each column and return results
     in a row vector.  For a multi-dimensional array, the calculation is
     done over the first non-singleton dimension.

     The optional argument OPT determines whether mean or median
     absolute deviation is calculated.  The default is 0 which
     corresponds to mean absolute deviation; A value of 1 corresponds to
     median absolute deviation.

     If the optional argument DIM is given, operate along this
     dimension.

     As a measure of dispersion, ‘mad’ is less affected by outliers than
     ‘std’.

     See also: *note bounds: XREFbounds, *note range: XREFrange, *note
     iqr: XREFiqr, *note std: XREFstd, *note mean: XREFmean, *note
     median: XREFmedian.

 -- : meansq (X)
 -- : meansq (X, DIM)
     Compute the mean square of the elements of the vector X.

     The mean square is defined as

          meansq (X) = 1/N SUM_i X(i)^2

     where N is the length of the X vector.

     If X is a matrix, return a row vector containing the mean square of
     each column.

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note var: XREFvar, *note std: XREFstd, *note moment:
     XREFmoment.

 -- : std (X)
 -- : std (X, OPT)
 -- : std (X, OPT, DIM)
     Compute the standard deviation of the elements of the vector X.

     The standard deviation is defined as

          std (X) = sqrt ( 1/(N-1) SUM_i (X(i) - mean(X))^2 )

     where N is the number of elements of the X vector.

     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:
          normalize with N-1, provides the square root of the best
          unbiased estimator of the variance [default]

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

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note var: XREFvar, *note bounds: XREFbounds, *note mad:
     XREFmad, *note range: XREFrange, *note iqr: XREFiqr, *note mean:
     XREFmean, *note median: XREFmedian.

   In addition to knowing the size of a dispersion it is useful to know
the shape of the data set.  For example, are data points massed to the
left or right of the mean?  Octave provides several common measures to
describe the shape of the data set.  Octave can also calculate moments
allowing arbitrary shape measures to be developed.

 -- : var (X)
 -- : var (X, OPT)
 -- : var (X, OPT, DIM)
     Compute the variance of the elements of the vector X.

     The variance is defined as

          var (X) = 1/(N-1) SUM_i (X(i) - mean(X))^2

     where N is the length of the X vector.

     If X is a matrix, compute the variance for each column and return
     them in a row vector.

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

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

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

     If N is equal to 1 the value of OPT is ignored and normalization by
     N is used.

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note cov: XREFcov, *note std: XREFstd, *note skewness:
     XREFskewness, *note kurtosis: XREFkurtosis, *note moment:
     XREFmoment.

 -- : skewness (X)
 -- : skewness (X, FLAG)
 -- : skewness (X, FLAG, DIM)
     Compute the sample skewness of the elements of X.

     The sample skewness is defined as

                         mean ((X - mean (X)).^3)
          skewness (X) = ------------------------.
                                std (X).^3

     The optional argument FLAG controls which normalization is used.
     If FLAG is equal to 1 (default value, used when FLAG is omitted or
     empty), return the sample skewness as defined above.  If FLAG is
     equal to 0, return the adjusted skewness coefficient instead:

                            sqrt (N*(N-1))   mean ((X - mean (X)).^3)
          skewness (X, 0) = -------------- * ------------------------.
                                (N - 2)             std (X).^3

     where N is the length of the X vector.

     The adjusted skewness coefficient is obtained by replacing the
     sample second and third central moments by their bias-corrected
     versions.

     If X is a matrix, or more generally a multi-dimensional array,
     return the skewness along the first non-singleton dimension.  If
     the optional DIM argument is given, operate along this dimension.

     See also: *note var: XREFvar, *note kurtosis: XREFkurtosis, *note
     moment: XREFmoment.

 -- : kurtosis (X)
 -- : kurtosis (X, FLAG)
 -- : kurtosis (X, FLAG, DIM)
     Compute the sample kurtosis of the elements of X.

     The sample kurtosis is defined as

               mean ((X - mean (X)).^4)
          k1 = ------------------------
                      std (X).^4

     The optional argument FLAG controls which normalization is used.
     If FLAG is equal to 1 (default value, used when FLAG is omitted or
     empty), return the sample kurtosis as defined above.  If FLAG is
     equal to 0, return the "bias-corrected" kurtosis coefficient
     instead:

                        N - 1
          k0 = 3 + -------------- * ((N + 1) * k1 - 3 * (N - 1))
                   (N - 2)(N - 3)

     where N is the length of the X vector.

     The bias-corrected kurtosis coefficient is obtained by replacing
     the sample second and fourth central moments by their unbiased
     versions.  It is an unbiased estimate of the population kurtosis
     for normal populations.

     If X is a matrix, or more generally a multi-dimensional array,
     return the kurtosis along the first non-singleton dimension.  If
     the optional DIM argument is given, operate along this dimension.

     See also: *note var: XREFvar, *note skewness: XREFskewness, *note
     moment: XREFmoment.

 -- : moment (X, P)
 -- : moment (X, P, TYPE)
 -- : moment (X, P, DIM)
 -- : moment (X, P, TYPE, DIM)
 -- : moment (X, P, DIM, TYPE)
     Compute the P-th central moment of the vector X.

     The P-th central moment of X is defined as:

          1/N SUM_i (X(i) - mean(X))^P

     where N is the length of the X vector.

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

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string TYPE specifies the type of moment to be
     computed.  Valid options are:

     "c"
          Central Moment (default).

     "a"
     "ac"
          Absolute Central Moment.  The moment about the mean ignoring
          sign defined as

               1/N SUM_i (abs (X(i) - mean(X)))^P

     "r"
          Raw Moment.  The moment about zero defined as

               moment (X) = 1/N SUM_i X(i)^P

     "ar"
          Absolute Raw Moment.  The moment about zero ignoring sign
          defined as

               1/N SUM_i ( abs (X(i)) )^P

     If both TYPE and DIM are given they may appear in any order.

     See also: *note var: XREFvar, *note skewness: XREFskewness, *note
     kurtosis: XREFkurtosis.

 -- : Q = quantile (X)
 -- : Q = quantile (X, P)
 -- : Q = quantile (X, P, DIM)
 -- : 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.

     If P is unspecified, return the quantiles for ‘[0.00 0.25 0.50 0.75
     1.00]’.  The optional argument DIM determines the dimension along
     which the quantiles are calculated.  If DIM is omitted it defaults
     to the first non-singleton dimension.

     The methods available to calculate sample quantiles are the nine
     methods used by R (<https://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 method’s
     representative cdf.

       4. Method 4: P(k) = k / N. That is, linear interpolation of the
          empirical cdf, where N is the length of P.

       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;
          <https://cran.r-project.org/doc/manuals/fullrefman.pdf>.

     Examples:

          x = randi (1000, [10, 1]);  # Create empirical data in range 1-1000
          q = quantile (x, [0, 1]);   # Return minimum, maximum of distribution
          q = quantile (x, [0.25 0.5 0.75]); # Return quartiles of distribution

     See also: *note prctile: XREFprctile.

 -- : Q = prctile (X)
 -- : Q = prctile (X, P)
 -- : Q = prctile (X, P, DIM)
     For a sample X, compute the quantiles, Q, corresponding to the
     cumulative probability values, P, in percent.

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

     If P is unspecified, return the quantiles for ‘[0 25 50 75 100]’.

     The optional argument DIM determines the dimension along which the
     percentiles are calculated.  If DIM is omitted it defaults to the
     first non-singleton dimension.

     Programming Note: All non-numeric values (NaNs) of X are ignored.

     See also: *note quantile: XREFquantile.

   A summary view of a data set can be generated quickly with the
‘statistics’ function.

 -- : statistics (X)
 -- : statistics (X, DIM)
     Return a vector with the minimum, first quartile, median, third
     quartile, maximum, mean, standard deviation, skewness, and kurtosis
     of the elements of the vector X.

     If X is a matrix, calculate statistics over the first non-singleton
     dimension.

     If the optional argument DIM is given, operate along this
     dimension.

     See also: *note min: XREFmin, *note max: XREFmax, *note median:
     XREFmedian, *note mean: XREFmean, *note std: XREFstd, *note
     skewness: XREFskewness, *note kurtosis: XREFkurtosis.


File: octave.info,  Node: Statistics on Sliding Windows of Data,  Next: Basic Statistical Functions,  Prev: Descriptive Statistics,  Up: Statistics

26.2 Statistics on Sliding Windows of Data
==========================================

It is often useful to calculate descriptive statistics over a subsection
(i.e., window) of a full dataset.  Octave provides the function ‘movfun’
which will call an arbitrary function handle with windows of data and
accumulate the results.  Many of the most commonly desired functions,
such as the moving average over a window of data (‘movmean’), are
already provided.

 -- : Y = movfun (FCN, X, WLEN)
 -- : Y = movfun (FCN, X, [NB, NA])
 -- : Y = movfun (..., "PROPERTY", VALUE)

     Apply function FCN to a moving window of length WLEN on data X.

     If WLEN is a scalar, the function FCN is applied to a moving window
     of length WLEN.  When WLEN is an odd number the window is symmetric
     and includes ‘(WLEN - 1) / 2’ elements on either side of the
     central element.  For example, when calculating the output at index
     5 with a window length of 3, ‘movfun’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movfun’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     During calculations the data input X is reshaped into a
     2-dimensional WLEN-by-N matrix and FCN is called on this new
     matrix.  Therefore, FCN must accept an array input argument and
     apply the computation along dimension 1, i.e., down the columns of
     the array.

     When applied to an array (possibly multi-dimensional) with N
     columns, FCN may return a result in either of two formats:
     Format 1) an array of size 1-by-N-by-DIM3-by-...-by-DIMN.  This is
     the typical output format from Octave core functions.  Type ‘demo
     ("movfun", 5)’ for an example of this use case. Format 2) a row
     vector of length ‘N * NUMEL_HIGHER_DIMS’ where NUMEL_HIGHER_DIMS is
     ‘prod (size (X)(3:end))’.  The output of FCN for the i-th input
     column must be found in the output at indices
     ‘i:N:(N*NUMEL_HIGHER_DIMS)’.  This format is useful when
     concatenating functions into arrays, or when using ‘nthargout’.
     Type ‘demo ("movfun", 6)’ for an example of this case.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "dim"
          Operate along the dimension specified, rather than the default
          of the first non-singleton dimension.

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               FCN (X(1:2))’, and ‘Y(end) = FCN (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = FCN ([NaN, X(1:2)])’, and ‘Y(end) = FCN ([X(end-1:end),
               NaN])’.  This option usually results in Y having ‘NaN’
               values at the boundaries, although it is influenced by
               how FCN handles ‘NaN’, and also by the property
               "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               FCN ([USER_VALUE, X(1:2)])’, and ‘Y(end) = FCN
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = FCN ([X(1), X(1:2)])’, and
               ‘Y(end) = FCN ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = FCN ([X(end),
               X(1:2)])’, and ‘Y(end) = FCN ([X(end-1:end), X(1)])’.

          Note that for some of these choices, the window size at the
          boundaries is not the same as for the central part, and FCN
          must work in these cases.

     "nancond"
          Controls whether ‘NaN’ and ‘NA’ values should be included
          (value: "includenan"), or excluded (value: "omitnan"), from
          the data passed to FCN.  The default is "includenan".
          Caution: The "omitnan" option is not yet implemented.

     "outdim"
          A row vector that selects which dimensions of the calculation
          will appear in the output Y.  This is only useful when FCN
          returns an N-dimensional array in Format 1.  The default is to
          return all output dimensions.

     Programming Note: The property "outdim" can be used to save memory
     when the output of FCN has many dimensions, or when a wrapper to
     the base function that selects the desired outputs is too costly.
     When memory is not an issue, the easiest way to select output
     dimensions is to first calculate the complete result with ‘movfun’
     and then filter that result with indexing.  If code complexity is
     not an issue then a wrapper can be created using anonymous
     functions.  For example, if ‘basefcn’ is a function returning a
     K-dimensional row output, and only dimension D is desired, then the
     following wrapper could be used.

          FCN = @(x) basefcn (x)(:,size(x,2) * (D-1) + (1:size(x,2)));
          Y = movfun (@fcn, ...);

     See also: *note movslice: XREFmovslice, *note prepad: XREFprepad,
     *note postpad: XREFpostpad, *note permute: XREFpermute, *note
     reshape: XREFreshape.

 -- : SLCIDX = movslice (N, WLEN)
 -- : [SLCIDX, C, CPRE, CPOST, WIN] = movslice (...)
     Generate indices to slice a vector of length N in to windows of
     length WLEN.

     FIXME: Document inputs N, wlen

     FIXME: Document outputs slcidx, C, Cpre, Cpost, win.

     See also: *note movfun: XREFmovfun.

 -- : Y = movmad (X, WLEN)
 -- : Y = movmad (X, [NA, NB])
 -- : Y = movmad (..., DIM)
 -- : Y = movmad (..., "NANCOND")
 -- : Y = movmad (..., PROPERTY, VALUE)
     Calculate the moving mean absolute deviation over a sliding window
     of length WLEN on data X.

     If WLEN is a scalar, the function ‘mad’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movmad’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movmad’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘mad’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               mad (X(1:2))’, and ‘Y(end) = mad (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = mad ([NaN, X(1:2)])’, and ‘Y(end) = mad ([X(end-1:end),
               NaN])’.  This option usually results in Y having ‘NaN’
               values at the boundaries, although it is influenced by
               how ‘mad’ handles ‘NaN’, and also by the property
               "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               mad ([USER_VALUE, X(1:2)])’, and ‘Y(end) = mad
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = mad ([X(1), X(1:2)])’, and
               ‘Y(end) = mad ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = mad ([X(end),
               X(1:2)])’, and ‘Y(end) = mad ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmax: XREFmovmax, *note movmean: XREFmovmean, *note
     movmedian: XREFmovmedian, *note movmin: XREFmovmin, *note movprod:
     XREFmovprod, *note movstd: XREFmovstd, *note movsum: XREFmovsum,
     *note movvar: XREFmovvar.

 -- : Y = movmax (X, WLEN)
 -- : Y = movmax (X, [NA, NB])
 -- : Y = movmax (..., DIM)
 -- : Y = movmax (..., "NANCOND")
 -- : Y = movmax (..., PROPERTY, VALUE)
     Calculate the moving maximum over a sliding window of length WLEN
     on data X.

     If WLEN is a scalar, the function ‘max’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movmax’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movmax’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘max’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               max (X(1:2))’, and ‘Y(end) = max (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = max ([NaN, X(1:2)])’, and ‘Y(end) = max ([X(end-1:end),
               NaN])’.  This option usually results in Y having ‘NaN’
               values at the boundaries, although it is influenced by
               how ‘max’ handles ‘NaN’, and also by the property
               "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               max ([USER_VALUE, X(1:2)])’, and ‘Y(end) = max
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = max ([X(1), X(1:2)])’, and
               ‘Y(end) = max ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = max ([X(end),
               X(1:2)])’, and ‘Y(end) = max ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmean: XREFmovmean, *note
     movmedian: XREFmovmedian, *note movmin: XREFmovmin, *note movprod:
     XREFmovprod, *note movstd: XREFmovstd, *note movsum: XREFmovsum,
     *note movvar: XREFmovvar.

 -- : Y = movmean (X, WLEN)
 -- : Y = movmean (X, [NA, NB])
 -- : Y = movmean (..., DIM)
 -- : Y = movmean (..., "NANCOND")
 -- : Y = movmean (..., PROPERTY, VALUE)
     Calculate the moving average over a sliding window of length WLEN
     on data X.

     If WLEN is a scalar, the function ‘mean’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movmean’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movmean’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘mean’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               mean (X(1:2))’, and ‘Y(end) = mean (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = mean ([NaN, X(1:2)])’, and ‘Y(end) = mean
               ([X(end-1:end), NaN])’.  This option usually results in Y
               having ‘NaN’ values at the boundaries, although it is
               influenced by how ‘mean’ handles ‘NaN’, and also by the
               property "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               mean ([USER_VALUE, X(1:2)])’, and ‘Y(end) = mean
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = mean ([X(1), X(1:2)])’, and
               ‘Y(end) = mean ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = mean ([X(end),
               X(1:2)])’, and ‘Y(end) = mean ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note
     movmedian: XREFmovmedian, *note movmin: XREFmovmin, *note movprod:
     XREFmovprod, *note movstd: XREFmovstd, *note movsum: XREFmovsum,
     *note movvar: XREFmovvar.

 -- : Y = movmedian (X, WLEN)
 -- : Y = movmedian (X, [NA, NB])
 -- : Y = movmedian (..., DIM)
 -- : Y = movmedian (..., "NANCOND")
 -- : Y = movmedian (..., PROPERTY, VALUE)
     Calculate the moving median over a sliding window of length WLEN on
     data X.

     If WLEN is a scalar, the function ‘movmedian’ is applied to a
     moving window of length WLEN.  When WLEN is an odd number the
     window is symmetric and includes ‘(WLEN - 1) / 2’ elements on
     either side of the central element.  For example, when calculating
     the output at index 5 with a window length of 3, ‘movmedian’ uses
     data elements ‘[4, 5, 6]’.  If WLEN is an even number, the window
     is asymmetric and has ‘WLEN/2’ elements to the left of the central
     element and ‘WLEN/2 - 1’ elements to the right of the central
     element.  For example, when calculating the output at index 5 with
     a window length of 4, ‘movmedian’ uses data elements
     ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘movmedian’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               movmedian (X(1:2))’, and ‘Y(end) = movmedian
               (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = movmedian ([NaN, X(1:2)])’, and ‘Y(end) = movmedian
               ([X(end-1:end), NaN])’.  This option usually results in Y
               having ‘NaN’ values at the boundaries, although it is
               influenced by how ‘movmedian’ handles ‘NaN’, and also by
               the property "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               movmedian ([USER_VALUE, X(1:2)])’, and ‘Y(end) =
               movmedian ([X(end-1:end), USER_VALUE])’.  A common choice
               for USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = movmedian ([X(1), X(1:2)])’,
               and ‘Y(end) = movmedian ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = movmedian ([X(end),
               X(1:2)])’, and ‘Y(end) = movmedian ([X(end-1:end),
               X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note movmean:
     XREFmovmean, *note movmin: XREFmovmin, *note movprod: XREFmovprod,
     *note movstd: XREFmovstd, *note movsum: XREFmovsum, *note movvar:
     XREFmovvar.

 -- : Y = movmin (X, WLEN)
 -- : Y = movmin (X, [NA, NB])
 -- : Y = movmin (..., DIM)
 -- : Y = movmin (..., "NANCOND")
 -- : Y = movmin (..., PROPERTY, VALUE)
     Calculate the moving minimum over a sliding window of length WLEN
     on data X.

     If WLEN is a scalar, the function ‘min’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movmin’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movmin’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘min’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               min (X(1:2))’, and ‘Y(end) = min (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = min ([NaN, X(1:2)])’, and ‘Y(end) = min ([X(end-1:end),
               NaN])’.  This option usually results in Y having ‘NaN’
               values at the boundaries, although it is influenced by
               how ‘min’ handles ‘NaN’, and also by the property
               "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               min ([USER_VALUE, X(1:2)])’, and ‘Y(end) = min
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = min ([X(1), X(1:2)])’, and
               ‘Y(end) = min ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = min ([X(end),
               X(1:2)])’, and ‘Y(end) = min ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note movmean:
     XREFmovmean, *note movmedian: XREFmovmedian, *note movprod:
     XREFmovprod, *note movstd: XREFmovstd, *note movsum: XREFmovsum,
     *note movvar: XREFmovvar.

 -- : Y = movprod (X, WLEN)
 -- : Y = movprod (X, [NA, NB])
 -- : Y = movprod (..., DIM)
 -- : Y = movprod (..., "NANCOND")
 -- : Y = movprod (..., PROPERTY, VALUE)
     Calculate the moving product over a sliding window of length WLEN
     on data X.

     If WLEN is a scalar, the function ‘movprod’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movprod’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movprod’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘movprod’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               movprod (X(1:2))’, and ‘Y(end) = movprod (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = movprod ([NaN, X(1:2)])’, and ‘Y(end) = movprod
               ([X(end-1:end), NaN])’.  This option usually results in Y
               having ‘NaN’ values at the boundaries, although it is
               influenced by how ‘movprod’ handles ‘NaN’, and also by
               the property "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               movprod ([USER_VALUE, X(1:2)])’, and ‘Y(end) = movprod
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = movprod ([X(1), X(1:2)])’,
               and ‘Y(end) = movprod ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = movprod ([X(end),
               X(1:2)])’, and ‘Y(end) = movprod ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note movmean:
     XREFmovmean, *note movmedian: XREFmovmedian, *note movmin:
     XREFmovmin, *note movstd: XREFmovstd, *note movsum: XREFmovsum,
     *note movvar: XREFmovvar.

 -- : Y = movstd (X, WLEN)
 -- : Y = movstd (X, [NA, NB])
 -- : Y = movstd (..., DIM)
 -- : Y = movstd (..., "NANCOND")
 -- : Y = movstd (..., PROPERTY, VALUE)
     Calculate the moving standard deviation over a sliding window of
     length WLEN on data X.

     If WLEN is a scalar, the function ‘movstd’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movstd’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movstd’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘movstd’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               movstd (X(1:2))’, and ‘Y(end) = movstd (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = movstd ([NaN, X(1:2)])’, and ‘Y(end) = movstd
               ([X(end-1:end), NaN])’.  This option usually results in Y
               having ‘NaN’ values at the boundaries, although it is
               influenced by how ‘movstd’ handles ‘NaN’, and also by the
               property "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               movstd ([USER_VALUE, X(1:2)])’, and ‘Y(end) = movstd
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = movstd ([X(1), X(1:2)])’, and
               ‘Y(end) = movstd ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = movstd ([X(end),
               X(1:2)])’, and ‘Y(end) = movstd ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note movmean:
     XREFmovmean, *note movmedian: XREFmovmedian, *note movmin:
     XREFmovmin, *note movprod: XREFmovprod, *note movsum: XREFmovsum,
     *note movvar: XREFmovvar.

 -- : Y = movsum (X, WLEN)
 -- : Y = movsum (X, [NA, NB])
 -- : Y = movsum (..., DIM)
 -- : Y = movsum (..., "NANCOND")
 -- : Y = movsum (..., PROPERTY, VALUE)
     Calculate the moving sum over a sliding window of length WLEN on
     data X.

     If WLEN is a scalar, the function ‘movsum’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movsum’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movsum’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘movsum’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               movsum (X(1:2))’, and ‘Y(end) = movsum (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = movsum ([NaN, X(1:2)])’, and ‘Y(end) = movsum
               ([X(end-1:end), NaN])’.  This option usually results in Y
               having ‘NaN’ values at the boundaries, although it is
               influenced by how ‘movsum’ handles ‘NaN’, and also by the
               property "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               movsum ([USER_VALUE, X(1:2)])’, and ‘Y(end) = movsum
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = movsum ([X(1), X(1:2)])’, and
               ‘Y(end) = movsum ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = movsum ([X(end),
               X(1:2)])’, and ‘Y(end) = movsum ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note movmean:
     XREFmovmean, *note movmedian: XREFmovmedian, *note movmin:
     XREFmovmin, *note movprod: XREFmovprod, *note movstd: XREFmovstd,
     *note movvar: XREFmovvar.

 -- : Y = movvar (X, WLEN)
 -- : Y = movvar (X, [NA, NB])
 -- : Y = movvar (..., DIM)
 -- : Y = movvar (..., "NANCOND")
 -- : Y = movvar (..., PROPERTY, VALUE)
     Calculate the moving variance over a sliding window of length WLEN
     on data X.

     If WLEN is a scalar, the function ‘var’ is applied to a moving
     window of length WLEN.  When WLEN is an odd number the window is
     symmetric and includes ‘(WLEN - 1) / 2’ elements on either side of
     the central element.  For example, when calculating the output at
     index 5 with a window length of 3, ‘movvar’ uses data elements
     ‘[4, 5, 6]’.  If WLEN is an even number, the window is asymmetric
     and has ‘WLEN/2’ elements to the left of the central element and
     ‘WLEN/2 - 1’ elements to the right of the central element.  For
     example, when calculating the output at index 5 with a window
     length of 4, ‘movvar’ uses data elements ‘[3, 4, 5, 6]’.

     If WLEN is an array with two elements ‘[NB, NA]’, the function is
     applied to a moving window ‘-NB:NA’.  This window includes NB
     number of elements _before_ the current element and NA number of
     elements _after_ the current element.  The current element is
     always included.  For example, given ‘WLEN = [3, 0]’, the data used
     to calculate index 5 is ‘[2, 3, 4, 5]’.

     If the optional argument DIM is given, operate along this
     dimension.

     The optional string argument "NANCOND" controls whether ‘NaN’ and
     ‘NA’ values should be included ("includenan"), or excluded
     ("omitnan"), from the data passed to ‘var’.  The default is
     "includenan".  Caution: the "omitnan" option is not yet
     implemented.

     The calculation can be controlled by specifying PROPERTY/VALUE
     pairs.  Valid properties are

     "Endpoints"

          This property controls how results are calculated at the
          boundaries (endpoints) of the window.  Possible values are:

          "shrink" (default)
               The window is truncated at the beginning and end of the
               array to exclude elements for which there is no source
               data.  For example, with a window of length 3, ‘Y(1) =
               var (X(1:2))’, and ‘Y(end) = var (X(end-1:end))’.

          "discard"
               Any Y values that use a window extending beyond the
               original data array are deleted.  For example, with a
               10-element data vector and a window of length 3, the
               output will contain only 8 elements.  The first element
               would require calculating the function over indices
               ‘[0, 1, 2]’ and is therefore discarded.  The last element
               would require calculating the function over indices
               ‘[9, 10, 11]’ and is therefore discarded.

          "fill"
               Any window elements outside the data array are replaced
               by ‘NaN’.  For example, with a window of length 3, ‘Y(1)
               = var ([NaN, X(1:2)])’, and ‘Y(end) = var ([X(end-1:end),
               NaN])’.  This option usually results in Y having ‘NaN’
               values at the boundaries, although it is influenced by
               how ‘var’ handles ‘NaN’, and also by the property
               "nancond".

          USER_VALUE
               Any window elements outside the data array are replaced
               by the specified value USER_VALUE which must be a numeric
               scalar.  For example, with a window of length 3, ‘Y(1) =
               var ([USER_VALUE, X(1:2)])’, and ‘Y(end) = var
               ([X(end-1:end), USER_VALUE])’.  A common choice for
               USER_VALUE is 0.

          "same"
               Any window elements outside the data array are replaced
               by the value of X at the boundary.  For example, with a
               window of length 3, ‘Y(1) = var ([X(1), X(1:2)])’, and
               ‘Y(end) = var ([X(end-1:end), X(end)])’.

          "periodic"
               The window is wrapped so that any missing data elements
               are taken from the other side of the data.  For example,
               with a window of length 3, ‘Y(1) = var ([X(end),
               X(1:2)])’, and ‘Y(end) = var ([X(end-1:end), X(1)])’.

     "SamplePoints"
          Caution: This option is not yet implemented.

     Programming Note: This function is a wrapper which calls ‘movfun’.
     For additional options and documentation, *Note movfun: XREFmovfun.

     See also: *note movfun: XREFmovfun, *note movslice: XREFmovslice,
     *note movmad: XREFmovmad, *note movmax: XREFmovmax, *note movmean:
     XREFmovmean, *note movmedian: XREFmovmedian, *note movmin:
     XREFmovmin, *note movprod: XREFmovprod, *note movstd: XREFmovstd,
     *note movsum: XREFmovsum.


File: octave.info,  Node: Basic Statistical Functions,  Next: Correlation and Regression Analysis,  Prev: Statistics on Sliding Windows of Data,  Up: Statistics

26.3 Basic Statistical Functions
================================

Octave supports various helpful statistical functions.  Many are useful
as initial steps to prepare a data set for further analysis.  Others
provide different measures from those of the basic descriptive
statistics.

 -- : center (X)
 -- : center (X, DIM)
     Center data by subtracting its mean.

     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, operate along this
     dimension.

     Programming Note: ‘center’ has obvious application for normalizing
     statistical data.  It is also useful for improving the precision of
     general numerical calculations.  Whenever there is a large value
     that is common to a batch of data, the mean can be subtracted off,
     the calculation performed, and then the mean added back to obtain
     the final answer.

     See also: *note zscore: XREFzscore.

 -- : Z = zscore (X)
 -- : Z = zscore (X, OPT)
 -- : Z = zscore (X, OPT, DIM)
 -- : [Z, MU, SIGMA] = zscore (...)
     Compute the Z score of X.

     If X is a vector, subtract its mean and divide by its standard
     deviation.  If the standard deviation is zero, divide by 1 instead.

     The optional parameter OPT determines the normalization to use when
     computing the standard deviation and has the same definition as the
     corresponding parameter for ‘std’.

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

     The optional outputs MU and SIGMA contain the mean and standard
     deviation.

     See also: *note mean: XREFmean, *note std: XREFstd, *note center:
     XREFcenter.

 -- : N = histc (X, EDGES)
 -- : N = histc (X, EDGES, DIM)
 -- : [N, IDX] = histc (...)
     Compute histogram counts.

     When X is a vector, the function counts the number of elements of X
     that fall in the histogram bins defined by EDGES.  This must be a
     vector of monotonically increasing values that define the edges of
     the histogram bins.  ‘N(k)’ contains the number of elements in X
     for which ‘EDGES(k) <= X < EDGES(k+1)’.  The final element of N
     contains the number of elements of X exactly equal to the last
     element of EDGES.

     When X is an N-dimensional array, the computation is carried out
     along dimension DIM.  If not specified DIM defaults to the first
     non-singleton dimension.

     When a second output argument is requested an index matrix is also
     returned.  The IDX matrix has the same size as X.  Each element of
     IDX contains the index of the histogram bin in which the
     corresponding element of X was counted.

     See also: *note hist: XREFhist.

‘unique’ function documented at *note unique: XREFunique. is often
useful for statistics.

 -- : C = nchoosek (N, K)
 -- : C = nchoosek (SET, K)

     Compute the binomial coefficient of N or list all possible
     combinations of a SET of items.

     If N is a scalar then calculate the binomial coefficient of N and K
     which is defined as

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

     This is the number of combinations of N items taken in groups of
     size K.

     If the first argument is a vector, SET, then generate all
     combinations of the elements of SET, taken K at a time, with one
     row per combination.  The result C has K columns and
     ‘nchoosek (length (SET), K)’ rows.

     For example:

     How many ways can three items be grouped into pairs?

          nchoosek (3, 2)
             ⇒ 3

     What are the possible pairs?

          nchoosek (1:3, 2)
             ⇒  1   2
                 1   3
                 2   3

     Programming Note: When calculating the binomial coefficient
     ‘nchoosek’ works only for non-negative, integer arguments.  Use
     ‘bincoeff’ for non-integer and negative scalar arguments, or for
     computing many binomial coefficients at once with vector inputs for
     N or K.

     See also: *note bincoeff: XREFbincoeff, *note perms: XREFperms.

 -- : perms (V)
     Generate all permutations of vector V with one row per permutation.

     Results are returned in inverse lexicographic order.  The result
     has size ‘factorial (N) * N’, where N is the length of V.  Any
     repetitions are included in the output.  To generate just the
     unique permutations use ‘unique (perms (V), "rows")(end:-1:1,:)’.

     Example

          perms ([1, 2, 3])
          ⇒
            3   2   1
            3   1   2
            2   3   1
            2   1   3
            1   3   2
            1   2   3

     Programming Note: The maximum length of V should be less than or
     equal to 10 to limit memory consumption.

     See also: *note permute: XREFpermute, *note randperm: XREFrandperm,
     *note nchoosek: XREFnchoosek.

 -- : ranks (X)
 -- : ranks (X, DIM)
 -- : ranks (X, DIM, RTYPE)
     Return the ranks (in the sense of order statistics) of X along the
     first non-singleton dimension adjusted for ties.

     If the optional DIM argument is given, operate along this
     dimension.

     The optional parameter RTYPE determines how ties are handled.  All
     examples below assume an input of ‘[ 1, 2, 2, 4 ]’.

     0 or "fractional" (default) for fractional ranking (1, 2.5,
          2.5, 4);

     1 or "competition" for competition ranking (1, 2, 2, 4);

     2 or "modified" for modified competition ranking (1, 3, 3, 4);

     3 or "ordinal" for ordinal ranking (1, 2, 3, 4);

     4 or "dense" for dense ranking (1, 2, 2, 3).

     See also: *note spearman: XREFspearman, *note kendall: XREFkendall.

 -- : run_count (X, N)
 -- : run_count (X, N, DIM)
     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 then operate along this
     dimension.

     See also: *note runlength: XREFrunlength.

 -- : count = runlength (X)
 -- : [count, value] = runlength (X)
     Find the lengths of all sequences of common values.

     COUNT is a vector with the lengths of each repeated value.

     The optional output VALUE contains the value that was repeated in
     the sequence.

          runlength ([2, 2, 0, 4, 4, 4, 0, 1, 1, 1, 1])
          ⇒   2   1   3   1   4

     See also: *note run_count: XREFrun_count.


File: octave.info,  Node: Correlation and Regression Analysis,  Next: Distributions,  Prev: Basic Statistical Functions,  Up: Statistics

26.4 Correlation and Regression Analysis
========================================

 -- : cov (X)
 -- : cov (X, OPT)
 -- : cov (X, Y)
 -- : cov (X, Y, OPT)
     Compute the covariance matrix.

     If each row of X and Y is an observation, and each column is a
     variable, then 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.

          cov (X) = 1/(N-1) * SUM_i (X(i) - mean(X)) * (Y(i) - mean(Y))

     where N is the length of the X and Y vectors.

     If called with one argument, compute ‘cov (X, X)’, the covariance
     between the columns of X.

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

     0:
          normalize with N-1, provides the best unbiased estimator of
          the covariance [default]

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

     Compatibility Note:: Octave always treats rows of X and Y as
     multivariate random variables.  For two inputs, however, MATLAB
     treats X and Y as two univariate distributions regardless of their
     shapes, and will calculate ‘cov ([X(:), Y(:)])’ whenever the number
     of elements in X and Y are equal.  This will result in a 2x2
     matrix.  Code relying on MATLAB’s definition will need to be
     changed when running in Octave.

     See also: *note corr: XREFcorr.

 -- : corr (X)
 -- : corr (X, Y)
     Compute matrix of correlation coefficients.

     If each row of X and Y is an observation and each column is a
     variable, then the (I, J)-th entry of ‘corr (X, Y)’ is the
     correlation between the I-th variable in X and the J-th variable in
     Y.

          corr (X,Y) = cov (X,Y) / (std (X) * std (Y))

     If called with one argument, compute ‘corr (X, X)’, the correlation
     between the columns of X.

     See also: *note cov: XREFcov.

 -- : R = corrcoef (X)
 -- : R = corrcoef (X, Y)
 -- : R = corrcoef (..., PARAM, VALUE, ...)
 -- : [R, P] = corrcoef (...)
 -- : [R, P, LCI, HCI] = corrcoef (...)
     Compute a matrix of correlation coefficients.

     X is an array where each column contains a variable and each row is
     an observation.

     If a second input Y (of the same size as X) is given then calculate
     the correlation coefficients between X and Y.

     PARAM, VALUE are optional pairs of parameters and values which
     modify the calculation.  Valid options are:

     "alpha"
          Confidence level used for the bounds of the confidence
          interval, LCI and HCI.  Default is 0.05, i.e., 95% confidence
          interval.

     "rows"
          Determine processing of NaN values.  Acceptable values are
          "all", "complete", and "pairwise".  Default is "all".  With
          "complete", only the rows without NaN values are considered.
          With "pairwise", the selection of NaN-free rows is made for
          each pair of variables.

     Output R is a matrix of Pearson’s product moment correlation
     coefficients for each pair of variables.

     Output P is a matrix of pair-wise p-values testing for the null
     hypothesis of a correlation coefficient of zero.

     Outputs LCI and HCI are matrices containing, respectively, the
     lower and higher bounds of the 95% confidence interval of each
     correlation coefficient.

     See also: *note corr: XREFcorr, *note cov: XREFcov.

 -- : spearman (X)
 -- : spearman (X, Y)
     Compute Spearman’s rank correlation coefficient RHO.

     For two data vectors X and Y, Spearman’s RHO is the correlation
     coefficient 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)’, where N is the length of the X and
     Y vectors, and is asymptotically normally distributed.

     ‘spearman (X)’ is equivalent to ‘spearman (X, X)’.

     See also: *note ranks: XREFranks, *note kendall: XREFkendall.

 -- : kendall (X)
 -- : kendall (X, Y)
     Compute Kendall’s TAU.

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

     ‘kendall (X)’ is equivalent to ‘kendall (X, X)’.

     See also: *note ranks: XREFranks, *note spearman: XREFspearman.


File: octave.info,  Node: Distributions,  Next: Random Number Generation,  Prev: Correlation and Regression Analysis,  Up: Statistics

26.5 Distributions
==================

Octave has functions for computing the Probability Density Function
(PDF), the Cumulative Distribution function (CDF), and the quantile (the
inverse of the CDF) for arbitrary user-defined distributions (discrete)
and for experimental data (empirical).

   The following table summarizes the supported distributions (in
alphabetical order).

Distribution           PDF               CDF               Quantile
-----------------------------------------------------------------------------
Univariate Discrete    ‘discrete_pdf’    ‘discrete_cdf’    ‘discrete_inv’
Distribution
Empirical              ‘empirical_pdf’   ‘empirical_cdf’   ‘empirical_inv’
Distribution

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

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

 -- : discrete_inv (X, V, P)
     For each element 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.

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

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

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


File: octave.info,  Node: Random Number Generation,  Prev: Distributions,  Up: Statistics

26.6 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
-----------------------------------------------------
Univariate Discrete           ‘discrete_rnd’
Distribution
Empirical Distribution        ‘empirical_rnd’
Exponential Distribution      ‘rande’
Gamma Distribution            ‘randg’
Poisson Distribution          ‘randp’
Standard Normal               ‘randn’
Distribution
Uniform Distribution          ‘rand’
Uniform Distribution          ‘randi’
(integers)

 -- : discrete_rnd (V, P)
 -- : discrete_rnd (V, P, R)
 -- : discrete_rnd (V, P, R, C, ...)
 -- : discrete_rnd (V, P, [SZ])
     Return a matrix of random samples from the univariate distribution
     which assumes the values in V with probabilities P.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is the common
     size of V and P.

 -- : empirical_rnd (DATA)
 -- : empirical_rnd (DATA, R)
 -- : empirical_rnd (DATA, R, C, ...)
 -- : empirical_rnd (DATA, [SZ])
     Return a matrix of random samples from the empirical distribution
     obtained from the univariate sample DATA.

     When called with a single size argument, return a square matrix
     with the dimension specified.  When called with more than one
     scalar argument the first two arguments are taken as the number of
     rows and columns and any further arguments specify additional
     matrix dimensions.  The size may also be specified with a vector of
     dimensions SZ.

     If no size arguments are given then the result matrix is a random
     ordering of the sample DATA.


File: octave.info,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Statistics,  Up: Top

27 Sets
*******

Octave has a number of functions for managing sets of data.  A set is
defined as a collection of unique elements and is typically represented
by a vector of numbers sorted in ascending order.  Any vector or matrix
can be converted to a set by removing duplicates through the use of the
‘unique’ function.  However, it isn’t necessary to explicitly create a
set as all of the functions which operate on sets will convert their
input to a set before proceeding.

 -- : unique (X)
 -- : unique (X, "rows")
 -- : [Y, I, J] = unique (...)
 -- : [Y, I, J] = unique (..., "first")
 -- : [Y, I, J] = unique (..., "last")
     Return the unique elements of X sorted in ascending order.

     If the input X is a column vector then return a column vector;
     Otherwise, return a row vector.  X may also be a cell array of
     strings.

     If the optional argument "rows" is given then return the unique
     rows of X sorted in ascending order.  The input must be a 2-D
     matrix to use this option.

     If requested, return index vectors I and J such that ‘Y = X(I)’ and
     ‘X = Y(J)’.

     Additionally, if I is a requested output then one of "first" or
     "last" may be given as an input.  If "last" is specified, return
     the highest possible indices in I, otherwise, if "first" is
     specified, return the lowest.  The default is "last".

     See also: *note union: XREFunion, *note intersect: XREFintersect,
     *note setdiff: XREFsetdiff, *note setxor: XREFsetxor, *note
     ismember: XREFismember.

* Menu:

* Set Operations::


File: octave.info,  Node: Set Operations,  Up: Sets

27.1 Set Operations
===================

Octave supports several basic set operations.  Octave can compute the
union, intersection, and difference of two sets.  Octave also supports
the _Exclusive Or_ set operation.

   The functions for set operations all work in the same way by
accepting two input sets and returning a third set.  As an example,
assume that ‘a’ and ‘b’ contains two sets, then

     union (a, b)

computes the union of the two sets.

   Finally, determining whether elements belong to a set can be done
with the ‘ismember’ function.  Because sets are ordered this operation
is very efficient and is of order O(log2(n)) which is preferable to the
‘find’ function which is of order O(n).

 -- : C = intersect (A, B)
 -- : C = intersect (A, B, "rows")
 -- : [C, IA, IB] = intersect (...)

     Return the unique elements common to both A and B sorted in
     ascending order.

     If A and B are both row vectors then return a row vector;
     Otherwise, return a column vector.  The inputs may also be cell
     arrays of strings.

     If the optional input "rows" is given then return the common rows
     of A and B.  The inputs must be 2-D matrices to use this option.

     If requested, return index vectors IA and IB such that ‘C = A(IA)’
     and ‘C = B(IB)’.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     setdiff: XREFsetdiff, *note setxor: XREFsetxor, *note ismember:
     XREFismember.

 -- : C = union (A, B)
 -- : C = union (A, B, "rows")
 -- : [C, IA, IB] = union (...)

     Return the unique elements that are in either A or B sorted in
     ascending order.

     If A and B are both row vectors then return a row vector;
     Otherwise, return a column vector.  The inputs may also be cell
     arrays of strings.

     If the optional input "rows" is given then return rows that are in
     either A or B.  The inputs must be 2-D matrices to use this option.

     The optional outputs IA and IB are index vectors such that ‘A(IA)’
     and ‘B(IB)’ are disjoint sets whose union is C.

     See also: *note unique: XREFunique, *note intersect: XREFintersect,
     *note setdiff: XREFsetdiff, *note setxor: XREFsetxor, *note
     ismember: XREFismember.

 -- : C = setdiff (A, B)
 -- : C = setdiff (A, B, "rows")
 -- : [C, IA] = setdiff (...)
     Return the unique elements in A that are not in B sorted in
     ascending order.

     If A is a row vector return a row vector; Otherwise, return a
     column vector.  The inputs may also be cell arrays of strings.

     If the optional input "rows" is given then return the rows in A
     that are not in B.  The inputs must be 2-D matrices to use this
     option.

     If requested, return the index vector IA such that ‘C = A(IA)’.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     intersect: XREFintersect, *note setxor: XREFsetxor, *note ismember:
     XREFismember.

 -- : C = setxor (A, B)
 -- : C = setxor (A, B, "rows")
 -- : [C, IA, IB] = setxor (...)

     Return the unique elements exclusive to sets A or B sorted in
     ascending order.

     If A and B are both row vectors then return a row vector;
     Otherwise, return a column vector.  The inputs may also be cell
     arrays of strings.

     If the optional input "rows" is given then return the rows
     exclusive to sets A and B.  The inputs must be 2-D matrices to use
     this option.

     If requested, return index vectors IA and IB such that ‘A(IA)’ and
     ‘B(IB)’ are disjoint sets whose union is C.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     intersect: XREFintersect, *note setdiff: XREFsetdiff, *note
     ismember: XREFismember.

 -- : TF = ismember (A, S)
 -- : TF = ismember (A, S, "rows")
 -- : [TF, S_IDX] = ismember (...)

     Return a logical matrix TF with the same shape as A which is true
     (1) if the element in A is found in S and false (0) if it is not.

     If a second output argument is requested then the index into S of
     each matching element is also returned.

          a = [3, 10, 1];
          s = [0:9];
          [tf, s_idx] = ismember (a, s)
               ⇒ tf = [1, 0, 1]
               ⇒ s_idx = [4, 0, 2]

     The inputs A and S may also be cell arrays.

          a = {"abc"};
          s = {"abc", "def"};
          [tf, s_idx] = ismember (a, s)
               ⇒ tf = 1
               ⇒ s_idx = 1

     If the optional third argument "rows" is given then compare rows in
     A with rows in S.  The inputs must be 2-D matrices with the same
     number of columns to use this option.

          a = [1:3; 5:7; 4:6];
          s = [0:2; 1:3; 2:4; 3:5; 4:6];
          [tf, s_idx] = ismember (a, s, "rows")
               ⇒ tf = logical ([1; 0; 1])
               ⇒ s_idx = [2; 0; 5];

     See also: *note lookup: XREFlookup, *note unique: XREFunique, *note
     union: XREFunion, *note intersect: XREFintersect, *note setdiff:
     XREFsetdiff, *note setxor: XREFsetxor.

 -- : powerset (A)
 -- : powerset (A, "rows")
     Compute the powerset (all subsets) of the set A.

     The set A must be a numerical matrix or a cell array of strings.
     The output will always be a cell array of either vectors or
     strings.

     With the optional argument "rows", each row of the set A is
     considered one element of the set.  The input must be a 2-D numeric
     matrix to use this argument.

     See also: *note unique: XREFunique, *note union: XREFunion, *note
     intersect: XREFintersect, *note setdiff: XREFsetdiff, *note setxor:
     XREFsetxor, *note ismember: XREFismember.

