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

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

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

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.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

using Petzold's DAE solver DASPK.

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

          0 = f (x, xdot, t)

     with

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

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

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

          RES = f (X, XDOT, T)

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

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

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

     The modified Jacobian function must have the form


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

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

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

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

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

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

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

     *See also:* dassl.

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

     Options include

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

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

          The local error test applied at each integration step is

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

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

            1. Given Y_d, calculate Y_a and Y'_d

            2. Given Y', calculate Y.

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

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

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

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

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

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

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

               Note that the maximum number of Newton iterations
               allowed in all 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 occaisionally suffer from
          severe scaling difficulties on the first step.  If you know a
          great deal about the scaling of your problem, you can help to
          alleviate this problem by specifying an initial stepsize
          (default is computed automatically).

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

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

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

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

          0 = f (x, xdot, t)

     with

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

     with functional stopping criteria (root solving).

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

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

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

          RES = f (X, XDOT, T)

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

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

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

     The modified Jacobian function must have the form


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

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

          G_OUT = g (X, T)

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

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

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

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

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

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

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

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

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

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

     *See also:* daspk, dasrt, lsode.

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

     Options include

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

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

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

    `"initial step size"'
          Differential-algebraic problems may occaisionally 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
***************

* 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
=======================

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

          min C'*x

     subject to

          A*x  = b
            x >= 0

     but may also solve problems of the form

          [ min | max ] C'*x

     subject to

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

     Input arguments:

    C
          A column array containing the objective function coefficients.

    A
          A matrix containing the constraints coefficients.

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

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

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

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

         `"U"'
               Variable with upper bound (`A(i,:)*x <= b(i)').

         `"S"'
               Fixed Variable (`A(i,:)*x = b(i)').

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

         `"D"'
               Double-bounded variable (`A(i,:)*x >= -b(i)' _and_
               (`A(i,:)*x <= b(i)').

    VARTYPE
          A column array containing the types of the variables.
         `"F"'
               "C" Continuous variable.  "I" Integer variable

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

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

          Integer parameters:

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

              1
                    Error messages only.

              2
                    Normal output .

              3
                    Full output (includes informational messages).

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

              1
                    Equilibration scaling .

              2
                    Geometric mean scaling, then equilibration scaling.

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

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

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

              1
                    Steepest edge pricing.

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

              1
                    Replace tiny primal and dual values by exact zero.

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

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

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

              1
                    Branch on the last variable.

              2
                    Branch using a heuristic by Driebeck and Tomlin.

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

              1
                    Breadth first search.

              2
                    Backtrack using the best projection heuristic.

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

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

              2
                    Interior point method.

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

          Real parameters:

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

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

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

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

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

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

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

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

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

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

     Output values:

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

    FOPT
          The optimum value of the objective function.

    STATUS
          Status of the optimization.

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

         181 (`LPX_FEAS')
               Solution is feasible.

         182 (`LPX_INFEAS')
               Solution is infeasible.

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

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

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

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

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

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

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

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

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

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

         207 (`LPX_E_ITLIM')
               Iterations limit exhausted.

         208 (`LPX_E_TMLIM')
               Time limit exhausted.

         209 (`LPX_E_NOFEAS')
               No feasible solution.

         210 (`LPX_E_INSTAB')
               Numerical instability.

         211 (`LPX_E_SING')
               Problems with basis matrix.

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

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

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

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

         `redcosts'
               Reduced Costs.

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

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

     Example:

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

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

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


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

25.2 Quadratic Programming
==========================

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

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

     subject to

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

     using a null-space active-set method.

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

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

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

         1
               The problem is not convex.  Local solution found.

         2
               The problem is not convex and unbounded.

         3
               Maximum number of iterations reached.

         6
               The problem is infeasible.


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

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

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

               min phi (x)
                x

     subject to

               g(x)  = 0
               h(x) >= 0

     using a successive quadratic programming method.

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

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

               y = phi (x)

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

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

     If supplied, the gradient function must be of the form

               g = gradient (x)

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

     If supplied, the hessian function must be of the form

               h = hessian (x)

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

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

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

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

               r = f (x)

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

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

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

     Here is an example of calling `sqp':

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

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

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

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

               x =

                 -1.71714
                  1.59571
                  1.82725
                 -0.76364
                 -0.76364

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

                 -0.0401627
                  0.0379578
                 -0.0052227

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

    102
          The BFGS update failed.

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


     *See also:* qp.


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

25.4 Linear Least Squares
=========================

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

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

    BETA
          The GLS estimator for b.

    V
          The GLS estimator for s^2.

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

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

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

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

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

    SIGMA
          The OLS estimator for the matrix S,

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

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


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

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

* Menu:

* Basic Statistical Functions::
* Tests::
* Models::
* Distributions::


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

26.1 Basic Statistical Functions
================================

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

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

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

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

    `"g"'
          Computer the geometric mean.

    `"h"'
          Compute the harmonic mean.

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

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

 -- Function File:  median (X)
     If X is a vector, compute the median value of the elements of X.

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

     *See also:* std, mean.

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

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

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

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

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

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

     *See also:* mean, median.

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

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

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

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

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

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

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

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

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

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

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

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


     *See also:* bincoeff.

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


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

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

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

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

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

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

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

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

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

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

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

     If X is a vector, treat it as a column vector.

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

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

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

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

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

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

 -- Function File:  ranks (X, DIM)
     If X is a vector, return the (column) vector of ranks of X
     adjusted for ties.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          moment (x, 3, "ac")

     computes the third central absolute moment of X.

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

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

 -- Function File:  logit (P)
     For each component of P, return the logit `log (P / (1-P))' of P.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          - log (- log (X))

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


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

26.2 Tests
==========

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     The output is a structure with the following elements:

    PVAL
          The p-value of the test.

    STAT
          The value of the test statistic.

    DIST
          The distribution of the test statistic.

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

    ALTERNATIVE
          The alternative hypothesis.

    METHOD
          The method used for testing.

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

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

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

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

     If not given explicitly, R = 0.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

26.3 Models
===========

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

     Suppose Y takes values in K ordered categories, and let `gamma_i
     (X)' be the cumulative probability that Y falls in one of the
     first I categories given the covariate X.  Then

          [theta, beta] = logistic_regression (y, x)

     fits the model

          logit (gamma_i (x)) = theta_i - beta' * x,   i = 1, ..., k-1

     The number of ordinal categories, K, is taken to be the number of
     distinct values of `round (Y)'.  If K equals 2, Y is binary and
     the model is ordinary logistic regression.  The matrix X is
     assumed to have full column rank.

     Given Y only, `theta = logistic_regression (y)' fits the model
     with baseline logit odds only.

     The full form is

          [theta, beta, dev, dl, d2l, gamma]
             = logistic_regression (y, x, print, theta, beta)

     in which all output arguments and all input arguments except Y are
     optional.

     Stting PRINT to 1 requests summary information about the fitted
     model to be displayed.  Setting PRINT to 2 requests information
     about convergence at each iteration.  Other values request no
     information to be displayed.  The input arguments THETA and BETA
     give initial estimates for THETA and BETA.

     The returned value DEV holds minus twice the log-likelihood.

     The returned values DL and D2L are the vector of first and the
     matrix of second derivatives of the log-likelihood with respect to
     THETA and BETA.

     P holds estimates for the conditional distribution of Y given X.


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

26.4 Distributions
==================

 -- Function File:  betacdf (X, A, B)
     For each element of X, returns the CDF at X of the beta
     distribution with parameters A and B, i.e., PROB (beta (A, B) <=
     X).

 -- Function File:  betainv (X, A, B)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Beta distribution with parameters A and B.

 -- Function File:  betapdf (X, A, B)
     For each element of X, returns the PDF at X of the beta
     distribution with parameters A and B.

 -- Function File:  betarnd (A, B, R, C)
 -- Function File:  betarnd (A, B, SZ)
     Return an R by C or `size (SZ)' matrix of random samples from the
     Beta distribution with parameters A and B.  Both A and B must be
     scalar or of size R  by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  binocdf (X, N, P)
     For each element of X, compute the CDF at X of the binomial
     distribution with parameters N and P.

 -- Function File:  binoinv (X, N, P)
     For each element of X, compute the quantile at X of the binomial
     distribution with parameters N and P.

 -- Function File:  binopdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the binomial distribution with parameters N and P.

 -- Function File:  binornd (N, P, R, C)
 -- Function File:  binornd (N, P, SZ)
     Return an R by C  or a `size (SZ)' matrix of random samples from
     the binomial distribution with parameters N and P.  Both N and P
     must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of N and P.

 -- Function File:  cauchy_cdf (X, LAMBDA, SIGMA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Cauchy distribution with location
     parameter LAMBDA and scale parameter SIGMA.  Default values are
     LAMBDA = 0, SIGMA = 1.

 -- Function File:  cauchy_inv (X, LAMBDA, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Cauchy distribution with location parameter
     LAMBDA and scale parameter SIGMA.  Default values are LAMBDA = 0,
     SIGMA = 1.

 -- Function File:  cauchy_pdf (X, LAMBDA, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the Cauchy distribution with location parameter
     LAMBDA and scale parameter SIGMA > 0.  Default values are LAMBDA =
     0, SIGMA = 1.

 -- Function File:  cauchy_rnd (LAMBDA, SIGMA, R, C)
 -- Function File:  cauchy_rnd (LAMBDA, SIGMA, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the Cauchy distribution with parameters LAMBDA and SIGMA which
     must both be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of LAMBDA and SIGMA.

 -- Function File:  chi2cdf (X, N)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the chisquare distribution with N degrees
     of freedom.

 -- Function File:  chi2inv (X, N)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the chisquare distribution with N degrees of freedom.

 -- Function File:  chisquare_pdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the chisquare distribution with N degrees of freedom.

 -- Function File:  chi2rnd (N, R, C)
 -- Function File:  chi2rnd (N, SZ)
     Return an R by C  or a `size (SZ)' matrix of random samples from
     the chisquare distribution with N degrees of freedom.  N must be a
     scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the size
     of N.

 -- Function File:  discrete_cdf (X, V, P)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of a univariate discrete distribution which
     assumes the values in V with probabilities P.

 -- Function File:  discrete_inv (X, V, P)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the univariate distribution which assumes the values
     in V with probabilities P.

 -- Function File:  discrete_pdf (X, V, P)
     For each element of X, compute the probability density function
     (pDF) at X of a univariate discrete distribution which assumes the
     values in V with probabilities P.

 -- Function File:  discrete_rnd (N, V, P)
 -- Function File:  discrete_rnd (V, P, R, C)
 -- Function File:  discrete_rnd (V, P, SZ)
     Generate a row vector containing a random sample of size N from
     the univariate distribution which assumes the values in V with
     probabilities P. N must be a scalar.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  empirical_cdf (X, DATA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the empirical distribution obtained from
     the univariate sample DATA.

 -- Function File:  empirical_inv (X, DATA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File:  empirical_pdf (X, DATA)
     For each element of X, compute the probability density function
     (PDF) at X of the empirical distribution obtained from the
     univariate sample DATA.

 -- Function File:  empirical_rnd (N, DATA)
 -- Function File:  empirical_rnd (DATA, R, C)
 -- Function File:  empirical_rnd (DATA, SZ)
     Generate a bootstrap sample of size N from the empirical
     distribution obtained from the univariate sample DATA.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  expcdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the exponential distribution with parameter
     LAMBDA.

     The arguments can be of common size or scalar.

 -- Function File:  expinv (X, LAMBDA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the exponential distribution with parameter LAMBDA.

 -- Function File:  exppdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) of the exponential distribution with parameter LAMBDA.

 -- Function File:  exprnd (LAMBDA, R, C)
 -- Function File:  exprnd (LAMBDA, SZ)
     Return an R by C matrix of random samples from the exponential
     distribution with parameter LAMBDA, which must be a scalar or of
     size R by C. Or if SZ is a vector, create a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the size
     of LAMBDA.

 -- Function File:  fcdf (X, M, N)
     For each element of X, compute the CDF at X of the F distribution
     with M and N degrees of freedom, i.e., PROB (F (M, N) <= X).

 -- Function File:  finv (X, M, N)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the F distribution with parameters M and N.

 -- Function File:  fpdf (X, M, N)
     For each element of X, compute the probability density function
     (PDF) at X of the F distribution with M and N degrees of freedom.

 -- Function File:  frnd (M, N, R, C)
 -- Function File:  frnd (M, N, SZ)
     Return an R by C matrix of random samples from the F distribution
     with M and N degrees of freedom.  Both M and N must be scalar or
     of size R by C.  If SZ is a vector the random samples are in a
     matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of M and N.

 -- Function File:  gamcdf (X, A, B)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Gamma distribution with parameters A
     and B.

     *See also:* gamma, gammaln, gammainc, gampdf, gaminv, gamrnd.

 -- Function File:  gaminv (X, A, B)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Gamma distribution with parameters A and B.

     *See also:* gamma, gammaln, gammainc, gampdf, gamcdf, gamrnd.

 -- Function File:  gampdf (X, A, B)
     For each element of X, return the probability density function
     (PDF) at X of the Gamma distribution with parameters A and B.

     *See also:* gamma, gammaln, gammainc, gamcdf, gaminv, gamrnd.

 -- Function File:  gamrnd (A, B, R, C)
 -- Function File:  gamrnd (A, B, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the Gamma distribution with parameters A and B.  Both A and B must
     be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

     *See also:* gamma, gammaln, gammainc, gampdf, gamcdf, gaminv.

 -- Function File:  geocdf (X, P)
     For each element of X, compute the CDF at X of the geometric
     distribution with parameter P.

 -- Function File:  geoinv (X, P)
     For each element of X, compute the quantile at X of the geometric
     distribution with parameter P.

 -- Function File:  geopdf (X, P)
     For each element of X, compute the probability density function
     (PDF) at X of the geometric distribution with parameter P.

 -- Function File:  geornd (P, R, C)
 -- Function File:  geornd (P, SZ)
     Return an R by C matrix of random samples from the geometric
     distribution with parameter P, which must be a scalar or of size R
     by C.

     If R and C are given create a matrix with R rows and C columns. Or
     if SZ is a vector, create a matrix of size SZ.

 -- Function File:  hygecdf (X, M, T, N)
     Compute the cumulative distribution function (CDF) at X of the
     hypergeometric distribution with parameters M, T, and N.  This is
     the probability of obtaining not more than X marked items when
     randomly drawing a sample of size N without replacement from a
     population of total size T containing M marked items.

     The parameters M, T, and N must positive integers with M and N not
     greater than T.

 -- Function File:  hygeinv (X, M, T, N)
     For each element of X, compute the quantile at X of the
     hypergeometric distribution with parameters M, T, and N.

     The parameters M, T, and N must positive integers with M and N not
     greater than T.

 -- Function File:  hygepdf (X, M, T, N)
     Compute the probability density function (PDF) at X of the
     hypergeometric distribution with parameters M, T, and N. This is
     the probability of obtaining X marked items when randomly drawing
     a sample of size N without replacement from a population of total
     size T containing M marked items.

     The arguments must be of common size or scalar.

 -- Function File:  hygernd (M, T, N, R, C)
 -- Function File:  hygernd (M, T, N, SZ)
     Return an R by C matrix of random samples from the hypergeometric
     distribution with parameters M, T, and N.

     The parameters M, T, and N must positive integers with M and N not
     greater than T.

 -- Function File:  kolmogorov_smirnov_cdf (X, TOL)
     Return the CDF at X of the Kolmogorov-Smirnov distribution,
                   Inf
          Q(x) =   SUM    (-1)^k exp(-2 k^2 x^2)
                 k = -Inf

     for X > 0.

     The optional parameter TOL specifies the precision up to which the
     series should be evaluated;  the default is TOL = `eps'.

 -- Function File:  laplace_cdf (X)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Laplace distribution.

 -- Function File:  laplace_inv (X)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the Laplace distribution.

 -- Function File:  laplace_pdf (X)
     For each element of X, compute the probability density function
     (PDF) at X of the Laplace distribution.

 -- Function File:  laplace_rnd (R, C)
 -- Function File:  laplace_rnd (SZ);
     Return an R by C matrix of random numbers from the Laplace
     distribution.  Or if SZ is a vector, create a matrix of SZ.

 -- Function File:  logistic_cdf (X)
     For each component of X, compute the CDF at X of the logistic
     distribution.

 -- Function File:  logistic_inv (X)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the logistic distribution.

 -- Function File:  logistic_pdf (X)
     For each component of X, compute the PDF at X of the logistic
     distribution.

 -- Function File:  logistic_rnd (R, C)
 -- Function File:  logistic_rnd (SZ)
     Return an R by C matrix of random numbers from the logistic
     distribution. Or if SZ is a vector, create a matrix of SZ.

 -- Function File:  logncdf (X, MU, SIGMA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the lognormal distribution with parameters
     MU and SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean MU and standard
     deviation SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File:  logninv (X, MU, SIGMA)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean `log (MU)' and
     variance SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File:  lognpdf (X, MU, SIGMA)
     For each element of X, compute the probability density function
     (PDF) at X of the lognormal distribution with parameters MU and
     SIGMA.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean MU and standard
     deviation SIGMA.

     Default values are MU = 1, SIGMA = 1.

 -- Function File:  lognrnd (MU, SIGMA, R, C)
 -- Function File:  lognrnd (MU, SIGMA, SZ)
     Return an R by C matrix of random samples from the lognormal
     distribution with parameters MU and SIGMA. Both MU and SIGMA must
     be scalar or of size R by C.  Or if SZ is a vector, create a
     matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of MU and SIGMA.

 -- Function File:  nbincdf (X, N, P)
     For each element of X, compute the CDF at x of the Pascal
     (negative binomial) distribution with parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  nbininv (X, N, P)
     For each element of X, compute the quantile at X of the Pascal
     (negative binomial) distribution with parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  nbinpdf (X, N, P)
     For each element of X, compute the probability density function
     (PDF) at X of the Pascal (negative binomial) distribution with
     parameters N and P.

     The number of failures in a Bernoulli experiment with success
     probability P before the N-th success follows this distribution.

 -- Function File:  nbinrnd (N, P, R, C)
 -- Function File:  nbinrnd (N, P, SZ)
     Return an R by C matrix of random samples from the Pascal
     (negative binomial) distribution with parameters N and P.  Both N
     and P must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of N and P. Or if SZ is a vector, create a matrix of
     size SZ.

 -- Function File:  normcdf (X, M, S)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the normal distribution with mean M and
     standard deviation S.

     Default values are M = 0, S = 1.

 -- Function File:  norminv (X, M, S)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the normal distribution with mean M and standard
     deviation S.

     Default values are M = 0, S = 1.

 -- Function File:  normpdf (X, M, S)
     For each element of X, compute the probability density function
     (PDF) at X of the normal distribution with mean M and standard
     deviation S.

     Default values are M = 0, S = 1.

 -- Function File:  normrnd (M, S, R, C)
 -- Function File:  normrnd (M, S, SZ)
     Return an R by C  or `size (SZ)' matrix of random samples from the
     normal distribution with parameters mean M and standard deviation
     S.  Both M and S must be scalar or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of M and S.

 -- Function File:  poisscdf (X, LAMBDA)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the Poisson distribution with parameter
     lambda.

 -- Function File:  poissinv (X, LAMBDA)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the Poisson distribution with parameter LAMBDA.

 -- Function File:  poisspdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) at X of the poisson distribution with parameter LAMBDA.

 -- Function File:  poissrnd (LAMBDA, R, C)
     Return an R by C matrix of random samples from the Poisson
     distribution with parameter LAMBDA, which must be a scalar or of
     size R by C.

     If R and C are omitted, the size of the result matrix is the size
     of LAMBDA.

 -- Function File:  tcdf (X, N)
     For each element of X, compute the CDF at X of the t (Student)
     distribution with N degrees of freedom, i.e., PROB (t(N) <= X).

 -- Function File:  tinv (X, N)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the t (Student) distribution with parameter N.

 -- Function File:  tpdf (X, N)
     For each element of X, compute the probability density function
     (PDF) at X of the T (Student) distribution with N degrees of
     freedom.

 -- Function File:  trnd (N, R, C)
 -- Function File:  trnd (N, SZ)
     Return an R by C matrix of random samples from the t (Student)
     distribution with N degrees of freedom.  N must be a scalar or of
     size R by C. Or if SZ is a vector create a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the size
     of N.

 -- Function File:  unidcdf (X, V)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of a univariate discrete distribution which
     assumes the values in V with equal probability.

 -- Function File:  unidinv (X, V)
     For each component of X, compute the quantile (the inverse of the
     CDF) at X of the univariate distribution which assumes the values
     in V with equal probability

 -- Function File:  unidpdf (X, V)
     For each element of X, compute the probability density function
     (pDF) at X of a univariate discrete distribution which assumes the
     values in V with equal probability.

 -- Function File:  unidrnd (MX);
 -- Function File:  unidrnd (MX, V);
 -- Function File:  unidrnd (MX, M, N, ...);
     Return random values from discrete uniform distribution, with
     maximum value(s) given by the integer MX, which may be a scalar or
     multidimensional array.

     If MX is a scalar, the size of the result is specified by the
     vector V, or by the optional arguments M, N, ....  Otherwise, the
     size of the result is the same as the size of MX.

 -- Function File:  unifcdf (X, A, B)
     Return the CDF at X of the uniform distribution on [A, B], i.e.,
     PROB (uniform (A, B) <= x).

     Default values are A = 0, B = 1.

 -- Function File:  unifinv (X, A, B)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the uniform distribution on [A, B].

     Default values are A = 0, B = 1.

 -- Function File:  unifpdf (X, A, B)
     For each element of X, compute the PDF at X of the uniform
     distribution on [A, B].

     Default values are A = 0, B = 1.

 -- Function File:  unifrnd (A, B, R, C)
 -- Function File:  unifrnd (A, B, SZ)
     Return an R by C or a `size (SZ)' matrix of random samples from
     the uniform distribution on [A, B].  Both A and B must be scalar
     or of size R by C.

     If R and C are omitted, the size of the result matrix is the
     common size of A and B.

 -- Function File:  wblcdf (X, SCALE, SHAPE)
     Compute the cumulative distribution function (CDF) at X of the
     Weibull distribution with shape parameter SCALE and scale
     parameter SHAPE, which is

          1 - exp(-(x/shape)^scale)

     for X >= 0.

 -- Function File:  wblinv (X, SCALE, SHAPE)
     Compute the quantile (the inverse of the CDF) at X of the Weibull
     distribution with shape parameter SCALE and scale parameter SHAPE.

 -- Function File:  wblpdf (X, SCALE, SHAPE)
     Compute the probability density function (PDF) at X of the Weibull
     distribution with shape parameter SCALE and scale parameter SHAPE
     which is given by

             scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)

     for X > 0.

 -- Function File:  wblrnd (SCALE, SHAPE, R, C)
 -- Function File:  wblrnd (SCALE, SHAPE, SZ)
     Return an R by C matrix of random samples from the Weibull
     distribution with parameters SCALE and SHAPE which must be scalar
     or of size R by C. Or if SZ is a vector return a matrix of size SZ.

     If R and C are omitted, the size of the result matrix is the
     common size of ALPHA and SIGMA.

 -- Function File:  wienrnd (T, D, N)
     Return a simulated realization of the D-dimensional Wiener Process
     on the interval [0, T].  If D is omitted, D = 1 is used. The first
     column of the return matrix contains time, the remaining columns
     contain the Wiener process.

     The optional parameter N gives the number of summands used for
     simulating the process over an interval of length 1.  If N is
     omitted, N = 1000 is used.


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

27 Financial Functions
**********************

 -- Function File:  fv (R, N, P, L, METHOD)
     Return the future value at the end of period N of an investment
     which consists of N payments of P in each period, assuming an
     interest rate R.

     The optional argument L may be used to specify an additional
     lump-sum payment.

     The optional argument METHOD may be used ot specify whether the
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  fvl (R, N, L)
     Return the future value at the end of N periods of an initial lump
     sum investment L, given a per-period interest rate R.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  irr (P, I)
     Return the internal rate of return of a series of payments P from
     an initial investment I (i.e., the solution of `npv (r, p) = i'.
     If the second argument is omitted, a value of 0 is used.

     *See also:* npv, pv, rate.

 -- Function File:  nper (R, P, A, L, METHOD)
     Return the number of regular payments of P necessary to amortize A
     loan of amount A and interest R.

     The optional argument L may be used to specify an additional
     lump-sum payment of L made at the end of the amortization time.

     The optional argument METHOD may be used to specify whether
     payments are made at the end ("E", default) or at the beginning
     ("B") of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

     *See also:* pv, pmt, rate, npv.

 -- Function File:  npv (R, P, I)
     Returns the net present value of a series of irregular (i.e., not
     necessarily identical) payments P which occur at the ends of N
     consecutive periods.  R specifies the one-period interest rates and
     can either be a scalar (constant rates) or a vector of the same
     length as P.

     The optional argument I may be used to specify an initial
     investment.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

     *See also:* irr, pv.

 -- Function File:  pmt (R, N, A, L, METHOD)
     Return the amount of periodic payment necessary to amortize a loan
     of amount a with interest rate R in N periods.

     The optional argument L may be used to specify a terminal lump-sum
     payment.

     The optional argument METHOD may be used to specify whether
     payments are made at the end ("E", default) or at the beginning
     ("B") of each period.

     *See also:* pv, nper, rate.

 -- Function File:  pv (R, N, P, L, METHOD)
     Returns the present value of an investment that will pay off P for
     N consecutive periods, assuming an interest R.

     The optional argument L may be used to specify an additional
     lump-sum payment made at the end of N periods.

     The optional argument METHOD may be used to specify whether
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

     *See also:* pmt, nper, rate, npv.

 -- Function File:  pvl (R, N, P)
     Return the present value of an investment that will pay off P in
     one lump sum at the end of N periods, given the interest rate R.

     Note that the rate R is specified as a fraction (i.e., 0.05, not 5
     percent).

 -- Function File:  rate (N, P, V, L, METHOD)
     Return the rate of return on an investment of present value V which
     pays P in N consecutive periods.

     The optional argument L may be used to specify an additional
     lump-sum payment made at the end of N periods.

     The optional string argument METHOD may be used to specify whether
     payments are made at the end (`"e"', default) or at the beginning
     (`"b"') of each period.

     *See also:* pv, pmt, nper, npv.

 -- Function File:  vol (X, M, N)
     Return the volatility of each column of the input matrix X.  The
     number of data sets per period is given by M (e.g. the number of
     data per year if you want to compute the volatility per year).
     The optional parameter N gives the number of past periods used for
     computation, if it is omitted, a value of 1 is used.  If T is the
     number of rows of X, `vol' returns the volatility from `n*m' to T.


File: octave.info,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Financial Functions,  Up: Top

28 Sets
*******

Octave has a limited set of functions for managing sets of data, where a
set is defined as a collection unique elements.

 -- Function File:  create_set (X)
     Return a row vector containing the unique values in X, sorted in
     ascending order.  For example,

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


     *See also:* union, intersection, complement.

 -- Function File:  ismember (A, S)
     Return a matrix the same shape as A which has 1 if `A(i,j)' is in
     S or 0 if it isn't.

     *See also:* unique, union, intersection, setxor, setdiff.

 -- Function File:  unique (X)
     Return the unique elements of X, sorted in ascending order.  If X
     is a row vector, return a row vector, but if X is a column vector
     or a matrix return a column vector.

 -- Function File:  unique (A, 'rows')
     Return the unique rows of A, sorted in ascending order.

 -- Function File: [Y, I, J] =  unique (X)
     Return index vectors I and J such that `x(i)==y' and `y(j)==x'.

     *See also:* union, intersect, setdiff, setxor, ismember.

 -- Function File:  union (X, Y)
     Return the set of elements that are in either of the sets X and Y.
     For example,

          union ([ 1, 2, 4 ], [ 2, 3, 5 ])
          => [ 1, 2, 3, 4, 5 ]


     *See also:* create_set, intersection, complement.

 -- Function File:  intersect (A, B)
 -- Function File: [C, IA, IB] = intersect (A, B)
     Return the elements in both A and B, sorted in ascending order. If
     A and B are both column vectors return a column vector, otherwise
     return a row vector.

     Return index vectors IA and IB such that `a(ia)==c' and `b(ib)==c'.



*See also:* unique, union, setxor, setdiff, ismember.

 -- Function File:  complement (X, Y)
     Return the elements of set Y that are not in set X.  For example,

          complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
          => 5


     *See also:* create_set, union, intersection.

 -- Function File:  setdiff (A, B)
 -- Function File:  setdiff (A, B, "rows")
     Return the elements in A that are not in B, sorted in ascending
     order.  If A and B are both column vectors return a column vector,
     otherwise return a row vector.

     Given the optional third argument `"rows"', return the rows in A
     that are not in B, sorted in ascending order by rows.

     *See also:* unique, union, intersect, setxor, ismember.

 -- Function File:  setxor (A, B)
     Return the elements exclusive to A or B, sorted in ascending
     order. If A and B are both column vectors return a column vector,
     otherwise return a row vector.


     *See also:* unique, union, intersect, setdiff, ismember.


File: octave.info,  Node: Polynomial Manipulations,  Next: Interpolation,  Prev: Sets,  Up: Top

29 Polynomial Manipulations
***************************

In Octave, a polynomial is represented by its coefficients (arranged in
descending order).  For example, a vector  $c$ of length  N

     p(x) = C(1) x^N + ... + C(N) x + C(N+1).

 -- Function File:  compan (C)
     Compute the companion matrix corresponding to polynomial
     coefficient vector C.

     The companion matrix is

               _                                                        _
              |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(N)/c(1)  -c(N+1)/c(1)  |
              |       1            0      ...       0             0      |
              |       0            1      ...       0             0      |
          A = |       .            .   .            .             .      |
              |       .            .       .        .             .      |
              |       .            .           .    .             .      |
              |_      0            0      ...       1             0     _|

     The eigenvalues of the companion matrix are equal to the roots of
     the polynomial.

     *See also:* poly, roots, residue, conv, deconv, polyval, polyderiv,
     polyinteg.

 -- Function File:  conv (A, B)
     Convolve two vectors.

     `y = conv (a, b)' returns a vector of length equal to `length (a)
     + length (b) - 1'.  If A and B are polynomial coefficient vectors,
     `conv' returns the coefficients of the product polynomial.

     *See also:* deconv, poly, roots, residue, polyval, polyderiv,
     polyinteg.

 -- Function File:  deconv (Y, A)
     Deconvolve two vectors.

     `[b, r] = deconv (y, a)' solves for B and R such that `y = conv
     (a, b) + r'.

     If Y and A are polynomial coefficient vectors, B will contain the
     coefficients of the polynomial quotient and R will be a remander
     polynomial of lowest order.

     *See also:* conv, poly, roots, residue, polyval, polyderiv,
     polyinteg.

 -- Loadable Function: y = conv2 (A, B, SHAPE)
 -- Loadable Function: y = conv2 (V1, V2, M, SHAPE)
     Returns 2D convolution of A and B where the size of C is given by

    SHAPE= 'full'
          returns full 2-D convolution

    SHAPE= 'same'
          same size as a. 'central' part of convolution

    SHAPE= 'valid'
          only parts which do not include zero-padded edges

     By default SHAPE is 'full'. When the third argument is a matrix
     returns the convolution of the matrix M by the vector V1 in the
     column direction and by vector V2 in the row direction

 -- Function File:  poly (A)
     If A is a square N-by-N matrix, `poly (A)' is the row vector of
     the coefficients of `det (z * eye (N) - a)', the characteristic
     polynomial of A.  If X is a vector, `poly (X)' is a vector of
     coefficients of the polynomial whose roots are the elements of X.

 -- Function File:  polyderiv (C)
 -- Function File: [Q] = polyder (B, A)
 -- Function File: [Q, R] = polyder (B, A)
     Return the coefficients of the derivative of the polynomial whose
     coefficients are given by vector C.  If a pair of polynomials is
     given B and A, the derivative of the product is returned in Q, or
     the quotient numerator in Q and the quotient denominator in R.

     *See also:* poly, polyinteg, polyreduce, roots, conv, deconv,
     residue, filter, polygcd, polyval, polyvalm.

 -- Function File:  polyder (C)
 -- Function File: [Q] = polyder (B, A)
 -- Function File: [Q, R] = polyder (B, A)
     See polyderiv.

 -- Function File: [P, S] = polyfit (X, Y, N)
     Return the coefficients of a polynomial P(X) of degree N that
     minimizes `sumsq (p(x(i)) - y(i))',  to best fit the data in the
     least squares sense.

     The polynomial coefficients are returned in a row vector.

     If two output arguments are requested, the second is a structure
     containing the following fields:

    `R'
          The Cholesky factor of the Vandermonde matrix used to compute
          the polynomial coefficients.

    `X'
          The Vandermonde matrix used to compute the polynomial
          coefficients.

    `df'
          The degrees of freedom.

    `normr'
          The norm of the residuals.

    `yf'
          The values of the polynomial for each value of X.

 -- Function File: Q = polygcd (B, A, TOL)
     Find greatest common divisor of two polynomials.  This is
     equivalent to the polynomial found by multiplying together all the
     common roots.  Together with deconv, you can reduce a ratio of two
     polynomials.  Tolerance defaults to
          sqrt(eps).
      Note that this is an unstable algorithm, so don't try it on large
     polynomials.

     Example
          polygcd (poly(1:8), poly(3:12)) - poly(3:8)
                   deconv (poly(1:8), polygcd (poly(1:8), poly(3:12))) - poly(1:2)


     *See also:* poly, polyinteg, polyderiv, polyreduce, roots, conv,
     deconv, residue, filter, polyval, and polyvalm.

 -- Function File:  polyinteg (C)
     Return the coefficients of the integral of the polynomial whose
     coefficients are represented by the vector C.

     The constant of integration is set to zero.

     *See also:* poly, polyderiv, polyreduce, roots, conv, deconv,
     residue, filter, polyval, and polyvalm.

 -- Function File:  polyreduce (C)
     Reduces a polynomial coefficient vector to a minimum number of
     terms by stripping off any leading zeros.

     *See also:* poly, roots, conv, deconv, residue, filter, polyval,
     polyvalm, polyderiv, polyinteg.

 -- Function File:  polyval (C, X)
     Evaluate a polynomial.

     `polyval (C, X)' will evaluate the polynomial at the specified
     value of X.

     If X is a vector or matrix, the polynomial is evaluated at each of
     the elements of X.

     *See also:* polyvalm, poly, roots, conv, deconv, residue, filter,
     polyderiv, polyinteg.

 -- Function File:  polyvalm (C, X)
     Evaluate a polynomial in the matrix sense.

     `polyvalm (C, X)' will evaluate the polynomial in the matrix
     sense, i.e. matrix multiplication is used instead of element by
     element multiplication as is used in polyval.

     The argument X must be a square matrix.

     *See also:* polyval, poly, roots, conv, deconv, residue, filter,
     polyderiv, and polyinteg.

 -- Function File:  residue (B, A, TOL)
     If B and A are vectors of polynomial coefficients, then residue
     calculates the partial fraction expansion corresponding to the
     ratio of the two polynomials.  

     The function `residue' returns R, P, K, and E, where the vector R
     contains the residue terms, P contains the pole values, K contains
     the coefficients of a direct polynomial term (if it exists) and E
     is a vector containing the powers of the denominators in the
     partial fraction terms.

     Assuming B and A represent polynomials  P (s) and Q(s)  we have:

           P(s)    M       r(m)         N
           ---- = SUM -------------  + SUM k(i)*s^(N-i)
           Q(s)   m=1 (s-p(m))^e(m)    i=1

     where M is the number of poles (the length of the R, P, and E
     vectors) and N is the length of the K vector.

     The argument TOL is optional, and if not specified, a default
     value of 0.001 is assumed.  The tolerance value is used to
     determine whether poles with small imaginary components are
     declared real.  It is also used to determine if two poles are
     distinct.  If the ratio of the imaginary part of a pole to the
     real part is less than TOL, the imaginary part is discarded.  If
     two poles are farther apart than TOL they are distinct.  For
     example,

           b = [1, 1, 1];
           a = [1, -5, 8, -4];
           [r, p, k, e] = residue (b, a);
          => r = [-2, 7, 3]
          => p = [2, 2, 1]
          => k = [](0x0)
          => e = [1, 2, 1]

     which implies the following partial fraction expansion

                  s^2 + s + 1       -2        7        3
             ------------------- = ----- + ------- + -----
             s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)


     *See also:* poly, roots, conv, deconv, polyval, polyderiv, and
     polyinteg.

 -- Function File:  roots (V)
     For a vector V with N components, return the roots of the
     polynomial

          v(1) * z^(N-1) + ... + v(N-1) * z + v(N)

 -- Function File:  polyout (C, X)
     Write formatted polynomial
             c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
      and return it as a string or write it to the screen (if NARGOUT
     is zero).  X defaults to the string `"s"'.

     *See also:* polyval, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, and polyinteg.

 -- Function File: YI = ppval (PP, XI)
     Evaluate piece-wise polynomial PP at the points XI.  If `PP.d' is
     a scalar greater than 1, or an array, then the returned value YI
     will be an array that is `d1, d1, ..., dk, length (XI)]'.

     *See also:* mkpp, unmkpp, spline.

 -- Function File: PP =  mkpp (X, P)
 -- Function File: PP =  mkpp (X, P, D)
     Construct a piece-wise polynomial structure from sample points X
     and coefficients P.  The ith row of P, `P (I,:)', contains the
     coefficients for the polynomial over the I-th interval, ordered
     from highest to lowest. There must be one row for each interval in
     X, so `rows (P) == length (X) - 1'.

     You can concatenate multiple polynomials of the same order over the
     same set of intervals using `P = [ P1; P2; ...; PD ]'.  In this
     case, `rows (P) == D * (length (X) - 1)'.

     D specifies the shape of the matrix P for all except the last
     dimension. If D is not specified it will be computed as `round
     (rows (P) / (length (X) - 1))' instead.


     *See also:* unmkpp, ppval, spline.

 -- Function File: [X, P, N, K, D] = unmkpp (PP)
     Extract the components of a piece-wise polynomial structure PP.
     These are as follows:

    X
          Samples points.

    P
          Polynomial coefficients for points in sample interval. `P (I,
          :)' contains the coefficients for the polynomial over
          interval I ordered from highest to lowest. If `D > 1', `P (R,
          I, :)' contains the coeffients for the r-th polynomial
          defined on interval I. However, this is stored as a 2-D array
          such that `C = reshape (P (:, J), N, D)' gives `C (I,  R)' is
          the j-th coefficient of the r-th polynomial over the i-th
          interval.

    N
          Number of polynomial pieces.

    K
          Order of the polynomial plus 1.

    D
          Number of polynomials defined for each interval.


     *See also:* mkpp, ppval, spline.


File: octave.info,  Node: Interpolation,  Next: Geometry,  Prev: Polynomial Manipulations,  Up: Top

30 Interpolation
****************

Octave provides the following functions for interpolation.

 -- Function File: YI = interp1 (X, Y, XI)
 -- Function File: YI = interp1 (..., METHOD)
 -- Function File: YI = interp1 (..., EXTRAP)
 -- Function File: PP = interp1 (..., 'pp')
     One-dimensional interpolation. Interpolate Y, defined at the
     points X, at the points XI. The sample points X must be strictly
     monotonic. If Y is an array, treat the columns of Y seperately.

     Method is one of:

    'nearest'
          Return the nearest neighbour.

    'linear'
          Linear interpolation from nearest neighbours

    'pchip'
          Piece-wise cubic hermite interpolating polynomial

    'cubic'
          Cubic interpolation from four nearest neighbours

    'spline'
          Cubic spline interpolation-smooth first and second derivatives
          throughout the curve

     Appending '*' to the start of the above method forces `interp1' to
     assume that X is uniformly spaced, and only `X (1)' and `X (2)'
     are referenced. This is usually faster, and is never slower. The
     default method is 'linear'.

     If EXTRAP is the string 'extrap', then extrapolate values beyond
     the endpoints.  If EXTRAP is a number, replace values beyond the
     endpoints with that number.  If EXTRAP is missing, assume NaN.

     If the string argument 'pp' is specified, then XI should not be
     supplied and `interp1' returns the piece-wise polynomial that can
     later be used with `ppval' to evaluate the interpolation.  There
     is an equivalence, such that `ppval (interp1 (X, Y, METHOD, 'pp'),
     XI) == interp1 (X, Y, XI, METHOD, 'extrap')'.

     An example of the use of `interp1' is

             xf=[0:0.05:10]; yf = sin(2*pi*xf/5);
             xp=[0:10];      yp = sin(2*pi*xp/5);
             lin=interp1(xp,yp,xf);
             spl=interp1(xp,yp,xf,'spline');
             cub=interp1(xp,yp,xf,'cubic');
             near=interp1(xp,yp,xf,'nearest');
             plot(xf,yf,';original;',xf,lin,';linear;',xf,spl,';spline;',...
                  xf,cub,';cubic;',xf,near,';nearest;',xp,yp,'*;;');


     *See also:* interpft.

 -- Function File: ZI= interp2 (X, Y, Z, XI, YI)
 -- Function File: ZI= interp2 (Z, XI, YI)
 -- Function File: ZI= interp2 (Z, N)
 -- Function File: ZI= interp2 (..., METHOD)
 -- Function File: ZI= interp2 (..., METHOD, EXTRAPVAL)
     Two-dimensional interpolation. X, Y and Z describe a surface
     function. If X and Y are vectors their length must correspondent
     to the size of Z. X and YY must be monotonic. If they are matrices
     they  must have the `meshgrid' format.

    `interp2 (X, Y, Z, XI, YI, ...)'
          Returns a matrix corresponding to the points described by the
          matrices  XI, YI.

          If the last argument is a string, the interpolation method can
          be specified. The method can be 'linear', 'nearest' or
          'cubic'.  If it is omitted 'linear' interpolation  is assumed.

    `interp2 (Z, XI, YI)'
          Assumes `X = 1:rows (Z)' and `Y = 1:columns (Z)'

    `interp2 (Z, N)'
          Interleaves the Matrix Z n-times. If N is ommited a value of
          `N = 1' is assumed.

     The variable METHOD defines the method to use for the
     interpolation. It can take one of the values

    'nearest'
          Return the nearest neighbor.

    'linear'
          Linear interpolation from nearest neighbors.

    'pchip'
          Piece-wise cubic hermite interpolating polynomial (not
          implemented yet).

    'cubic'
          Cubic interpolation from four nearest neighbors.

    'spline'
          Cubic spline interpolation-smooth first and second derivatives
          throughout the curve (not implemented yet).

     If a scalar value EXTRAPVAL is defined as the final value, then
     values outside the mesh as set to this value. Note that in this
     case METHOD must be defined as well. If EXTRAPVAL is not defined
     then NaN is assumed.


     *See also:* interp1.

 -- Function File:  interpft (X, N)
 -- Function File:  interpft (X, N, DIM)
     Fourier interpolation. If X is a vector, then X is resampled with
     N points. The data in X is assumed to be equispaced. If X is an
     array, then operate along each column of the array seperately. If
     DIM is specified, then interpolate along the dimension DIM.

     `interpft' assumes that the interpolated function is periodic, and
     so assumption are made about the end points of the inetrpolation.


     *See also:* interp1.

 -- Loadable Function: VI = interpn (X1, X2, ..., XN, V, Y1, Y2, ...,
          YN)
     Perform N-dimensional interpolation.  Each element of then
     N-dimensional array V represents a value at a location given by
     the parameters X1, X2,...,XN. The parameters X1, X2, ..., XN are
     either N-dimensional arrays of the same size as the array V in the
     "ndgrid" format or vectors.  The parameters Y1, Y2, ..., YN are
     all N-dimensional arrays of the same size and represent the points
     at which the array VI is interpolated.

     This function only performs linear interpolation.

     *See also:* interp1, interp2, ndgrid.

 -- Function File: ZI= bicubic (X, Y, Z, XI, YI)
     Return a matrix ZI corresponding to the bicubic interpolations at
     XI and YI of the data supplied as X, Y and Z.

     For further information please see bicubic.pdf available at
     `http://wiki.woodpecker.org.cn/moin/Octave/Bicubic'

     *See also:* interp2.

 -- Function File: PP =  spline (X, Y)
 -- Function File: YI =  spline (X, Y, XI)
     Returns the cubic spline interpolation of Y at the point X. Called
     with two arguments the piece-wise polynomial PP that may later be
     used with `ppval' to evaluate the polynomial at specific points.

     The variable X must be a vector of length N, and Y can be either a
     vector or array. In the case where Y is a vector, it can have a
     length of either N or `N + 2'.  If the length of Y is N, then the
     'not-a-knot' end condition is used. If the length of Y is `N + 2',
     then the first and last values of the vector Y are the first
     derivative of the cubic spline at the end-points.

     If Y is an array, then the size of Y must have the form `[S1, S2,
     ..., SK, N]' or `[S1, S2, ..., SK, N + 2]'.  The array is then
     reshaped internally to a matrix where to leading dimension is
     given by `S1 * S2 * ... * SK' and each row this matrix is then
     treated seperately. Note that this is exactly the opposite
     treatment than `interp1' and is done for compatiability.

     Called with a third input argument, `spline' evaluates the
     piece-wise spline at the points XI. There is an equivalence
     between `ppval (spline (X, Y), XI)' and `spline (X, Y, XI)'.


     *See also:* ppval, mkpp, unmkpp.

 -- Function File: IDX = lookup (TABLE, Y)
     Lookup values in a sorted table.  Usually used as a prelude to
     interpolation.

     If table is strictly increasing and `idx = lookup (table, y)', then
     `table(idx(i)) <= y(i) < table(idx(i+1))' for all `y(i)' within
     the table.  If `y(i)' is before the table, then `idx(i)' is 0. If
     `y(i)' is after the table then `idx(i)' is `table(n)'.

     If the table is strictly decreasing, then the tests are reversed.
     There are no guarantees for tables which are non-monotonic or are
     not strictly monotonic.

     To get an index value which lies within an interval of the table,
     use:

          idx = lookup (table(2:length(table)-1), y) + 1

     This expression puts values before the table into the first
     interval, and values after the table into the last interval.


File: octave.info,  Node: Geometry,  Next: Hashing Functions,  Prev: Interpolation,  Up: Top

31 Geometry
***********

 -- Function File:  polyarea (X, Y)
 -- Function File:  polyarea (X, Y, DIM)
     Determines area of a polygon by triangle method. The variables X
     and Y define the vertex pairs, and must therefore have the same
     shape. Then might be either vectors or arrays. If they are arrays
     then the columns of X and Y are treated seperately and an area
     returned for each.

     If the optional DIM argument is given, then `polyarea' works along
     this dimension of the arrays X and Y.



File: octave.info,  Node: Hashing Functions,  Next: Control Theory,  Prev: Geometry,  Up: Top

32 Hashing Functions
********************

 -- Loadable Function:  md5sum (FILE)
 -- Loadable Function:  md5sum (STR, OPT)
     Calculates the MD5 sum of the file FILE. If the second parameter
     OPT exists and is true, then calculate the MD5 sum of the string
     STR.


File: octave.info,  Node: Control Theory,  Next: Signal Processing,  Prev: Hashing Functions,  Up: Top

33 Control Theory
*****************

The Octave Control Systems Toolbox (OCST) was initially developed by
Dr. A. Scottedward Hodel <a.s.hodel@eng.auburn.edu> with the assistance
of his students
   * R. Bruce Tenison <btenison@dibbs.net>,

   * David C. Clem,

   * John E. Ingram <John.Ingram@sea.siemans.com>, and

   * Kristi McGowan.
   This development was supported in part by NASA's Marshall Space
Flight Center as part of an in-house CACSD environment.  Additional
important contributions were made by Dr. Kai Mueller
<mueller@ifr.ing.tu-bs.de> and Jose Daniel Munoz Frias (`place.m').

   An on-line menu-driven tutorial is available via `DEMOcontrol';
beginning OCST users should start with this program.

 -- Function File:  DEMOcontrol
     Octave Control Systems Toolbox demo/tutorial program.  The demo
     allows the user to select among several categories of OCST
     function:
          octave:1> DEMOcontrol
          O C T A V E    C O N T R O L   S Y S T E M S   T O O L B O X
          Octave Controls System Toolbox Demo

            [ 1] System representation
            [ 2] Block diagram manipulations
            [ 3] Frequency response functions
            [ 4] State space analysis functions
            [ 5] Root locus functions
            [ 6] LQG/H2/Hinfinity functions
            [ 7] End
     Command examples are interactively run for users to observe
     the use of OCST functions.

     *See also:* Demo Programs: bddemo.m, frdemo.m, analdemo.m,
     moddmeo.m, rldemo.m.

* Menu:

* sysstruct::
* sysinterface::
* sysdisp::
* blockdiag::
* numerical::
* sysprop::
* systime::
* sysfreq::
* cacsd::
* misc::


File: octave.info,  Node: sysstruct,  Next: sysinterface,  Up: Control Theory

33.1 System Data Structure
==========================

* Menu:

* sysstructvars::
* sysstructtf::
* sysstructzp::
* sysstructss::

   The OCST stores all dynamic systems in a single data structure
format that can represent continuous systems, discrete-systems, and
mixed (hybrid) systems in state-space form, and can also represent
purely continuous/discrete systems in either transfer function or
pole-zero form. In order to provide more flexibility in treatment of
discrete/hybrid systems, the OCST also keeps a record of which system
outputs are sampled.

   Octave structures are accessed with a syntax much like that used by
the C programming language.  For consistency in use of the data
structure used in the OCST, it is recommended that the system structure
access m-files be used (*note sysinterface::).  Some elements of the
data structure are absent depending on the internal system
representation(s) used.  More than one system representation can be
used for SISO systems; the OCST m-files ensure that all representations
used are consistent with one another.

 -- Function File:  sysrepdemo
     Tutorial for the use of the system data structure functions.


File: octave.info,  Node: sysstructvars,  Next: sysstructtf,  Up: sysstruct

33.1.1 Variables common to all OCST system formats
--------------------------------------------------

The data structure elements (and variable types) common to all  system
representations are listed below; examples of the initialization and
use of the system data structures are given in subsequent sections and
in the online demo `DEMOcontrol'.
N
NZ
     The respective number of continuous and discrete states in the
     system (scalar)

INNAME
OUTNAME
     list of name(s) of the system input, output signal(s). (list of
     strings)

SYS
     System status vector.  (vector)

     This vector indicates both what representation was used to
     initialize the system data structure (called the primary system
     type) and which other representations are currently up-to-date
     with the primary system type (*note structaccess::).

     The value of the first element of the vector indicates the primary
     system type.

    0
          for tf form (initialized with `tf2sys' or `fir2sys')

    1
          for zp form (initialized with `zp2sys')

    2
          for ss form (initialized with `ss2sys')

     The next three elements are boolean flags that indicate whether
     tf, zp, or ss, respectively, are "up to date" (whether it is safe
     to use the variables associated with these representations).
     These flags are changed when calls are made to the `sysupdate'
     command.

TSAM
     Discrete time sampling period  (nonnegative scalar).   TSAM is set
     to 0 for continuous time systems.

YD
     Discrete-time output list (vector)

     indicates which outputs are discrete time (i.e.,     produced by
     D/A converters) and which are continuous time.      yd(ii) = 0 if
     output ii is continuous, = 1 if discrete.

   The remaining variables of the  system data structure are only
present if the corresponding entry of the `sys' vector is true (=1).


File: octave.info,  Node: sysstructtf,  Next: sysstructzp,  Prev: sysstructvars,  Up: sysstruct

33.1.2 `tf' format variables
----------------------------

NUM
     numerator coefficients   (vector)

DEN
     denominator coefficients   (vector)



File: octave.info,  Node: sysstructzp,  Next: sysstructss,  Prev: sysstructtf,  Up: sysstruct

33.1.3 `zp' format variables
----------------------------

ZER
     system zeros   (vector)

POL
     system poles    (vector)

K
     leading coefficient   (scalar)



File: octave.info,  Node: sysstructss,  Prev: sysstructzp,  Up: sysstruct

33.1.4 `ss' format variables
----------------------------

A
B
C
D
     The usual state-space matrices. If a system has both
     continuous and discrete states, they are sorted so that
     continuous states come first, then discrete states

     *Note* some functions (e.g., `bode', `hinfsyn') will not accept
     systems with both discrete and continuous states/outputs

STNAME
     names of system states   (list of strings)



File: octave.info,  Node: sysinterface,  Next: sysdisp,  Prev: sysstruct,  Up: Control Theory

33.2 System Construction and Interface Functions
================================================

Construction and manipulations of the OCST system data structure (*note
sysstruct::) requires attention to many details in order to ensure that
data structure contents remain consistent.  Users are strongly
encouraged to use the system interface functions in this section.
Functions for the formatted display in of system data structures are
given in *Note sysdisp::.

* Menu:

* fir2sys::
* ss2sys::
* tf2sys::
* zp2sys::
* structaccess::


File: octave.info,  Node: fir2sys,  Next: ss2sys,  Up: sysinterface

33.2.1 Finite impulse response system interface functions
---------------------------------------------------------

 -- Function File:  fir2sys (NUM, TSAM, INNAME, OUTNAME)
     construct a system data structure from FIR description

     *Inputs*
    NUM
          vector of coefficients [c0, c1, ..., cn] of the SISO FIR
          transfer function C(z) = c0 + c1*z^(-1) + c2*z^(-2) + ... +
          cn*z^(-n)

    TSAM
          sampling time (default: 1)

    INNAME
          name of input signal;  may be a string or a list with a
          single entry.

    OUTNAME
          name of output signal; may be a string or a list with a
          single entry.

     *Output*
    SYS
          system data structure

     *Example*
          octave:1> sys = fir2sys([1 -1 2 4],0.342,\
          > "A/D input","filter output");
          octave:2> sysout(sys)
          Input(s)
                  1: A/D input

          Output(s):
                  1: filter output (discrete)

          Sampling interval: 0.342
          transfer function form:
          1*z^3 - 1*z^2 + 2*z^1 + 4
          -------------------------
          1*z^3 + 0*z^2 + 0*z^1 + 0

 -- Function File: [C, TSAM, INPUT, OUTPUT] = sys2fir (SYS)
     Extract FIR data from system data structure; see `fir2sys' for
     parameter descriptions.

     *See also:* fir2sys.


File: octave.info,  Node: ss2sys,  Next: tf2sys,  Prev: fir2sys,  Up: sysinterface

33.2.2 State space system interface functions
---------------------------------------------

 -- Function File: OUTSYS = ss (A, B, C, D, TSAM, N, NZ, STNAME,
          INNAME, OUTNAME, OUTLIST)
     Create system structure from state-space data.   May be continous,
     discrete, or mixed (sampled data)

     *Inputs*
    A
    B
    C
    D
          usual state space matrices.

          default: D = zero matrix

    TSAM
          sampling rate.  Default: tsam = 0 (continuous system)

    N
    NZ
          number of continuous, discrete states in the system

          If TSAM is 0, n = `rows'(A), nz = 0.

          If TSAM is greater than zero, n = 0, nz = `rows'(A)

          see below for system partitioning

    STNAME
          cell array of strings of state signal names

          default (STNAME=[] on input): `x_n' for continuous states,
          `xd_n' for discrete states

    INNAME
          cell array of strings of input signal names

          default (INNAME = [] on input): `u_n'

    OUTNAME
          cell array of strings of output signal names

          default (OUTNAME = [] on input): `y_n'

    OUTLIST
          list of indices of outputs y that are sampled

          If TSAM is 0, outlist = [].

          If TSAM is greater than 0, outlist = 1:`rows'(C).

     Unlike states, discrete/continous outputs may appear in any order.

     `sys2ss' returns a vector YD where YD(OUTLIST) = 1; all other
     entries of YD are 0.

     *Output*
    OUTSYS
          system data structure

     *System partitioning*

     Suppose for simplicity that outlist specified that the first
     several outputs were continuous and the remaining outputs were
     discrete.  Then the system is partitioned as
          x = [ xc ]  (n x 1)
              [ xd ]  (nz x 1 discrete states)
          a = [ acc acd ]  b = [ bc ]
              [ adc add ]      [ bd ]
          c = [ ccc ccd ]  d = [ dc ]
              [ cdc cdd ]      [ dd ]

              (cdc = c(outlist,1:n), etc.)
     with dynamic equations: d/dt xc(t)     = acc*xc(t)      +
     acd*xd(k*tsam) + bc*u(t)

     xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)

     yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)

     yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)

     *Signal partitions*
                  | continuous      | discrete               |
          ----------------------------------------------------
          states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
          ----------------------------------------------------
          outputs | outname(cout,:) | outname(outlist,:)     |
          ----------------------------------------------------
     where cout is the list of in 1:`rows'(P) that are not
     contained in outlist. (Discrete/continuous outputs may be entered
     in any order desired by the user.)

     *Example*
          octave:1> a = [1 2 3; 4 5 6; 7 8 10];
          octave:2> b = [0 0 ; 0 1 ; 1 0];
          octave:3> c = eye (3);
          octave:4> sys = ss (a, b, c, [], 0, 3, 0, {"volts", "amps", "joules"});
          octave:5> sysout(sys);
          Input(s)
                  1: u_1
                  2: u_2

          Output(s):
                  1: y_1
                  2: y_2
                  3: y_3

          state-space form:
          3 continuous states, 0 discrete states
          State(s):
                  1: volts
                  2: amps
                  3: joules

          A matrix: 3 x 3
             1   2   3
             4   5   6
             7   8  10
          B matrix: 3 x 2
            0  0
            0  1
            1  0
          C matrix: 3 x 3
            1  0  0
            0  1  0
            0  0  1
          D matrix: 3 x 3
            0  0
            0  0
            0  0
     Notice that the D matrix is constructed  by default to the correct
     dimensions.  Default input and output signals names were assigned
     since none were given.

 -- Function File:  ss (A, B, C, D, TSAM, N, NZ, STNAME, INNAME,
          OUTNAME, OUTLIST)
     Create system structure from state-space data.   May be continous,
     discrete, or mixed (sampled data)

     *Inputs*
    A
    B
    C
    D
          usual state space matrices.

          default: D = zero matrix

    TSAM
          sampling rate.  Default: tsam = 0 (continuous system)

    N
    NZ
          number of continuous, discrete states in the system

          If TSAM is 0, n = `rows'(A), nz = 0.

          If TSAM is greater than zero, n = 0, nz = `rows'(A)

          see below for system partitioning

    STNAME
          cell array of strings of state signal names

          default (STNAME=[] on input): `x_n' for continuous states,
          `xd_n' for discrete states

    INNAME
          cell array of strings of input signal names

          default (INNAME = [] on input): `u_n'

    OUTNAME
          cell array of strings of input signal names

          default (OUTNAME = [] on input): `y_n'

    OUTLIST
          list of indices of outputs y that are sampled

          If TSAM is 0, outlist = [].

          If TSAM is greater than 0, outlist = 1:`rows'(C).

     Unlike states, discrete/continous outputs may appear in any order.

     `sys2ss' returns a vector YD where YD(OUTLIST) = 1; all other
     entries of YD are 0.

     *Outputs* OUTSYS = system data structure

     *System partitioning*

     Suppose for simplicity that outlist specified that the first
     several outputs were continuous and the remaining outputs were
     discrete.  Then the system is partitioned as
          x = [ xc ]  (n x 1)
              [ xd ]  (nz x 1 discrete states)
          a = [ acc acd ]  b = [ bc ]
              [ adc add ]      [ bd ]
          c = [ ccc ccd ]  d = [ dc ]
              [ cdc cdd ]      [ dd ]

              (cdc = c(outlist,1:n), etc.)
     with dynamic equations: d/dt xc(t)     = acc*xc(t)      +
     acd*xd(k*tsam) + bc*u(t)

     xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)

     yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)

     yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)

     *Signal partitions*
                  | continuous      | discrete               |
          ----------------------------------------------------
          states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
          ----------------------------------------------------
          outputs | outname(cout,:) | outname(outlist,:)     |
          ----------------------------------------------------
     where cout is the list of in 1:`rows'(P) that are not
     contained in outlist. (Discrete/continuous outputs may be entered
     in any order desired by the user.)

     *Example*
          octave:1> a = [1 2 3; 4 5 6; 7 8 10];
          octave:2> b = [0 0 ; 0 1 ; 1 0];
          octave:3> c = eye (3);
          octave:4> sys = ss (a, b, c, [], 0, 3, 0, {"volts", "amps", "joules"});
          octave:5> sysout(sys);
          Input(s)
                  1: u_1
                  2: u_2

          Output(s):
                  1: y_1
                  2: y_2
                  3: y_3

          state-space form:
          3 continuous states, 0 discrete states
          State(s):
                  1: volts
                  2: amps
                  3: joules

          A matrix: 3 x 3
             1   2   3
             4   5   6
             7   8  10
          B matrix: 3 x 2
            0  0
            0  1
            1  0
          C matrix: 3 x 3
            1  0  0
            0  1  0
            0  0  1
          D matrix: 3 x 3
            0  0
            0  0
            0  0
     Notice that the D matrix is constructed  by default to the correct
     dimensions.  Default input and output signals names were assigned
     since none were given.

 -- Function File: [A, B, C, D, TSAM, N, NZ, STNAME, INNAME, OUTNAME,
YD] = sys2ss (SYS)
     Extract state space representation from system data structure.

     *Input*
    SYS
          System data structure.

     *Outputs*
    A
    B
    C
    D
          State space matrices for SYS.

    TSAM
          Sampling time of SYS (0 if continuous).

    N
    NZ
          Number of continuous, discrete states (discrete states come
          last in state vector X).

    STNAME
    INNAME
    OUTNAME
          Signal names (lists of strings);  names of states, inputs,
          and outputs, respectively.

    YD
          Binary vector; YD(II) is 1 if output Y(II) is discrete
          (sampled); otherwise  YD(II) is 0.

     A warning massage is printed if the system is a mixed continuous
     and discrete system.

     *Example*
          octave:1> sys=tf2sys([1 2],[3 4 5]);
          octave:2> [a,b,c,d] = sys2ss(sys)
          a =
             0.00000   1.00000
            -1.66667  -1.33333
          b =
            0
            1
          c = 0.66667  0.33333
          d = 0


File: octave.info,  Node: tf2sys,  Next: zp2sys,  Prev: ss2sys,  Up: sysinterface

33.2.3 Transfer function system interface functions
---------------------------------------------------

 -- Function File:  tf (NUM, DEN, TSAM, INNAME, OUTNAME)
     build system data structure from transfer function format data

     *Inputs*
    NUM
    DEN
          coefficients of numerator/denominator polynomials

    TSAM
          sampling interval. default: 0 (continuous time)

    INNAME
    OUTNAME
          input/output signal names; may be a string or cell array with
          a single string entry.

     *Outputs* SYS = system data structure

     *Example*
          octave:1> sys=tf([2 1],[1 2 1],0.1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1 (discrete)
          Sampling interval: 0.1
          transfer function form:
          2*z^1 + 1
          -----------------
          1*z^2 + 2*z^1 + 1

 -- Function File:  tf2sys (NUM, DEN, TSAM, INNAME, OUTNAME)
     Build system data structure from transfer function format data.

     *Inputs*
    NUM
    DEN
          Coefficients of numerator/denominator polynomials.

    TSAM
          Sampling interval; default: 0 (continuous time).

    INNAME
    OUTNAME
          Input/output signal names; may be a string or cell array with
          a single string entry.

     *Output*
    SYS
          System data structure.

     *Example*
          octave:1> sys=tf2sys([2 1],[1 2 1],0.1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1 (discrete)
          Sampling interval: 0.1
          transfer function form:
          2*z^1 + 1
          -----------------
          1*z^2 + 2*z^1 + 1

 -- Function File: [NUM, DEN, TSAM, INNAME, OUTNAME] = sys2tf (SYS)
     Extract transfer function data from a system data structure.

     See `tf' for parameter descriptions.

     *Example*
          octave:1> sys=ss([1 -2; -1.1,-2.1],[0;1],[1 1]);
          octave:2> [num,den] = sys2tf(sys)
          num = 1.0000  -3.0000
          den = 1.0000   1.1000  -4.3000


File: octave.info,  Node: zp2sys,  Next: structaccess,  Prev: tf2sys,  Up: sysinterface

33.2.4 Zero-pole system interface functions
-------------------------------------------

 -- Function File:  zp (ZER, POL, K, TSAM, INNAME, OUTNAME)
     Create system data structure from zero-pole data.

     *Inputs*
    ZER
          vector of system zeros

    POL
          vector of system poles

    K
          scalar leading coefficient

    TSAM
          sampling period. default: 0 (continuous system)

    INNAME
    OUTNAME
          input/output signal names (lists of strings)

     *Outputs* sys: system data structure

     *Example*
          octave:1> sys=zp([1 -1],[-2 -2 0],1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          zero-pole form:
          1 (s - 1) (s + 1)
          -----------------
          s (s + 2) (s + 2)

 -- Function File:  zp2sys (ZER, POL, K, TSAM, INNAME, OUTNAME)
     Create system data structure from zero-pole data.

     *Inputs*
    ZER
          Vector of system zeros.

    POL
          Vector of system poles.

    K
          Scalar leading coefficient.

    TSAM
          Sampling period; default: 0 (continuous system).

    INNAME
    OUTNAME
          Input/output signal names (lists of strings).

     *Output*
    SYS
          System data structure.

     *Example*
          octave:1> sys=zp2sys([1 -1],[-2 -2 0],1);
          octave:2> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          zero-pole form:
          1 (s - 1) (s + 1)
          -----------------
          s (s + 2) (s + 2)

 -- Function File: [ZER, POL, K, TSAM, INNAME, OUTNAME] = sys2zp (SYS)
     Extract zero/pole/leading coefficient information from a system
     data structure.

     See `zp' for parameter descriptions.

     *Example*
          octave:1> sys=ss([1 -2; -1.1,-2.1],[0;1],[1 1]);
          octave:2> [zer,pol,k] = sys2zp(sys)
          zer = 3.0000
          pol =
            -2.6953
             1.5953
          k = 1


File: octave.info,  Node: structaccess,  Prev: zp2sys,  Up: sysinterface

33.2.5 Data structure access functions
--------------------------------------

 -- Function File:  syschnames (SYS, OPT, LIST, NAMES)
     Superseded by `syssetsignals'.

 -- Function File:  syschtsam (SYS, TSAM)
     This function changes the sampling time (tsam) of the system.
     Exits with an error if sys is purely continuous time.

 -- Function File: [N, NZ, M, P, YD] = sysdimensions (SYS, OPT)
     return the number of states, inputs, and/or outputs in the system
     SYS.

     *Inputs*
    SYS
          system data structure

    OPT
          String indicating which dimensions are desired.  Values:
         `"all"'
               (default) return all parameters as specified under
               Outputs below.

         `"cst"'
               return N= number of continuous states

         `"dst"'
               return N= number of discrete states

         `"in"'
               return N= number of inputs

         `"out"'
               return N= number of outputs

     *Outputs*
    N
          number of continuous states (or individual requested
          dimension as specified by OPT).

    NZ
          number of discrete states

    M
          number of system inputs

    P
          number of system outputs

    YD
          binary vector; YD(II) is nonzero if output II is discrete.
          yd(ii) = 0 if output II is continous


     *See also:* sysgetsignals, sysgettsam.

 -- Function File: [STNAME, INNAME, OUTNAME, YD] = sysgetsignals (SYS)
 -- Function File: SIGLIST = sysgetsignals (SYS, SIGID)
 -- Function File: SIGNAME = sysgetsignals (SYS, SIGID, SIGNUM, STRFLG)
     Get signal names from a system

     *Inputs*
    SYS
          system data structure for the state space system

    SIGID
          signal id.  String.  Must be one of
         `"in"'
               input signals

         `"out"'
               output signals

         `"st"'
               stage signals

         `"yd"'
               value of logical vector YD

    SIGNUM
          index(indices) or name(s) or signals; see `sysidx'

    STRFLG
          flag to return a string instead of a cell array;  Values:
         `0'
               (default) return a cell array (even if signum specifies
               an individual signal)

         `1'
               return a string.  Exits with an error if signum does not
               specify an individual signal.


     *Outputs*
    *If SIGID is not specified:

         STNAME
         INNAME
         OUTNAME
               signal names (cell array of strings);  names of states,
               inputs, and outputs, respectively.

         YD
               binary vector; YD(II) is nonzero if output II is
               discrete.

    *If SIGID is specified but SIGNUM is not specified:

         `sigid="in"'
               SIGLIST is set to the cell array of input names.

         `sigid="out"'
               SIGLIST is set to the cell array of output names.

         `sigid="st"'
               SIGLIST is set to the cell array of state names.

               stage signals

         `sigid="yd"'
               SIGLIST is set to logical vector indicating discrete
               outputs; SIGLIST(II) = 0 indicates that output II is
               continuous (unsampled), otherwise it is discrete.


    *If the first three input arguments are specified:
          SIGNAME is a cell array of the specified signal names (SIGID
          is `"in"', `"out"', or `"st"'), or else the logical flag
          indicating whether output(s) SIGNUM is(are) discrete
          (SIGVAL=1) or continuous (SIGVAL=0).

     *Examples* (From `sysrepdemo')
          octave> sys=ss(rand(4),rand(4,2),rand(3,4));
          octave># get all signal names
          octave> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys)
          Ast =
          (
            [1] = x_1
            [2] = x_2
            [3] = x_3
            [4] = x_4
          )
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          Aout =
          (
            [1] = y_1
            [2] = y_2
            [3] = y_3
          )
          Ayd =

            0  0  0
          octave> # get only input signal names:
          octave> Ain = sysgetsignals(sys,"in")
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          octave> # get name of output 2 (in cell array):
          octave> Aout = sysgetsignals(sys,"out",2)
          Aout =
          (
            [1] = y_2
          )
          octave> # get name of output 2 (as string):
          octave> Aout = sysgetsignals(sys,"out",2,1)
          Aout = y_2

 -- Function File:  sysgettype (SYS)
     return the initial system type of the system

     *Input*
    SYS
          System data structure.

     *Output*
    SYSTYPE
          String indicating how the structure was initially
          constructed. Values: `"ss"', `"zp"', or `"tf"'.

     FIR initialized systems return `systype="tf"'.

 -- Function File:  syssetsignals (SYS, OPT, NAMES, SIG_IDX)
     change the names of selected inputs, outputs and states.

     *Inputs*
    SYS
          System data structure.

    OPT
          Change default name (output).

         `"out"'
               Change selected output names.

         `"in"'
               Change selected input names.

         `"st"'
               Change selected state names.

         `"yd"'
               Change selected outputs from discrete to continuous or
               from continuous to discrete.

    NAMES

         `opt = "out", "in", "st"'
               string or string array containing desired signal names
               or values.

         `opt = "yd"'
               To desired output continuous/discrete flag.  Set name to
               0 for continuous, or 1 for discrete.

    SIG_IDX
          indices or names of outputs, yd, inputs, or states whose
          respective names/values should be changed.

          Default: replace entire cell array of names/entire yd vector.

     *Outputs*
    RETSYS
          SYS with appropriate signal names changed (or YD values,
          where appropriate).

     *Example*
          octave:1> sys=ss([1 2; 3 4],[5;6],[7 8]);
          octave:2> sys = syssetsignals(sys,"st",str2mat("Posx","Velx"));
          octave:3> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          state-space form:
          2 continuous states, 0 discrete states
          State(s):
                  1: Posx
                  2: Velx
          A matrix: 2 x 2
            1  2
            3  4
          B matrix: 2 x 1
            5
            6
          C matrix: 1 x 2
            7  8
          D matrix: 1 x 1
          0

 -- Function File:  sysupdate (SYS, OPT)
     Update the internal representation of a system.

     *Inputs*
    SYS:
          system data structure

    OPT
          string:
         `"tf"'
               update transfer function form

         `"zp"'
               update zero-pole form

         `"ss"'
               update state space form

         `"all"'
               all of the above

     *Outputs*
    RETSYS
          Contains union of data in sys and requested data.  If
          requested data in SYS is already up to date then RETSYS=SYS.

     Conversion to `tf' or `zp' exits with an error if the system is
     mixed continuous/digital.

     *See also:* tf, ss, zp, sysout, sys2ss, sys2tf, sys2zp.

 -- Function File: [SYSTYPE, NOUT, NIN, NCSTATES, NDSTATES] = minfo
          (INMAT)
     Determines the type of system matrix.  INMAT can be a varying, a
     system, a constant, and an empty matrix.

     *Outputs*
    SYSTYPE
          Can be one of: varying, system, constant, and empty.

    NOUT
          The number of outputs of the system.

    NIN
          The number of inputs of the system.

    NCSTATES
          The number of continuous states of the system.

    NDSTATES
          The number of discrete states of the system.

 -- Function File:  sysgettsam (SYS)
     Return the sampling time of the system SYS.


File: octave.info,  Node: sysdisp,  Next: blockdiag,  Prev: sysinterface,  Up: Control Theory

33.3 System display functions
=============================

 -- Function File:  sysout (SYS, OPT)
     print out a system data structure in desired format
    SYS
          system data structure

    OPT
          Display option
         `[]'
               primary system form (default)

         `"ss"'
               state space form

         `"tf"'
               transfer function form

         `"zp"'
               zero-pole form

         `"all"'
               all of the above

 -- Function File:  tfout (NUM, DENOM, X)
     Print formatted transfer function n(s)/d(s) to the screen.  X
     defaults to the string `"s"'

     *See also:* polyval, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, polyinteg, polyout.

 -- Function File:  zpout (ZER, POL, K, X)
     print formatted zero-pole form to the screen.  X defaults to the
     string `"s"'

     *See also:* polyval, polyvalm, poly, roots, conv, deconv, residue,
     filter, polyderiv, polyinteg, polyout.


File: octave.info,  Node: blockdiag,  Next: numerical,  Prev: sysdisp,  Up: Control Theory

33.4 Block Diagram Manipulations
================================

*Note systime::.

   Unless otherwise noted, all parameters (input,output) are system
data structures.

 -- Function File:  bddemo (INPUTS)
     Octave Controls toolbox demo: Block Diagram Manipulations demo.

 -- Function File:  buildssic (CLST, ULST, OLST, ILST, S1, S2, S3, S4,
          S5, S6, S7, S8)
     Form an arbitrary complex (open or closed loop) system in
     state-space form from several systems. `buildssic' can easily
     (despite its cryptic syntax) integrate transfer functions from a
     complex block diagram into a single system with one call.  This
     function is especially useful for building open loop
     interconnections for H-infinity and H-2 designs or for closing
     loops with these controllers.

     Although this function is general purpose, the use of `sysgroup'
     `sysmult', `sysconnect' and the like is recommended for standard
     operations since they can handle mixed discrete and continuous
     systems and also the names of inputs, outputs, and states.

     The parameters consist of 4 lists that describe the connections
     outputs and inputs and up to 8 systems S1-S8.  Format of the lists:
    CLST
          connection list, describes the input signal of each system.
          The maximum number of rows of Clst is equal to the sum of all
          inputs of s1-s8.

          Example: `[1 2 -1; 2 1 0]' means that:  new input 1 is old
          input 1 + output 2 - output 1, and new input 2 is old input 2
          + output 1. The order of rows is arbitrary.

    ULST
          if not empty the old inputs in vector ULST will be appended
          to the outputs. You need this if you want to "pull out" the
          input of a system. Elements are input numbers of S1-S8.

    OLST
          output list, specifiy the outputs of the resulting systems.
          Elements are output numbers of S1-S8.  The numbers are
          allowed to be negative and may appear in any order. An empty
          matrix means all outputs.

    ILST
          input list, specifiy the inputs of the resulting systems.
          Elements are input numbers of S1-S8.  The numbers are allowed
          to be negative and may appear in any order. An empty matrix
          means all inputs.

     Example:  Very simple closed loop system.
          w        e  +-----+   u  +-----+
           --->o--*-->|  K  |--*-->|  G  |--*---> y
               ^  |   +-----+  |   +-----+  |
             - |  |            |            |
               |  |            +----------------> u
               |  |                         |
               |  +-------------------------|---> e
               |                            |
               +----------------------------+

     The closed loop system GW can be optained by
          GW = buildssic([1 2; 2 -1], 2, [1 2 3], 2, G, K);

    CLST
          1st row: connect input 1 (G) with output 2 (K).

          2nd row: connect input 2 (K) with negative output 1 (G).

    ULST
          Append input of 2 (K) to the number of outputs.

    OLST
          Outputs are output of 1 (G), 2 (K) and appended output 3
          (from ULST).

    ILST
          The only input is 2 (K).

     Here is a real example:
                                   +----+
              -------------------->| W1 |---> v1
          z   |                    +----+
          ----|-------------+
              |             |
              |    +---+    v      +----+
              *--->| G |--->O--*-->| W2 |---> v2
              |    +---+       |   +----+
              |                |
              |                v
             u                  y

          min || GW   ||
                   vz   infty

     The closed loop system GW from [z, u]' to [v1, v2, y]' can be
     obtained by (all SISO systems):
          GW = buildssic([1, 4; 2, 4; 3, 1], 3, [2, 3, 5],
                         [3, 4], G, W1, W2, One);
     where "One" is a unity gain (auxillary) function with order 0.
     (e.g. `One = ugain(1);')

 -- Function File: SYS = jet707 ()
     Creates a linearized state-space model of a Boeing 707-321 aircraft
     at V=80 m/s (M = 0.26, GA0 = -3 deg, ALPHA0 = 4 deg, KAPPA = 50
     deg).

     System inputs: (1) thrust and (2) elevator angle.

     System outputs:  (1) airspeed and (2) pitch angle.

     *Reference*: R. Brockhaus: `Flugregelung' (Flight Control),
     Springer, 1994.

     *See also:* ord2.

 -- Function File:  ord2 (NFREQ, DAMP, GAIN)
     Creates a continuous 2nd order system with parameters:

     *Inputs*
    NFREQ
          natural frequency [Hz]. (not in rad/s)

    DAMP
          damping coefficient

    GAIN
          dc-gain This is steady state value only for damp > 0.  gain
          is assumed to be 1.0 if ommitted.

     *Output*
    OUTSYS
          system data structure has representation with w = 2 * pi *
          nfreq:
                   /                                        \
                   | / -2w*damp -w \  / w \                 |
               G = | |             |, |   |, [ 0  gain ], 0 |
                   | \   w       0 /  \ 0 /                 |
                   \                                        /
*See also* `jet707' (MIMO example, Boeing 707-321
     aircraft model)

 -- Function File:  sysadd (GSYS, HSYS)
     returns SYS = GSYS + HSYS.
        * Exits with an error if GSYS and HSYS are not compatibly
          dimensioned.

        * Prints a warning message is system states have identical
          names; duplicate names are given a suffix to make them unique.

        * SYS input/output names are taken from GSYS.

                    ________
               ----|  gsys  |---
          u   |    ----------  +|
          -----                (_)----> y
              |     ________   +|
               ----|  hsys  |---
                    --------

 -- Function File: SYS = sysappend (SYST, B, C, D, OUTNAME, INNAME, YD)
     appends new inputs and/or outputs to a system

     *Inputs*
    SYST
          system data structure

    B
          matrix to be appended to sys "B" matrix (empty if none)

    C
          matrix to be appended to sys "C" matrix (empty if none)

    D
          revised sys d matrix (can be passed as [] if the revised d is
          all zeros)

    OUTNAME
          list of names for new outputs

    INNAME
          list of names for new inputs

    YD
          binary vector; yd(ii)=0 indicates a continuous output;
          yd(ii)=1 indicates a discrete output.

     *Outputs*
    SYS
                  sys.b := [syst.b , b]
                  sys.c := [syst.c  ]
                           [ c     ]
                  sys.d := [syst.d | D12 ]
                           [ D21   | D22 ]
          where D12, D21, and D22 are the appropriate dimensioned
          blocks of the input parameter D.
             * The leading block D11 of D is ignored.

             * If INNAME and OUTNAME are not given as arguments,
               the new inputs and outputs are be assigned default names.

             * YD is a binary vector of length rows(c) that indicates
                 continuous/sampled outputs.  Default value for YD is:
                  - SYS is continuous or mixed YD = `zeros(1,rows(c))'

                  - SYS is discrete YD = `ones(1,rows(c))'

 -- Function File: CLSYS = sysconnect (SYS, OUT_IDX, IN_IDX, ORDER, TOL)
     Close the loop from specified outputs to respective specified
     inputs

     *Inputs*
    SYS
          System data structure.

    OUT_IDX
    IN_IDX
          Names or indices of signals to connect (see `sysidx').  The
          output specified by out_idx(ii) is connected to the input
          specified by in_idx(ii).

    ORDER
          logical flag (default = 0)
         `0'
               Leave inputs and outputs in their original order.

         `1'
               Permute inputs and outputs to the order shown in the
               diagram below.

    TOL
          Tolerance for singularities in algebraic loops, default:
          200`eps'.

     *Outputs*
    CLSYS
          Resulting closed loop system.

     *Method*

     `sysconnect' internally permutes selected inputs, outputs as shown
     below, closes the loop, and then permutes inputs and outputs back
     to their original order
                           --------------------
           u_1       ----->|                  |----> y_1
                           |        sys       |
                   old u_2 |                  |
          u_2* ---->(+)--->|                  |----->y_2
          (in_idx)   ^     --------------------    | (out_idx)
                     |                             |
                     -------------------------------
     The input that has the summing junction added to it has an *
     added to the end  of the input name.

 -- Function File: [CSYS, ACD, CCD] = syscont (SYS)
     Extract the purely continuous subsystem of an input system.

     *Input*
    SYS
          system data structure.

     *Outputs*
    CSYS
          is the purely continuous input/output connections of SYS

    ACD
    CCD
          connections from discrete states to continuous states,
          discrete states to continuous outputs, respectively.

          returns CSYS empty if no continuous/continous path exists

 -- Function File: [DSYS, ADC, CDC] = sysdisc (SYS)
     *Input*
    SYS
          System data structure.

     *Outputs*
    DSYS
          Purely discrete portion of sys (returned empty if there is no
          purely discrete path from inputs to outputs).

    ADC
    CDC
          Connections from continuous states to discrete states and
          discrete.  outputs, respectively.

 -- Function File: RETSYS = sysdup (ASYS, OUT_IDX, IN_IDX)
     Duplicate specified input/output connections of a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX
    IN_IDX
          indices or names of desired signals (see `sigidx').
          duplicates are made of `y(out_idx(ii))' and `u(in_idx(ii))'.

     *Output*
    RETSYS
          Resulting closed loop system: duplicated i/o names are
          appended with a `"+"' suffix.

     *Method*

     `sysdup' creates copies of selected inputs and outputs as shown
     below.  U1, Y1 is the set of original inputs/outputs, and U2, Y2
     is the set of duplicated inputs/outputs in the order specified in
     IN_IDX, OUT_IDX, respectively
                    ____________________
          u1  ----->|                  |----> y1
                    |       asys       |
          u2 ------>|                  |----->y2
          (in_idx)  -------------------- (out_idx)

 -- Function File: SYS = sysgroup (ASYS, BSYS)
     Combines two systems into a single system.

     *Inputs*
    ASYS
    BSYS
          System data structures.

     *Output*
    SYS
          sys = block diag(asys,bsys)

                   __________________
                   |    ________    |
          u1 ----->|--> | asys |--->|----> y1
                   |    --------    |
                   |    ________    |
          u2 ----->|--> | bsys |--->|----> y2
                   |    --------    |
                   ------------------
                        Ksys
     The function also rearranges the internal state-space
     realization of SYS so that the continuous states come first and
     the discrete states come last.  If there are duplicate names, the
     second name has a unique suffix appended on to the end of the name.

 -- Function File: SYS = sysmult (ASYS, BSYS)
     Compute sys = Asys*Bsys (series connection):
          u   ----------     ----------
          --->|  Bsys  |---->|  Asys  |--->
              ----------     ----------
     A warning occurs if there is direct feed-through from an input
     or a continuous state of BSYS, through a discrete output of BSYS,
     to a continuous state or output in ASYS (system data structure
     does not recognize discrete inputs).

 -- Function File: RETSYS = sysprune (ASYS, OUT_IDX, IN_IDX)
     Extract specified inputs/outputs from a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX
    IN_IDX
          Indices or signal names of the outputs and inputs to be kept
          in the returned system; remaining connections are "pruned"
          off.  May select as [] (empty matrix) to specify all
          outputs/inputs.

               retsys = sysprune (Asys, [1:3,4], "u_1");
               retsys = sysprune (Asys, {"tx", "ty", "tz"}, 4);


     *Output*
    RETSYS
          Resulting system.

                     ____________________
          u1 ------->|                  |----> y1
           (in_idx)  |       Asys       | (out_idx)
          u2 ------->|                  |----| y2
            (deleted)-------------------- (deleted)

 -- Function File: PV = sysreorder (VLEN, LIST)
     *Inputs*
    VLEN
          Vector length.

    LIST
          A subset of `[1:vlen]'.

     *Output*
    PV
          A permutation vector to order elements of `[1:vlen]' in
          `list' to the end of a vector.

     Used internally by `sysconnect' to permute vector elements to their
     desired locations.

 -- Function File: RETSYS = sysscale (SYS, OUTSCALE, INSCALE, OUTNAME,
          INNAME)
     scale inputs/outputs of a system.

     *Inputs*
    SYS
          Structured system.

    OUTSCALE
    INSCALE
          Constant matrices of appropriate dimension.

    OUTNAME
    INNAME
          Lists of strings with the names of respectively outputs and
          inputs.

     *Output*
    RETSYS
          resulting open loop system:
                     -----------    -------    -----------
               u --->| inscale |--->| sys |--->| outscale |---> y
                     -----------    -------    -----------
     If the input names and output names (each a list of strings)
     are not given and the scaling matrices are not square, then
     default names will be given to the inputs and/or outputs.

     A warning message is printed if outscale attempts to add continuous
     system outputs to discrete system outputs; otherwise YD is set
     appropriately in the returned value of SYS.

 -- Function File: SYS = syssub (GSYS, HSYS)
     Return sys = Gsys - Hsys.

     *Method*

     GSYS and HSYS are connected in parallel.  The input vector is
     connected to both systems; the outputs are subtracted.  Returned
     system names are those of GSYS.
                   +--------+
              +--->|  Gsys  |---+
              |    +--------+   |
              |                +|
          u --+                (_)--> y
              |                -|
              |    +--------+   |
              +--->|  Hsys  |---+
                   +--------+

 -- Function File:  ugain (N)
     Creates a system with unity gain, no states.  This trivial system
     is sometimes needed to create arbitrary complex systems from
     simple systems with `buildssic'.  Watch out if you are forming
     sampled systems since `ugain' does not contain a sampling period.

     *See also:* hinfdemo, jet707.

 -- Function File: W = wgt1o (VL, VH, FC)
     State space description of a first order weighting function.

     Weighting function are needed by the H-2/H-infinity design
     procedure.  These function are part of the augmented plant P (see
     `hinfdemo' for an application example).

     *Inputs*
    VL
          Gain at low frequencies.

    VH
          Gain at high frequencies.

    FC
          Corner frequency (in Hz, *not* in rad/sec)

     *Output*
    W
          Weighting function, given in form of a system data structure.

 -- Function File: KSYS = parallel (ASYS, BSYS)
     Forms the parallel connection of two systems.

                       --------------------
                       |      --------    |
              u  ----->|----> | asys |--->|----> y1
                  |    |      --------    |
                  |    |      --------    |
                  |--->|----> | bsys |--->|----> y2
                       |      --------    |
                       --------------------
                            ksys

 -- Function File: [RETSYS, NC, NO] = sysmin (SYS, FLG)
     Returns a minimal (or reduced order) system

     *Inputs*
    SYS
          System data structure

    FLG
          When equal to 0 (default value), returns minimal system, in
          which state names are lost; when equal to 1, returns system
          with physical states removed that are either uncontrollable or
          unobservable (cannot reduce further without discarding
          physical meaning of states).
     *Outputs*
    RETSYS
          Returned system.

    NC
          Number of controllable states in the returned system.

    NO
          Number of observable states in the returned system.

    CFLG
          `is_controllable(retsys)'.

    OFLG
          `is_observable(retsys)'.


File: octave.info,  Node: numerical,  Next: sysprop,  Prev: blockdiag,  Up: Control Theory

33.5 Numerical Functions
========================

 -- Function File: X = are (A, B, C, OPT)
     Solve the Algebraic Riccati Equation
          a' * x + x * a - x * b * x + c = 0

     *Inputs* for identically dimensioned square matrices
    A
          N by N matrix;

    B
          N by N matrix or N by M matrix; in the latter case B is
          replaced by b:=b*b';

    C
          N by N matrix or P by M matrix; in the latter case C is
          replaced by c:=c'*c;

    OPT
          (optional argument; default = `"B"'): String option passed to
          `balance' prior to ordered Schur decomposition.

     *Output*
    X
          solution of the ARE.

     *Method* Laub's Schur method (IEEE Transactions on Automatic
     Control, 1979) is applied to the appropriate Hamiltonian matrix.

     *See also:* balance, dare.

 -- Function File: X = dare (A, B, Q, R, OPT)
     Return the solution, X of the discrete-time algebraic Riccati
     equation
          a' x a - x + a' x b (r + b' x b)^(-1) b' x a + q = 0
     *Inputs*
    A
          N by N matrix;

    B
          N by M matrix;

    Q
          N by N matrix, symmetric positive semidefinite, or a P by N
          matrix, In the latter case q:=q'*q is used;

    R
          M by M, symmetric positive definite (invertible);

    OPT
          (optional argument; default = `"B"'): String option passed to
          `balance' prior to ordered QZ decomposition.

     *Output*
    X
          solution of DARE.

     *Method* Generalized eigenvalue approach (Van Dooren; SIAM J.
     Sci. Stat. Comput., Vol 2) applied  to the appropriate symplectic
     pencil.

     See also: Ran and Rodman, `Stable Hermitian Solutions of Discrete
     Algebraic Riccati Equations', Mathematics of Control, Signals and
     Systems, Vol 5, no 2 (1992), pp 165-194.

     *See also:* balance, are.

 -- Function File: [TVALS, PLIST] = dre (SYS, Q, R, QF, T0, TF, PTOL,
          MAXITS)
     Solve the differential Riccati equation
            -d P/dt = A'P + P A - P B inv(R) B' P + Q
            P(tf) = Qf
     for the LTI system sys.  Solution of standard LTI state feedback
     optimization
            min int(t0, tf) ( x' Q x + u' R u ) dt + x(tf)' Qf x(tf)
     optimal input is
            u = - inv(R) B' P(t) x
     *Inputs*
    SYS
          continuous time system data structure

    Q
          state integral penalty

    R
          input integral penalty

    QF
          state terminal penalty

    T0
    TF
          limits on the integral

    PTOL
          tolerance (used to select time samples; see below); default =
          0.1

    MAXITS
          number of refinement iterations (default=10)
     *Outputs*
    TVALS
          time values at which P(T) is computed

    PLIST
          list values of P(T); PLIST { I } is P(TVALS(I))
     TVALS is selected so that:
          || Plist{i} - Plist{i-1} || < Ptol
     for every I between 2 and length(TVALS).

 -- Function File:  dgram (A, B)
     Return controllability gramian of discrete time system
            x(k+1) = a x(k) + b u(k)

     *Inputs*
    A
          N by N matrix

    B
          N by M matrix

     *Output*
    M
          N by N matrix, satisfies
                a m a' - m + b*b' = 0

 -- Function File:  dlyap (A, B)
     Solve the discrete-time Lyapunov equation

     *Inputs*
    A
          N by N matrix;

    B
          Matrix: N by N, N by M, or P by N.

     *Output*
    X
          matrix satisfying appropriate discrete time Lyapunov equation.

     Options:
        * B is square: solve `a x a' - x + b = 0'

        * B is not square: X satisfies either
               a x a' - x + b b' = 0
          or
               a' x a - x + b' b = 0,
          whichever is appropriate.

     *Method* Uses Schur decomposition method as in Kitagawa, `An
     Algorithm for Solving the Matrix Equation X = F X F' + S',
     International Journal of Control, Volume 25, Number 5, pages
     745-753 (1977).

     Column-by-column solution method as suggested in Hammarling,
     `Numerical Solution of the Stable, Non-Negative Definite Lyapunov
     Equation', IMA Journal of Numerical Analysis, Volume 2, pages
     303-323 (1982).

 -- Function File:  gram (A, B)
     Return controllability gramian M of the continuous time system
     dx/dt = a x + b u.

     M satisfies a m + m a' + b b' = 0.

 -- Function File:  lyap (A, B, C)
 -- Function File:  lyap (A, B)
     Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart
     algorithm (Communications of the ACM, 1972).

     If A, B, and C are specified, then `lyap' returns the solution of
     the  Sylvester equation
              a x + x b + c = 0
     If only `(a, b)' are specified, then `lyap' returns the solution
     of the Lyapunov equation
              a' x + x a + b = 0
     If B is not square, then `lyap' returns the solution of either
              a' x + x a + b' b = 0
     or
              a x + x a' + b b' = 0
     whichever is appropriate.

     Solves by using the Bartels-Stewart algorithm (1972).

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

     A and B must be real matrices.

     `qzval' is obsolete; use `qz' instead.

 -- Function File: Y = zgfmul (A, B, C, D, X)
     Compute product of ZGEP incidence matrix F with vector X.  Used by
     `zgepbal' (in `zgscal') as part of generalized conjugate gradient
     iteration.

 -- Function File:  zgfslv (N, M, P, B)
     Solve system of equations for dense zgep problem.

 -- Function File: ZZ = zginit (A, B, C, D)
     Construct right hand side vector ZZ for the zero-computation
     generalized eigenvalue problem balancing procedure.  Called by
     `zgepbal'.

 -- Function File:  zgreduce (SYS, MEPS)
     Implementation of procedure REDUCE in (Emami-Naeini and Van Dooren,
     Automatica, # 1982).

 -- Function File: [NONZ, ZER] = zgrownorm (MAT, MEPS)
     Return NONZ = number of rows of MAT whose two norm exceeds MEPS,
     and ZER = number of rows of mat whose two norm is less than MEPS.

 -- Function File: X = zgscal (F, Z, N, M, P)
     Generalized conjugate gradient iteration to solve zero-computation
     generalized eigenvalue problem balancing equation fx=z; called by
     `zgepbal'.

 -- Function File: [a, b] = zgsgiv (C, S, A, B)
     Apply givens rotation c,s to row vectors A, B.  No longer used in
     zero-balancing (__zgpbal__); kept for backward compatibility.

 -- Function File: X = zgshsr (Y)
     Apply householder vector based on e^(m) to column vector Y.
     Called by `zgfslv'.

   *References*
*ZGEP*
     Hodel, `Computation of Zeros with Balancing', 1992, Linear Algebra
     and its Applications

**Generalized CG**
     Golub and Van Loan, `Matrix Computations, 2nd ed' 1989.


File: octave.info,  Node: sysprop,  Next: systime,  Prev: numerical,  Up: Control Theory

33.6 System Analysis-Properties
===============================

 -- Function File:  analdemo ()
     Octave Controls toolbox demo: State Space analysis demo

 -- Function File: [N, M, P] = abcddim (A, B, C, D)
     Check for compatibility of the dimensions of the matrices defining
     the linear system [A, B, C, D] corresponding to

          dx/dt = a x + b u
          y = c x + d u

     or a similar discrete-time system.

     If the matrices are compatibly dimensioned, then `abcddim' returns

    N
          The number of system states.

    M
          The number of system inputs.

    P
          The number of system outputs.

     Otherwise `abcddim' returns N = M = P = -1.

     Note: n = 0 (pure gain block) is returned without warning.

     *See also:* is_abcd.

 -- Function File:  ctrb (SYS, B)
 -- Function File:  ctrb (A, B)
     Build controllability matrix:
                       2       n-1
          Qs = [ B AB A B ... A   B ]

     of a system data structure or the pair (A, B).

     `ctrb' forms the controllability matrix.  The numerical properties
     of `is_controllable' are much better for controllability tests.

 -- Function File:  h2norm (SYS)
     Computes the H-2 norm of a system data structure (continuous time
     only).

     Reference: Doyle, Glover, Khargonekar, Francis, `State-Space
     Solutions to Standard' `H-2 and H-infinity' `Control Problems',
     IEEE TAC August 1989.

 -- Function File: [G, GMIN, GMAX] = hinfnorm (SYS, TOL, GMIN, GMAX,
          PTOL)
     Computes the H-infinity norm of a system data structure.

     *Inputs*
    SYS
          system data structure

    TOL
          H-infinity norm search tolerance (default: 0.001)

    GMIN
          minimum value for norm search (default: 1e-9)

    GMAX
          maximum value for norm search (default: 1e+9)

    PTOL
          pole tolerance:
             * if sys is continuous, poles with  |real(pole))| <
               ptol*||H||  (H is appropriate Hamiltonian) are
               considered to be on the imaginary axis.

             * if sys is discrete, poles with |abs(pole)-1| <
               ptol*||[s1,s2]|| (appropriate symplectic pencil) are
               considered to be on the unit circle.

             * Default value: 1e-9

     *Outputs*
    G
          Computed gain, within TOL of actual gain.  G is returned as
          Inf if the system is unstable.

    GMIN
    GMAX
          Actual system gain lies in the interval [GMIN, GMAX].

     References: Doyle, Glover, Khargonekar, Francis, `State-space
     solutions to standard' `H-2 and H-infinity' `control problems',
     IEEE TAC August 1989; Iglesias and Glover, `State-Space approach
     to discrete-time' `H-infinity' `control', Int. J. Control, vol 54,
     no. 5, 1991; Zhou, Doyle, Glover, `Robust and Optimal Control',
     Prentice-Hall, 1996.

 -- Function File:  obsv (SYS, C)
 -- Function File:  obsv (A, C)
     Build observability matrix:
               | C        |
               | CA       |
          Qb = | CA^2     |
               | ...      |
               | CA^(n-1) |
     of a system data structure or the pair (A, C).

     The numerical properties of `is_observable' are much better for
     observability tests.

 -- Function File: [ZER, POL] = pzmap (SYS)
     Plots the zeros and poles of a system in the complex plane.

     *Input*
    SYS
          System data structure.

     *Outputs*
    POL

    ZER
          if omitted, the poles and zeros are plotted on the screen.
          otherwise, POL and ZER are returned as the system poles and
          zeros (see `sys2zp' for a preferable function call).

 -- Function File: RETVAL = is_abcd (A, B, C, D)
     Returns RETVAL = 1 if the dimensions of A, B, C, D are compatible,
     otherwise RETVAL = 0 with an  appropriate diagnostic message
     printed to the screen.  The matrices B, C, or D may be omitted.

     *See also:* abcddim.

 -- Function File: [RETVAL, U] = is_controllable (SYS, TOL)
 -- Function File: [RETVAL, U] = is_controllable (A, B, TOL)
     Logical check for system controllability.

     *Inputs*
    SYS
          system data structure

    A
    B
          N by N, N by M matrices, respectively

    TOL
          optional roundoff parameter.  Default value: `10*eps'

     *Outputs*
    RETVAL
          Logical flag; returns true (1) if the system SYS or the pair
          (A, B) is controllable, whichever was passed as input
          arguments.

    U
          U is an orthogonal basis of the controllable subspace.

     *Method* Controllability is determined by applying Arnoldi
     iteration with complete re-orthogonalization to obtain an
     orthogonal basis of the Krylov subspace
          span ([b,a*b,...,a^{n-1}*b]).
     The Arnoldi iteration is executed with `krylov' if the system has
     a single input; otherwise a block Arnoldi iteration is performed
     with `krylovb'.

     *See also:* size, rows, columns, length, ismatrix, isscalar,
     isvector is_observable, is_stabilizable, is_detectable, krylov,
     krylovb.

 -- Function File: RETVAL = is_detectable (A, C, TOL, DFLG)
 -- Function File: RETVAL = is_detectable (SYS, TOL)
     Test for detactability (observability of unstable modes) of (A, C).

     Returns 1 if the system A or the pair (A, C) is detectable, 0 if
     not, and -1 if the system has unobservable modes at the imaginary
     axis (unit circle for discrete-time systems).

     *See* `is_stabilizable' for detailed description of arguments and
     computational method.

     *See also:* is_stabilizable, size, rows, columns, length, ismatrix,
     isscalar, isvector.

 -- Function File: [RETVAL, DGKF_STRUCT ] = is_dgkf (ASYS, NU, NY, TOL )
     Determine whether a continuous time state space system meets
     assumptions of DGKF algorithm.  Partitions system into:
          [dx/dt]   [A  | Bw  Bu  ][w]
          [ z   ] = [Cz | Dzw Dzu ][u]
          [ y   ]   [Cy | Dyw Dyu ]
     or similar discrete-time system.  If necessary, orthogonal
     transformations QW, QZ and nonsingular transformations RU, RY are
     applied to respective vectors W, Z, U, Y in order to satisfy DGKF
     assumptions.  Loop shifting is used if DYU block is nonzero.

     *Inputs*
    ASYS
          system data structure

    NU
          number of controlled inputs

    NY
          number of measured outputs

    TOL
          threshold for 0; default: 200*`eps'.
     *Outputs*
    RETVAL
          true(1) if system passes check, false(0) otherwise

    DGKF_STRUCT
          data structure of `is_dgkf' results.  Entries:
         NW
         NZ
               dimensions of W, Z

         A
               system A matrix

         BW
               (N x NW) QW-transformed disturbance input matrix

         BU
               (N x NU) RU-transformed controlled input matrix;

               B = [Bw Bu]

         CZ
               (NZ x N) Qz-transformed error output matrix

         CY
               (NY x N) RY-transformed measured output matrix

               C = [Cz; Cy]

         DZU

         DYW
               off-diagonal blocks of transformed system D matrix that
               enter Z, Y from U, W respectively

         RU
               controlled input transformation matrix

         RY
               observed output transformation matrix

         DYU_NZ
               nonzero if the DYU block is nonzero.

         DYU
               untransformed DYU block

         DFLG
               nonzero if the system is discrete-time
     `is_dgkf' exits with an error if the system is mixed
     discrete/continuous.

     *References*
    *[1]*
          Doyle, Glover, Khargonekar, Francis, `State Space Solutions
          to Standard' `H-2 and H-infinity' `Control Problems', IEEE
          TAC August 1989.

    *[2]*
          Maciejowksi, J.M., `Multivariable Feedback Design',
          Addison-Wesley, 1989.

 -- Function File: DIGITAL = is_digital (SYS, EFLG)
     Return nonzero if system is digital.

     *Inputs*
    SYS
          System data structure.

    EFLG
          When equal to 0 (default value), exits with an error if the
          system is mixed (continuous and discrete components); when
          equal to 1, print a warning if the system is mixed
          (continuous and discrete); when equal to 2, operate silently.

     *Output*
    DIGITAL
          When equal to 0, the system is purely continuous; when equal
          to 1, the system is purely discrete; when equal to -1, the
          system is mixed continuous and discrete.
     Exits with an error if SYS is a mixed (continuous and discrete)
     system.

 -- Function File: [RETVAL, U] = is_observable (A, C, TOL)
 -- Function File: [RETVAL, U] = is_observable (SYS, TOL)
     Logical check for system observability.

     Default: tol = `tol = 10*norm(a,'fro')*eps'

     Returns 1 if the system SYS or the pair (A, C) is observable, 0 if
     not.

     See `is_controllable' for detailed description of arguments and
     default values.

     *See also:* size, rows, columns, length, ismatrix, isscalar,
     isvector.

 -- Function File:  is_sample (TS)
     Return true if TS is a valid sampling time (real, scalar, > 0).

 -- Function File:  is_siso (SYS)
     Returns nonzero if the system data structure SYS is single-input,
     single-output.

 -- Function File: RETVAL = is_stabilizable (SYS, TOL)
 -- Function File: RETVAL = is_stabilizable (A, B, TOL, DFLG)
     Logical check for system stabilizability (i.e., all unstable modes
     are controllable).  Returns 1 if the system is stabilizable, 0 if
     the system is not stabilizable, -1 if the system has non
     stabilizable modes at the imaginary axis (unit circle for
     discrete-time systems.

     Test for stabilizability is performed via Hautus Lemma. If DFLG!=0
     assume that discrete-time matrices (a,b) are supplied.

     *See also:* size, rows, columns, length, ismatrix, isscalar,
     isvector is_observable, is_stabilizable, is_detectable.

 -- Function File:  is_signal_list (MYLIST)
     Return true if MYLIST is a list of individual strings.

 -- Function File:  is_stable (A, TOL, DFLG)
 -- Function File:  is_stable (SYS, TOL)
     Returns 1 if the matrix A or the system SYS is stable, or 0 if not.

     *Inputs*
    TOL
          is a roundoff parameter, set to 200*`eps' if omitted.

    DFLG
          Digital system flag (not required for system data structure):
         `DFLG != 0'
               stable if eig(a) is in the unit circle

         `DFLG == 0'
               stable if eig(a) is in the open LHP (default)


     *See also:* size, rows, columns, length, ismatrix, isscalar,
     isvector is_observable, is_stabilizable, is_detectable, krylov,
     krylovb.


File: octave.info,  Node: systime,  Next: sysfreq,  Prev: sysprop,  Up: Control Theory

33.7 System Analysis-Time Domain
================================

 -- Function File:  c2d (SYS, OPT, T)
 -- Function File:  c2d (SYS, T)
     Converts the system data structure describing:
          .
          x = Ac x + Bc u
     into a discrete time equivalent model:
          x[n+1] = Ad x[n] + Bd u[n]
     via the matrix exponential or bilinear transform.

     *Inputs*
    SYS
          system data structure (may have both continuous time and
          discrete time subsystems)

    OPT
          string argument; conversion option (optional argument; may be
          omitted as shown above)
         `"ex"'
               use the matrix exponential (default)

         `"bi"'
               use the bilinear transformation
                        2(z-1)
                    s = -----
                        T(z+1)
               FIXME: This option exits with an error if SYS is not
               purely continuous. (The `ex' option can handle mixed
               systems.)

         `"matched"'
               Use the matched pole/zero equivalent transformation
               (currently only works for purely continuous SISO
               systems).

    T
          sampling time; required if SYS is purely continuous.

          *Note* that if the second argument is not a string, `c2d()'
          assumes that the second argument is T and performs
          appropriate argument checks.

     *Output*
    DSYS
          Discrete time equivalent via zero-order hold, sample each T
          sec.

     This function adds the suffix  `_d' to the names of the new
     discrete states.

 -- Function File:  d2c (SYS, TOL)
 -- Function File:  d2c (SYS, OPT)
     Convert a discrete (sub)system into a purely continuous one.  The
     sampling time used is `sysgettsam(SYS)'.

     *Inputs*
    SYS
          system data structure with discrete components

    TOL
          Scalar value.  Tolerance for convergence of default `"log"'
          option (see below)

    OPT
          conversion option.  Choose from:
         `"log"'
               (default) Conversion is performed via a matrix logarithm.
               Due to some problems with this computation, it is
               followed by a steepest descent algorithm to identify
               continuous time A, B, to get a better fit to the
               original data.

               If called as `d2c (SYS, TOL)', with TOL positive scalar,
               the `"log"' option is used.  The default value for TOL
               is `1e-8'.

         `"bi"'
               Conversion is performed via bilinear transform z = (1 +
               s T / 2)/(1 - s T / 2) where T is the system sampling
               time (see `sysgettsam').

               FIXME: bilinear option exits with an error if SYS is not
               purely discrete
     *Output*
    CSYS
          continuous time system (same dimensions and signal names as
          in SYS).

 -- Function File: [DSYS, FIDX] = dmr2d (SYS, IDX, SPREFIX, TS2, CUFLG)
     convert a multirate digital system to a single rate digital system
     states specified by IDX, SPREFIX are sampled at TS2, all others
     are assumed sampled at TS1 = `sysgettsam (SYS)'.

     *Inputs*
    SYS
          discrete time system; `dmr2d' exits with an error if SYS is
          not discrete

    IDX
          indices or names of states with sampling time
          `sysgettsam(SYS)' (may be empty); see `cellidx'

    SPREFIX
          list of string prefixes of states with sampling time
          `sysgettsam(SYS)' (may be empty)

    TS2
          sampling time of states not specified by IDX, SPREFIX must be
          an integer multiple of `sysgettsam(SYS)'

    CUFLG
          "constant u flag" if CUFLG is nonzero then the system inputs
          are assumed to be constant over the revised sampling interval
          TS2.  Otherwise, since the inputs can change during the
          interval T in [k ts2, (k+1) ts2], an additional set of inputs
          is included in the revised B matrix so that these intersample
          inputs may be included in the single-rate system.  default
          CUFLG = 1.

     *Outputs*
    DSYS
          equivalent discrete time system with sampling time TS2.

          The sampling time of sys is updated to TS2.

          if CUFLG=0 then a set of additional inputs is added to the
          system with suffixes _d1, ..., _dn to indicate their delay
          from the starting time k TS2, i.e.  u = [u_1; u_1_d1; ...,
          u_1_dn] where u_1_dk is the input k*ts1 units of time after
          u_1 is sampled. (TS1 is the original sampling time of the
          discrete time system and TS2 = (n+1)*ts1)

    FIDX
          indices of "formerly fast" states specified by IDX and
          SPREFIX; these states are updated to the new (slower)
          sampling interval TS2.

     *WARNING* Not thoroughly tested yet; especially when CUFLG == 0.

 -- Function File:  damp (P, TSAM)
     Displays eigenvalues, natural frequencies and damping ratios of
     the eigenvalues of a matrix P or the A matrix of a system P,
     respectively.  If P is a system, TSAM must not be specified.  If P
     is a matrix and TSAM is specified, eigenvalues of P are assumed to
     be in Z-domain.

     *See also:* eig.

 -- Function File:  dcgain (SYS, TOL)
     Returns dc-gain matrix. If dc-gain is infinite an empty matrix is
     returned.  The argument TOL is an optional tolerance for the
     condition number of the A Matrix in SYS (default TOL = 1.0e-10)

 -- Function File: [Y, T] = impulse (SYS, INP, TSTOP, N)
     Impulse response for a linear system.  The system can be discrete
     or multivariable (or both).  If no output arguments are specified,
     `impulse' produces a plot or the impulse response data for system
     SYS.

     *Inputs*
    SYS
          System data structure.

    INP
          Index of input being excited

    TSTOP
          The argument TSTOP (scalar value) denotes the time when the
          simulation should end.

    N
          the number of data values.

          Both parameters TSTOP and N can be omitted and will be
          computed from the eigenvalues of the A Matrix.
     *Outputs*
    Y
          Values of the impulse response.

    T
          Times of the impulse response.


     *See also:* step, __stepimp__.

 -- Function File: [Y, T] = step (SYS, INP, TSTOP, N)
     Step response for a linear system.  The system can be discrete or
     multivariable (or both).  If no output arguments are specified,
     `step' produces a plot or the step response data for system SYS.

     *Inputs*
    SYS
          System data structure.

    INP
          Index of input being excited

    TSTOP
          The argument TSTOP (scalar value) denotes the time when the
          simulation should end.

    N
          the number of data values.

          Both parameters TSTOP and N can be omitted and will be
          computed from the eigenvalues of the A Matrix.
     *Outputs*
    Y
          Values of the step response.

    T
          Times of the step response.

     When invoked with the output parameter Y the plot is not displayed.

     *See also:* impulse, __stepimp__.


File: octave.info,  Node: sysfreq,  Next: cacsd,  Prev: systime,  Up: Control Theory

33.8 System Analysis-Frequency Domain
=====================================

*Demonstration/tutorial script*

 -- Function File:  frdemo ()
     Octave Control Toolbox demo: Frequency Response demo.

 -- Function File: [MAG, PHASE, W] = bode (SYS, W, OUT_IDX, IN_IDX)
     If no output arguments are given: produce Bode plots of a system;
     otherwise, compute the frequency response of a system data
     structure

     *Inputs*
    SYS
          a system data structure (must be either purely continuous or
          discrete; see is_digital)

    W
          frequency values for evaluation.

          if SYS is continuous, then bode evaluates G(jw) where G(s) is
          the system transfer function.

          if SYS is discrete, then bode evaluates G(`exp'(jwT)), where
             * T is the system sampling time

             * G(z) is the system transfer function.

          *Default* the default frequency range is selected as follows:
          (These steps are *not* performed if W is specified)
            1. via routine __bodquist__, isolate all poles and zeros
               away from W=0 (JW=0 or `exp'(jwT)=1) and select the
               frequency range based on the breakpoint locations of the
               frequencies.

            2. if SYS is discrete time, the frequency range is limited
                           to jwT in [0,2 pi /T]

            3. A "smoothing" routine is used to ensure that the plot
               phase does not change excessively from point to point
               and that singular points (e.g., crossovers from +/- 180)
               are accurately shown.


    OUT_IDX
    IN_IDX
          The names or indices of outputs and inputs to be used in the
          frequency response.  See `sysprune'.

          *Example*
               bode(sys,[],"y_3", {"u_1","u_4"});
     *Outputs*
    MAG
    PHASE
          the magnitude and phase of the frequency response G(jw) or
          G(`exp'(jwT)) at the selected frequency values.

    W
          the vector of frequency values used

       1. If no output arguments are given, e.g.,
               bode(sys);
          bode plots the results to the screen.  Descriptive labels are
          automatically placed.

          Failure to include a concluding semicolon will yield some
          garbage being printed to the screen (`ans = []').

       2. If the requested plot is for an MIMO system, mag is set to
          ||G(jw)|| or ||G(`exp'(jwT))|| and phase information is not
          computed.

 -- Function File: [WMIN, WMAX] = bode_bounds (ZER, POL, DFLG, TSAM)
     Get default range of frequencies based on cutoff frequencies of
     system poles and zeros.  Frequency range is the interval [10^WMIN,
     10^WMAX]

     Used internally in `__freqresp__' (`bode', `nyquist')

 -- Function File:  freqchkw (W)
     Used by `__freqresp__' to check that input frequency vector W is
     valid.  Returns boolean value.

 -- Function File: OUT = ltifr (A, B, W)
 -- Function File: OUT = ltifr (SYS, W)
     Linear time invariant frequency response of single-input systems.

     *Inputs*
    A
    B
          coefficient matrices of dx/dt = A x + B u

    SYS
          system data structure

    W
          vector of frequencies
     *Output*
    OUT
          frequency response, that is:

                                     -1
                       G(s) = (jw I-A) B
     for complex frequencies s = jw.

 -- Function File: [REALP, IMAGP, W] = nyquist (SYS, W, OUT_IDX,
          IN_IDX, ATOL)
 -- Function File:  nyquist (SYS, W, OUT_IDX, IN_IDX, ATOL)
     Produce Nyquist plots of a system; if no output arguments are
     given, Nyquist plot is printed to the screen.

     Compute the frequency response of a system.

     *Inputs* (pass as empty to get default values)
    SYS
          system data structure (must be either purely continuous or
          discrete; see `is_digital')

    W
          frequency values for evaluation.  If sys is continuous, then
          bode evaluates G(JW); if sys is discrete, then bode evaluates
          G(exp(JWT)), where T is the system sampling time.

    DEFAULT
          the default frequency range is selected as follows: (These
          steps are *not* performed if W is specified)
            1. via routine `__bodquist__', isolate all poles and zeros
               away from W=0 (JW=0 or exp(JWT)=1) and select the
               frequency range based on the breakpoint locations of the
               frequencies.

            2. if SYS is discrete time, the frequency range is limited
               to JWT in [0,2p*pi]

            3. A "smoothing" routine is used to ensure that the plot
               phase does not change excessively from point to point
               and that singular points (e.g., crossovers from +/- 180)
               are accurately shown.

    ATOL
          for interactive nyquist plots: atol is a change-in-slope
          tolerance for the of asymptotes (default = 0; 1e-2 is a good
          choice).  This allows the user to "zoom in" on portions of
          the Nyquist plot too small to be seen with large asymptotes.
     *Outputs*
    REALP
    IMAGP
          the real and imaginary parts of the frequency response G(jw)
          or G(exp(jwT)) at the selected frequency values.

    W
          the vector of frequency values used

     If no output arguments are given, nyquist plots the results to the
     screen.  If ATOL != 0 and asymptotes are detected then the user is
     asked interactively if they wish to zoom in (remove asymptotes)
     Descriptive labels are automatically placed.

     Note: if the requested plot is for an MIMO system, a warning
     message is presented; the returned information is of the magnitude
     ||G(jw)|| or ||G(exp(jwT))|| only; phase information is not
     computed.

 -- Function File: [MAG, PHASE, W] = nichols (SYS, W, OUTPUTS, INPUTS)
     Produce Nichols plot of a system.

     *Inputs*
    SYS
          System data structure (must be either purely continuous or
          discrete; see `is_digital').

    W
          Frequency values for evaluation.
             * if sys is continuous, then nichols evaluates G(jw).

             * if sys is discrete, then nichols evaluates G(exp(jwT)),
               where T=SYS. TSAM is the system sampling time.

             * the default frequency range is selected as follows (These
                     steps are *not* performed if W is specified):
                 1. via routine `__bodquist__', isolate all poles and
                    zeros away from W=0 (jw=0 or exp(jwT)=1) and select
                    the frequency range based on the breakpoint
                    locations of the frequencies.

                 2. if sys is discrete time, the frequency range is
                    limited to jwT in [0,2p*pi].

                 3. A "smoothing" routine is used to ensure that the
                    plot phase does not change excessively from point
                    to point and that singular points (e.g., crossovers
                    from +/- 180) are accurately shown.

    OUTPUTS
    INPUTS
          the names or indices of the output(s) and input(s) to be used
          in the frequency response; see `sysprune'.
     *Outputs*
    MAG
    PHASE
          The magnitude and phase of the frequency response G(jw) or
          G(exp(jwT)) at the selected frequency values.

    W
          The vector of frequency values used.
     If no output arguments are given, `nichols' plots the results to
     the screen.  Descriptive labels are automatically placed. See
     `xlabel', `ylabel', and `title'.

     Note: if the requested plot is for an MIMO system, MAG is set to
     ||G(jw)|| or ||G(exp(jwT))|| and phase information is not computed.

 -- Function File: [ZER, GAIN] = tzero (A, B, C, D, OPT)
 -- Function File: [ZER, GAIN] = tzero (SYS, OPT)
     Compute transmission zeros of a continuous system:
          .
          x = Ax + Bu
          y = Cx + Du
     or of a discrete one:
          x(k+1) = A x(k) + B u(k)
          y(k)   = C x(k) + D u(k)

     *Outputs*
    ZER
          transmission zeros of the system

    GAIN
          leading coefficient (pole-zero form) of SISO transfer function
          returns gain=0 if system is multivariable
     *References*
       1. Emami-Naeini and Van Dooren, Automatica, 1982.

       2. Hodel, `Computation of Zeros with Balancing', 1992 Lin. Alg.
          Appl.

 -- Function File: ZR = tzero2 (A, B, C, D, BAL)
     Compute the transmission zeros of A, B, C, D.

     BAL = balancing option (see balance); default is `"B"'.

     Needs to incorporate `mvzero' algorithm to isolate finite zeros;
     use `tzero' instead.


File: octave.info,  Node: cacsd,  Next: misc,  Prev: sysfreq,  Up: Control Theory

33.9 Controller Design
======================

 -- Function File:  dgkfdemo ()
     Octave Controls toolbox demo: H-2/H-infinity options demos.

 -- Function File:  hinfdemo ()
     H-infinity design demos for continuous SISO and MIMO systems and a
     discrete system.  The SISO system is difficult to control because
     it is non-minimum-phase and unstable. The second design example
     controls the `jet707' plant, the linearized state space model of a
     Boeing 707-321 aircraft at V=80 m/s (M = 0.26, GA0 = -3 deg,
     ALPHA0 = 4 deg, KAPPA = 50 deg).  Inputs: (1) thrust and (2)
     elevator angle Outputs: (1) airspeed and (2) pitch angle. The
     discrete system is a stable and second order.

    SISO plant:
                               s - 2
                    G(s) = --------------
                           (s + 2)(s - 1)


                                             +----+
                        -------------------->| W1 |---> v1
                    z   |                    +----+
                    ----|-------------+
                        |             |
                        |    +---+    v   y  +----+
                      u *--->| G |--->O--*-->| W2 |---> v2
                        |    +---+       |   +----+
                        |                |
                        |    +---+       |
                        -----| K |<-------
                             +---+

               min || T   ||
                       vz   infty

          W1 und W2 are the robustness and performance weighting
          functions.

    MIMO plant:
          The optimal controller minimizes the H-infinity norm of the
          augmented plant P (mixed-sensitivity problem):
                    w
                     1 -----------+
                                  |                   +----+
                              +---------------------->| W1 |----> z1
                    w         |   |                   +----+
                     2 ------------------------+
                              |   |            |
                              |   v   +----+   v      +----+
                           +--*-->o-->| G  |-->o--*-->| W2 |---> z2
                           |          +----+      |   +----+
                           |                      |
                           ^                      v
                           u                       y (to K)
                        (from controller K)

                                 +    +           +    +
                                 | z  |           | w  |
                                 |  1 |           |  1 |
                                 | z  | = [ P ] * | w  |
                                 |  2 |           |  2 |
                                 | y  |           | u  |
                                 +    +           +    +

    Discrete system:
          This is not a true discrete design. The design is carried out
          in continuous time while the effect of sampling is described
          by a bilinear transformation of the sampled system.  This
          method works quite well if the sampling period is "small"
          compared to the plant time constants.

    The continuous plant:
                                  1
                    G (s) = --------------
                     k      (s + 2)(s + 1)

          is discretised with a ZOH (Sampling period = TS = 1 second):

                              0.199788z + 0.073498
                    G(z) = --------------------------
                           (z - 0.36788)(z - 0.13534)


                                             +----+
                        -------------------->| W1 |---> v1
                    z   |                    +----+
                    ----|-------------+
                        |             |
                        |    +---+    v      +----+
                        *--->| G |--->O--*-->| W2 |---> v2
                        |    +---+       |   +----+
                        |                |
                        |    +---+       |
                        -----| K |<-------
                             +---+

               min || T   ||
                       vz   infty
          W1 and W2 are the robustness and performance weighting
          functions.

 -- Function File: [L, M, P, E] = dlqe (A, G, C, SIGW, SIGV, Z)
     Construct the linear quadratic estimator (Kalman filter) for the
     discrete time system

          x[k+1] = A x[k] + B u[k] + G w[k]
            y[k] = C x[k] + D u[k] + v[k]

     where W, V are zero-mean gaussian noise processes with respective
     intensities `SIGW = cov (W, W)' and `SIGV = cov (V, V)'.

     If specified, Z is `cov (W, V)'.  Otherwise `cov (W, V) = 0'.

     The observer structure is

          z[k|k] = z[k|k-1] + L (y[k] - C z[k|k-1] - D u[k])
          z[k+1|k] = A z[k|k] + B u[k]

     The following values are returned:

    L
          The observer gain, (A - ALC).  is stable.

    M
          The Riccati equation solution.

    P
          The estimate error covariance after the measurement update.

    E
          The closed loop poles of (A - ALC).

 -- Function File: [K, P, E] = dlqr (A, B, Q, R, Z)
     Construct the linear quadratic regulator for the discrete time
     system

          x[k+1] = A x[k] + B u[k]

     to minimize the cost functional

          J = Sum (x' Q x + u' R u)

     Z omitted or

          J = Sum (x' Q x + u' R u + 2 x' Z u)

     Z included.

     The following values are returned:

    K
          The state feedback gain, (A - BK) is stable.

    P
          The solution of algebraic Riccati equation.

    E
          The closed loop poles of (A - BK).

 -- Function File: [LP, LF, P, Z] = dkalman (A, G, C, QW, RV, S)
     Construct the linear quadratic estimator (Kalman predictor) for the
     discrete time system

          x[k+1] = A x[k] + B u[k] + G w[k]
            y[k] = C x[k] + D u[k] + v[k]

     where W, V are zero-mean gaussian noise processes with respective
     intensities `QW = cov (W, W)' and `RV = cov (V, V)'.

     If specified, S is `cov (W, V)'.  Otherwise `cov (W, V) = 0'.

     The observer structure is

          x[k+1|k] = A x[k|k-1] + B u[k] + LP (y[k] - C x[k|k-1] - D u[k])
          x[k|k] = x[k|k-1] + LF (y[k] - C x[k|k-1] - D u[k])

     The following values are returned:

    LP
          The predictor gain, (A - LP C) is stable.

    LF
          The filter gain.

    P
          The Riccati solution.

          P = E [(x - x[n|n-1])(x - x[n|n-1])']

    Z
          The updated error covariance matrix.

          Z = E [(x - x[n|n])(x - x[n|n])']

 -- Function File: [K, GAIN, KC, KF, PC, PF] =  h2syn (ASYS, NU, NY,
          TOL)
     Design H-2 optimal controller per procedure in Doyle, Glover,
     Khargonekar, Francis, `State-Space Solutions to Standard' `H-2 and
     H-infinity' `Control Problems', IEEE TAC August 1989.

     Discrete-time control per Zhou, Doyle, and Glover, `Robust and
     optimal control', Prentice-Hall, 1996.

     *Inputs*
    ASYS
          system data structure (see ss, sys2ss)
             * controller is implemented for continuous time systems

             * controller is *not* implemented for discrete time systems

    NU
          number of controlled inputs

    NY
          number of measured outputs

    TOL
          threshold for 0.  Default: 200*`eps'

     *Outputs*
    K
          system controller

    GAIN
          optimal closed loop gain

    KC
          full information control (packed)

    KF
          state estimator (packed)

    PC
          ARE solution matrix for regulator subproblem

    PF
          ARE solution matrix for filter subproblem

 -- Function File: K = hinf_ctr (DGS, F, H, Z, G)
     Called by `hinfsyn' to compute the H-infinity optimal controller.

     *Inputs*
    DGS
          data structure returned by `is_dgkf'

    F
    H
          feedback and filter gain (not partitioned)

    G
          final gamma value
     *Outputs*
    K
          controller (system data structure)

     Do not attempt to use this at home; no argument checking performed.

 -- Function File: [K, G, GW, XINF, YINF] = hinfsyn (ASYS, NU, NY,
          GMIN, GMAX, GTOL, PTOL, TOL)
     *Inputs* input system is passed as either
    ASYS
          system data structure (see `ss', `sys2ss')
             * controller is implemented for continuous time systems

             * controller is *not* implemented for discrete time
               systems  (see bilinear transforms in `c2d', `d2c')

    NU
          number of controlled inputs

    NY
          number of measured outputs

    GMIN
          initial lower bound on H-infinity optimal gain

    GMAX
          initial upper bound on H-infinity Optimal gain.

    GTOL
          Gain threshold.  Routine quits when GMAX/GMIN < 1+tol.

    PTOL
          poles with `abs(real(pole))' < ptol*||H|| (H is appropriate
          Hamiltonian) are considered to be on the imaginary axis.
          Default: 1e-9.

    TOL
          threshold for 0.  Default: 200*`eps'.

          GMAX, MIN, TOL, and TOL must all be postive scalars.
     *Outputs*
    K
          System controller.

    G
          Designed gain value.

    GW
          Closed loop system.

    XINF
          ARE solution matrix for regulator subproblem.

    YINF
          ARE solution matrix for filter subproblem.

     References:
       1. Doyle, Glover, Khargonekar, Francis, `State-Space Solutions
          to Standard' `H-2 and H-infinity' `Control Problems', IEEE
          TAC August 1989.

       2. Maciejowksi, J.M., `Multivariable feedback design',
          Addison-Wesley, 1989, ISBN 0-201-18243-2.

       3. Keith Glover and John C. Doyle, `State-space formulae for all
          stabilizing controllers that satisfy an' `H-infinity-norm'
          `bound and relations to risk sensitivity', Systems & Control
          Letters 11, Oct. 1988, pp 167-172.

 -- Function File: [RETVAL, PC, PF] = hinfsyn_chk (A, B1, B2, C1, C2,
          D12, D21, G, PTOL)
     Called by `hinfsyn' to see if gain G satisfies conditions in
     Theorem 3 of Doyle, Glover, Khargonekar, Francis, `State Space
     Solutions to Standard' `H-2 and H-infinity' `Control Problems',
     IEEE TAC August 1989.

     *Warning:* do not attempt to use this at home; no argument
     checking performed.

     *Inputs*

     As returned by `is_dgkf', except for:
    G
          candidate gain level

    PTOL
          as in `hinfsyn'

     *Outputs*
    RETVAL
          1 if g exceeds optimal Hinf closed loop gain, else 0

    PC
          solution of "regulator" H-infinity ARE

    PF
          solution of "filter" H-infinity ARE
     Do not attempt to use this at home; no argument checking performed.

 -- Function File: [XINF, X_HA_ERR] = hinfsyn_ric (A, BB, C1, D1DOT, R,
          PTOL)
     Forms
          xx = ([bb; -c1'*d1dot]/r) * [d1dot'*c1 bb'];
          Ha = [a 0*a; -c1'*c1 - a'] - xx;
     and solves associated Riccati equation.  The error code X_HA_ERR
     indicates one of the following conditions:
    0
          successful

    1
          XINF has imaginary eigenvalues

    2
          HX not Hamiltonian

    3
          XINF has infinite eigenvalues (numerical overflow)

    4
          XINF not symmetric

    5
          XINF not positive definite

    6
          R is singular

 -- Function File: [K, P, E] = lqe (A, G, C, SIGW, SIGV, Z)
     Construct the linear quadratic estimator (Kalman filter) for the
     continuous time system

          dx
          -- = A x + G u
          dt

          y = C x + v

     where W and V are zero-mean gaussian noise processes with
     respective intensities

          sigw = cov (w, w)
          sigv = cov (v, v)

     The optional argument Z is the cross-covariance `cov (W, V)'.  If
     it is omitted, `cov (W, V) = 0' is assumed.

     Observer structure is `dz/dt = A z + B u + k (y - C z - D u)'

     The following values are returned:

    K
          The observer gain, (A - KC) is stable.

    P
          The solution of algebraic Riccati equation.

    E
          The vector of closed loop poles of (A - KC).

 -- Function File: [K, Q1, P1, EE, ER] = lqg (SYS, SIGW, SIGV, Q, R,
          IN_IDX)
     Design a linear-quadratic-gaussian optimal controller for the
     system
          dx/dt = A x + B u + G w       [w]=N(0,[Sigw 0    ])
              y = C x + v               [v]  (    0   Sigv ])
     or
          x(k+1) = A x(k) + B u(k) + G w(k)       [w]=N(0,[Sigw 0    ])
            y(k) = C x(k) + v(k)                  [v]  (    0   Sigv ])

     *Inputs*
    SYS
          system data structure

    SIGW
    SIGV
          intensities of independent Gaussian noise processes (as above)

    Q
    R
          state, control weighting respectively.  Control ARE is

    IN_IDX
          names or indices of controlled inputs (see `sysidx',
          `cellidx')

          default: last dim(R) inputs are assumed to be controlled
          inputs, all others are assumed to be noise inputs.
     *Outputs*
    K
          system data structure format LQG optimal controller (Obtain
          A, B, C matrices with `sys2ss', `sys2tf', or `sys2zp' as
          appropriate).

    P1
          Solution of control (state feedback) algebraic Riccati
          equation.

    Q1
          Solution of estimation algebraic Riccati equation.

    EE
          Estimator poles.

    ES
          Controller poles.


     *See also:* h2syn, lqe, lqr.

 -- Function File: [K, P, E] = lqr (A, B, Q, R, Z)
     construct the linear quadratic regulator for the continuous time
     system

          dx
          -- = A x + B u
          dt

     to minimize the cost functional

                infinity
                /
            J = |  x' Q x + u' R u
               /
              t=0

     Z omitted or

                infinity
                /
            J = |  x' Q x + u' R u + 2 x' Z u
               /
              t=0

     Z included.

     The following values are returned:

    K
          The state feedback gain, (A - BK) is stable and minimizes the
          cost functional

    P
          The stabilizing solution of appropriate algebraic Riccati
          equation.

    E
          The vector of the closed loop poles of (A - BK).

     *Reference* Anderson and Moore, `Optimal control: linear quadratic
     methods', Prentice-Hall, 1990, pp. 56-58.

 -- Function File: [Y, X] = lsim (SYS, U, T, X0)
     Produce output for a linear simulation of a system; produces a
     plot for the output of the system, SYS.

     U is an array that contains the system's inputs.  Each row in U
     corresponds to a different time step.  Each column in U
     corresponds to a different input.  T is an array that contains the
     time index of the system; T should be regularly spaced.  If
     initial conditions are required on the system, the X0 vector
     should be added to the argument list.

     When the lsim function is invoked a plot is not displayed;
     however, the data is returned in Y (system output) and X (system
     states).

 -- Function File: K = place (SYS, P)
     Computes the matrix K such that if the state is feedback with gain
     K, then the eigenvalues  of the closed loop system (i.e. A-BK) are
     those specified in the vector P.

     Version: Beta (May-1997): If you have any comments, please let me
     know.  (see the file place.m for my address)


File: octave.info,  Node: misc,  Prev: cacsd,  Up: Control Theory

33.10 Miscellaneous Functions (Not yet properly filed/documented)
=================================================================

 -- Function File:  axis2dlim (AXDATA)
     Determine axis limits for 2-D data (column vectors); leaves a 10%
     margin around the plots.  Inserts margins of +/- 0.1 if data is
     one-dimensional (or a single point).

     *Input*
    AXDATA
          N by 2 matrix of data [X, Y].

     *Output*
    AXVEC
          Vector of axis limits appropriate for call to `axis' function.

 -- Function File:  moddemo (INPUTS)
     Octave Control toolbox demo: Model Manipulations demo.

 -- Function File:  prompt (STR)
     Prompt user to continue

     *Input*
    STR
          Input string. Its default value is:
               \n ---- Press a key to  continue ---

 -- Function File:  rldemo (INPUTS)
     Octave Control toolbox demo: Root Locus demo.

 -- Function File: [RLDATA, K] = rlocus (SYS[, INCREMENT, MIN_K, MAX_K])
     Display root locus plot of the specified SISO system.
                 -----   ---     --------
             --->| + |---|k|---->| SISO |----------->
                 -----   ---     --------        |
                 - ^                             |
                   |_____________________________|

     *Inputs*
    SYS
          system data structure

    MIN_K
          Minimum value of K

    MAX_K
          Maximum value of K

    INCREMENT
          The increment used in computing gain values

     *Outputs*

     Plots the root locus to the screen.
    RLDATA
          Data points plotted: in column 1 real values, in column 2 the
          imaginary values.

    K
          Gains for real axis break points.

 -- Function File: [YY, IDX] = sortcom (XX[, OPT])
     Sort a complex vector.

     *Inputs*
    XX
          Complex vector

    OPT
          sorting option:
         `"re"'
               Real part (default);

         `"mag"'
               By magnitude;

         `"im"'
               By imaginary part.
          if OPT is not chosen as `"im"', then complex conjugate pairs
          are grouped together, a - jb followed by a + jb.

     *Outputs*
    YY
          Sorted values

    IDX
          Permutation vector: `yy = xx(idx)'

 -- Function File: [NUM, DEN] = ss2tf (A, B, C, D)
     Conversion from tranfer function to state-space.  The state space
     system:
                .
                x = Ax + Bu
                y = Cx + Du

     is converted to a transfer function:

                          num(s)
                    G(s)=-------
                          den(s)

     used internally in system data structure format manipulations.

 -- Function File: [POL, ZER, K] = ss2zp (A, B, C, D)
     Converts a state space representation to a set of poles and zeros;
     K is a gain associated with the zeros.

     Used internally in system data structure format manipulations.

 -- Function File:  starp (P, K, NY, NU)
     Redheffer star product or upper/lower LFT, respectively.

                         +-------+
               --------->|       |--------->
                         |   P   |
                    +--->|       |---+  ny
                    |    +-------+   |
                    +-------------------+
                                     |  |
                    +----------------+  |
                    |                   |
                    |    +-------+      |
                    +--->|       |------+ nu
                         |   K   |
               --------->|       |--------->
                         +-------+
     If NY and NU "consume" all inputs and outputs of K then the
     result is a lower fractional transformation.  If NY and NU
     "consume" all inputs and outputs of P then the result is an upper
     fractional transformation.

     NY and/or NU may be negative (i.e. negative feedback).

 -- Function File: [A, B, C, D] = tf2ss (NUM, DEN)
     Conversion from tranfer function to state-space.  The state space
     system:
                .
                x = Ax + Bu
                y = Cx + Du
     is obtained from a transfer function:
                          num(s)
                    G(s)=-------
                          den(s)

     The vector DEN must contain only one row, whereas the vector NUM
     may contain as many rows as there are outputs Y of the system. The
     state space system matrices obtained from this function will be in
     controllable canonical form as described in `Modern Control
     Theory', (Brogan, 1991).

 -- Function File: [ZER, POL, K] = tf2zp (NUM, DEN)
     Converts transfer functions to poles-and-zero representations.

     Returns the zeros and poles of the SISO system defined by NUM/DEN.
     K is a gain associated with the system zeros.

 -- Function File: [A, B, C, D] = zp2ss (ZER, POL, K)
     Conversion from zero / pole to state space.

     *Inputs*
    ZER
    POL
          Vectors of (possibly) complex poles and zeros of a transfer
          function. Complex values must come in conjugate pairs (i.e.,
          x+jy in ZER means that x-jy is also in ZER).  The number of
          zeros must not exceed the number of poles.

    K
          Real scalar (leading coefficient).

     *Outputs*
    A
    B
    C
    D
          The state space system, in the form:
                    .
                    x = Ax + Bu
                    y = Cx + Du

 -- Function File: [NUM, DEN] = zp2tf (ZER, POL, K)
     Converts zeros / poles to a transfer function.

     *Inputs*
    ZER
    POL
          Vectors of (possibly complex) poles and zeros of a transfer
          function.  Complex values must appear in conjugate pairs.

    K
          Real scalar (leading coefficient).


File: octave.info,  Node: Signal Processing,  Next: Image Processing,  Prev: Control Theory,  Up: Top

34 Signal Processing
********************

 -- Function File:  detrend (X, P)
     If X is a vector, `detrend (X, P)' removes the best fit of a
     polynomial of order P from the data X.

     If X is a matrix, `detrend (X, P)' does the same for each column
     in X.

     The second argument is optional.  If it is not specified, a value
     of 1 is assumed.  This corresponds to removing a linear trend.

 -- Loadable Function:  fft (A, N, DIM)
     Compute the FFT of A using subroutines from FFTW. The FFT is
     calculated along the first non-singleton dimension of the array.
     Thus if A is a matrix, `fft (A)' computes the FFT for each column
     of A.

     If called with two arguments, N is expected to be an integer
     specifying the number of elements of A to use, or an empty matrix
     to specify that its value should be ignored. If N is larger than
     the dimension along which the FFT is calculated, then A is resized
     and padded with zeros. Otherwise, if N is smaller than the
     dimension along which the FFT is calculated, then A is truncated.

     If called with three arguments, DIM is an integer specifying the
     dimension of the matrix along which the FFT is performed

     *See also:* ifft, fft2, fftn, fftw_wisdom.

 -- Loadable Function: METHOD = fftw ('planner')
 -- Loadable Function:  fftw ('planner', METHOD)
 -- Loadable Function: WISDOM = fftw ('dwisdom')
 -- Loadable Function: WISDOM = fftw ('dwisdom', WISDOM)
     Manage FFTW wisdom data. Wisdom data can be used to significantly
     accelerate the calculation of the FFTs but implies a initial cost
     in its calculation. The wisdom used by Octave can be imported
     directly, usually from a file /etc/fftw/wisdom, or "fftw" can be
     used to import wisdom. For example

          WISDOM = fftw ('dwisdom')

     will save the existing wisdom used by Octave to the string WISDOM.
     This string can then be saved in the usual manner. This existing
     wisdom can be reimported as follows

          fftw ('dwisdom', WISDOM)

     If WISDOM is an empty matrix, then the wisdom used is cleared.

     During the calculation of fourier transforms further wisdom is
     generated.  The fashion in which this wisdom is generated is
     equally controlled by the "fftw" function. There are five
     different manners in which the wisdom can be treated, these being

    'estimate'
          This specifies that no run-time measurement of the optimal
          means of calculating a particular is performed, and a simple
          heuristic is used to pick a (probably sub-optimal) plan. The
          advantage of this method is that there is little or no
          overhead in the generation of the plan, which is appropriate
          for a fourier transform that will be calculated once.

    'measure'
          In this case a range of algorithms to perform the transform
          is considered and the best is selected based on their
          execution time.

    'patient'
          This is like 'measure', but a wider range of algorithms is
          considered.

    'exhasutive'
          This is like 'meaure', but all possible algorithms that may
          be used to treat the transform are considered.

    'hybrid'
          As run-time measurement of the algorithm can be expensive,
          this is a compromise where 'measure' is used for transforms
          upto the size of 8192 and beyond that the 'estimate' method
          is used.

     The default method is 'estimate', and the method currently being
     used can be probed with

          METHOD = fftw ('planner')

     and the method used can be set using

          fftw ('planner', METHOD)

     Note that calculated wisdom will be lost when restarting Octave.
     However, the wisdom data can be reloaded if it is saved to a file
     as described above.  Also, any system-wide wisdom file that has
     been found will also be used. Saved wisdom files should not be
     used on different platforms since they will not be efficient and
     the point of calculating the wisdom is lost.

     *See also:* fft, ifft, fft2, ifft2, fftn, ifftn.

 -- Loadable Function:  ifft (A, N, DIM)
     Compute the inverse FFT of A using subroutines from FFTW. The
     inverse FFT is calculated along the first non-singleton dimension
     of the array. Thus if A is a matrix, `fft (A)' computes the
     inverse FFT for each column of A.

     If called with two arguments, N is expected to be an integer
     specifying the number of elements of A to use, or an empty matrix
     to specify that its value should be ignored. If N is larger than
     the dimension along which the inverse FFT is calculated, then A is
     resized and padded with zeros. Otherwise, ifN is smaller than the
     dimension along which the inverse FFT is calculated, then A is
     truncated.

     If called with three agruments, DIM is an integer specifying the
     dimension of the matrix along which the inverse FFT is performed

     *See also:* fft, ifft2, ifftn, fftw_wisdom.

 -- Loadable Function:  fft2 (A, N, M)
     Compute the two dimensional FFT of A using subroutines from FFTW.
     The optional arguments N and M may be used specify the number of
     rows and columns of A to use.  If either of these is larger than
     the size of A, A is resized and padded with zeros.

     If A is a multi-dimensional matrix, each two-dimensional sub-matrix
     of A is treated seperately

     *See also:* ifft2, fft, fftn, fftw_wisdom.

 -- Loadable Function:  fft2 (A, N, M)
     Compute the inverse two dimensional FFT of A using subroutines from
     FFTW. The optional arguments N and M may be used specify the
     number of rows and columns of A to use.  If either of these is
     larger than the size of A, A is resized and padded with zeros.

     If A is a multi-dimensional matrix, each two-dimensional sub-matrix
     of A is treated seperately

     *See also:* fft2, ifft, ifftn, fftw_wisdom.

 -- Loadable Function:  fftn (A, SIZE)
     Compute the N dimensional FFT of A using subroutines from FFTW.
     The optional vector argument SIZE may be used specify the
     dimensions of the array to be used. If an element of SIZE is
     smaller than the corresponding dimension, then the dimension is
     truncated prior to performing the FFT. Otherwise if an element of
     SIZE is larger than the corresponding dimension A is resized and
     padded with zeros.

     *See also:* ifftn, fft, fft2, fftw_wisdom.

 -- Loadable Function:  ifftn (A, SIZE)
     Compute the invesre N dimensional FFT of A using subroutines from
     FFTW. The optional vector argument SIZE may be used specify the
     dimensions of the array to be used. If an element of SIZE is
     smaller than the corresponding dimension, then the dimension is
     truncated prior to performing the inverse FFT. Otherwise if an
     element of SIZE is larger than the corresponding dimension A is
     resized and padded with zeros.

     *See also:* fftn, ifft, ifft2, fftw_wisdom.

 -- Function File:  fftconv (A, B, N)
     Return the convolution of the vectors A and B, as a vector with
     length equal to the `length (a) + length (b) - 1'.  If A and B are
     the coefficient vectors of two polynomials, the returned value is
     the coefficient vector of the product polynomial.

     The computation uses the FFT by calling the function `fftfilt'.  If
     the optional argument N is specified, an N-point FFT is used.

 -- Function File:  fftfilt (B, X, N)
     With two arguments, `fftfilt' filters X with the FIR filter B
     using the FFT.

     Given the optional third argument, N, `fftfilt' uses the
     overlap-add method to filter X with B using an N-point FFT.

     If X is a matrix, filter each column of the matrix.

 -- Loadable Function: y = filter (B, A, X)
 -- Loadable Function: [Y, SF] = filter (B, A, X, SI)
 -- Loadable Function: [Y, SF] = filter (B, A, X, [], DIM)
 -- Loadable Function: [Y, SF] = filter (B, A, X, SI, DIM)
     Return the solution to the following linear, time-invariant
     difference equation:

             N                   M
            SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k)      for 1<=n<=length(x)
            k=0                 k=0

     where  N=length(a)-1 and M=length(b)-1.  over the first
     non-singleton dimension of X or over DIM if supplied. An
     equivalent form of this equation is:

                      N                   M
            y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k)  for 1<=n<=length(x)
                     k=1                 k=0

     where  c = a/a(1) and d = b/a(1).

     If the fourth argument SI is provided, it is taken as the initial
     state of the system and the final state is returned as SF.  The
     state vector is a column vector whose length is equal to the
     length of the longest coefficient vector minus one.  If SI is not
     supplied, the initial state vector is set to all zeros.

     In terms of the z-transform, y is the result of passing the
     discrete- time signal x through a system characterized by the
     following rational system function:

                       M
                      SUM d(k+1) z^(-k)
                      k=0
            H(z) = ----------------------
                         N
                    1 + SUM c(k+1) z^(-k)
                        k=1

 -- Function File: Y = filter2 (B, X)
 -- Function File: Y = filter2 (B, X, SHAPE)
     Apply the 2-D FIR filter B to X. If the argument SHAPE is
     specified, return an array of the desired shape.  Possible values
     are:

    'full'
          pad X with zeros on all sides before filtering.

    'same'
          unpadded X (default)

    'valid'
          trim X after filtering so edge effects are no included.

     Note this is just a variation on convolution, with the parameters
     reversed and B rotated 180 degrees.

     *See also:* conv2.

 -- Function File: [H, W] = freqz (B, A, N, "whole")
     Return the complex frequency response H of the rational IIR filter
     whose numerator and denominator coefficients are B and A,
     respectively.  The response is evaluated at N angular frequencies
     between 0 and  2*pi.

     The output value W is a vector of the frequencies.

     If the fourth argument is omitted, the response is evaluated at
     frequencies between 0 and  pi.

     If N is omitted, a value of 512 is assumed.

     If A is omitted, the denominator is assumed to be 1 (this
     corresponds to a simple FIR filter).

     For fastest computation, N should factor into a small number of
     small primes.

 -- Function File: H = freqz (B, A, W)
     Evaluate the response at the specific frequencies in the vector W.
     The values for W are measured in radians.

 -- Function File: [...] = freqz (..., FS)
     Return frequencies in Hz instead of radians assuming a sampling
     rate FS.  If you are evaluating the response at specific
     frequencies W, those frequencies should be requested in Hz rather
     than radians.

 -- Function File:  freqz (...)
     Plot the pass band, stop band and phase response of H rather than
     returning them.

 -- Function File:  freqz_plot (W, H)
     Plot the pass band, stop band and phase response of H.

 -- Function File:  sinc (X)
     Return  sin(pi*x)/(pi*x).

 -- Function File: B = unwrap (A, TOL, DIM)
     Unwrap radian phases by adding multiples of 2*pi as appropriate to
     remove jumps greater than TOL.  TOL defaults to pi.

     Unwrap will unwrap along the first non-singleton dimension of A,
     unless the optional argument DIM is given, in which case the data
     will be unwrapped along this dimension

 -- Function File: [A, B] = arch_fit (Y, X, P, ITER, GAMMA, A0, B0)
     Fit an ARCH regression model to the time series Y using the
     scoring algorithm in Engle's original ARCH paper.  The model is

          y(t) = b(1) * x(t,1) + ... + b(k) * x(t,k) + e(t),
          h(t) = a(1) + a(2) * e(t-1)^2 + ... + a(p+1) * e(t-p)^2

     in which e(t) is N(0, h(t)), given a time-series vector Y up to
     time t-1 and a matrix of (ordinary) regressors X up to t.  The
     order of the regression of the residual variance is specified by P.

     If invoked as `arch_fit (Y, K, P)' with a positive integer K, fit
     an ARCH(K, P) process, i.e., do the above with the t-th row of X
     given by

          [1, y(t-1), ..., y(t-k)]

     Optionally, one can specify the number of iterations ITER, the
     updating factor GAMMA, and initial values a0 and b0 for the
     scoring algorithm.

 -- Function File:  arch_rnd (A, B, T)
     Simulate an ARCH sequence of length T with AR coefficients B and
     CH coefficients A.  I.e., the result y(t) follows the model

          y(t) = b(1) + b(2) * y(t-1) + ... + b(lb) * y(t-lb+1) + e(t),

     where e(t), given Y up to time t-1, is N(0, h(t)), with

          h(t) = a(1) + a(2) * e(t-1)^2 + ... + a(la) * e(t-la+1)^2

 -- Function File: [PVAL, LM] = arch_test (Y, X, P)
     For a linear regression model

          y = x * b + e

     perform a Lagrange Multiplier (LM) test of the null hypothesis of
     no conditional heteroscedascity against the alternative of CH(P).

     I.e., the model is

          y(t) = b(1) * x(t,1) + ... + b(k) * x(t,k) + e(t),

     given Y up to t-1 and X up to t, e(t) is N(0, h(t)) with

          h(t) = v + a(1) * e(t-1)^2 + ... + a(p) * e(t-p)^2,

     and the null is a(1) == ... == a(p) == 0.

     If the second argument is a scalar integer, k, perform the same
     test in a linear autoregression model of order k, i.e., with

          [1, y(t-1), ..., y(t-K)]

     as the t-th row of X.

     Under the null, LM approximately has a chisquare distribution with
     P degrees of freedom and PVAL is the p-value (1 minus the CDF of
     this distribution at LM) of the test.

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

 -- Function File:  arma_rnd (A, B, V, T, N)
     Return a simulation of the ARMA model

          x(n) = a(1) * x(n-1) + ... + a(k) * x(n-k)
               + e(n) + b(1) * e(n-1) + ... + b(l) * e(n-l)

     in which K is the length of vector A, L is the length of vector B
     and E is gaussian white noise with variance V.  The function
     returns a vector of length T.

     The optional parameter N gives the number of dummy X(I) used for
     initialization, i.e., a sequence of length T+N is generated and
     X(N+1:T+N) is returned.  If N is omitted, N = 100 is used.

 -- Function File:  autocor (X, H)
     Return the autocorrelations from lag 0 to H of vector X.  If H is
     omitted, all autocorrelations are computed.  If X is a matrix, the
     autocorrelations of each column are computed.

 -- Function File:  autocov (X, H)
     Return the autocovariances from lag 0 to H of vector X.  If H is
     omitted, all autocovariances are computed.  If X is a matrix, the
     autocovariances of each column are computed.

 -- Function File:  autoreg_matrix (Y, K)
     Given a time series (vector) Y, return a matrix with ones in the
     first column and the first K lagged values of Y in the other
     columns.  I.e., for T > K, `[1, Y(T-1), ..., Y(T-K)]' is the t-th
     row of the result.  The resulting matrix may be used as a
     regressor matrix in autoregressions.

 -- Function File:  bartlett (M)
     Return the filter coefficients of a Bartlett (triangular) window of
     length M.

     For a definition of the Bartlett window, see e.g. A. V. Oppenheim &
     R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File:  blackman (M)
     Return the filter coefficients of a Blackman window of length M.

     For a definition of the  Blackman window, see e.g. A. V. Oppenheim
     & R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File: [D, DD] = diffpara (X, A, B)
     Return the estimator D for the differencing parameter of an
     integrated time series.

     The frequencies from [2*pi*a/t, 2*pi*b/T] are used for the
     estimation.  If B is omitted, the interval [2*pi/T, 2*pi*a/T] is
     used.  If both B and A are omitted then a = 0.5 * sqrt (T) and b =
     1.5 * sqrt (T) is used, where T is the sample size.  If X is a
     matrix, the differencing parameter of each column is estimated.

     The estimators for all frequencies in the intervals described
     above is returned in DD.  The value of D is simply the mean of DD.

     Reference: Brockwell, Peter J. & Davis, Richard A. Time Series:
     Theory and Methods Springer 1987.

 -- Function File:  durbinlevinson (C, OLDPHI, OLDV)
     Perform one step of the Durbin-Levinson algorithm.

     The vector C specifies the autocovariances `[gamma_0, ...,
     gamma_t]' from lag 0 to T, OLDPHI specifies the coefficients based
     on C(T-1) and OLDV specifies the corresponding error.

     If OLDPHI and OLDV are omitted, all steps from 1 to T of the
     algorithm are performed.

 -- Function File:  fftshift (V)
 -- Function File:  fftshift (V, DIM)
     Perform a shift of the vector V, for use with the `fft' and `ifft'
     functions, in order the move the frequency 0 to the center of the
     vector or matrix.

     If V is a vector of N elements corresponding to N time samples
     spaced of Dt each, then `fftshift (fft (V))' corresponds to
     frequencies

          f = ((1:N) - ceil(N/2)) / N / Dt

     If V is a matrix, the same holds for rows and columns. If V is an
     array, then the same holds along each dimension.

     The optional DIM argument can be used to limit the dimension along
     which the permutation occurs.

 -- Function File:  ifftshift (V)
 -- Function File:  ifftshift (V, DIM)
     Undo the action of the `fftshift' function.  For even length V,
     `fftshift' is its own inverse, but odd lengths differ slightly.

 -- Function File:  fractdiff (X, D)
     Compute the fractional differences (1-L)^d x where L denotes the
     lag-operator and d is greater than -1.

 -- Function File:  hamming (M)
     Return the filter coefficients of a Hamming window of length M.

     For a definition of the Hamming window, see e.g. A. V. Oppenheim &
     R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File:  hanning (M)
     Return the filter coefficients of a Hanning window of length M.

     For a definition of this window type, see e.g. A. V. Oppenheim &
     R. W. Schafer, "Discrete-Time Signal Processing".

 -- Function File:  hurst (X)
     Estimate the Hurst parameter of sample X via the rescaled range
     statistic.  If X is a matrix, the parameter is estimated for every
     single column.

 -- Function File: PP =  pchip (X, Y)
 -- Function File: YI =  pchip (X, Y, XI)
     Piecewise Cubic Hermite interpolating polynomial. Called with two
     arguments, the piece-wise polynomial PP is returned, that may
     later be used with `ppval' to evaluate the polynomial at specific
     points.

     The variable X must be a strictly monotonic vector (either
     increasing or decreasing). While Y can be either a vector or
     array. In the case where Y is a vector, it must have a length of
     N. If Y is an array, then the size of Y must have the form `[S1,
     S2, ..., SK, N]' The array is then reshaped internally to a matrix
     where to leading dimension is given by `S1 * S2 * ... * SK' and
     each row this matrix is then treated seperately. Note that this is
     exactly the opposite treatment than `interp1' and is done for
     compatiability.

     Called with a third input argument, `pchip' evaluates the
     piece-wise polynomial at the points XI. There is an equivalence
     between `ppval (pchip (X, Y), XI)' and `pchip (X, Y, XI)'.


     *See also:* spline, ppval, mkpp, unmkpp.

 -- Function File:  periodogram (X)
     For a data matrix X from a sample of size N, return the
     periodogram.

 -- Function File:  rectangle_lw (N, B)
     Rectangular lag window. Subfunction used for spectral density
     estimation.

 -- Function File:  rectangle_sw (N, B)
     Rectangular spectral window.  Subfunction used for spectral density
     estimation.

 -- Function File:  sinetone (FREQ, RATE, SEC, AMPL)
     Return a sinetone of frequency FREQ with length of SEC seconds at
     sampling rate RATE and with amplitude AMPL.  The arguments FREQ
     and AMPL may be vectors of common size.

     Defaults are RATE = 8000, SEC = 1 and AMPL = 64.

 -- Function File:  sinewave (M, N, D)
     Return an M-element vector with I-th element given by `sin (2 * pi
     * (I+D-1) / N)'.

     The default value for D is 0 and the default value for N is M.

 -- Function File:  spectral_adf (C, WIN, B)
     Return the spectral density estimator given a vector of
     autocovariances C, window name WIN, and bandwidth, B.

     The window name, e.g., `"triangle"' or `"rectangle"' is used to
     search for a function called `WIN_sw'.

     If WIN is omitted, the triangle window is used.  If B is omitted,
     `1 / sqrt (length (X))' is used.

 -- Function File:  spectral_xdf (X, WIN, B)
     Return the spectral density estimator given a data vector X,
     window name WIN, and bandwidth, B.

     The window name, e.g., `"triangle"' or `"rectangle"' is used to
     search for a function called `WIN_sw'.

     If WIN is omitted, the triangle window is used.  If B is omitted,
     `1 / sqrt (length (X))' is used.

 -- Function File:  spencer (X)
     Return Spencer's 15 point moving average of every single column of
     X.

 -- Function File: [Y, C] = stft (X, WIN_SIZE, INC, NUM_COEF, W_TYPE)
     Compute the short-term Fourier transform of the vector X with
     NUM_COEF coefficients by applying a window of WIN_SIZE data points
     and an increment of INC points.

     Before computing the Fourier transform, one of the following
     windows is applied:

    hanning
          w_type = 1

    hamming
          w_type = 2

    rectangle
          w_type = 3

     The window names can be passed as strings or by the W_TYPE number.

     If not all arguments are specified, the following defaults are
     used: WIN_SIZE = 80, INC = 24, NUM_COEF = 64, and W_TYPE = 1.

     `Y = stft (X, ...)' returns the absolute values of the Fourier
     coefficients according to the NUM_COEF positive frequencies.

     `[Y, C] = stft (`x', ...)' returns the entire STFT-matrix Y and a
     3-element vector C containing the window size, increment, and
     window type, which is needed by the synthesis function.

 -- Function File:  synthesis (Y, C)
     Compute a signal from its short-time Fourier transform Y and a
     3-element vector C specifying window size, increment, and window
     type.

     The values Y and C can be derived by

          [Y, C] = stft (X , ...)

 -- Function File:  triangle_lw (N, B)
     Triangular lag window. Subfunction used for spectral density
     estimation.

 -- Function File:  triangle_sw (N, B)
     Triangular spectral window.  Subfunction used for spectral density
     estimation.

 -- Function File: [A, V] = yulewalker (C)
     Fit an AR (p)-model with Yule-Walker estimates given a vector C of
     autocovariances `[gamma_0, ..., gamma_p]'.

     Returns the AR coefficients, A, and the variance of white noise, V.


File: octave.info,  Node: Image Processing,  Next: Audio Processing,  Prev: Signal Processing,  Up: Top

35 Image Processing
*******************

Since an image basically is a matrix Octave is a very powerful
environment for processing and analysing images. To illustrate how easy
it is to do image processing in Octave, the following example will load
an image, smooth it by a 5-by-5 averaging filter, and compute the
gradient of the smoothed image.

     I = loadimage ("default.img");
     S = conv2 (I, ones (5, 5) / 25, "same");
     [Dx, Dy] = gradient (S);

In this example `S' contains the smoothed image, and `Dx' and `Dy'
contains the partial spatial derivatives of the image.

* Menu:

* Loading and Saving Images::
* Displaying Images::
* Representing Images::
* Plotting on top of Images::
* Color Conversion::


File: octave.info,  Node: Loading and Saving Images,  Next: Displaying Images,  Up: Image Processing

35.1 Loading and Saving Images
==============================

The first step in most image processing tasks is to load an image into
Octave. Currently Octave only support saving images in the Portable
Pixmap Format (PPM), PostScript, and Octave's own format, and loading
images in Octave's format. Most image processing code will follow the
structure of this code

     I = loadimage ("my_input_image.img");
     J = process_my_image (I);
     saveimage ("my_output_image.img", J);

 -- Function File: [X, MAP] = loadimage (FILE)
     Load an image file and it's associated color map from the specified
     FILE.  The image must be stored in Octave's image format.

     *See also:* saveimage, load, save.

 -- Function File:  saveimage (FILE, X, FMT, MAP)
     Save the matrix X to FILE in image format FMT.  Valid values for
     FMT are

    `"img"'
          Octave's image format.  The current colormap is also saved in
          the file.

    `"ppm"'
          Portable pixmap format.

    `"ps"'
          PostScript format.  Note that images saved in PostScript
          format can not be read back into Octave with loadimage.

     If the fourth argument is supplied, the specified colormap will
     also be saved along with the image.

     Note: if the colormap contains only two entries and these entries
     are black and white, the bitmap ppm and PostScript formats are
     used.  If the image is a gray scale image (the entries within each
     row of the colormap are equal) the gray scale ppm and PostScript
     image formats are used, otherwise the full color formats are used.

     *See also:* loadimage, save, load, colormap.

 -- Built-in Function: VAL = IMAGE_PATH ()
 -- Built-in Function: OLD_VAL = IMAGE_PATH (NEW_VAL)
     Query or set the internal variable that specifies a colon separated
     list of directories in which to search for image files.


File: octave.info,  Node: Displaying Images,  Next: Representing Images,  Prev: Loading and Saving Images,  Up: Image Processing

35.2 Displaying Images
======================

A natural part of image processing is visualization of an image.  The
most basic function for this is the `imshow' function that shows the
image given in the first input argument. This function uses an external
program to show the image. If gnuplot 4.2 or later is available it will
be used to display the image, otherwise the `display', `xv', or
`xloadimage' program is used. The actual program can be selected with
the `image_viewer' function.

 -- Function File:  imshow (IM)
 -- Function File:  imshow (IM, LIMITS)
 -- Function File:  imshow (IM, MAP)
 -- Function File:  imshow (R, G, B, ...)
 -- Function File:  imshow (FILENAME)
 -- Function File:  imshow (..., STRING_PARAM1, VALUE1, ...)
     Display the image IM, where IM can be a 2-dimensional (gray-scale
     image) or a 3-dimensional (RGB image) matrix. If three matrices of
     the same size are given as arguments, they will be concatenated
     into a 3-dimensional (RGB image) matrix.

     If LIMITS is a 2-element vector `[LOW, HIGH]', the image is shown
     using a display range between LOW and HIGH.  If an empty matrix is
     passed for LIMITS, the display range is computed as the range
     between the minimal and the maximal value in the image.

     If MAP is a valid color map, the image will be shown as an indexed
     image using the supplied color map.

     If a file name is given instead of an image, the file will be read
     and shown.

     If given, the parameter STRING_PARAM1 has value VALUE1.
     STRING_PARAM1 can be any of the following:
    `"displayrange"'
          VALUE1 is the display range as described above.


     *See also:* image, imagesc, colormap, gray2ind, rgb2ind.

 -- Function File:  image (IMG)
 -- Function File:  image (X, Y, IMG)
     Display a matrix as a color image.  The elements of X are indices
     into the current colormap and should have values between 1 and the
     length of the colormap.

     It first tries to use `gnuplot', then `display' from
     `ImageMagick', then `xv', and then `xloadimage'.  The actual
     program used can be changed using the `image_viewer' function.

     The axis values corresponding to the matrix elements are specified
     in X and Y. If you're not using gnuplot 4.2 or later, these
     variables are ignored.

     *See also:* imshow, imagesc, colormap, image_viewer.

 -- Function File:  imagesc (A)
 -- Function File:  imagesc (X, Y, A)
 -- Function File:  imagesc (..., LIMITS)
 -- Function File:  B =  imagesc (...)
     Display a scaled version of the matrix A as a color image.  The
     matrix is scaled so that its entries are indices into the current
     colormap.  The scaled matrix is returned.  If LIMITS = [LO, HI] are
     given, then that range maps into the full range of the colormap
     rather than the minimum and maximum values of A.

     The axis values corresponding to the matrix elements are specified
     in X and Y, either as pairs giving the minimum and maximum values
     for the respective axes, or as values for each row and column of
     the matrix A.

     *See also:* image, imshow.

 -- Function File: [FCN, DEFAULT_ZOOM] = image_viewer (FCN,
          DEFAULT_ZOOM)
     Change the program or function used for viewing images and return
     the previous values.

     When the `image' or `imshow' function is called it will launch an
     external program to display the image.  The default behaviour is
     to use gnuplot if the installed version supports image viewing,
     and otherwise try the programs `display', `xv', and `xloadimage'.
     Using this function it is possible to change that behaviour.

     When called with one input argument images will be displayed by
     saving the image to a file and the system command COMMAND will
     called to view the image.  The COMMAND must be a string containing
     `%s' and possibly `%f'. The `%s' will be replaced by the filename
     of the image, and the `%f' will (if present) be replaced by the
     zoom factor given to the `image' function.  For example,
          image_viewer ("eog %s");
     changes the image viewer to the `eog' program.

     With two input arguments, images will be displayed by calling the
     function FUNCTION_HANDLE.  For example,
          image_viewer (data, @my_image_viewer);
     sets the image viewer function to `my_image_viewer'.  The image
     viewer function is called with
          my_image_viewer (X, Y, IM, ZOOM, DATA)
     where X and Y are the axis of the image, IM is the image variable,
     and DATA is extra user-supplied data to be passed to the viewer
     function.

     With three input arguments it is possible to change the zooming.
     Some programs (like `xloadimage') require the zoom factor to be
     between 0 and 100, and not 0 and 1 like Octave assumes. This is
     solved by setting the third argument to 100.


     *See also:* image, imshow, __img_gnuplot__, __img_via_file__.


File: octave.info,  Node: Representing Images,  Next: Plotting on top of Images,  Prev: Displaying Images,  Up: Image Processing

35.3 Representing Images
========================

In general Octave supports four different kinds of images, gray-scale
images, RGB images, binary images, and indexed images. A gray-scale
image is represented with an M-by-N matrix in which each element
corresponds to the intensity of a pixel. An RGB image is represented
with an M-by-N-by3 array where each 3-vector corresponds to the red,
green, and blue intensities of each pixel.

   The actual meaning of the value of a pixel in a gray-scale or RGB
image depends on the class of the matrix. If the matrix is of class
`double' pixel intensities are between 0 and 1, if it is of class
`uint8' intensities are between 0 and 255, and if it is of class
`uint16' intensities are between 0 and 65535.

   A binary image is a M-by-N matrix of class `logical'.  A pixel in a
binary image is black if it is `false' and white if it is `true'.

   An indexed image consists of an M-by-N matrix of integers and a
C-by-3 color map. Each integer corresponds to an index in the color
map, and each row in the color map corresponds to a RGB color. The
color map must be of class `double' with values between 0 and 1.

 -- Function File: [IMG, MAP] = gray2ind ()
     Convert a gray scale intensity image to an Octave indexed image.

 -- Function File:  ind2gray (X, MAP)
     Convert an Octave indexed image to a gray scale intensity image.
     If MAP is omitted, the current colormap is used to determine the
     intensities.

     *See also:* gray2ind, rgb2ntsc, image, colormap.

 -- Function File: [X, MAP] = rgb2ind (RGB)
 -- Function File: [X, MAP] = rgb2ind (R, G, B)
     Convert and RGB image to an Octave indexed image.

     *See also:* ind2rgb, rgb2ntsc.

 -- Function File: RGB = ind2rgb (X, MAP)
 -- Function File: [R, G, B] = ind2rgb (X, MAP)
     Convert an indexed image to red, green, and blue color components.
     If the colormap doesn't contain enough colors, pad it with the
     last color in the map.  If MAP is omitted, the current colormap is
     used for the conversion.

     *See also:* rgb2ind, image, imshow, ind2gray, gray2ind.

 -- Function File:  colormap (MAP)
 -- Function File:  colormap ("default")
     Set the current colormap.

     `colormap (MAP)' sets the current colormap to MAP.  The color map
     should be an N row by 3 column matrix.  The columns contain red,
     green, and blue intensities respectively.  All entries should be
     between 0 and 1 inclusive.  The new colormap is returned.

     `colormap ("default")' restores the default colormap (a gray scale
     colormap with 64 entries).  The default colormap is returned.

     With no arguments, `colormap' returns the current color map.

 -- Function File:  gray (N)
     Return a gray colormap with N entries corresponding to values from
     0 to N-1.  The argument N should be a scalar.  If it is omitted,
     64 is assumed.

 -- Function File:  ocean (N)
     Create color colormap.  The argument N should be a scalar.  If it
     is omitted, 64 is assumed.


File: octave.info,  Node: Plotting on top of Images,  Next: Color Conversion,  Prev: Representing Images,  Up: Image Processing

35.4 Plotting on top of Images
==============================

If gnuplot is being used to display images it is possible to plot on
top of images. Since an image is a matrix it is indexed by row and
column values. The plotting system is, however, based on the
traditional (x, y) system. To minimize the difference between the two
systems Octave places the origin of the coordinate system in the point
corresponding to the pixel at (1, 1). So, to plot points given by row
and column values on top of an image, one should simply call `plot'
with the column values as the first argument and the row values as the
second. As an example the following code generates an image with random
intensities between 0 and 1, and shows the image with red circles over
pixels with an intensity above 0.99.

     I = rand (100, 100);
     [row, col] = find (I > 0.99);
     hold ("on");
     imshow (I);
     plot (col, row, "ro");
     hold ("off");


File: octave.info,  Node: Color Conversion,  Prev: Plotting on top of Images,  Up: Image Processing

35.5 Color Conversion
=====================

Octave supports conversion from the RGB color system to NTSC and HSV
and vice versa.

 -- Function File: HSV_MAP = rgb2hsv (RGB_MAP)
     Transform a colormap from the rgb space to the hsv space.

     A color n the RGB space consists of the red, green and blue
     intensities.

     In the HSV space each color is represented by their hue, saturation
     and value (brightness).  Value gives the amount of light in the
     color.  Hue describes the dominant wavelegth.  Saturation is the
     amount of Hue mixed into the color.

     *See also:* hsv2rgb.

 -- Function File: RGB_MAP = hsv2rgb (HSV_MAP)
     Transform a colormap from the hsv space to the rgb space.

     *See also:* rgb2hsv.

 -- Function File:  rgb2ntsc (RGB)
     Image format conversion.

 -- Function File:  ntsc2rgb (YIQ)
     Image format conversion.


File: octave.info,  Node: Audio Processing,  Next: Quaternions,  Prev: Image Processing,  Up: Top

36 Audio Processing
*******************

Octave provides a few functions for dealing with audio data.  An audio
`sample' is a single output value from an A/D converter, i.e., a small
integer number (usually 8 or 16 bits), and audio data is just a series
of such samples.  It can be characterized by three parameters:  the
sampling rate (measured in samples per second or Hz, e.g. 8000 or
44100), the number of bits per sample (e.g. 8 or 16), and the number of
channels (1 for mono, 2 for stereo, etc.).

   There are many different formats for representing such data.
Currently, only the two most popular, _linear encoding_ and _mu-law
encoding_, are supported by Octave.  There is an excellent FAQ on audio
formats by Guido van Rossum <guido@cwi.nl> which can be found at any
FAQ ftp site, in particular in the directory
`/pub/usenet/news.answers/audio-fmts' of the archive site
`rtfm.mit.edu'.

   Octave simply treats audio data as vectors of samples (non-mono data
are not supported yet).  It is assumed that audio files using linear
encoding have one of the extensions `lin' or `raw', and that files
holding data in mu-law encoding end in `au', `mu', or `snd'.

 -- Function File:  lin2mu (X, N)
     Converts audio data from linear to mu-law.  Mu-law values use 8-bit
     unsigned integers.  Linear values use N-bit signed integers or
     floating point values in the range -1<=X<=1 if N is 0.  If N is
     not specified it defaults to 0, 8 or 16 depending on the range
     values in X.

     *See also:* mu2lin, loadaudio, saveaudio, playaudio, setaudio,
     record.

 -- Function File:  mu2lin (X, BPS)
     Converts audio data from linear to mu-law.  Mu-law values are 8-bit
     unsigned integers.  Linear values use N-bit signed integers or
     floating point values in the range -1<=y<=1 if N is 0.  If N is
     not specified it defaults to 8.

     *See also:* lin2mu, loadaudio, saveaudio, playaudio, setaudio,
     record.

 -- Function File:  loadaudio (NAME, EXT, BPS)
     Loads audio data from the file `NAME.EXT' into the vector X.

     The extension EXT determines how the data in the audio file is
     interpreted;  the extensions `lin' (default) and `raw' correspond
     to linear, the extensions `au', `mu', or `snd' to mu-law encoding.

     The argument BPS can be either 8 (default) or 16, and specifies
     the number of bits per sample used in the audio file.

     *See also:* lin2mu, mu2lin, saveaudio, playaudio, setaudio, record.

 -- Function File:  saveaudio (NAME, X, EXT, BPS)
     Saves a vector X of audio data to the file `NAME.EXT'.  The
     optional parameters EXT and BPS determine the encoding and the
     number of bits per sample used in the audio file (see
     `loadaudio');  defaults are `lin' and 8, respectively.

     *See also:* lin2mu, mu2lin, loadaudio, playaudio, setaudio, record.

   The following functions for audio I/O require special A/D hardware
and operating system support.  It is assumed that audio data in linear
encoding can be played and recorded by reading from and writing to
`/dev/dsp', and that similarly `/dev/audio' is used for mu-law
encoding.  These file names are system-dependent.  Improvements so that
these functions will work without modification on a wide variety of
hardware are welcome.

 -- Function File:  playaudio (NAME, EXT)
 -- Function File:  playaudio (X)
     Plays the audio file `NAME.EXT' or the audio data stored in the
     vector X.

     *See also:* lin2mu, mu2lin, loadaudio, saveaudio, setaudio, record.

 -- Function File:  record (SEC, SAMPLING_RATE)
     Records SEC seconds of audio input into the vector X.  The default
     value for SAMPLING_RATE is 8000 samples per second, or 8kHz.  The
     program waits until the user types <RET> and then immediately
     starts to record.

     *See also:* lin2mu, mu2lin, loadaudio, saveaudio, playaudio,
     setaudio.

 -- Function File:  setaudio ([W_TYPE [, VALUE]])
     Execute the shell command `mixer [W_TYPE [, VALUE]]'

 -- Function File: Y = wavread (FILENAME)
     Load the RIFF/WAVE sound file FILENAME, and return the samples in
     vector Y.  If the file contains multichannel data, then Y is a
     matrix with the channels represented as columns.

 -- Function File: [Y, FS, BITS] = wavread (FILENAME)
     Additionally return the sample rate (FS) in Hz and the number of
     bits per sample (BITS).

 -- Function File: [...] = wavread (FILENAME, N)
     Read only the first N samples from each channel.

 -- Function File: [...] = wavread (FILENAME,[N1 N2])
     Read only samples N1 through N2 from each channel.

 -- Function File: [SAMPLES, CHANNELS] = wavread (FILENAME, "size")
     Return the number of samples (N) and channels (CH) instead of the
     audio data.

     *See also:* wavwrite.

 -- Function File:  wavwrite (FILENAME, Y)
     Write Y to the canonical RIFF/WAVE sound file FILENAME. A sample
     rate of 8000 Hz and 16-bit samples are assumed. Each column of the
     data represents a separate channel.

 -- Function File:  wavwrite (FILENAME, Y, FS)
     Set the sample rate to FS Hz.

 -- Function File:  wavwrite (FILENAME, Y, FS, BITS)
     Set the sample rate to FS Hz and resolution to BITS bits.

     *See also:* wavread.


File: octave.info,  Node: Quaternions,  Next: System Utilities,  Prev: Audio Processing,  Up: Top

37 Quaternions
**************

Quaternions are hypercomplex numbers used to represent spatial
rotations in three dimensions.  This set of routines provides a useful
basis for working with quaternions in Octave.  A tutorial is in the
Octave source, scripts/quaternion/quaternion.ps.

   These functions were written by A. S. Hodel, Associate Professor,
Auburn University.

 -- Function File: [A, B, C, D] = quaternion (w)
 -- Function File: [VV, THETA] = quaternion (w)
 -- Function File: W = quaternion (A, B, C, D)
 -- Function File: W = quaternion (VV, THETA)
     Construct or extract a quaternion

          w = a*i + b*j + c*k + d

     from given data.

 -- Function File:  qconj (Q)
     Conjugate of a quaternion.

          q = [w, x, y, z] = w*i + x*j + y*k + z
          qconj (q) = -w*i -x*j -y*k + z

 -- Function File:  qderiv (omega)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to
     a rotating frame.  If the rotating frame is rotating about the [x,
     y, z] axes at angular rates [wx, wy, wz], then the derivative of Q
     is given by

          Q' = qderivmat (omega) * Q

     If the passive convention is used (rotate the frame, not the
     vector), then

          Q' = -qderivmat (omega) * Q

 -- Function File:  qderivmat (OMEGA)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to
     a rotating frame.  If the rotating frame is rotating about the [x,
     y, z] axes at angular rates [wx, wy, wz], then the derivative of Q
     is given by

          Q' = qderivmat (omega) * Q

     If the passive convention is used (rotate the frame, not the
     vector), then

          Q' = -qderivmat (omega) * Q.

 -- Function File:  qinv (Q)
     Return the inverse of a quaternion.

          q = [w, x, y, z] = w*i + x*j + y*k + z
          qmult (q, qinv (q)) = 1 = [0 0 0 1]

 -- Function File:  qmult (A, B)
     Multiply two quaternions.

          [w, x, y, z] = w*i + x*j + y*k + z

     identities:

          i^2 = j^2 = k^2 = -1
          ij = k                 jk = i
          ki = j                 kj = -i
          ji = -k                ik = -j

 -- Function File:  qtrans (V, Q)
     Transform the unit quaternion V by the unit quaternion Q.  Returns
     `V = Q*V/Q'.

 -- Function File:  qtransv (V, Q)
     Transform the 3-D vector V by the unit quaternion Q.  Return a
     column vector.

          vi = (2*real(q)^2 - 1)*vb + 2*imag(q)*(imag(q)'*vb)
             + 2*real(q)*cross(imag(q),vb)

     Where imag(q) is a column vector of length 3.

 -- Function File:  qtransvmat (QIB)
     Construct a 3x3 transformation matrix from quaternion QIB that is
     equivalent to rotation of th radians about axis VV, where `[VV,
     TH] = quaternion (QIB)'.

 -- Function File:  qcoordinate_plot (QF, QB, QV)
     Plot in the current figure a set of coordinate axes as viewed from
     the orientation specified by quaternion QV.  Inertial axes are
     also plotted:

    QF
          Quaternion from reference (x,y,z) to inertial.

    QB
          Quaternion from reference to body.

    QV
          Quaternion from reference to view angle.


File: octave.info,  Node: System Utilities,  Next: Packages,  Prev: Quaternions,  Up: Top

38 System Utilities
*******************

This chapter describes the functions that are available to allow you to
get information about what is happening outside of Octave, while it is
still running, and use this information in your program.  For example,
you can get information about environment variables, the current time,
and even start other programs from the Octave prompt.

* Menu:

* Timing Utilities::
* Filesystem Utilities::
* File Archiving Utilities::
* Networking Utilities::
* Controlling Subprocesses::
* Process ID Information::
* Environment Variables::
* Current Working Directory::
* Password Database Functions::
* Group Database Functions::
* System Information::


File: octave.info,  Node: Timing Utilities,  Next: Filesystem Utilities,  Up: System Utilities

38.1 Timing Utilities
=====================

Octave's core set of functions for manipulating time values are
patterned after the corresponding functions from the standard C library.
Several of these functions use a data structure for time that includes
the following elements:

`usec'
     Microseconds after the second (0-999999).

`sec'
     Seconds after the minute (0-61).  This number can be 61 to account
     for leap seconds.

`min'
     Minutes after the hour (0-59).

`hour'
     Hours since midnight (0-23).

`mday'
     Day of the month (1-31).

`mon'
     Months since January (0-11).

`year'
     Years since 1900.

`wday'
     Days since Sunday (0-6).

`yday'
     Days since January 1 (0-365).

`isdst'
     Daylight Savings Time flag.

`zone'
     Time zone.

In the descriptions of the following functions, this structure is
referred to as a TM_STRUCT.

 -- Loadable Function:  time ()
     Return the current time as the number of seconds since the epoch.
     The epoch is referenced to 00:00:00 CUT (Coordinated Universal
     Time) 1 Jan 1970.  For example, on Monday February 17, 1997 at
     07:15:06 CUT, the value returned by `time' was 856163706.

     *See also:* strftime, strptime, localtime, gmtime, mktime, now,
     date, clock, datenum, datestr, datevec, calendar, weekday.

 -- Function File: t = now ()
     Returns the current local time as the number of days since Jan 1,
     0000.  By this reckoning, Jan 1, 1970 is day number 719529.

     The integral part, `floor (now)' corresponds to 00:00:00 today.

     The fractional part, `rem (now, 1)' corresponds to the current
     time on Jan 1, 0000.

     The returned value is also called a "serial date number" (see
     `datenum').

     *See also:* clock, date, datenum.

 -- Function File:  ctime (T)
     Convert a value returned from `time' (or any other nonnegative
     integer), to the local time and return a string of the same form as
     `asctime'.  The function `ctime (time)' is equivalent to `asctime
     (localtime (time))'.  For example,

          ctime (time ())
          => "Mon Feb 17 01:15:06 1997\n"

 -- Loadable Function:  gmtime (T)
     Given a value returned from time (or any nonnegative integer),
     return a time structure corresponding to CUT.  For example,

          gmtime (time ())
               => {
                     usec = 0
                     year = 97
                     mon = 1
                     mday = 17
                     sec = 6
                     zone = CST
                     min = 15
                     wday = 1
                     hour = 7
                     isdst = 0
                     yday = 47
                   }


     *See also:* strftime, strptime, localtime, mktime, time, now,
     date, clock, datenum, datestr, datevec, calendar, weekday.

 -- Loadable Function:  localtime (T)
     Given a value returned from time (or any nonnegative integer),
     return a time structure corresponding to the local time zone.

          localtime (time ())
               => {
                     usec = 0
                     year = 97
                     mon = 1
                     mday = 17
                     sec = 6
                     zone = CST
                     min = 15
                     wday = 1
                     hour = 1
                     isdst = 0
                     yday = 47
                   }


     *See also:* strftime, strptime, gmtime, mktime, time, now, date,
     clock, datenum, datestr, datevec, calendar, weekday.

 -- Loadable Function:  mktime (TM_STRUCT)
     Convert a time structure corresponding to the local time to the
     number of seconds since the epoch.  For example,

          mktime (localtime (time ())
               => 856163706


     *See also:* strftime, strptime, localtime, gmtime, time, now,
     date, clock, datenum, datestr, datevec, calendar, weekday.

 -- Function File:  asctime (TM_STRUCT)
     Convert a time structure to a string using the following five-field
     format: Thu Mar 28 08:40:14 1996.  For example,

          asctime (localtime (time ())
          => "Mon Feb 17 01:15:06 1997\n"

     This is equivalent to `ctime (time ())'.

 -- Loadable Function:  strftime (FMT, TM_STRUCT)
     Format the time structure TM_STRUCT in a flexible way using the
     format string FMT that contains `%' substitutions similar to those
     in `printf'.  Except where noted, substituted fields have a fixed
     size; numeric fields are padded if necessary.  Padding is with
     zeros by default; for fields that display a single number, padding
     can be changed or inhibited by following the `%' with one of the
     modifiers described below.  Unknown field specifiers are copied as
     normal characters.  All other characters are copied to the output
     without change.  For example,

          strftime ("%r (%Z) %A %e %B %Y", localtime (time ()))
               => "01:15:06 AM (CST) Monday 17 February 1997"

     Octave's `strftime' function supports a superset of the ANSI C
     field specifiers.

     Literal character fields:

    `%'
          % character.

    `n'
          Newline character.

    `t'
          Tab character.

     Numeric modifiers (a nonstandard extension):

    `- (dash)'
          Do not pad the field.

    `_ (underscore)'
          Pad the field with spaces.

     Time fields:

    `%H'
          Hour (00-23).

    `%I'
          Hour (01-12).

    `%k'
          Hour (0-23).

    `%l'
          Hour (1-12).

    `%M'
          Minute (00-59).

    `%p'
          Locale's AM or PM.

    `%r'
          Time, 12-hour (hh:mm:ss [AP]M).

    `%R'
          Time, 24-hour (hh:mm).

    `%s'
          Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard
          extension).

    `%S'
          Second (00-61).

    `%T'
          Time, 24-hour (hh:mm:ss).

    `%X'
          Locale's time representation (%H:%M:%S).

    `%Z'
          Time zone (EDT), or nothing if no time zone is determinable.

     Date fields:

    `%a'
          Locale's abbreviated weekday name (Sun-Sat).

    `%A'
          Locale's full weekday name, variable length (Sunday-Saturday).

    `%b'
          Locale's abbreviated month name (Jan-Dec).

    `%B'
          Locale's full month name, variable length (January-December).

    `%c'
          Locale's date and time (Sat Nov 04 12:02:33 EST 1989).

    `%C'
          Century (00-99).

    `%d'
          Day of month (01-31).

    `%e'
          Day of month ( 1-31).

    `%D'
          Date (mm/dd/yy).

    `%h'
          Same as %b.

    `%j'
          Day of year (001-366).

    `%m'
          Month (01-12).

    `%U'
          Week number of year with Sunday as first day of week (00-53).

    `%w'
          Day of week (0-6).

    `%W'
          Week number of year with Monday as first day of week (00-53).

    `%x'
          Locale's date representation (mm/dd/yy).

    `%y'
          Last two digits of year (00-99).

    `%Y'
          Year (1970-).


     *See also:* strptime, localtime, gmtime, mktime, time, now, date,
     clock, datenum, datestr, datevec, calendar, weekday.

 -- Loadable Function: [TM_STRUCT, NCHARS] = strptime (STR, FMT)
     Convert the string STR to the time structure TM_STRUCT under the
     control of the format string FMT.

     If FMT fails to match, NCHARS is 0; otherwise it is set to the
     position of last matched character plus 1. Always check for this
     unless you're absolutely sure the date string will be parsed
     correctly.

     *See also:* strftime, localtime, gmtime, mktime, time, now, date,
     clock, datenum, datestr, datevec, calendar, weekday.

   Most of the remaining functions described in this section are not
patterned after the standard C library.  Some are available for
compatiblity with MATLAB and others are provided because they are
useful.

 -- Function File:  clock ()
     Return a vector containing the current year, month (1-12), day
     (1-31), hour (0-23), minute (0-59) and second (0-61).  For example,

          clock ()
          => [ 1993, 8, 20, 4, 56, 1 ]

     The function clock is more accurate on systems that have the
     `gettimeofday' function.

 -- Function File:  date ()
     Return the date as a character string in the form DD-MMM-YY.  For
     example,

          date ()
          => "20-Aug-93"

 -- Function File:  etime (T1, T2)
     Return the difference (in seconds) between two time values
     returned from `clock'.  For example:

          t0 = clock ();
           many computations later...
          elapsed_time = etime (clock (), t0);

     will set the variable `elapsed_time' to the number of seconds since
     the variable `t0' was set.

     *See also:* tic, toc, clock, cputime.

 -- Function File: [TOTAL, USER, SYSTEM] = cputime ();
     Return the CPU time used by your Octave session.  The first output
     is the total time spent executing your process and is equal to the
     sum of second and third outputs, which are the number of CPU
     seconds spent executing in user mode and the number of CPU seconds
     spent executing in system mode, respectively.  If your system does
     not have a way to report CPU time usage, `cputime' returns 0 for
     each of its output values.  Note that because Octave used some CPU
     time to start, it is reasonable to check to see if `cputime' works
     by checking to see if the total CPU time used is nonzero.

 -- Function File:  is_leap_year (YEAR)
     Return 1 if the given year is a leap year and 0 otherwise.  If no
     arguments are provided, `is_leap_year' will use the current year.
     For example,

          is_leap_year (2000)
          => 1

 -- Function File:  tic ()
 -- Function File:  toc ()
     These functions set and check a wall-clock timer.  For example,

          tic ();
           many computations later...
          elapsed_time = toc ();

     will set the variable `elapsed_time' to the number of seconds since
     the most recent call to the function `tic'.

     Nested timing with `tic' and `toc' is not supported.  Therefore
     `toc' will always return the elapsed time from the most recent
     call to `tic'.

     If you are more interested in the CPU time that your process used,
     you should use the `cputime' function instead.  The `tic' and
     `toc' functions report the actual wall clock time that elapsed
     between the calls.  This may include time spent processing other
     jobs or doing nothing at all.  For example,

          tic (); sleep (5); toc ()
          => 5
          t = cputime (); sleep (5); cputime () - t
          => 0

     (This example also illustrates that the CPU timer may have a fairly
     coarse resolution.)

 -- Built-in Function:  pause (SECONDS)
     Suspend the execution of the program.  If invoked without any
     arguments, Octave waits until you type a character.  With a
     numeric argument, it pauses for the given number of seconds.  For
     example, the following statement prints a message and then waits 5
     seconds before clearing the screen.

          fprintf (stderr, "wait please...
          ");
          pause (5);
          clc;

 -- Built-in Function:  sleep (SECONDS)
     Suspend the execution of the program for the given number of
     seconds.

 -- Built-in Function:  usleep (MICROSECONDS)
     Suspend the execution of the program for the given number of
     microseconds.  On systems where it is not possible to sleep for
     periods of time less than one second, `usleep' will pause the
     execution for `round (MICROSECONDS / 1e6)' seconds.

 -- Function File: STR = datestr (DATE, [F, [P]])
     Format the given date/time according to the format `f' and return
     the result in STR. DATE is a serial date number (see `datenum') or
     a date vector (see `datevec').  The value of DATE may also be a
     string or cell array of strings.

     F can be an integer which corresponds to one of the codes in the
     table below, or a date format string.

     P is the year at the start of the century in which two-digit years
     are to be interpreted in. If not specified, it defaults to the
     current year minus 50.

     For example, the date 730736.65149 (2000-09-07 15:38:09.0934)
     would be formatted as follows:

     Code    Format                         Example
     --------------------------------------------------------------- 
     0       dd-mmm-yyyy HH:MM:SS           07-Sep-2000 15:38:09
     1       dd-mmm-yyyy                    07-Sep-2000
     2       mm/dd/yy                       09/07/00
     3       mmm                            Sep
     4       m                              S
     5       mm                             09
     6       mm/dd                          09/07
     7       dd                             07
     8       ddd                            Thu
     9       d                              T
     10      yyyy                           2000
     11      yy                             00
     12      mmmyy                          Sep00
     13      HH:MM:SS                       15:38:09
     14      HH:MM:SS PM                    03:38:09 PM
     15      HH:MM                          15:38
     16      HH:MM PM                       03:38 PM
     17      QQ-YY                          Q3-00
     18      QQ                             Q3
     19      dd/mm                          13/03
     20      dd/mm/yy                       13/03/95
     21      mmm.dd.yyyy HH:MM:SS           Mar.03.1962 13:53:06
     22      mmm.dd.yyyy                    Mar.03.1962
     23      mm/dd/yyyy                     03/13/1962
     24      dd/mm/yyyy                     12/03/1962
     25      yy/mm/dd                       95/03/13
     26      yyyy/mm/dd                     1995/03/13
     27      QQ-YYYY                        Q4-2132
     28      mmmyyyy                        Mar2047
     29      yyyymmdd                       20470313
     30      yyyymmddTHHMMSS                20470313T132603
     31      yyyy-mm-dd HH:MM:SS            1047-03-13 13:26:03

     If F is a format string, the following symbols are recognised:

     Symbol  Meaning                                         Example
     ---------------------------------------------------------------------- 
     yyyy    Full year                                       2005
     yy      Two-digit year                                  2005
     mmmm    Full month name                                 December
     mmm     Abbreviated month name                          Dec
     mm      Numeric month number (padded with zeros)        01, 08, 12
     m       First letter of month name (capitalized)        D
     dddd    Full weekday name                               Sunday
     ddd     Abbreviated weekday name                        Sun
     dd      Numeric day of month (padded with zeros)        11
     d       First letter of weekday name (capitalized)      S
     HH      Hour of day, padded with zeros if PM is set     09:00
             and not padded with zeros otherwise             9:00 AM
     MM      Minute of hour (padded with zeros)              10:05
     SS      Second of minute (padded with zeros)            10:05:03
     PM      Use 12-hour time format                         11:30 PM

     If F is not specified or is `-1', then use 0, 1 or 16, depending
     on whether the date portion or the time portion of DATE is empty.

     If P is nor specified, it defaults to the current year minus 50.

     If a matrix or cell array of dates is given, a vector of date
     strings is returned.


     *See also:* datenum, datevec, date, clock, now, datetick.

 -- Function File: V = datevec (DATE)
 -- Function File: V = datevec (DATE, F)
 -- Function File: V = datevec (DATE, P)
 -- Function File: V = datevec (DATE, F, P)
 -- Function File: [Y, M, D, H, MI, S] = datevec (...)
     Convert a serial date number (see `datenum') or date string (see
     `datestr') into a date vector.

     A date vector is a row vector with six members, representing the
     year, month, day, hour, minute, and seconds respectively.

     F is the format string used to interpret date strings (see
     `datestr').

     P is the year at the start of the century in which two-digit years
     are to be interpreted in. If not specified, it defaults to the
     current year minus 50.

     *See also:* datenum, datestr, date, clock, now.

 -- Function File:  calendar (...)
 -- Function File: C = calendar ()
 -- Function File: C = calendar (D)
 -- Function File: C = calendar (Y, M)
     If called with no arguments, return the current monthly calendar in
     a 6x7 matrix.

     If D is specified, return the calendar for the month containing
     the day D, which must be a serial date number or a date string.

     If Y and M are specified, return the calendar for year Y and month
     M.

     If no output arguments are specified, print the calendar on the
     screen instead of returning a matrix.

     *See also:* datenum.

 -- Function File: [N, S] = weekday (D, [FORM])
     Return the day of week as a number in N and a string in S, for
     example `[1, "Sun"]', `[2, "Mon"]', ..., or `[7, "Sat"]'.

     D is a serial date number or a date string.

     If the string FORM is given and is `"long"', S will contain the
     full name of the weekday; otherwise (or if FORM is `"short"'), S
     will contain the abbreviated name of the weekday.

     *See also:* datenum, datevec, eomday.

 -- Function File: E = eomday (Y, M)
     Return the last day of the month M for the year Y.

     *See also:* datenum, datevec, weekday.


File: octave.info,  Node: Filesystem Utilities,  Next: File Archiving Utilities,  Prev: Timing Utilities,  Up: System Utilities

38.2 Filesystem Utilities
=========================

Octave includes the following functions for renaming and deleting files,
creating, deleting, and reading directories, and for getting information
about the status of files.

 -- Built-in Function: [ERR, MSG] = rename (OLD, NEW)
     Change the name of file OLD to NEW.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

     *See also:* ls, dir.

 -- Built-in Function: [ERR, MSG] = link (OLD, NEW)
     Create a new link (also known as a hard link) to an existing file.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

     *See also:* symlink.

 -- Built-in Function: [ERR, MSG] = symlink (OLD, NEW)
     Create a symbolic link NEW which contains the string OLD.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

     *See also:* link, readlink.

 -- Built-in Function: [RESULT, ERR, MSG] = readlink (SYMLINK)
     Read the value of the symbolic link SYMLINK.

     If successful, RESULT contains the contents of the symbolic link
     SYMLINK, ERR is 0 and MSG is an empty string.  Otherwise, ERR is
     nonzero and MSG contains a system-dependent error message.

     *See also:* link, symlink.

 -- Built-in Function: [ERR, MSG] = unlink (FILE)
     Delete the file named FILE.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function: [FILES, ERR, MSG] = readdir (DIR)
     Return names of the files in the directory DIR as a cell array of
     strings.  If an error occurs, return an empty cell array in FILES.

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

     *See also:* dir, glob.

 -- Built-in Function: [STATUS, MSG, MSGID] = mkdir (DIR)
 -- Built-in Function: [STATUS, MSG, MSGID] = mkdir (PARENT, DIR)
     Create a directory named DIR.

     If successful, STATUS is 1, with MSG and MSGID empty character
     strings.  Otherwise, STATUS is 0, MSG contains a system-dependent
     error message, and MSGID contains a unique message identifier.

     *See also:* rmdir.

 -- Built-in Function: [STATUS, MSG, MSGID] = rmdir (DIR)
 -- Built-in Function: [STATUS, MSG, MSGID] = rmdir (DIR, `"s"')
     Remove the directory named DIR.

     If successful, STATUS is 1, with MSG and MSGID empty character
     strings.  Otherwise, STATUS is 0, MSG contains a system-dependent
     error message, and MSGID contains a unique message identifier.

     If the optional second parameter is suplied with value `"s"',
     recursively remove all subdirectories as well.

     *See also:* mkdir, confirm_recursive_rmdir.

 -- Built-in Function: VAL = confirm_recursive_rmdir ()
 -- Built-in Function: OLD_VAL = confirm_recursive_rmdir (NEW_VAL)
     Query or set the internal variable that controls whether Octave
     will ask for confirmation before recursively removing a directory
     tree.

 -- Built-in Function: [ERR, MSG] = mkfifo (NAME, MODE)
     Create a FIFO special file named NAME with file mode MODE

     If successful, ERR is 0 and MSG is an empty string.  Otherwise,
     ERR is nonzero and MSG contains a system-dependent error message.

 -- Built-in Function:  umask (MASK)
     Set the permission mask for file creation.  The parameter MASK is
     an integer, interpreted as an octal number.  If successful,
     returns the previous value of the mask (as an integer to be
     interpreted as an octal number); otherwise an error message is
     printed.

 -- Built-in Function: [INFO, ERR, MSG] = stat (FILE)
 -- Built-in Function: [INFO, ERR, MSG] = lstat (FILE)
     Return a structure S containing the following information about
     FILE.

    `dev'
          ID of device containing a directory entry for this file.

    `ino'
          File number of the file.

    `mode'
          File mode, as an integer.  Use the functions `S_ISREG',
          `S_ISDIR', `S_ISCHR', `S_ISBLK', `S_ISFIFO', `S_ISLNK', or
          `S_ISSOCK' to extract information from this value.

    `modestr'
          File mode, as a string of ten letters or dashes as would be
          returned by `ls -l'.

    `nlink'
          Number of links.

    `uid'
          User ID of file's owner.

    `gid'
          Group ID of file's group.

    `rdev'
          ID of device for block or character special files.

    `size'
          Size in bytes.

    `atime'
          Time of last access in the same form as time values returned
          from `time'.  *Note Timing Utilities::.

    `mtime'
          Time of last modification in the same form as time values
          returned from `time'.  *Note Timing Utilities::.

    `ctime'
          Time of last file status change in the same form as time
          values returned from `time'.  *Note Timing Utilities::.

    `blksize'
          Size of blocks in the file.

    `blocks'
          Number of blocks allocated for file.

     If the call is successful ERR is 0 and MSG is an empty string.  If
     the file does not exist, or some other error occurs, S is an empty
     matrix, ERR is -1, and MSG contains the corresponding system error
     message.

     If FILE is a symbolic link, `stat' will return information about
     the actual file the is referenced by the link.  Use `lstat' if you
     want information about the symbolic link itself.

     For example,

          [s, err, msg] = stat ("/vmlinuz")
                => s =
                  {
                    atime = 855399756
                    rdev = 0
                    ctime = 847219094
                    uid = 0
                    size = 389218
                    blksize = 4096
                    mtime = 847219094
                    gid = 6
                    nlink = 1
                    blocks = 768
                    mode = -rw-r--r--
                    modestr = -rw-r--r--
                    ino = 9316
                    dev = 2049
                  }
               => err = 0
               => msg =

 -- Built-in Function: [INFO, ERR, MSG] = lstat (FILE)
     See stat.

 -- Function File: [STATUS, MSG, MSGID] = fileattrib (FILE)
     Return information about FILE.

     If successful, STATUS is 1, with RESULT containing a structure
     with the following fields:

    `Name'
          Full name of FILE.

    `archive'
          True if FILE is an archive (Windows).

    `system'
          True if FILE is a system file (Windows).

    `hidden'
          True if FILE is a hidden file (Windows).

    `directory'
          True if FILE is a directory.

    `UserRead'
    `GroupRead'
    `OtherRead'
          True if the user (group; other users) has read permission for
          FILE.

    `UserWrite'
    `GroupWrite'
    `OtherWrite'
          True if the user (group; other users) has write permission for
          FILE.

    `UserExecute'
    `GroupExecute'
    `OtherExecute'
          True if the user (group; other users) has execute permission
          for FILE.
     If an attribute does not apply (i.e., archive on a Unix system)
     then the field is set to NaN.

     With no input arguments, return information about the current
     directory.

     If FILE contains globbing characters, return information about all
     the matching files.

     *See also:* glob.

 -- Function File:  isdir (F)
     Return true if F is a directory.

 -- Built-in Function:  glob (PATTERN)
     Given an array of strings (as a char array or a cell array) in
     PATTERN, return a cell array of file names that match any of them,
     or an empty cell array if no patterns match.  Tilde expansion is
     performed on each of the patterns before looking for matching file
     names.  For example,

          glob ("/vm*")
               => "/vmlinuz"


     *See also:* dir, ls, stat, readdir.

 -- Built-in Function:  fnmatch (PATTERN, STRING)
     Return 1 or zero for each element of STRING that matches any of
     the elements of the string array PATTERN, using the rules of
     filename pattern matching.  For example,

          fnmatch ("a*b", {"ab"; "axyzb"; "xyzab"})
               => [ 1; 1; 0 ]

 -- Built-in Function:  file_in_path (PATH, FILE)
 -- Built-in Function:  file_in_path (PATH, FILE, "all")
     Return the absolute name of FILE if it can be found in PATH.  The
     value of PATH should be a colon-separated list of directories in
     the format described for `path'.  If no file is found, return an
     empty matrix.  For example,

          file_in_path (EXEC_PATH, "sh")
               => "/bin/sh"

     If the second argument is a cell array of strings, search each
     directory of the path for element of the cell array and return the
     first that matches.

     If the third optional argument `"all"' is supplied, return a cell
     array containing the list of all files that have the same name in
     the path.  If no files are found, return an empty cell array.

     *See also:* file_in_loadpath.

 -- Built-in Function:  tilde_expand (STRING)
     Performs tilde expansion on STRING.  If STRING begins with a tilde
     character, (`~'), all of the characters preceding the first slash
     (or all characters, if there is no slash) are treated as a
     possible user name, and the tilde and the following characters up
     to the slash are replaced by the home directory of the named user.
     If the tilde is followed immediately by a slash, the tilde is
     replaced by the home directory of the user running Octave.  For
     example,

          tilde_expand ("~joeuser/bin")
               => "/home/joeuser/bin"
          tilde_expand ("~/bin")
               => "/home/jwe/bin"

 -- Built-in Function: [CNAME, STATUS, MSG] canonicalize_file_name
          (NAME)
     Return the canonical name of file NAME.

 -- Function File: [STATUS, MSG, MSGID] = movefile (F1, F2)
     Move the file F1 to the new name F2.  The name F1 may contain
     globbing patterns.  If F1 expands to multiple file names, F2 must
     be a directory.

     If successful, STATUS is 1, with MSG and MSGID empty\n\ character
     strings.  Otherwise, STATUS is 0, MSG contains a\n\
     system-dependent error message, and MSGID contains a unique\n\
     message identifier.\n\

     *See also:* glob.

 -- Function File: [STATUS, MSG, MSGID] = copyfile (F1, F2, FORCE)
     Copy the file F1 to the new name F2.  The name F1 may contain
     globbing patterns.  If F1 expands to multiple file names, F2 must
     be a directory. If FORCE is given and equals the string "f" the
     copy operation will be forced.

     If successful, STATUS is 1, with MSG and MSGID empty\n\ character
     strings.  Otherwise, STATUS is 0, MSG contains a\n\
     system-dependent error message, and MSGID contains a unique\n\
     message identifier.\n\

     *See also:* glob, movefile.

 -- Function File: [DIR, NAME, EXT, VER] = fileparts (FILENAME)
     Return the directory, name, extension, and version components of
     FILENAME.

     *See also:* fullfile.

 -- Built-in Function:  filesep ()
     Return the system-dependent character used to separate directory
     names.

     *See also:* pathsep, dir, ls.

 -- Function File: FILENAME = fullfile (DIR1, DIR2, ..., FILE)
     Return a complete filename constructed from the given components.

     *See also:* fileparts.

 -- Function File: DIR = fullfile ()
     Return the name of the system's directory for temporary files.

 -- Function File: filename =  tempname ()
     This function is an alias for `tmpnam'.

 -- Built-in Function:  P_tmpdir ()
     Return the default name of the directory for temporary files on
     this system.  The name of this directory is system dependent.


File: octave.info,  Node: File Archiving Utilities,  Next: Networking Utilities,  Prev: Filesystem Utilities,  Up: System Utilities

38.3 File Archiving Utilities
=============================

 -- Function File:  bunzip2 (BZFILE, DIR)
     Unpack the bzip2 archive BZFILE to the directory DIR. If DIR is
     not specified, it defaults to the current directory.

     *See also:* unpack, bzip2, tar, untar, gzip, gunzip, zip, unzip.

 -- Function File:  gunzip (GZFILE, DIR)
     Unpack the gzip archive GZFILE to the directory DIR. If DIR is not
     specified, it defaults to the current directory. If the GZFILE is
     a directory, all files in the directory will be recursively
     gunzipped.

     *See also:* unpack, bzip2, bunzip2, tar, untar, gzip, gunzip, zip,
     unzip.

 -- Function File: ENTRIES = tar (TARFILE, FILES, ROOT)
     Pack FILES FILES into the TAR archive TARFILE.  The list of files
     must be a string or a cell array of strings.

     The optional argument ROOT changes the relative path of FILES from
     the current directory.

     If an output argument is requested the entries in the archive are
     returned in a cell array.

     *See also:* untar, gzip, gunzip, zip, unzip.

 -- Function File:  untar (TARFILE, DIR)
     Unpack the TAR archive TARFILE to the directory DIR.  If DIR is
     not specified, it defaults to the current directory.

     *See also:* unpack, bzip2, bunzip2, tar, gzip, gunzip, zip, unzip.

 -- Function File: ENTRIES = zip (ZIPFILE, FILES)
 -- Function File: ENTRIES = zip (ZIPFILE, FILES, ROOTDIR)
     Compress the list of files and/or directories specified in FILES
     into the archive ZIPFILES in the same directory. If ROOTDIR is
     defined the FILES is located relative to ROOTDIR rather than the
     current directory

     *See also:* unzip,tar.

 -- Function File:  unzip (ZIPFILE, DIR)
     Unpack the ZIP archive ZIPFILE to the directory DIR.  If DIR is
     not specified, it defaults to the current directory.

     *See also:* unpack, bzip2, bunzip2, tar, untar, gzip, gunzip, zip.

 -- Function File:  pack ()
     This function is provided for compatibility with MATLAB, but it
     doesn't actually do anything.

 -- Function File: FILES = unpack (FILE, DIR)
 -- Function File: FILES = unpack (FILE, DIR, FILETYPE)
     Unpack the archive FILE based on its extension to the directory
     DIR.  If FILE is a cellstr, then all files will be handled
     individually.  If DIR is not specified, it defaults to the current
     directory.  It returns a list of FILES unpacked. If a directory is
     in the file list, then the FILETYPE to unpack must also be
     specified.

     The FILES includes the entire path to the output files.

     *See also:* bzip2,bunzip2,tar,untar,gzip,gunzip,zip,unzip.

