This is octave.info, produced by makeinfo version 4.6 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: Specialized Two-Dimensional Plots,  Next: Three-Dimensional Plotting,  Prev: Two-Dimensional Plotting,  Up: Plotting

Specialized Two-Dimensional Plots
=================================

 - Function File:  bar (X, Y)
     Given two vectors of x-y data, `bar' produces a bar graph.

     If only one argument is given, it is taken as a vector of y-values
     and the x coordinates are taken to be the indices of the elements.

     If two output arguments are specified, the data are generated but
     not plotted.  For example,

          bar (x, y);

     and

          [xb, yb] = bar (x, y);
          plot (xb, yb);

     are equivalent.

 - Function File:  contour (Z, N)
 - Function File:  contour (X, Y, Z, N)
     Make a contour plot of the three-dimensional surface described by
     Z.  Someone needs to improve `gnuplot''s contour routines before
     this will be very useful.

 - Function File:  hist (Y, X, NORM)
     Produce histogram counts or plots.

     With one vector input argument, plot a histogram of the values with
     10 bins.  The range of the histogram bins is determined by the
     range of the data.

     Given a second scalar argument, use that as the number of bins.

     Given a second vector argument, use that as the centers of the
     bins, with the width of the bins determined from the adjacent
     values in the vector.

     If third argument is provided, the histogram is normalised such
     that the sum of the bars is equal to NORM.

     Extreme values are lumped in the first and last bins.

     With two output arguments, produce the values NN and XX such that
     `bar (XX, NN)' will plot the histogram.

 - Function File:  loglog (ARGS)
     Make a two-dimensional plot using log scales for both axes.  See
     the description of `plot' for a description of the arguments that
     `loglog' will accept.

 - Function File:  polar (THETA, RHO, FMT)
     Make a two-dimensional plot given polar the coordinates THETA and
     RHO.

     The optional third argument specifies the line type.

 - Function File:  semilogx (ARGS)
     Make a two-dimensional plot using a log scale for the X axis.  See
     the description of `plot' for a description of the arguments that
     `semilogx' will accept.

 - Function File:  semilogy (ARGS)
     Make a two-dimensional plot using a log scale for the Y axis.  See
     the description of `plot' for a description of the arguments that
     `semilogy' will accept.

 - Function File:  stairs (X, Y)
     Given two vectors of x-y data, bar produces a `stairstep' plot.

     If only one argument is given, it is taken as a vector of y-values
     and the x coordinates are taken to be the indices of the elements.

     If two output arguments are specified, the data are generated but
     not plotted.  For example,

          stairs (x, y);

     and

          [xs, ys] = stairs (x, y);
          plot (xs, ys);

     are equivalent.

 - Function File:  errorbar (ARGS)
     This function produces two-dimensional plots with errorbars. Many
     different combinations of arguments are possible.  The simplest
     form is

          errorbar (Y, EY)

     where the first argument is taken as the set of Y coordinates and
     the second argument EY is taken as the errors of the Y values. X
     coordinates are taken to be the indices of the elements, starting
     with 1.

     If more than two arguments are given, they are interpreted as

          errorbar (X, Y, ..., FMT ...)

     where after X and Y there can be up to four error parameters such
     as EY, EX, LY, UY etc., depending on the plot type. Any number of
     argument sets may appear, as long as they are separated with a
     format string FMT.

     If Y is a matrix, X and error parameters must also be matrices
     having same dimensions. The columns of Y are plotted versus the
     corresponding columns of X and errorbars are drawn from the
     corresponding columns of error parameters.

     If FMT is missing, yerrorbars ("~") plot style is assumed.  If the
     FMT argument is supplied, it is interpreted as in normal plots
     (See __pltopt__). In addition the following plot styles are
     supported by errorbar:

    `~'
          Set yerrorbars plot style (default).

    `>'
          Set xerrorbars plot style.

    `~>'
          Set xyerrorbars plot style.

    `#'
          Set boxes plot style.

    `#~'
          Set boxerrorbars plot style.

    `#~>'
          Set boxxyerrorbars plot style.


     Examples:

          errorbar(X, Y, EX, ">")

     xerrorbar plot of Y versus X with X errorbars drawn from X-EX to
     X+EX.

          errorbar(X, Y1, EY, "~", X, Y2, LY, UY)

     Two yerrorbar plots with Y1 and Y2 versus X.  Errorbars for Y1 are
     drawn from Y1-EY to Y1+EY, errorbars for Y2 from Y2-LY to Y2+UY.

          errorbar(X, Y, LX, UX, LY, UY, "~>")

     xyerrorbar plot of Y versus X where X errorbars are drawn from
     X-LX to X+UX and Y errorbars from Y-LY to Y+UY.


 - Function File:  loglogerr (ARGS)
     This function produces two-dimensional plots on double logarithm
     axis with errorbars. Many different combinations of arguments are
     possible.  The most used form is

          loglogerr (X, Y, EY, FMT)

     which produces a double logarithm plot of Y versus X with errors
     in the Y-scale defined by EY and the plot format defined by FMT.
     See errorbar for available formats and additional information.


 - Function File:  semilogxerr (ARGS)
     This function produces two-dimensional plots on a semilogarithm
     axis with errorbars. Many different combinations of arguments are
     possible.  The most used form is

          semilogxerr (X, Y, EY, FMT)

     which produces a semi-logarithm plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT. See
     errorbar for available formats and additional information.


 - Function File:  semilogyerr (ARGS)
     This function produces two-dimensional plots on a semilogarithm
     axis with errorbars. Many different combinations of arguments are
     possible.  The most used form is

          semilogyerr (X, Y, EY, FMT)

     which produces a semi-logarithm plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT. See
     errorbar for available formats and additional information.



File: octave.info,  Node: Three-Dimensional Plotting,  Next: Plot Annotations,  Prev: Specialized Two-Dimensional Plots,  Up: Plotting

Three-Dimensional Plotting
==========================

 - Command: gsplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 3-dimensional plot.

     The RANGES, USING, TITLE, and STYLE arguments are optional, and
     the USING, TITLE and STYLE qualifiers may appear in any order
     after the expression.  You may plot multiple expressions with a
     single command by separating them with commas.  Each expression
     may have its own set of qualifiers.

     The optional item RANGES has the syntax

          [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]

     and may be used to specify the ranges for the axes of the plot,
     independent of the actual range of the data.  The range for the y
     and z axes and any of the individual limits may be omitted.  A
     range `[:]' indicates that the default limits should be used.  This
     normally means that a range just large enough to include all the
     data points will be used.

     The expression to be plotted must not contain any literal matrices
     (e.g.  `[ 1, 2; 3, 4 ]') since it is nearly impossible to
     distinguish a plot range from a matrix of data.

     See the help for `gnuplot' for a description of the syntax for the
     optional items.

     By default, the `gsplot' command plots each column of the
     expression as the z value, using the row index as the x value, and
     the column index as the y value.  The indices are counted from
     zero, not one.  For example,

          gsplot rand (5, 2)

     will plot a random surface, with the x and y values taken from the
     row and column indices of the matrix.

     If parametric plotting mode is set (using the command `gset
     parametric', then `gsplot' takes the columns of the matrix three
     at a time as the x, y and z values that define a line in three
     space.  Any extra columns are ignored, and the x and y values are
     expected to be sorted.  For example, with `parametric' set, it
     makes sense to plot a matrix like

          1 1 3 2 1 6 3 1 9
          1 2 2 2 2 5 3 2 8
          1 3 1 2 3 4 3 3 7

     but not `rand (5, 30)'.

   The MATLAB-style three-dimensional plotting commands are:

 - Function File:  mesh (X, Y, Z)
     Plot a mesh given matrices X, and Y from `meshdom' and a matrix Z
     corresponding to the X and Y coordinates of the mesh.  If X and Y
     are vectors, then a typical vertex is (X(j), Y(i), Z(i,j)).  Thus,
     columns of Z correspond to different X values and rows of Z
     correspond to different Y values.

 - Function File: [XX, YY] = meshgrid (X, Y)
 - Function File: [XX, YY] = meshgrid (X)
     Given vectors of X and Y coordinates, return two matrices
     corresponding to the X and Y coordinates of a mesh.  The rows of
     XX are copies of X, and the columns of YY are copies of Y.

 - Function File:  meshdom (X, Y)
     Given vectors of X and Y coordinates, return two matrices
     corresponding to the X and Y coordinates of the mesh.

     Note: this function is provided for compatibility with older
     versions of MATLAB.  You should use `meshgrid' instead.


File: octave.info,  Node: Plot Annotations,  Next: Multiple Plots on One Page,  Prev: Three-Dimensional Plotting,  Up: Plotting

Plot Annotations
================

 - Function File:  grid (ARG)
     For two-dimensional plotting, force the display of a grid on the
     plot.  The argument may be either `"on"' or `"off"'.  If it is
     omitted, `"on"' is assumed.

 - Function File:  title (STRING)
     Specify a title for a plot.  If you already have a plot displayed,
     use the command `replot' to redisplay it with the new title.

 - Function File:  bottom_title (STRING)
     See top_title.

 - Function File:  xlabel (STRING)
 - Function File:  ylabel (STRING)
 - Function File:  zlabel (STRING)
     Specify x, y, and z axis labels for the plot.  If you already have
     a plot displayed, use the command `replot' to redisplay it with
     the new labels.


File: octave.info,  Node: Multiple Plots on One Page,  Next: Multiple Plot Windows,  Prev: Plot Annotations,  Up: Plotting

Multiple Plots on One Page
==========================

The following functions all require a version of `gnuplot' that
supports the multiplot feature.

 - Function File:  mplot (X, Y)
 - Function File:  mplot (X, Y, FMT)
 - Function File:  mplot (X1, Y1, X2, Y2)
     This is a modified version of the `plot' function that works with
     the multiplot version of `gnuplot' to plot multiple plots per page.
     This plot version automatically advances to the next subplot
     position after each set of arguments are processed.

     See the description of the PLOT function for the various options.

 - Function File:  multiplot (XN, YN)
     Sets and resets multiplot mode.

     If the arguments are non-zero, `multiplot' will set up multiplot
     mode with XN, YN subplots along the X and Y axes.  If both
     arguments are zero, `multiplot' closes multiplot mode.

 - Function File:  oneplot ()
     If in multiplot mode, switches to single plot mode.

 - Function File:  plot_border (...)
     Multiple arguments allowed to specify the sides on which the border
     is shown.  Allowed arguments include:

    `"blank"'
          No borders displayed.

    `"all"'
          All borders displayed

    `"north"'
          North Border

    `"south"'
          South Border

    `"east"'
          East Border

    `"west"'
          West Border

     The arguments may be abbreviated to single characters.  Without any
     arguments, `plot_border' turns borders off.

 - Function File:  subplot (ROWS, COLS, INDEX)
 - Function File:  subplot (RCN)
     Sets `gnuplot' in multiplot mode and plots in location given by
     index (there are COLS by ROWS subwindows).

     The global variable __MULTIPLOT_SCALE__ should be used when the
     command `gset size xsize, ysize' has been used prior to calling
     `subplot'.

     The value of __MULTIPLOT_SCALE__ should be a vector with two
     elements, the first set equal to XSIZE and the second to YSIZE.

     Input:

    ROWS
          Number of rows in subplot grid.

    COLUMNS
          Number of columns in subplot grid.

    INDEX
          Index of subplot where to make the next plot.

     If only one argument is supplied, then it must be a three digit
     value specifying the location in digits 1 (rows) and 2 (columns)
     and the plot index in digit 3.

     The plot index runs row-wise.  First all the columns in a row are
     filled and then the next row is filled.

     For example, a plot with 4 by 2 grid will have plot indices
     running as follows:
          +-----+-----+-----+-----+
          |  1  |  2  |  3  |  4  |
          +-----+-----+-----+-----+
          |  5  |  6  |  7  |  8  |
          +-----+-----+-----+-----+

 - Function File:  subwindow (XN, YN)
     Sets the subwindow position in multiplot mode for the next plot.
     The multiplot mode has to be previously initialized using the
     `multiplot' function, otherwise this command just becomes an alias
     to `multiplot'

 - Function File:  top_title (STRING)
 - Function File:  bottom_title (STRING)
     Makes a title with text STRING at the top (bottom) of the plot.


File: octave.info,  Node: Multiple Plot Windows,  Next: Interaction with gnuplot,  Prev: Multiple Plots on One Page,  Up: Plotting

Multiple Plot Windows
=====================

 - Function File:  figure (N)
     Set the current plot window to plot window N.  This function
     currently requires X11 and a version of gnuplot that supports
     multiple frames.


File: octave.info,  Node: Interaction with gnuplot,  Prev: Multiple Plot Windows,  Up: Plotting

Interaction with `gnuplot'
==========================

 - Built-in Variable: gnuplot_binary
     The name of the program invoked by the plot command.  The default
     value is `"gnuplot"'.  *Note Installation::.

 - Built-in Variable: gnuplot_has_frames
     If the value of this variable is nonzero, Octave assumes that your
     copy of gnuplot has support for multiple frames that is included
     in recent 3.6beta releases.  It's initial value is determined by
     configure, but it can be changed in your startup script or at the
     command line in case configure got it wrong, or if you upgrade
     your gnuplot installation.

 - Built-in Function:  graw (STRING)
     Send STRING directly to gnuplot subprocess.

 - Built-in Variable: gnuplot_command_plot

 - Built-in Variable: gnuplot_command_replot

 - Built-in Variable: gnuplot_command_splot

 - Built-in Variable: gnuplot_command_using

 - Built-in Variable: gnuplot_command_with

 - Built-in Variable: gnuplot_command_axes

 - Built-in Variable: gnuplot_command_title

 - Built-in Variable: gnuplot_command_end


File: octave.info,  Node: Matrix Manipulation,  Next: Arithmetic,  Prev: Plotting,  Up: Top

Matrix Manipulation
*******************

There are a number of functions available for checking to see if the
elements of a matrix meet some condition, and for rearranging the
elements of a matrix.  For example, Octave can easily tell you if all
the elements of a matrix are finite, or are less than some specified
value.  Octave can also rotate the elements, extract the upper- or
lower-triangular parts, or sort the columns of a matrix.

* Menu:

* Finding Elements and Checking Conditions::
* Rearranging Matrices::
* Special Utility Matrices::
* Famous Matrices::


File: octave.info,  Node: Finding Elements and Checking Conditions,  Next: Rearranging Matrices,  Up: Matrix Manipulation

Finding Elements and Checking Conditions
========================================

The functions `any' and `all' are useful for determining whether any or
all of the elements of a matrix satisfy some condition.  The `find'
function is also useful in determining which elements of a matrix meet
a specified condition.

 - Built-in Function:  any (X, DIM)
     For a vector argument, return 1 if any element of the vector is
     nonzero.

     For a matrix argument, return a row vector of ones and zeros with
     each element indicating whether any of the elements of the
     corresponding column of the matrix are nonzero.  For example,

          any (eye (2, 4))
               => [ 1, 1, 0, 0 ]

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

          any (eye (2, 4), 2)
               => [ 1; 1 ]

 - Built-in Function:  all (X, DIM)
     The function `all' behaves like the function `any', except that it
     returns true only if all the elements of a vector, or all the
     elements along dimension DIM of a matrix, are nonzero.

   Since the comparison operators (*note Comparison Ops::) return
matrices of ones and zeros, it is easy to test a matrix for many
things, not just whether the elements are nonzero.  For example,

     all (all (rand (5) < 0.9))
          => 0

tests a random 5 by 5 matrix to see if all of its elements are less
than 0.9.

   Note that in conditional contexts (like the test clause of `if' and
`while' statements) Octave treats the test as if you had typed `all
(all (condition))'.

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

 - Function File:  is_duplicate_entry (X)
     Return non-zero if any entries in X are duplicates of one another.

 - Function File:  diff (X, K)
     If X is a vector of length N, `diff (X)' is the vector of first
     differences X(2) - X(1), ..., X(n) - X(n-1).

     If X is a matrix, `diff (X)' is the matrix of column differences.

     The second argument is optional.  If supplied, `diff (X, K)',
     where K is a nonnegative integer, returns the K-th differences.

 - Mapping Function:  isinf (X)
     Return 1 for elements of X that are infinite and zero otherwise.
     For example,

          isinf ([13, Inf, NA, NaN])
               => [ 0, 1, 0, 0 ]

 - Mapping Function:  isnan (X)
     Return 1 for elements of X that are NaN values and zero otherwise.
     For example,

          isnan ([13, Inf, NA, NaN])
               => [ 0, 0, 0, 1 ]

 - Mapping Function:  finite (X)
     Return 1 for elements of X that are finite values and zero
     otherwise. For example,

          finite ([13, Inf, NaN])
               => [ 1, 0, 0 ]

 - Loadable Function:  find (X)
     Return a vector of indices of nonzero elements of a matrix.  To
     obtain a single index for each matrix element, Octave pretends
     that the columns of a matrix form one long vector (like Fortran
     arrays are stored).  For example,

          find (eye (2))
               => [ 1; 4 ]

     If two outputs are requested, `find' returns the row and column
     indices of nonzero elements of a matrix.  For example,

          [i, j] = find (2 * eye (2))
               => i = [ 1; 2 ]
               => j = [ 1; 2 ]

     If three outputs are requested, `find' also returns a vector
     containing the nonzero values.  For example,

          [i, j, v] = find (3 * eye (2))
               => i = [ 1; 2 ]
               => j = [ 1; 2 ]
               => v = [ 3; 3 ]

 - Function File: [ERR, Y1, ...] = common_size (X1, ...)
     Determine if all input arguments are either scalar or of common
     size.  If so, ERR is zero, and YI is a matrix of the common size
     with all entries equal to XI if this is a scalar or XI otherwise.
     If the inputs cannot be brought to a common size, errorcode is 1,
     and YI is XI.  For example,

          [errorcode, a, b] = common_size ([1 2; 3 4], 5)
          => errorcode = 0
          => a = [ 1, 2; 3, 4 ]
          => b = [ 5, 5; 5, 5 ]

     This is useful for implementing functions where arguments can
     either be scalars or of common size.


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

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

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

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

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

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

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

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

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

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

 - Function File:  reshape (A, M, N, ...)
 - Function File:  reshape (A, SIZ)
     Return a matrix with the given dimensions whose elements are taken
     from the matrix A.  The elements of the matrix are access in
     column-major order (like Fortran arrays are stored).

     For example,

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

     Note that the total number of elements in the original matrix must
     match the total number of elements in the new matrix.

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

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

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

     For example,

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

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

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

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

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

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

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

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

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

     For example,

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

     and

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

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

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

 - Function File:  prepad (X, L, C)
 - Function File:  postpad (X, L, C)
     Prepends (appends) the scalar value C to the vector X until it is
     of length L.  If the third argument is not supplied, a value of 0
     is used.

     If `length (X) > L', elements from the beginning (end) of X are
     removed until a vector of length L is obtained.

     If X is a matrix, elements are prepended or removed from each row.

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

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


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

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

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

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

     The following expressions all produce the same result:

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

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

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

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

          val_matrix = val * ones (n, m)

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

 - Function File:  repmat (A, M, N)
 - Function File:  repmat (A, [M N])
     Form a block matrix of size M by N, with a copy of matrix A as
     each element.  If N is not specified, form an M by M block matrix.

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

          rand ("seed", X)

     where X is a scalar value.  If called as

          rand ("seed")

     `rand' returns the current value of the seed.

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

          randn ("seed", X)

     where X is a scalar value.  If called as

          randn ("seed")

     `randn' returns the current value of the seed.

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

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

and

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

produce equivalent results.

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

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

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

 - Function File:  randperm (N)
     Return a row vector containing a random permutation of the
     integers from 1 to N.

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

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

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

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

     The `linspace' function always returns a row vector.

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

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

 - Built-in Variable: warn_neg_dim_as_zero
     If the value of `warn_neg_dim_as_zero' is nonzero, print a warning
     for expressions like

          eye (-1)

     The default value is 0.

 - Built-in Variable: warn_imag_to_real
     If the value of `warn_imag_to_real' is nonzero, a warning is
     printed for implicit conversions of complex numbers to real
     numbers.  The default value is 0.


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

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

The following functions return famous matrix forms.

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

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

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

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

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

 - Function File:  invhilb (N)
     Return the inverse of a Hilbert matrix of order N.  This can be
     computed computed exactly using

                      (i+j)         /n+i-1\  /n+j-1\   /i+j-2\ 2
           A(i,j) = -1      (i+j-1)(       )(       ) (       )
                                    \ n-j /  \ n-i /   \ i-2 /
          
                  = p(i) p(j) / (i+j-1)
     where
                       k  /k+n-1\   /n\
              p(k) = -1  (       ) (   )
                          \ k-1 /   \k/

     The validity of this formula can easily be checked by expanding
     the binomial coefficients in both formulas as factorials.  It can
     be derived more directly via the theory of Cauchy matrices: see J.
     W. Demmel, Applied Numerical Linear Algebra, page 92.

     Compare this with the numerical calculation of `inverse (hilb
     (n))', which suffers from the ill-conditioning of the Hilbert
     matrix, and the finite precision of your computer's floating point
     arithmetic.


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

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

     A square Toeplitz matrix has the form

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

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

     A Vandermonde matrix has the form

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


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

Arithmetic
**********

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

* Menu:

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


File: octave.info,  Node: Utility Functions,  Next: Complex Arithmetic,  Up: Arithmetic

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

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

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

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

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

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

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

          gcd (a1, ..., ak)

     is the same as

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

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

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

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

          lcm (a1, ..., ak)

     is the same as

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

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

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

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

 - Mapping Function:  max (X, Y)
 - Mapping Function: [W, IW] = max (X)
     For a vector argument, return the maximum value.  For a matrix
     argument, return the maximum value from each column, as a row
     vector.  For two matrices (or a matrix and scalar), return the
     pair-wise maximum.  Thus,

          max (max (X))

     returns the largest element of X, and

          max (2:5, pi)
              =>  3.1416  3.1416  4.0000  5.0000

     compares each element of the range `2:5' with `pi', and returns a
     row vector of the maximum values.

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

     If called with one input and two output arguments, `max' also
     returns the first index of the maximum value(s). Thus,

          [x, ix] = max ([1, 3, 5, 2, 5])
              =>  x = 5
                  ix = 3

 - Mapping Function:  min (X, Y)
 - Mapping Function: [W, IW] = min (X)
     For a vector argument, return the minimum value.  For a matrix
     argument, return the minimum value from each column, as a row
     vector.  For two matrices (or a matrix and scalar), return the
     pair-wise minimum.  Thus,

          min (min (X))

     returns the smallest element of X, and

          min (2:5, pi)
              =>  2.0000  3.0000  3.1416  3.1416

     compares each element of the range `2:5' with `pi', and returns a
     row vector of the minimum values.

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

     If called with one input and two output arguments, `min' also
     returns the first index of the minimum value(s). Thus,

          [x, ix] = min ([1, 3, 0, 2, 5])
              =>  x = 0
                  ix = 3

 - Mapping Function:  mod (X, Y)
     Compute modulo function, using

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

     Note that this handles negative numbers correctly: `mod (-1, 3)'
     is 2, not -1 as `rem (-1, 3)' returns.  Also, `mod (X, 0)' returns
     X.

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

     For example,

          abs (3 + 4i)
               => 5

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

     in radians.

     For example,

          arg (3 + 4i)
               => 0.92730

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

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

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


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

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

Octave provides the following trigonometric functions.  Angles are
specified in radians.  To convert from degrees to radians multipy by
`pi/180'  (e.g. `sin (30 * pi/180)' returns the sine of 30 degrees).

 - Mapping Function:  sin (X)
     Compute the sin of each element of X.

 - Mapping Function:  cos (X)
     Compute the cosine of each element of X.

 - Mapping Function:  tan (Z)
     Compute tanget of each element of X.

 - Mapping Function:  sec (X)
     Compute the secant of each element of X.

 - Mapping Function:  csc (X)
     Compute the cosecant of each element of X.

 - Mapping Function:  cot (X)
     Compute the cotangent of each element of X.

 - Mapping Function:  asin (X)
     Compute the inverse sine of each element of X.

 - Mapping Function:  acos (X)
     Compute the inverse cosine of each element of X.

 - Mapping Function:  atan (X)
     Compute the inverse tangent of each element of X.

 - Mapping Function:  asec (X)
     Compute the inverse secant of each element of X.

 - Mapping Function:  acsc (X)
     Compute the inverse cosecant of each element of X.

 - Mapping Function:  acot (X)
     Compute the inverse cotangent of each element of X.

 - Mapping Function:  sinh (X)
     Compute the inverse hyperbolic sin of each element of X.

 - Mapping Function:  cosh (X)
     Compute the hyperbolic cosine of each element of X.

 - Mapping Function:  tanh (X)
     Compute hyperbolic tangent of each element of X.

 - Mapping Function:  sech (X)
     Compute the hyperbolic secant of each element of X.

 - Mapping Function:  csch (X)
     Compute the hyperbolic cosecant of each element of X.

 - Mapping Function:  coth (X)
     Compute the hyperbolic cotangent of each element of X.

 - Mapping Function:  asinh (X)
     Ompute the inverse hyperbolic sine of each element of X.

 - Mapping Function:  acosh (X)
     Compute the inverse hyperbolic cosine of each element of X.

 - Mapping Function:  atanh (X)
     Compute the inverse hyperbolic tanget of each element of X.

 - Mapping Function:  asech (X)
     Compute the inverse hyperbolic secant of each element of X.

 - Mapping Function:  acsch (X)
     Compute the inverse hyperbolic cosecant of each element of X.

 - Mapping Function: acoth (X)
     Compute the inverse hyperbolic cotangent of each element of X.

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

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

 - Mapping Function:  atan2 (Y, X)
     Compute atan (Y / X) for corresponding elements of Y and X.  The
     result is in range -pi to pi.


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

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

 - Built-in Function:  sum (X, DIM)
     Sum of elements along dimension DIM.  If DIM is omitted, it
     defaults to 1 (column-wise sum).

 - Built-in Function:  prod (X, DIM)
     Product of elements along dimension DIM.  If DIM is omitted, it
     defaults to 1 (column-wise products).

 - Built-in Function:  cumsum (X, DIM)
     Cumulative sum of elements along dimension DIM.  If DIM is
     omitted, it defaults to 1 (column-wise cumulative sums).

 - Built-in Function:  cumprod (X, DIM)
     Cumulative product of elements along dimension DIM.  If DIM is
     omitted, it defaults to 1 (column-wise cumulative products).

 - Built-in Function:  sumsq (X, DIM)
     Sum of squares of elements along dimension DIM.  If DIM is
     omitted, it defaults to 1 (column-wise sum of squares).

     This function is equivalent to computing
          sum (x .* conj (x), dim)
     but it uses less memory and avoids calling conj if X is real.


File: octave.info,  Node: Special Functions,  Next: Coordinate Transformations,  Prev: Sums and Products,  Up: Arithmetic

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

 - Loadable Function: [J, IERR] = besselj (ALPHA, X, OPT)
 - Loadable Function: [Y, IERR] = bessely (ALPHA, X, OPT)
 - Loadable Function: [I, IERR] = besseli (ALPHA, X, OPT)
 - Loadable Function: [K, IERR] = besselk (ALPHA, X, OPT)
 - Loadable Function: [H, IERR] = besselh (ALPHA, K, X, OPT)
     Compute Bessel or Hankel functions of various kinds:

    `besselj'
          Bessel functions of the first kind.

    `bessely'
          Bessel functions of the second kind.

    `besseli'
          Modified Bessel functions of the first kind.

    `besselk'
          Modified Bessel functions of the second kind.

    `besselh'
          Compute Hankel functions of the first (K = 1) or second (K  =
          2) kind.

     If the argument OPT is supplied, the result is scaled by the `exp
     (-I*X)' for K = 1 or `exp (I*X)' for  K = 2.

     If ALPHA is a scalar, the result is the same size as X.  If X is a
     scalar, the result is the same size as ALPHA.  If ALPHA is a row
     vector and X is a column vector, the result is a matrix with
     `length (X)' rows and `length (ALPHA)' columns.  Otherwise, ALPHA
     and X must conform and the result will be the same size.

     The value of ALPHA must be real.  The value of X may be complex.

     If requested, IERR contains the following status information and
     is the same size as the result.

       0. Normal return.

       1. Input error, return `NaN'.

       2. Overflow, return `Inf'.

       3. Loss of significance by argument reduction results in less
          than half of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          `NaN'.

       5. Error--no computation, algorithm termination condition not
          met, return `NaN'.

 - Loadable Function: [A, IERR] = airy (K, Z, OPT)
     Compute Airy functions of the first and second kind, and their
     derivatives.

            K   Function   Scale factor (if a third argument is supplied)
           ---  --------   ----------------------------------------------
            0   Ai (Z)     exp ((2/3) * Z * sqrt (Z))
            1   dAi(Z)/dZ  exp ((2/3) * Z * sqrt (Z))
            2   Bi (Z)     exp (-abs (real ((2/3) * Z *sqrt (Z))))
            3   dBi(Z)/dZ  exp (-abs (real ((2/3) * Z *sqrt (Z))))

     The function call `airy (Z)' is equivalent to `airy (0, Z)'.

     The result is the same size as Z.

     If requested, IERR contains the following status information and
     is the same size as the result.

       0. Normal return.

       1. Input error, return `NaN'.

       2. Overflow, return `Inf'.

       3. Loss of significance by argument reduction results in less
          than half  of machine accuracy.

       4. Complete loss of significance by argument reduction, return
          `NaN'.

       5. Error--no computation, algorithm termination condition not
          met, return `NaN'

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

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

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

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

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

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

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

     For example,

          bincoeff (5, 2)
          => 10

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

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

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

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

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

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

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

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

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

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

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

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

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

     If X and Y are two - dimensional matrices the cross product is
     applied along the first dimension with 3 elements.


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

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

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

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

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


File: octave.info,  Node: Coordinate Transformations,  Next: Mathematical Constants,  Prev: Special Functions,  Up: Arithmetic

Coordinate Transformations
==========================

 - Function File:  [THETA, R] = cart2pol (X, Y)
 - Function File:  [THETA, R, Z] = cart2pol (X, Y, Z)
     Transform cartesian to polar or cylindrical coordinates.  X, Y
     (and Z) must be of same shape.  THETA describes the angle relative
     to the x - axis.  R is the distance to the z - axis (0, 0, z).

 - Function File:  [X, Y] = pol2cart (THETA, R)
 - Function File:  [X, Y, Z] = pol2cart (THETA, R, Z)
     Transform polar or cylindrical to cartesian coordinates.  THETA, R
     (and Z) must be of same shape.  THETA describes the angle relative
     to the x - axis.  R is the distance to the z - axis (0, 0, z).

 - Function File:  [THETA, PHI, R] = cart2sph (X, Y, Z)
     Transform cartesian to spherical coordinates.  X, Y and Z must be
     of same shape.  THETA describes the angle relative to the x - axis.
     PHI is the angle relative to the xy - plane.  R is the distance to
     the origin (0, 0, 0).

 - Function File:  [X, Y, Z] = sph2cart (THETA, PHI, R)
     Transform spherical to cartesian coordinates.  X, Y and Z must be
     of same shape.  THETA describes the angle relative to the x-axis.
     PHI is the angle relative to the xy-plane.  R is the distance to
     the origin (0, 0, 0).


File: octave.info,  Node: Mathematical Constants,  Prev: Coordinate Transformations,  Up: Arithmetic

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

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

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

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

     Note that NaN always compares not equal to NaN.  This behavior is
     specified by the IEEE standard for floating point arithmetic.  To
     find NaN values, you must use the `isnan' function.

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

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

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

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

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


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

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

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

* Menu:

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


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

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

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

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

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

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

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

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

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

     Algebraic eigenvalue balancing uses standard LAPACK routines.

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

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

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

 - Function File:  dmult (A, B)
     If A is a vector of length `rows (B)', return `diag (A) * B' (but
     computed much more efficiently).

 - Function File:  dot (X, Y)
     Computes the dot product of two vectors.

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

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

     For example,

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

 - Loadable Function: [X, RCOND] =  inv (A)
 - Loadable Function: [X, RCOND] =  inverse (A)
     Compute the inverse of the square matrix A.  Return an estimate of
     the reciprocal condition number if requested, otherwise warn of an
     ill-conditioned matrix if the reciprocal condition number is small.

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

     If A is a matrix:

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

    P = `2'
          Largest singular value of A.

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

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

     If A is a vector or a scalar:

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

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

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

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

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

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

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

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

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

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

     If the second argument is omitted, it is assumed that

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

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

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

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

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

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


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

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

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

          r' * r = a.

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

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

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

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

     returns

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

     The matrix is not required to be square..

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

          [q, r] = qr (a)

     returns

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

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

          `min norm(A x - b)'

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

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

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

     returns

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

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

 - Loadable Function: LAMBDA = qz (A, B)
     Generalized eigenvalue problem A x = s B x, QZ decomposition.
     Three ways to call:
       1. `lambda = qz(A,B)'

          Computes the generalized eigenvalues LAMBDA of (A - sB).

       2. `[AA, BB, Q, Z, V, W, lambda] = qz (A, B)'

          Computes qz decomposition, generalized eigenvectors, and
            generalized eigenvalues of (A - sB)
                       A V = B V diag(lambda)
                       W' A = diag(lambda) W' B
                       AA = Q'*A*Z, BB = Q'*B*Z  with Q, Z orthogonal (unitary)= I

       3. `[AA,BB,Z{,lambda}] = qz(A,B,opt)'

          As in form [2], but allows ordering of generalized eigenpairs
                 for (e.g.) solution of discrete time algebraic
          Riccati equations.          Form 3 is not available for
          complex matrices and does not compute         the generalized
          eigenvectors V, W, nor the orthogonal matrix Q.
         OPT
               for ordering eigenvalues of the GEP pencil.  The leading
               block              of the revised pencil contains all
               eigenvalues that satisfy:
              `"N"'
                    = unordered (default)

              `"S"'
                    = small: leading block has all |lambda| <=1

              `"B"'
                    = big: leading block has all |lambda >= 1

              `"-"'
                    = negative real part: leading  block has all
                    eigenvalues                   in the open left
                    half-plant

              `"+"'
                    = nonnegative real part:  leading block has all
                    eigenvalues                   in the closed right
                    half-plane

     Note: qz performs permutation balancing, but not scaling (see
     balance).        Order of output arguments was selected for
     compatibility with MATLAB

     See also: balance, dare, eig, schur

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

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

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

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

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

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

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

          a = u * sigma * v'

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

          svd (hilb (3))

     returns

          ans =
          
            1.4083189
            0.1223271
            0.0026873

     and

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

     returns

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

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

 - Function File: [HOUSV, BETA, ZER] = housh (X, J, Z)
     Computes householder reflection vector housv to reflect x to be
     jth column of identity, i.e., (I - beta*housv*housv')x =e(j) inputs
      x: vector   j: index into vector   z: threshold for zero
     (usually should be the number 0) outputs: (see Golub and Van Loan)
      beta: If beta = 0, then no reflection need be applied (zer set
     to 0)   housv: householder vector

 - Function File: [U, H, NU] = krylov (A, V, K, EPS1, PFLG);
     construct orthogonal basis U of block Krylov subspace;  [v a*v
     a^2*v ... a^(k+1)*v]; method used: householder reflections to
     guard against loss of orthogonality eps1: threshhold for 0
     (default: 1e-12) pflg: flag to use row pivoting  (improves
     numerical behavior)   0 [default]: no pivoting; prints a warning
     message if trivial                null space is corrupted   1
        : pivoting performed

     outputs:   u: orthogonal basis of block krylov subspace   h:
     Hessenberg matrix; if v is a vector then a u = u h      otherwise
     h is meaningless  nu: dimension of span of krylov subspace (based
     on eps1) if b is a vector and k > m-1, krylov returns h = the
     Hessenberg decompostion of a.

     Reference: Hodel and Misra, "Partial Pivoting in the Computation of
        Krylov Subspaces", to be submitted to Linear Algebra and its
      Applications


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

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

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

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

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

               -1
          D (a)   N (a)

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

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

 - Loadable Function: [RESULT, ERROR_ESTIMATE] = sqrtm (A)
     Compute the matrix square root of the square matrix A.

     Ref: Nicholas J. Higham. A new sqrtm for MATLAB. Numerical Analysis
     Report No. 336, Manchester Centre for Computational Mathematics,
     Manchester, England, January 1999.

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

          x = [a(i, j) b]

     For example,

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

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

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

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


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

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

Octave can solve sets of nonlinear equations of the form

     F (x) = 0

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

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

     If FCN is a two-element string array, the first element names the
     function f described above, and the second element names a
     function of the form `j (X)' to compute the Jacobian matrix with
     elements

                     df_i
          jac(i,j) = ----
                     dx_j

     You can use the function `fsolve_options' to set optional
     parameters for `fsolve'.

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

     Options include

    `"tolerance"'
          Nonnegative relative tolerance.

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

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

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

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

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

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

results in the solution

     x =
     
       0.57983
       2.54621
     
     info = 1

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

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

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


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

Quadrature
**********

* Menu:

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


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

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

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

          y = f (x)

     where Y and X are scalars.

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

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

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

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

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

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

     Options include

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

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

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

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

from X = 0 to X = 3.

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

   The first step is to define the function:

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

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

   Then we simply call quad:

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

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


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

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

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

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

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

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

   Then the solution at the roots R is

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


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

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

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

* Menu:

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


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

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

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

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

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

          dx
          -- = f(x, t)
          dt

     with

          x(t_0) = x_0

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

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

          XDOT = f (X, T)

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

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

          JAC = j (X, T)

     in which JAC is the matrix of partial derivatives

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

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

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

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

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

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

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

     Options include

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

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

          The local error test applied at each integration step is

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

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

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

         "bdf"

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

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

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

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

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

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

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

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

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

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

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

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

   Octave also includes ODESSA, a modification of LSODE that allows for
the computation of parametric sensitivity information simultaneously
with the solution of the set of ODEs.

 - Loadable Function: [X, SX, ISTATE, MSG] odessa (FCN, X_0, P, SX_0,
          T, T_CRIT)
     Solve the set of differential equations

          dx
          -- = f(x, t; p)
          dt

     with

          x(t_0) = x_0

     and simultaneously compute the first-order sensitivity coefficients
     given by

          s'(t) = j(t)*s(t) + df/dp

     in which

          s(t)  = dx(t)/dp        (sensitivity functions)
          s'(t) = d(dx(t)/dp)/dt
          j(t)  = df(x,t;p)/dx(t) (Jacobian matrix)
          df/dp = df(x,t;p)/dp    (inhomogeneity matrix)

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

     The sensitivities are returned in a list of matrices, SX, with
     each element of the list corresponding to an element of the vector
     T.

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

          XDOT = f (X, T, P)

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

     The variable P is a vector of parameters.

     The FCN argument may also be an array of strings

          ["f"; "j"; "b"]

     in which the first element names the function f described above,
     the second element names a function to compute the Jacobian of f,
     and the third element names a function to compute the
     inhomogeneity matrix.

     The Jacobian function must have the form

          JAC = j (X, T, P)

     in which X, T, and P have the same meanings as above for the
     function F, and  JAC is the matrix of partial derivatives

                df_i
          jac = ----
                dx_j

     The function B must have the form

          DFDP = b (X, T, P, C)

     in which X, T, and P have the same meanings as above for the
     function F, C indicates which partial derivatives to return in
     DFDP.  For example, if C is 2, you should return the vector

                 df_i
          dfdp = ----,    i = 1:length(x)
                 dp_2

     The second argument, X_0, specifies the intial state of the system.

     The third argument, P, specifies the set of parameters.

     The fourth argument, SX_0 specifies the initial values of the
     sensitivities.

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

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

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

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

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

     Options include

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

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

          The local error test applied at each integration step is

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

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

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

         "bdf"

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

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

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

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

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

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

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


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

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

 - 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 (xdot, x, 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 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 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 saem 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'.

 - 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

Optimization
************

* Menu:

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


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

Linear Programming
==================


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

Quadratic Programming
=====================


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

Nonlinear Programming
=====================


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

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

Statistics
**********

I hope that someday Octave will include more statistics functions.  If
you would like to help improve Octave in this area, please contact
<bug-octave@bevo.che.wisc.edu>.

* Menu:

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


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

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.

 - Function File:  std (X)
     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.

 - 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)
     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 row vector containing the
     kurtosis of each column.

 - 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)
     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 row vector containing the
     skewness of each column.

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

 - 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)
     If X is a vector, subtract its mean and divide by its standard
     deviation.

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

 - 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 in the columns of X of length 1, 2, ..., N-1
     and greater than or equal to N.

 - Function File:  ranks (X)
     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 each column of X.

 - Function File:  range (X)
     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.

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

 - Function File:  meansq (X)
     For vector arguments, return the mean square of the values.  For
     matrix arguments, return a row vector contaning the mean square of
     each column.

 - 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)
     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 each column of X.

 - 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)
     If X is a vector, subtract its mean.  If X is a matrix, do the
     above for each column.


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

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

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

Distributions
=============

 - Function File:  beta_cdf (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:  beta_inv (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:  beta_pdf (X, A, B)
     For each element of X, returns the PDF at X of the beta
     distribution with parameters A and B.

 - Function File:  beta_rnd (A, B, R, C)
     Return an R by C 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:  binomial_cdf (X, N, P)
     For each element of X, compute the CDF at X of the binomial
     distribution with parameters N and P.

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

 - Function File:  binomial_pdf (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:  binomial_rnd (N, P, R, C)
     Return an R by C 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)
     Return an R by C 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:  chisquare_cdf (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:  chisquare_inv (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 K degrees of freedom.

 - Function File:  chisquare_rnd (N, R, C)
     Return an R by C 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)
     Generate a row vector containing a random sample of size N from
     the univariate distribution which assumes the values in V with
     probabilities P.

     Currently, N must be a scalar.

 - 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)
     Generate a bootstrap sample of size N from the empirical
     distribution obtained from the univariate sample DATA.

 - Function File:  exponential_cdf (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:  exponential_inv (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:  exponential_pdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) of the exponential distribution with parameter LAMBDA.

 - Function File:  exponential_rnd (LAMBDA, R, C)
     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.

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

 - Function File:  f_cdf (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:  f_inv (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:  f_pdf (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:  f_rnd (M, N, R, C)
     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 R and C are omitted, the size of the result matrix is the
     common size of M and N.

 - Function File:  gamma_cdf (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.

 - Function File:  gamma_inv (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.

 - Function File:  gamma_pdf (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.

 - Function File:  gamma_rnd (A, B, R, C)
     Return an R by C 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.

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

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

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

 - Function File:  geometric_rnd (P, R, C)
     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 omitted, the size of the result matrix is the size
     of P.

 - Function File:  hypergeometric_cdf (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:  hypergeometric_inv (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:  hypergeometric_pdf (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:  hypergeometric_rnd (N_SIZE, M, T, N)
     Generate a row vector containing a random sample of size N_SIZE
     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)
     Return an R by C matrix of random numbers from the Laplace
     distribution.

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

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

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

 - Function File:  logistic_rnd (R, C)
     Return an R by C matrix of random numbers from the logistic
     distribution.

 - Function File:  lognormal_cdf (X, A, V)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the lognormal distribution with parameters
     A and V.  If a random variable follows this distribution, its
     logarithm is normally distributed with mean `log (A)' and variance
     V.

     Default values are A = 1, V = 1.

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

     Default values are A = 1, V = 1.

 - Function File:  lognormal_pdf (X, A, V)
     For each element of X, compute the probability density function
     (PDF) at X of the lognormal distribution with parameters A and V.
     If a random variable follows this distribution, its logarithm is
     normally distributed with mean `log (A)' and variance V.

     Default values are A = 1, V = 1.

 - Function File:  lognormal_rnd (A, V, R, C)
     Return an R by C matrix of random samples from the lognormal
     distribution with parameters A and V. Both A and V 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 V.

 - Function File:  normal_cdf (X, M, V)
     For each element of X, compute the cumulative distribution
     function (CDF) at X of the normal distribution with mean M and
     variance V.

     Default values are M = 0, V = 1.

 - Function File:  normal_inv (X, M, V)
     For each element of X, compute the quantile (the inverse of the
     CDF) at X of the normal distribution with mean M and variance V.

     Default values are M = 0, V = 1.

 - Function File:  normal_pdf (X, M, V)
     For each element of X, compute the probability density function
     (PDF) at X of the normal distribution with mean M and variance V.

     Default values are M = 0, V = 1.

 - Function File:  normal_rnd (M, V, R, C)
     Return an R by C matrix of random samples from the normal
     distribution with parameters M and V.  Both M and V 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 V.

 - Function File:  pascal_cdf (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:  pascal_inv (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:  pascal_pdf (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:  pascal_rnd (N, P, R, C)
     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.

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

 - Function File:  poisson_inv (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:  poisson_pdf (X, LAMBDA)
     For each element of X, compute the probability density function
     (PDF) at X of the poisson distribution with parameter LAMBDA.

 - Function File:  poisson_rnd (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:  stdnormal_cdf (X)
     For each component of X, compute the CDF of the standard normal
     distribution at X.

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

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

 - Function File:  stdnormal_rnd (R, C)
     Return an R by C matrix of random numbers from the standard normal
     distribution.

 - Function File:  t_cdf (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:  t_inv (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:  t_pdf (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:  t_rnd (N, R, C)
     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.

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

 - Function File:  uniform_cdf (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:  uniform_inv (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:  uniform_pdf (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:  uniform_rnd (A, B, R, C)
     Return an R by C 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:  weibull_cdf (X, ALPHA, SIGMA)
     Compute the cumulative distribution function (CDF) at X of the
     Weibull distribution with shape parameter ALPHA and scale
     parameter SIGMA, which is

          1 - exp(-(x/sigma)^alpha)

     for X >= 0.

 - Function File:  weibull_inv (X, LAMBDA, ALPHA)
     Compute the quantile (the inverse of the CDF) at X of the Weibull
     distribution with shape parameter ALPHA and scale parameter SIGMA.

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

             alpha * sigma^(-alpha) * x^(alpha-1) * exp(-(x/sigma)^alpha)

     for X > 0.

 - Function File:  weibull_rnd (ALPHA, SIGMA, R, C)
     Return an R by C matrix of random samples from the Weibull
     distribution with parameters ALPHA and SIGMA which 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 ALPHA and SIGMA.

 - Function File:  wiener_rnd (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

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.

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

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

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

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

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

 - 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

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 ]

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

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

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

 - 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


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

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.

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

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

 - 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)
     Return the coefficients of the derivative of the polynomial whose
     coefficients are given by vector C.

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

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

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

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

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

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


File: octave.info,  Node: Control Theory,  Next: Signal Processing,  Prev: Polynomial Manipulations,  Up: Top

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.

* Menu:

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


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

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

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

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

NUM
     numerator coefficients   (vector)

DEN
     denominator coefficients   (vector)



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

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

ZER
     system zeros   (vector)

POL
     system poles    (vector)

K
     leading coefficient   (scalar)



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

`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

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::
* structintern::


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

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 [c_0 c_1 ... c_n] of the SISO FIR
          transfer function

          C(z) = c0 + c1*z^{-1} + c2*z^{-2} + ... + znz^{-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.

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


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

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

 - 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 (sampeled-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
          list of strings of state signal names

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

    INNAME
          list of strings of input signal names

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

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

     *Note* `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,list("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.

     *Inputs* 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) 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

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

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

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

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

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

     *Outputs* 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,  Next: structintern,  Prev: zp2sys,  Up: sysinterface

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

 - 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, then

         `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, then 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> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys) i  # get all signal names
          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> Ain = sysgetsignals(sys,"in")   # get only input signal names
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          octave> Aout = sysgetsignals(sys,"out",2)   # get name of output 2 (in cell array)
          Aout =
          (
            [1] = y_2
          )
          octave> Aout = sysgetsignals(sys,"out",2,1)  # get name of output 2 (as string)
          Aout = y_2

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

     *Inputs* SYS: system data structure

     *Outputs* SYSTYPE: string indicating how the structure was
     initially constructed: values: `"ss"', `"zp"', or `"tf"'

     *Note* 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", or "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.

   function [systype, nout, nin, ncstates, ndstates] = minfo(inmat)

   MINFO:  Determines the type of system matrix.  INMAT can be
a varying(*), system, constant, and empty matrix.

   Returns:      systype can be one of:            varying, system,
constant, and empty      nout is the number of outputs of the system
 nin is the number of inputs of the system      ncstates is the number
of continuous states of the system       ndstates is the number of
discrete states of the system

 - Function File:  sysgettsam (SYS)
     Return the sampling time of the system SYS.


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

Data structure internal functions
---------------------------------


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

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

 - Function File:  zpout (ZER, POL, K, X)
     print formatted zero-pole form to the screen.  X defaults to the
     string `"s"'


File: octave.info,  Node: blockdiag,  Next: numerical,  Prev: sysdisp,  Up: Control Theory

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 it's 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 H2 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]' ==> new input 1 is old inpout 1 +
          output 2 - output 1, 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 alowed
          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 alowed
          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
          (1. row) connect input 1 (G) with output 2 (K).  (2. row)
          connect input 2 (K) with neg. 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   |                    +----+
          ----|-------------+                   || GW   ||     => min.
              |             |                        vz   infty
              |    +---+    v      +----+
              *--->| G |--->O--*-->| W2 |---> v2
              |    +---+       |   +----+
              |                |
              |                v
             u                  y

     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:  jet707 ()
     Creates linearized state space model of a Boeing 707-321 aircraft
     at v=80m/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 Ref: R. Brockhaus:
     Flugregelung (Flight Control), Springer, 1994

 - 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.
     *Outputs* 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:  sysappend (SYS, B, C, D, OUTNAME, INNAME, YD)
     appends new inputs and/or outputs to a system

     *Inputs*
    SYS
          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 := [sys.b , b]
             sys.c := [sys.c  ]
                      [ c     ]
             sys.d := [sys.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 = continuous or mixed YD = `zeros(1,rows(c))'

        * SYS = discrete YD = `ones(1,rows(c))'

 - Function File:  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: 200EPS

     *Outputs* SYS: 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.

     *Inputs* SYS is a 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)
     *Inputs* 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:  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))'.

     *Outputs* 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:  sysgroup (ASYS, BSYS)
     Combines two systems into a single system

     *Inputs* ASYS, BSYS: system data structures

     *Outputs* 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:  sysmult (ASYS, BSYS)
     Compute sys = Asys*Bsys (series connection):
          u   ----------     ----------
          --->|  bsys  |---->|  asys  |--->
              ----------     ----------
     A warning occurs if there is direct feed-through from an
     input of Bsys 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:  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,list("tx","ty","tz"), 4);


     *Outputs* RETSYS: resulting system
                     ____________________
          u1 ------->|                  |----> y1
           (in_idx)  |       Asys       | (out_idx)
          u2 ------->|                  |----| y2
            (deleted)-------------------- (deleted)

 - Function File:  sysreorder (VLEN, LIST)
     *Inputs* VLEN=vector length, LIST= a subset of `[1:vlen]',

     *Outputs* 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:  sysscale (SYS, OUTSCALE, INSCALE, OUTNAME, INNAME)
     scale inputs/outputs of a system.

     *Inputs* sys: structured system outscale, inscale: constant
     matrices of appropriate dimension

     *Outputs* SYS: 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:  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.

 - Function File:  wgt1o (VL, VH, FC)
     State space description of a first order weighting function.

     Weighting function are needed by the H2/H_infinity design
     procedure.  These function are part of thye augmented plant P (see
     hinfdemo for an applicattion example).

     vl = Gain at low frequencies

     vh = Gain at high frequencies

     fc = Corner frequency (in Hz, *not* in rad/sec)

 - Function File:  parallel (ASYS, BSYS)
     Forms the parallel connection of two systems.

     ____________________              |      ________    |     u
     ---->|---> | asys |-->|---> y1         |    |      -------    |
         |    |      ________    |         |-->|---> | bsys |-->|--->
     y2              |      -------    |
     -------------------                   ksys

 - Function File: [RETSYS, NC, NO] = sysmin (SYS, FLG)
     return a minimal (or reduced order) system inputs:   sys: system
     data structure   flg: 0 [default] return minimal system; state
     names lost      : 1           return 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

Numerical Functions
===================

 - Function File:  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
          NxN matrix.

    B
          NxN matrix or NxM matrix; in the latter case B is replaced by
          b:=b*b'.

    C
          NxN matrix or PxM 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.

     *Outputs* X: solution of the ARE.

     *Method* Laub's Schur method (IEEE Transactions on Automatic
     Control, 1979) is applied to the appropriate Hamiltonian matrix.


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

    B
          N by M.

    Q
          N by N, symmetric positive semidefinite, or P by N.  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.

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


 - 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_{t_0}^{t_f} x' Q x + u' R u dt + x(t_f)' Qf x(t_f)
     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 { II } is P(TVALS(II)).

    TVALS
               is selected so that || Plist{ii} - Plist{ii-1} || < Ptol
               for ii=2:length(tvals)

 - Function File:  dgram (A, B)
     Return controllability grammian of discrete time system
            x(k+1) = a x(k) + b u(k)

     *Inputs*
    A
          N by N matrix

    B
          N by M matrix

     *Outputs* M (N by N) 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.

     *Outputs* 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 grammian 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.

     *Note* `qzval' is obsolete; use `qz' instead.

 - Function File:  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:  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:  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:  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

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.


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

     *Note* `ctrb' forms the controllability matrix.  The numerical
     properties of `is_controllable' are much better for
     controllability tests.

 - Function Fil:  h2norm (SYS)
     Computes the H2 norm of a system data structure (continuous time
     only)

     Reference: Doyle, Glover, Khargonekar, Francis, "State Space
     Solutions to Standard H2 and Hinf 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: 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 H2 and Hinf control problems", IEEE TAC
     August 1989 Iglesias and Glover, "State-Space approach to
     discrete-time Hinf control," Int. J. Control, vol 54, #5, 1991
     Zhou, Doyle, Glover, "Robust and Optimal Control," Prentice-Hall,
     1996

 - Function File:  obsv (SYS, C)
     Build observability matrix
               | C        |
               | CA       |
          Qb = | CA^2     |
               | ...      |
               | CA^(n-1) |
     of a system data structure or the pair (A, C).

     Note: `obsv()' forms the observability matrix.

     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.
     *Inputs* SYS system data structure

     *Outputs* if omitted, the poles and zeros are plotted on the
     screen.  otherwise, pol, zer are returned as the system poles and
     zeros.  (see sys2zp for a preferable function call)

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

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

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


 - 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
          threshhold for 0.  Default: 200EPS
     *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;

               *Note* B = [Bw Bu]

         CZ
               (NZ x N) Qz-transformed error output matrix

         CY
               (NY x N) RY-transformed measured output matrix

               *Note* 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 H2 and Hinf Control Problems," IEEE TAC August
          1989

    *[2]*
          Maciejowksi, J.M.: "Multivariable feedback design,"

 - Function File:  is_digital (SYS)
     Return nonzero if system is digital; inputs: sys: system data
     structure eflg: 0 [default] exit with an error if system is mixed
     (continuous and discrete components)     : 1 print a warning if
     system is mixed (continuous and discrete)     : 2 silent operation
     outputs: DIGITAL:  0: system is purely continuous        :  1:
     system is purely discrete        : -1: system is mixed continuous
     and discrete Exits with an error of 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 = 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.

 - Function File:  is_sample (TS)
     Return true if TS is a valid sampling time (real,scalar, > 0)

 - Function File:  is_siso (SYS)
     return nonzero if the system data structure SYS is single-input,
     single-output.

   This file is part of Octave.

   Octave is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.

   Octave is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

   You should have received a copy of the GNU General Public License
along with Octave; see the file COPYING.  If not, write to the Free
Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA.

 - 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 paramter, set to 200*EPS if omitted.

    DFLG
          Digital system flag (not required for system data structure):
         `DFLG != 0'
               stable if eig(a) in unit circle

         `DFLG == 0'
               stable if eig(a) in open LHP (default)


File: octave.info,  Node: systime,  Next: sysfreq,  Prev: sysprop,  Up: Control Theory

System Analysis-Time Domain
===========================

 - Function File:  c2d (SYS, OPT, T)
 - Function File:  c2d (SYS, T)
     *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.)

    T
          sampling time; required if sys is purely continuous.

          *Note* If the 2nd argument is not a string, `c2d' assumes that
          the 2nd argument is T and performs appropriate argument
          checks.

    "MATCHED"
          Use the matched pole/zero equivalent transformation
          (currently only works for purely continuous SISO systems).

     *Outputs* DSYS discrete time equivalent via zero-order hold,
     sample each T sec.

     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

     *Note* 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 discrete (sub)system to a purely continuous system.
     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
     *Outputs* 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 `listidx'

    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.

 - 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, T: impulse response

 - 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, T: impulse response

     When invoked with the output paramter y the plot is not displayed.


File: octave.info,  Node: sysfreq,  Next: cacsd,  Prev: systime,  Up: Control Theory

System Analysis-Frequency Domain
================================

*Demonstration/tutorial script*

 - Function File:  frdemo ()
     Octave Controls 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",list("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

     *Notes*
       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:  ltifr (A, B, W)
 - Function File:  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
     *Outputs* OUT
                                     -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.
          outputs, inputs: names or indices of the output(s) and
     input(s) to be used in the frequency response; see sysprune.

     *Inputs* (pass as empty to get default values)
    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:  tzero (A, B, C, D, OPT)
 - Function File:  tzero (SYS, OPT)
     Compute transmission zeros of a continuous
          .
          x = Ax + Bu
          y = Cx + Du
     or discrete
          x(k+1) = A x(k) + B u(k)
          y(k)   = C x(k) + D u(k)
     system.  *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:  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

Controller Design
=================

 - Function File:  dgkfdemo ()
     Octave Controls toolbox demo: H2/Hinfinity 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=80m/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   |                    +----+
                    ----|-------------+                   || T   ||     => min.
                        |             |                       vz   infty
                        |    +---+    v   y  +----+
                      u *--->| G |--->O--*-->| W2 |---> v2
                        |    +---+       |   +----+
                        |                |
                        |    +---+       |
                        -----| K |<-------
                             +---+
          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 (from                 y (to K)
                              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(s) = --------------------------
                           (z - 0.36788)(z - 0.13534)
               
                                             +----+
                        -------------------->| W1 |---> v1
                    z   |                    +----+
                    ----|-------------+                   || T   ||     => min.
                        |             |                       vz   infty
                        |    +---+    v      +----+
                        *--->| G |--->O--*-->| W2 |---> v2
                        |    +---+       |   +----+
                        |                |
                        |    +---+       |
                        -----| K |<-------
                             +---+
          W1 and W2 are the robustness and performancs 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 H2 optimal controller per procedure in Doyle, Glover,
     Khargonekar, Francis, "State Space Solutions to Standard H2 and
     Hinf Control Problems", IEEE TAC August 1989

     Discrete time control per Zhou, Doyle, and Glover, ROBUST AND
     OPTIMAL CONTROL, Prentice-Hall, 1996

     *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

    NU
          number of controlled inputs

    NY
          number of measured outputs

    TOL
          threshhold 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:  hinf_ctr (DGS, F, H, Z, G)
     Called by `hinfsyn' to compute the H_inf optimal controller.

     *Inputs*
    DGS
          data structure returned by `is_dgkf'

    F
    H
          feedback and filter gain (not partitioned)

    G
          final gamma value
     *Outputs* 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 threshhold.  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
          threshhold 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

       1. Doyle, Glover, Khargonekar, Francis, "State Space Solutions
          to Standard H2 and Hinf 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 and 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 H2 and Hinf 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-inf ARE

    PF
          solution of "filter" H-inf 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 + b u
          dt
          
          y = c x + d u

     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',
          `listidx')

          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

 - 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:  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 with output parameters: [y,x] =
     lsim(sys,u,t,[x0]) a plot is not displayed, however, the data is
     returned in y = system output and x = system states.

 - Function File:  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

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.  puts in margins of +/- 0.1 if data is
     one dimensional (or a single point)

     *Inputs* AXDATA nx2 matrix of data [x,y]

     *Outputs* AXVEC vector of axis limits appropriate for call to
     axis() function

 - Function File:  moddemo (INPUTS)
     Octave Controls toolbox demo: Model Manipulations demo

 - Function File:  prompt (INPUTS)
     function prompt([str])
     Prompt user to continue
     str: input string. Default value: "\n ---- Press a key to continue ---"

 - Function File:  rldemo (INPUTS)
     Octave Controls toolbox demo: Root Locus demo

 - Function File:  rlocus (INPUTS)
     [rldata, k] = rlocus(sys[,increment,min_k,max_k])
     Displays root locus plot of the specified SISO system.
     
            -----   ---     --------
        --->| + |---|k|---->| SISO |----------->
            -----   ---     --------        |
            - ^                             |
              |_____________________________|
     
     inputs: sys = system data structure
     min_k, max_k,increment: minimum, maximum values of k and
     the increment used in computing gain values
     Outputs: plots the root locus to the screen.
     rldata: Data points plotted column 1: real values, column 2: imaginary
     values)
     k: gains for real axis break points.

 - Function File:  sortcom (INPUTS)
     [yy,idx] = sortcom(xx[,opt]): sort a complex vector
     xx: complex vector
     opt: sorting option:
      "re": real part (default)
      "mag": by magnitude
      "im": by imaginary part
     
     if opt != "im" then complex conjugate pairs are grouped together,
     a - jb followed by a + jb.
     yy: sorted values
     idx: permutation vector: yy = xx(idx)

 - Function File:  ss2tf (INPUTS)
     [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:  ss2zp (INPUTS)
     Converts a state space representation to a set of poles and zeros.
     
     [pol,zer,k] = ss2zp(a,b,c,d) returns the poles and zeros of the state space
     system (a,b,c,d).  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 (= negative feedback)

 - Function File:  tf2ss (INPUTS)
     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)
     
     via the function call [a,b,c,d] = tf2ss(num,den).
     The vector 'den' must contain only one row, whereas the vector 'num'
     may contain as many rows as there are outputs of the system 'y'.
     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:  tf2zp (INPUTS)
     Converts transfer functions to poles / zeros.

     [zer,pol,k] = tf2zp(num,den) 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)

    K
          real scalar (leading coefficient)
     *Outputs* A, B, C, D The state space system
          .
          x = Ax + Bu
          y = Cx + Du
     is obtained from a vector of zeros and a vector of poles via the
     function call `[a,b,c,d] = zp2ss(zer,pol,k)'.  The vectors `zer'
     and `pol' may either be row or column vectors.  Each zero and pole
     that has an imaginary part must have a conjugate in the list.  The
     number of zeros must not exceed the number of poles.  `k' is
     `zp'-form leading coefficient.

 - 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 should appear in conjugate pairs

    K
          real scalar (leading coefficient)
     `[num,den] = zp2tf(zer,pol,k)' forms the transfer function
     `num/den' from the vectors of poles and zeros.


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

Signal Processing
*****************

I hope that someday Octave will include more signal processing
functions.  If you would like to help improve Octave in this area,
please contact <bug-octave@bevo.che.wisc.edu>.

 - 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, ifN is smaller than the
     dimension along which the 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 FFT is performed

 - 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

 - 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

 - 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

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

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

 - 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)
     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.  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: [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 columns of A unless the row dimension
     of A is 1 or DIM is given with a value of 1, when it will unwrap
     along the row(s).

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

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

Image Processing
****************

Octave can display images with the X Window System using the
`xloadimage' program.  You do not need to be running X in order to
manipulate images, however, so some of these functions may be useful
even if you are not able to view the results.

   Loading images only works with Octave's image format (a file with a
matrix containing the image data, and a matrix containing the
colormap).  Contributions of robust, well-written functions to read
other image formats are welcome.  If you can provide them, or would like
to improve Octave's image processing capabilities in other ways, please
contact <bug-octave@bevo.che.wisc.edu>.

 - 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: [IMG, MAP] = gray2ind ()
     Convert a gray scale intensity image to an Octave indexed image.

 - Function File:  image (X, ZOOM)
 - Function File:  image (X, Y, A, ZOOM)
     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.  If ZOOM is omitted, the image will be
     scaled to fit within 600x350 (to a max of 4).

     It first tries to use `display' from `ImageMagick' then `xv' and
     then `xloadimage'.

     The axis values corresponding to the matrix elements are specified
     in X and Y. At present they are ignored.

 - Function File:  imagesc (A)
 - Function File:  imagesc (X, Y, A)
 - Function File:  imagesc (..., ZOOM)
 - 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 ZOOM is omitted, a
     comfortable size is chosen.  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.  At present they are ignored.

 - Function File:  imshow (I)
 - Function File:  imshow (X, MAP)
 - Function File:  imshow (X, N)
 - Function File:  imshow (I, N)
 - Function File:  imshow (R, G, B)
     Display an image.

     `imshow (X)' displays an intensity image, estimating the number of
     gray levels.

     `imshow (X, MAP)' displays an indexed image using the specified
     colormap.

     `imshow (I, N)' displays a gray scale intensity image of N levels.

     `imshow (R, G, B)' displays an RGB image.

     The string `truesize' can always be used as an optional final
     argument to prevent automatic zooming of the 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.

 - Function File: [R, G, B] = ind2rgb (X, MAP)
     Convert an indexed image to red, green, and blue color components.
     If MAP is omitted, the current colormap is used for the conversion.

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

 - Function File:  rgb2ntsc (RGB)
     Image format conversion.

 - Function File:  ntsc2rgb (YIQ)
     Image format conversion.

 - Function File:  RGB_MAP = hsv2rgb (HSV_MAP)
     Transform a colormap from the hsv space to the rgb space.

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

 - Function File:  ocean (N)
     Create color colormap.  The argument N should be a scalar.  If it
     is omitted, 64 is assumed.

 - Function File: [X, MAP] = rgb2ind (R, G, B)
     Convert and RGB image to an Octave indexed image.

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

 - Built-in Variable: IMAGEPATH
     A colon separated list of directories in which to search for image
     files.


File: octave.info,  Node: Audio Processing,  Next: Quaternions,  Prev: Image Processing,  Up: Top

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.

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

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

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

   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.

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

 - Function File: setaudio ([W_TYPE [, VALUE]])
     executes the shell command `mixer [W_TYPE [, VALUE]]'


File: octave.info,  Node: Quaternions,  Next: System Utilities,  Prev: Audio Processing,  Up: Top

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: Tips,  Prev: Quaternions,  Up: Top

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

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.

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

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

 - 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

 - 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 (TM_STRUCT)
     Format a time structure in a flexible way using `%' 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-).

 - Loadable Function: [TM_STRUCT, NCHARS] = strptime (STR, FMT)
     Convert the string STR to a time structure under the control of
     the format FMT.

   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.

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

     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.

