### DO NOT EDIT!
###
### This file is generated automatically from the Octave sources.
### Edit those files instead and run make to update this file.

lin2mu
-*- texinfo -*-
@deftypefn {Function File} {} lin2mu (@var{x}, @var{n})
Converts audio data from linear to mu-law.  Mu-law values use 8-bit
unsigned integers.  Linear values use @var{n}-bit signed integers or 
floating point values in the range -1<=@var{x}<=1 if @var{n} is 0.  
If @var{n} is not specified it defaults to 0, 8 or 16 depending on 
the range values in @var{x}.
@seealso{mu2lin, loadaudio, saveaudio, playaudio, setaudio, record}
@end deftypefn
loadaudio
-*- texinfo -*-
@deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps})
Loads audio data from the file @file{@var{name}.@var{ext}} into the
vector @var{x}.

The extension @var{ext} determines how the data in the audio file is
interpreted;  the extensions @file{lin} (default) and @file{raw}
correspond to linear, the extensions @file{au}, @file{mu}, or @file{snd}
to mu-law encoding.

The argument @var{bps} can be either 8 (default) or 16, and specifies
the number of bits per sample used in the audio file.
@seealso{lin2mu, mu2lin, saveaudio, playaudio, setaudio, record}
@end deftypefn
mu2lin
-*- texinfo -*-
@deftypefn {Function File} {} mu2lin (@var{x}, @var{bps})
Converts audio data from linear to mu-law.  Mu-law values are 8-bit
unsigned integers.  Linear values use @var{n}-bit signed integers
or floating point values in the range -1<=y<=1 if @var{n} is 0.  If
@var{n} is not specified it defaults to 8.
@seealso{lin2mu, loadaudio, saveaudio, playaudio, setaudio, record}
@end deftypefn
playaudio
-*- texinfo -*-
@deftypefn {Function File} {} playaudio (@var{name}, @var{ext})
@deftypefnx {Function File} {} playaudio (@var{x})
Plays the audio file @file{@var{name}.@var{ext}} or the audio data
stored in the vector @var{x}.
@seealso{lin2mu, mu2lin, loadaudio, saveaudio, setaudio, record}
@end deftypefn
record
-*- texinfo -*-
@deftypefn {Function File} {} record (@var{sec}, @var{sampling_rate})
Records @var{sec} seconds of audio input into the vector @var{x}.  The
default value for @var{sampling_rate} is 8000 samples per second, or
8kHz.  The program waits until the user types @key{RET} and then
immediately starts to record.
@seealso{lin2mu, mu2lin, loadaudio, saveaudio, playaudio, setaudio}
@end deftypefn
saveaudio
-*- texinfo -*-
@deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps})
Saves a vector @var{x} of audio data to the file
@file{@var{name}.@var{ext}}.  The optional parameters @var{ext} and
@var{bps} determine the encoding and the number of bits per sample used
in the audio file (see @code{loadaudio});  defaults are @file{lin} and
8, respectively.
@seealso{lin2mu, mu2lin, loadaudio, playaudio, setaudio, record}
@end deftypefn
setaudio
-*- texinfo -*-
@deftypefn {Function File} {} setaudio ([@var{w_type} [, @var{value}]])
Execute the shell command @samp{mixer [@var{w_type} [, @var{value}]]}
@end deftypefn
wavread
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} wavread (@var{filename})
Load the RIFF/WAVE sound file @var{filename}, and return the samples
in vector @var{y}.  If the file contains multichannel data, then
@var{y} is a matrix with the channels represented as columns.

@deftypefnx {Function File} {[@var{y}, @var{Fs}, @var{bits}] =} wavread (@var{filename})
Additionally return the sample rate (@var{fs}) in Hz and the number of bits 
per sample (@var{bits}).

@deftypefnx {Function File} {[@dots{}] =} wavread (@var{filename}, @var{n})
Read only the first @var{n} samples from each channel.

@deftypefnx {Function File} {[@dots{}] =} wavread (@var{filename},[@var{n1} @var{n2}])
Read only samples @var{n1} through @var{n2} from each channel.

@deftypefnx {Function File} {[@var{samples}, @var{channels}] =} wavread (@var{filename}, "size")
Return the number of samples (@var{n}) and channels (@var{ch})
instead of the audio data.
@seealso{wavwrite}
@end deftypefn
wavwrite
-*- texinfo -*-
@deftypefn {Function File} {} wavwrite (@var{filename}, @var{y})
Write @var{y} to the canonical RIFF/WAVE sound file @var{filename}. A sample 
rate of 8000 Hz and 16-bit samples are assumed. Each column of the data 
represents a separate channel.

@deftypefnx {Function File} {} wavwrite (@var{filename}, @var{y}, @var{fs})
Set the sample rate to @var{fs} Hz.

@deftypefnx {Function File} {} wavwrite (@var{filename}, @var{y}, @var{fs}, @var{bits})
Set the sample rate to @var{fs} Hz and resolution to @var{bits} bits.
@seealso{wavread}
@end deftypefn
DEMOcontrol
-*- texinfo -*-
@deftypefn {Function File} {} DEMOcontrol
Octave Control Systems Toolbox demo/tutorial program.  The demo
allows the user to select among several categories of @acronym{OCST} function:
@example
@group
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
@end group
@end example
Command examples are interactively run for users to observe the use
of @acronym{OCST} functions.
@seealso{Demo Programs: bddemo.m, frdemo.m, analdemo.m,
moddmeo.m, rldemo.m}
@end deftypefn
__bodquist__
-*- texinfo -*-
@deftypefn {Function File} {[@var{f}, @var{w}, @var{rsys}] =} __bodquist__ (@var{sys}, @var{w}, @var{out_idx}, @var{in_idx})
Used internally by @command{bode}, @command{nyquist}; compute system frequency response.

@strong{Inputs}
@table @var
@item sys
input system structure
@item w
range of frequencies; empty if user wants default
@item out_idx
@itemx in_idx
names or indices of output/input signal names; empty if user wants all
@item rname
name of routine that called __bodquist__ ("bode", "nyquist", or "nichols")
@end table
@strong{Outputs}
@table @var
@item w
list of frequencies
@item f
frequency response of sys; @math{f(ii) = f(omega(ii))}
@item rsys
system with selected inputs and outputs
@end table

@code{bode}, @code{nichols}, and @code{nyquist} share the same 
introduction, so the common parts are
in __bodquist__.  It contains the part that finds the number of arguments,
determines whether or not the system is @acronym{SISO}, and computes the frequency
response.  Only the way the response is plotted is different between the
these functions.
@end deftypefn
__freqresp__
-*- texinfo -*-
@deftypefn {Function File} {} __freqresp__ (@var{sys}, @var{USEW}, @var{w})
Frequency response function - used internally by @command{bode}, @command{nyquist}.
minimal argument checking; ``do not attempt to do this at home''.

@strong{Inputs}
@table @var
@item sys
system data structure
@item USEW
returned by @code{freqchkw}
@item optional
must be present if @var{USEW} is true (nonzero)
@end table
@strong{Outputs}
@table @var
@item @var{out}
vector of finite @math{G(j*w)} entries (or @math{||G(j*w)||} for @acronym{MIMO})
@item w
vector of corresponding frequencies
@end table
@end deftypefn
__stepimp__
-*- texinfo -*-
@deftypefn {Function File} {[@var{y}, @var{t}] =} __stepimp__ (@var{sitype}, @var{sys} [, @var{inp}, @var{tstop}, @var{n}])
Impulse or step response for a linear system.
The system can be discrete or multivariable (or both).
This m-file contains the ``common code'' of step and impulse.

Produces a plot or the response data for system @var{sys}.

Limited argument checking; ``do not attempt to do this at home''.
Used internally in @command{impulse}, @command{step}. Use @command{step}
or @command{impulse} instead.
@seealso{step, impulse}
@end deftypefn
analdemo
-*- texinfo -*-
@deftypefn {Function File} {} analdemo ()
Octave Controls toolbox demo: State Space analysis demo
@end deftypefn
are
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} are (@var{a}, @var{b}, @var{c}, @var{opt})
Solve the Algebraic Riccati Equation
@iftex
@tex
$$
A^TX + XA - XBX + C = 0
$$
@end tex
@end iftex
@ifinfo
@example
a' * x + x * a - x * b * x + c = 0
@end example
@end ifinfo

@strong{Inputs}
@noindent
for identically dimensioned square matrices
@table @var
@item a
@var{n} by @var{n} matrix;
@item b
@var{n} by @var{n} matrix or @var{n} by @var{m} matrix; in the latter case
@var{b} is replaced by @math{b:=b*b'};
@item c
@var{n} by @var{n} matrix or @var{p} by @var{m} matrix; in the latter case
@var{c} is replaced by @math{c:=c'*c};
@item opt
(optional argument; default = @code{"B"}):
String option passed to @code{balance} prior to ordered Schur decomposition.
@end table

@strong{Output}
@table @var
@item x
solution of the @acronym{ARE}.
@end table

@strong{Method}
Laub's Schur method (@acronym{IEEE} Transactions on
Automatic Control, 1979) is applied to the appropriate Hamiltonian
matrix.
@seealso{balance, dare}
@end deftypefn
bddemo
-*- texinfo -*-
@deftypefn {Function File} {} bddemo (@var{inputs})
Octave Controls toolbox demo: Block Diagram Manipulations demo.
@end deftypefn
bode
-*- texinfo -*-
@deftypefn {Function File} {[@var{mag}, @var{phase}, @var{w}] =} bode (@var{sys}, @var{w}, @var{out_idx}, @var{in_idx})
If no output arguments are given: produce Bode plots of a system; otherwise,
compute the frequency response of a system data structure

@strong{Inputs}
@table @var
@item   sys
a system data structure (must be either purely continuous or discrete;
see is_digital)
@item   w
frequency values for evaluation.

if @var{sys} is continuous, then bode evaluates @math{G(jw)} where
@math{G(s)} is the system transfer function.

if @var{sys} is discrete, then bode evaluates G(@code{exp}(jwT)), where
@itemize @bullet
@item @math{T} is the system sampling time
@item @math{G(z)} is the system transfer function.
@end itemize

@strong{Default} the default frequency range is selected as follows: (These
steps are @strong{not} performed if @var{w} is specified)
@enumerate
@item via routine __bodquist__, isolate all poles and zeros away from
@var{w}=0 (@var{jw}=0 or @math{@code{exp}(jwT)}=1) and select the frequency
range based on the breakpoint locations of the frequencies.
@item if @var{sys} is discrete time, the frequency range is limited
              to @math{jwT} in
@ifinfo
[0,2 pi /T]
@end ifinfo
@iftex
@tex
$[0,2\pi/T]$
@end tex
@end iftex
@item 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.

@end enumerate
@item out_idx
@itemx in_idx

The names or indices of outputs and inputs to be used in the frequency
response.  See @code{sysprune}.

@strong{Example}
@example
bode(sys,[],"y_3", @{"u_1","u_4"@});
@end example
@end table
@strong{Outputs}
@table @var
@item mag
@itemx phase
the magnitude and phase of the frequency response @math{G(jw)} or
@math{G(@code{exp}(jwT))} at the selected frequency values.
@item w
the vector of frequency values used
@end table

@enumerate
@item If no output arguments are given, e.g.,
@example
bode(sys);
@end example
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 (@code{ans = []}).

@item If the requested plot is for an @acronym{MIMO} system, mag is set to
@math{||G(jw)||} or @math{||G(@code{exp}(jwT))||}
and phase information is not computed.
@end enumerate
@end deftypefn
bode_bounds
-*- texinfo -*-
@deftypefn {Function File} {[@var{wmin}, @var{wmax}] =} bode_bounds (@var{zer}, @var{pol}, @var{dflg}, @var{tsam})
Get default range of frequencies based on cutoff frequencies of system
poles and zeros.
Frequency range is the interval
@iftex
@tex
$ [ 10^{w_{min}}, 10^{w_{max}} ] $
@end tex
@end iftex
@ifinfo
[10^@var{wmin}, 10^@var{wmax}]
@end ifinfo

Used internally in @command{__freqresp__} (@command{bode}, @command{nyquist})
@end deftypefn
controldemo
-*- texinfo -*-
@deftypefn {Function File} {} controldemo ()
Control Systems Toolbox demo.
@seealso{Demo programs: bddemo, frdemo, analdemo, moddmeo, rldemo}
@end deftypefn
ctrb
-*- texinfo -*-
@deftypefn {Function File} {} ctrb (@var{sys}, @var{b})
@deftypefnx {Function File} {} ctrb (@var{a}, @var{b})
Build controllability matrix:
@iftex
@tex
$$ Q_s = [ B AB A^2B \ldots A^{n-1}B ] $$
@end tex
@end iftex
@ifinfo
@example
             2       n-1
Qs = [ B AB A B ... A   B ]
@end example
@end ifinfo

of a system data structure or the pair (@var{a}, @var{b}).

@command{ctrb} forms the controllability matrix.
The numerical properties of @command{is_controllable}
are much better for controllability tests.
@end deftypefn
damp
-*- texinfo -*-
@deftypefn {Function File} {} damp (@var{p}, @var{tsam})
Displays eigenvalues, natural frequencies and damping ratios
of the eigenvalues of a matrix @var{p} or the @math{A} matrix of a
system @var{p}, respectively.
If @var{p} is a system, @var{tsam} must not be specified.
If @var{p} is a matrix and @var{tsam} is specified, eigenvalues
of @var{p} are assumed to be in @var{z}-domain.
@seealso{eig}
@end deftypefn
dare
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} dare (@var{a}, @var{b}, @var{q}, @var{r}, @var{opt})

Return the solution, @var{x} of the discrete-time algebraic Riccati
equation
@iftex
@tex
$$
A^TXA - X + A^TXB  (R + B^TXB)^{-1} B^TXA + Q = 0
$$
@end tex
@end iftex
@ifinfo
@example
a' x a - x + a' x b (r + b' x b)^(-1) b' x a + q = 0
@end example
@end ifinfo
@noindent

@strong{Inputs}
@table @var
@item a
@var{n} by @var{n} matrix;

@item b
@var{n} by @var{m} matrix;

@item q
@var{n} by @var{n} matrix, symmetric positive semidefinite, or a @var{p} by @var{n} matrix,
In the latter case @math{q:=q'*q} is used;

@item r
@var{m} by @var{m}, symmetric positive definite (invertible);

@item opt
(optional argument; default = @code{"B"}):
String option passed to @code{balance} prior to ordered @var{QZ} decomposition.
@end table

@strong{Output}
@table @var
@item x
solution of @acronym{DARE}.
@end table

@strong{Method}
Generalized eigenvalue approach (Van Dooren; @acronym{SIAM} J.
 Sci. Stat. Comput., Vol 2) applied  to the appropriate symplectic pencil.

 See also: Ran and Rodman, @cite{Stable Hermitian Solutions of Discrete
 Algebraic Riccati Equations}, Mathematics of Control, Signals and
 Systems, Vol 5, no 2 (1992), pp 165--194.
@seealso{balance, are}
@end deftypefn
dcgain
-*- texinfo -*-
@deftypefn {Function File} {} dcgain (@var{sys}, @var{tol})
Returns dc-gain matrix. If dc-gain is infinite
an empty matrix is returned.
The argument @var{tol} is an optional tolerance for the condition
number of the @math{A} Matrix in @var{sys} (default @var{tol} = 1.0e-10)
@end deftypefn
dgram
-*- texinfo -*-
@deftypefn {Function File} {} dgram (@var{a}, @var{b})
Return controllability gramian of discrete time system
@iftex
@tex
$$ x_{k+1} = ax_k + bu_k $$
@end tex
@end iftex
@ifinfo
@example
  x(k+1) = a x(k) + b u(k)
@end example
@end ifinfo

@strong{Inputs}
@table @var
@item a
@var{n} by @var{n} matrix
@item b
@var{n} by @var{m} matrix
@end table

@strong{Output}
@table @var
@item m 
@var{n} by @var{n} matrix, satisfies
@iftex
@tex
$$ ama^T - m + bb^T = 0 $$
@end tex
@end iftex
@ifinfo
@example
 a m a' - m + b*b' = 0
@end example
@end ifinfo
@end table
@end deftypefn
dkalman
-*- texinfo -*-
@deftypefn {Function File} {[@var{Lp}, @var{Lf}, @var{P}, @var{Z}] =} dkalman (@var{A}, @var{G}, @var{C}, @var{Qw}, @var{Rv}, @var{S})
Construct the linear quadratic estimator (Kalman predictor) for the
discrete time system
@iftex
@tex
$$
 x_{k+1} = A x_k + B u_k + G w_k
$$
$$
 y_k = C x_k + D u_k + v_k
$$
@end tex
@end iftex
@ifinfo

@example
x[k+1] = A x[k] + B u[k] + G w[k]
  y[k] = C x[k] + D u[k] + v[k]
@end example

@end ifinfo
where @var{w}, @var{v} are zero-mean gaussian noise processes with
respective intensities @code{@var{Qw} = cov (@var{w}, @var{w})} and
@code{@var{Rv} = cov (@var{v}, @var{v})}.

If specified, @var{S} is @code{cov (@var{w}, @var{v})}.  Otherwise
@code{cov (@var{w}, @var{v}) = 0}.

The observer structure is
@iftex
@tex
$x_{k+1|k} = A x_{k|k-1} + B u_k + L_p (y_k - C x_{k|k-1} - D u_k)$
$x_{k|k} = x_{k|k} + L_f (y_k - C x_{k|k-1} - D u_k)$
@end tex
@end iftex
@ifinfo

@example
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])
@end example
@end ifinfo

@noindent
The following values are returned:

@table @var
@item Lp
The predictor gain,
@iftex
@tex
$(A - L_p C)$.
@end tex
@end iftex
@ifinfo
(@var{A} - @var{Lp} @var{C})
@end ifinfo
is stable.

@item Lf
The filter gain.

@item P
The Riccati solution. 
@iftex
@tex
$P = E \{(x - x_{n|n-1})(x - x_{n|n-1})'\}$
@end tex
@end iftex

@ifinfo
P = E [(x - x[n|n-1])(x - x[n|n-1])']
@end ifinfo

@item Z
The updated error covariance matrix.
@iftex
@tex
$Z = E \{(x - x_{n|n})(x - x_{n|n})'\}$
@end tex
@end iftex

@ifinfo
Z = E [(x - x[n|n])(x - x[n|n])']
@end ifinfo
@end table
@end deftypefn
dlqe
-*- texinfo -*-
@deftypefn {Function File} {[@var{l}, @var{m}, @var{p}, @var{e}] =} dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z})
Construct the linear quadratic estimator (Kalman filter) for the
discrete time system
@iftex
@tex
$$
 x_{k+1} = A x_k + B u_k + G w_k
$$
$$
 y_k = C x_k + D u_k + v_k
$$
@end tex
@end iftex
@ifinfo

@example
x[k+1] = A x[k] + B u[k] + G w[k]
  y[k] = C x[k] + D u[k] + v[k]
@end example

@end ifinfo
where @var{w}, @var{v} are zero-mean gaussian noise processes with
respective intensities @code{@var{sigw} = cov (@var{w}, @var{w})} and
@code{@var{sigv} = cov (@var{v}, @var{v})}.

If specified, @var{z} is @code{cov (@var{w}, @var{v})}.  Otherwise
@code{cov (@var{w}, @var{v}) = 0}.

The observer structure is
@iftex
@tex
$$
 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
$$
@end tex
@end iftex
@ifinfo

@example
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]
@end example
@end ifinfo

@noindent
The following values are returned:

@table @var
@item l
The observer gain,
@iftex
@tex
$(A - ALC)$.
@end tex
@end iftex
@ifinfo
(@var{a} - @var{a}@var{l}@var{c}).
@end ifinfo
is stable.

@item m
The Riccati equation solution.

@item p
The estimate error covariance after the measurement update.

@item e
The closed loop poles of
@iftex
@tex
$(A - ALC)$.
@end tex
@end iftex
@ifinfo
(@var{a} - @var{a}@var{l}@var{c}).
@end ifinfo
@end table
@end deftypefn
dlqr
-*- texinfo -*-
@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z})
Construct the linear quadratic regulator for the discrete time system
@iftex
@tex
$$
 x_{k+1} = A x_k + B u_k
$$
@end tex
@end iftex
@ifinfo

@example
x[k+1] = A x[k] + B u[k]
@end example

@end ifinfo
to minimize the cost functional
@iftex
@tex
$$
 J = \sum x^T Q x + u^T R u
$$
@end tex
@end iftex
@ifinfo

@example
J = Sum (x' Q x + u' R u)
@end example
@end ifinfo

@noindent
@var{z} omitted or
@iftex
@tex
$$
 J = \sum x^T Q x + u^T R u + 2 x^T Z u
$$
@end tex
@end iftex
@ifinfo

@example
J = Sum (x' Q x + u' R u + 2 x' Z u)
@end example

@end ifinfo
@var{z} included.

The following values are returned:

@table @var
@item k
The state feedback gain,
@iftex
@tex
$(A - B K)$
@end tex
@end iftex
@ifinfo
(@var{a} - @var{b}@var{k})
@end ifinfo
is stable.

@item p
The solution of algebraic Riccati equation.

@item e
The closed loop poles of
@iftex
@tex
$(A - B K)$.
@end tex
@end iftex
@ifinfo
(@var{a} - @var{b}@var{k}).
@end ifinfo
@end table
@end deftypefn
dlyap
-*- texinfo -*-
@deftypefn {Function File} {} dlyap (@var{a}, @var{b})
Solve the discrete-time Lyapunov equation

@strong{Inputs}
@table @var
@item a
@var{n} by @var{n} matrix;
@item b
  Matrix: @var{n} by @var{n}, @var{n} by @var{m}, or @var{p} by @var{n}.
@end table

@strong{Output}
@table @var
@item x
matrix satisfying appropriate discrete time Lyapunov equation.
@end table

Options:
@itemize @bullet
@item @var{b} is square: solve 
@iftex
@tex
$$ axa^T - x + b = 0 $$
@end tex
@end iftex
@ifinfo
@code{a x a' - x + b = 0}
@end ifinfo
@item @var{b} is not square: @var{x} satisfies either
@iftex
@tex
$$ axa^T - x + bb^T = 0 $$
@end tex
@end iftex
@ifinfo
@example
a x a' - x + b b' = 0
@end example
@end ifinfo
@noindent
or
@iftex
@tex
$$ a^Txa - x + b^Tb = 0, $$
@end tex
@end iftex
@ifinfo
@example
a' x a - x + b' b = 0,
@end example
@end ifinfo
@noindent
whichever is appropriate.
@end itemize

@strong{Method}
Uses Schur decomposition method as in Kitagawa,
@cite{An Algorithm for Solving the Matrix Equation @math{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, @cite{Numerical Solution of the Stable, Non-Negative
Definite Lyapunov Equation}, @acronym{IMA} Journal of Numerical Analysis, Volume
2, pages 303--323 (1982).
@end deftypefn
dre
-*- texinfo -*-
@deftypefn {Function File} {[@var{tvals}, @var{plist}] =} dre (@var{sys}, @var{q}, @var{r}, @var{qf}, @var{t0}, @var{tf}, @var{ptol}, @var{maxits})
Solve the differential Riccati equation
@ifinfo
@example
  -d P/dt = A'P + P A - P B inv(R) B' P + Q
  P(tf) = Qf
@end example
@end ifinfo
@iftex
@tex
$$ -{dP \over dt} = A^T P+PA-PBR^{-1}B^T P+Q $$
$$ P(t_f) = Q_f $$
@end tex
@end iftex
for the @acronym{LTI} system sys.  Solution of 
standard @acronym{LTI} state feedback optimization
@ifinfo
@example
  min int(t0, tf) ( x' Q x + u' R u ) dt + x(tf)' Qf x(tf)
@end example
@end ifinfo
@iftex
@tex
$$ \min \int_{t_0}^{t_f} x^T Q x + u^T R u dt + x(t_f)^T Q_f x(t_f) $$
@end tex
@end iftex
optimal input is
@ifinfo
@example
  u = - inv(R) B' P(t) x
@end example
@end ifinfo
@iftex
@tex
$$ u = - R^{-1} B^T P(t) x $$
@end tex
@end iftex
@strong{Inputs}
@table @var
@item sys
continuous time system data structure
@item q
state integral penalty
@item r
input integral penalty
@item qf
state terminal penalty
@item t0
@itemx tf
limits on the integral
@item ptol
tolerance (used to select time samples; see below); default = 0.1
@item maxits
number of refinement iterations (default=10)
@end table
@strong{Outputs}
@table @var
@item tvals
time values at which @var{p}(@var{t}) is computed
@item plist
list values of @var{p}(@var{t}); @var{plist} @{ @var{i} @}
is @var{p}(@var{tvals}(@var{i}))
@end table
@var{tvals} is selected so that:
@iftex
@tex
$$ \Vert plist_{i} - plist_{i-1} \Vert < ptol $$
@end tex
@end iftex
@ifinfo
@example
|| Plist@{i@} - Plist@{i-1@} || < Ptol
@end example
@end ifinfo
for every @var{i} between 2 and length(@var{tvals}).
@end deftypefn
frdemo
-*- texinfo -*-
@deftypefn {Function File} {} frdemo ()
Octave Control Toolbox demo: Frequency Response demo.
@end deftypefn
freqchkw
-*- texinfo -*-
@deftypefn {Function File} {} freqchkw (@var{w})
Used by @command{__freqresp__} to check that input frequency vector @var{w}
is valid.
Returns boolean value.
@end deftypefn
gram
-*- texinfo -*-
@deftypefn {Function File} {} gram (@var{a}, @var{b})
Return controllability gramian @var{m} of the continuous time system
@math{dx/dt = a x + b u}.

@var{m} satisfies @math{a m + m a' + b b' = 0}.
@end deftypefn
impulse
-*- texinfo -*-
@deftypefn {Function File} {[@var{y}, @var{t}] =} impulse (@var{sys}, @var{inp}, @var{tstop}, @var{n})
Impulse response for a linear system.
The system can be discrete or multivariable (or both).
If no output arguments are specified, @code{impulse}
produces a plot or the impulse response data for system @var{sys}.

@strong{Inputs}
@table @var
@item sys
System data structure.
@item inp
Index of input being excited
@item tstop
The argument @var{tstop} (scalar value) denotes the time when the
simulation should end.
@item n
the number of data values.

Both parameters @var{tstop} and @var{n} can be omitted and will be
computed from the eigenvalues of the A Matrix.
@end table
@strong{Outputs}
@table @var
@item y
Values of the impulse response.
@item t
Times of the impulse response.
@end table
@seealso{step, __stepimp__}
@end deftypefn
lqe
-*- texinfo -*-
@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z})
Construct the linear quadratic estimator (Kalman filter) for the
continuous time system
@iftex
@tex
$$
 {dx\over dt} = A x + G u
$$
$$
 y = C x + v
$$
@end tex
@end iftex
@ifinfo

@example
dx
-- = A x + G u
dt

y = C x + v
@end example

@end ifinfo
where @var{w} and @var{v} are zero-mean gaussian noise processes with
respective intensities

@example
sigw = cov (w, w)
sigv = cov (v, v)
@end example

The optional argument @var{z} is the cross-covariance
@code{cov (@var{w}, @var{v})}.  If it is omitted,
@code{cov (@var{w}, @var{v}) = 0} is assumed.

Observer structure is @code{dz/dt = A z + B u + k (y - C z - D u)}

The following values are returned:

@table @var
@item k
The observer gain,
@iftex
@tex
$(A - K C)$
@end tex
@end iftex
@ifinfo
(@var{a} - @var{k}@var{c})
@end ifinfo
is stable.

@item p
The solution of algebraic Riccati equation.

@item e
The vector of closed loop poles of
@iftex
@tex
$(A - K C)$.
@end tex
@end iftex
@ifinfo
(@var{a} - @var{k}@var{c}).
@end ifinfo
@end table
@end deftypefn
lqg
-*- texinfo -*-
@deftypefn {Function File} {[@var{k}, @var{q1}, @var{p1}, @var{ee}, @var{er}] =} lqg (@var{sys}, @var{sigw}, @var{sigv}, @var{q}, @var{r}, @var{in_idx})
Design a linear-quadratic-gaussian optimal controller for the system
@example
dx/dt = A x + B u + G w       [w]=N(0,[Sigw 0    ])
    y = C x + v               [v]  (    0   Sigv ])
@end example
or
@example
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 ])
@end example

@strong{Inputs}
@table @var
@item  sys
system data structure
@item  sigw
@itemx  sigv
intensities of independent Gaussian noise processes (as above)
@item  q
@itemx  r
state, control weighting respectively.  Control @acronym{ARE} is
@item  in_idx
names or indices of controlled inputs (see @command{sysidx}, @command{cellidx})

default: last dim(R) inputs are assumed to be controlled inputs, all
others are assumed to be noise inputs.
@end table
@strong{Outputs}
@table @var
@item    k
system data structure format @acronym{LQG} optimal controller (Obtain A, B, C
matrices with @command{sys2ss}, @command{sys2tf}, or @command{sys2zp} as
appropriate).
@item    p1
Solution of control (state feedback) algebraic Riccati equation.
@item    q1
Solution of estimation algebraic Riccati equation.
@item    ee
Estimator poles.
@item    es
Controller poles.
@end table
@seealso{h2syn, lqe, lqr}
@end deftypefn
lqr
-*- texinfo -*-
@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z})
construct the linear quadratic regulator for the continuous time system
@iftex
@tex
$$
 {dx\over dt} = A x + B u
$$
@end tex
@end iftex
@ifinfo

@example
dx
-- = A x + B u
dt
@end example

@end ifinfo
to minimize the cost functional
@iftex
@tex
$$
 J = \int_0^\infty x^T Q x + u^T R u
$$
@end tex
@end iftex
@ifinfo

@example
      infinity
      /
  J = |  x' Q x + u' R u
     /
    t=0
@end example
@end ifinfo

@noindent
@var{z} omitted or
@iftex
@tex
$$
 J = \int_0^\infty x^T Q x + u^T R u + 2 x^T Z u
$$
@end tex
@end iftex
@ifinfo

@example
      infinity
      /
  J = |  x' Q x + u' R u + 2 x' Z u
     /
    t=0
@end example

@end ifinfo
@var{z} included.

The following values are returned:

@table @var
@item k
The state feedback gain,
@iftex
@tex
$(A - B K)$
@end tex
@end iftex
@ifinfo
(@var{a} - @var{b}@var{k})
@end ifinfo
is stable and minimizes the cost functional

@item p
The stabilizing solution of appropriate algebraic Riccati equation.

@item e
The vector of the closed loop poles of
@iftex
@tex
$(A - B K)$.
@end tex
@end iftex
@ifinfo
(@var{a} - @var{b}@var{k}).
@end ifinfo
@end table

@strong{Reference}
Anderson and Moore, @cite{Optimal control: linear quadratic methods},
Prentice-Hall, 1990, pp. 56--58.
@end deftypefn
lsim
-*- texinfo -*-
@deftypefn {Function File} {[@var{y}, @var{x}] =} lsim (@var{sys}, @var{u}, @var{t}, @var{x0})
Produce output for a linear simulation of a system; produces 
a plot for the output of the system, @var{sys}.

@var{u} is an array that contains the system's inputs.  Each row in @var{u}
corresponds to a different time step.  Each column in @var{u} corresponds to a
different input.  @var{t} is an array that contains the time index of the
system; @var{t} should be regularly spaced.  If initial conditions are required
on the system, the @var{x0} vector should be added to the argument list.

When the lsim function is invoked a plot is not displayed; 
however, the data is returned in @var{y} (system output)
and @var{x} (system states).
@end deftypefn
ltifr
-*- texinfo -*-
@deftypefn {Function File} {@var{out} =} ltifr (@var{a}, @var{b}, @var{w})
@deftypefnx {Function File} {@var{out} =} ltifr (@var{sys}, @var{w})
Linear time invariant frequency response of single-input systems.

@strong{Inputs}
@table @var
@item a
@itemx b
coefficient matrices of @math{dx/dt = A x + B u}
@item sys
system data structure
@item w
vector of frequencies
@end table
@strong{Output}
@table @var
@item out
frequency response, that is:
@end table
@iftex
@tex
$$ G(j\omega) = (j\omega I-A)^{-1}B $$
@end tex
@end iftex
@ifinfo
@example
                           -1
             G(s) = (jw I-A) B
@end example
@end ifinfo
for complex frequencies @math{s = jw}.
@end deftypefn
lyap
-*- texinfo -*-
@deftypefn {Function File} {} lyap (@var{a}, @var{b}, @var{c})
@deftypefnx {Function File} {} lyap (@var{a}, @var{b})
Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart
algorithm (Communications of the @acronym{ACM}, 1972).

If @var{a}, @var{b}, and @var{c} are specified, then @code{lyap} returns
the solution of the  Sylvester equation
@iftex
@tex
  $$ A X + X B + C = 0 $$
@end tex
@end iftex
@ifinfo
@example
    a x + x b + c = 0
@end example
@end ifinfo
If only @code{(a, b)} are specified, then @command{lyap} returns the
solution of the Lyapunov equation
@iftex
@tex
  $$ A^T X + X A + B = 0 $$
@end tex
@end iftex
@ifinfo
@example
    a' x + x a + b = 0
@end example
@end ifinfo
If @var{b} is not square, then @code{lyap} returns the solution of either
@iftex
@tex
  $$ A^T X + X A + B^T B = 0 $$
@end tex
@end iftex
@ifinfo
@example
    a' x + x a + b' b = 0
@end example
@end ifinfo
@noindent
or
@iftex
@tex
  $$ A X + X A^T + B B^T = 0 $$
@end tex
@end iftex
@ifinfo
@example
    a x + x a' + b b' = 0
@end example
@end ifinfo
@noindent
whichever is appropriate.

Solves by using the Bartels-Stewart algorithm (1972).
@end deftypefn
nichols
-*- texinfo -*-
@deftypefn {Function File} {[@var{mag}, @var{phase}, @var{w}] =} nichols (@var{sys}, @var{w}, @var{outputs}, @var{inputs})
Produce Nichols plot of a system.

@strong{Inputs}
@table @var
@item sys
System data structure (must be either purely continuous or discrete; 
see @command{is_digital}).
@item w
Frequency values for evaluation.
@itemize
@item if sys is continuous, then nichols evaluates @math{G(jw)}.
@item if sys is discrete, then nichols evaluates @math{G(exp(jwT))}, 
where @var{T}=@var{sys}. @var{tsam} is the system sampling time.
@item the default frequency range is selected as follows (These
       steps are @strong{not} performed if @var{w} is specified):
@enumerate
@item via routine @command{__bodquist__}, isolate all poles and zeros away from
@var{w}=0 (@math{jw=0} or @math{exp(jwT)=1}) and select the frequency range 
based on the breakpoint locations of the frequencies.
@item if sys is discrete time, the frequency range is limited to jwT in 
@iftex
@tex
$ [0, 2p\pi] $.
@end tex
@end iftex
@ifinfo
[0,2p*pi].
@end ifinfo
@item 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.
@end enumerate
@end itemize
@item outputs
@itemx inputs
the names or indices of the output(s) and input(s) to be used in the 
frequency response; see @command{sysprune}.
@end table
@strong{Outputs}
@table @var
@item mag
@itemx phase
The magnitude and phase of the frequency response @math{G(jw)} or 
@math{G(exp(jwT))} at the selected frequency values.
@item w
The vector of frequency values used.
@end table
If no output arguments are given, @command{nichols} plots the results to the screen.
Descriptive labels are automatically placed. See @command{xlabel}, 
@command{ylabel}, and @command{title}.

Note: if the requested plot is for an @acronym{MIMO} system, @var{mag} is set to
@iftex
@tex
$ \Vert G(jw) \Vert $ or $ \Vert G( {\rm exp}(jwT) \Vert $
@end tex
@end iftex
@ifinfo
||G(jw)|| or ||G(exp(jwT))||
@end ifinfo
and phase information is not computed.
@end deftypefn
nyquist
-*- texinfo -*-
@deftypefn {Function File} {[@var{realp}, @var{imagp}, @var{w}] =} nyquist (@var{sys}, @var{w}, @var{out_idx}, @var{in_idx}, @var{atol})
@deftypefnx {Function File} {} nyquist (@var{sys}, @var{w}, @var{out_idx}, @var{in_idx}, @var{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.

@strong{Inputs} (pass as empty to get default values)
@table @var
@item sys
system data structure (must be either purely continuous or discrete;
see @code{is_digital})
@item w
frequency values for evaluation.
If sys is continuous, then bode evaluates @math{G(@var{jw})}; 
if sys is discrete, then bode evaluates @math{G(exp(@var{jwT}))},
where @var{T} is the system sampling time.
@item default
the default frequency range is selected as follows: (These
steps are @strong{not} performed if @var{w} is specified)
@enumerate
@item via routine @command{__bodquist__}, isolate all poles and zeros away from
@var{w}=0 (@var{jw}=0 or @math{exp(@var{jwT})=1}) and select the frequency
range based on the breakpoint locations of the frequencies.
@item if @var{sys} is discrete time, the frequency range is limited
to @var{jwT} in
@ifinfo
[0,2p*pi]
@end ifinfo
@iftex
@tex
$ [ 0,2  p \pi ] $
@end tex
@end iftex
@item 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.
@end enumerate
@item   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.
@end table
@strong{Outputs}
@table @var
@item    realp
@itemx   imagp
the real and imaginary parts of the frequency response
@math{G(jw)} or @math{G(exp(jwT))} at the selected frequency values.
@item w
the vector of frequency values used
@end table

If no output arguments are given, nyquist plots the results to the screen.
If @var{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 @acronym{MIMO} system, a warning message is
presented; the returned information is of the magnitude
@iftex
@tex
$ \Vert G(jw) \Vert $ or $ \Vert G( {\rm exp}(jwT) \Vert $
@end tex
@end iftex
@ifinfo
||G(jw)|| or ||G(exp(jwT))||
@end ifinfo
only; phase information is not computed.
@end deftypefn
obsv
-*- texinfo -*-
@deftypefn {Function File} {} obsv (@var{sys}, @var{c})
@deftypefnx {Function File} {} obsv (@var{a}, @var{c})
Build observability matrix:
@iftex
@tex
$$ Q_b = \left[ \matrix{  C       \cr
                          CA    \cr
                          CA^2  \cr
                          \vdots  \cr
                          CA^{n-1} } \right ] $$
@end tex
@end iftex
@ifinfo
@example
@group
     | C        |
     | CA       |
Qb = | CA^2     |
     | ...      |
     | CA^(n-1) |
@end group
@end example
@end ifinfo
of a system data structure or the pair (@var{a}, @var{c}).

The numerical properties of @command{is_observable}
are much better for observability tests.
@end deftypefn
place
-*- texinfo -*-
@deftypefn {Function File} {@var{K} =} place (@var{sys}, @var{p})
Computes the matrix @var{K} such that if the state
is feedback with gain @var{K}, then the eigenvalues  of the closed loop
system (i.e. @math{A-BK}) are those specified in the vector @var{p}.

Version: Beta (May-1997): If you have any comments, please let me know.
(see the file place.m for my address)
@end deftypefn
pzmap
-*- texinfo -*-
@deftypefn {Function File} {[@var{zer}, @var{pol}] =} pzmap (@var{sys})
Plots the zeros and poles of a system in the complex plane.

@strong{Input}
@table @var
@item sys
System data structure.
@end table

@strong{Outputs}
@table @var
@item pol
@item zer
if omitted, the poles and zeros are plotted on the screen.
otherwise, @var{pol} and @var{zer} are returned as the 
system poles and zeros (see @command{sys2zp} for a preferable function call).
@end table
@end deftypefn
rldemo
-*- texinfo -*-
@deftypefn {Function File} {} rldemo (@var{inputs})
Octave Control toolbox demo: Root Locus demo.
@end deftypefn
rlocus
-*- texinfo -*-
@deftypefn {Function File} {[@var{rldata}, @var{k}] =} rlocus (@var{sys}[, @var{increment}, @var{min_k}, @var{max_k}])

Display root locus plot of the specified @acronym{SISO} system.
@example
@group
       -----   ---     --------
   --->| + |---|k|---->| SISO |----------->
       -----   ---     --------        |
       - ^                             |
         |_____________________________|
@end group
@end example

@strong{Inputs}
@table @var
@item sys
system data structure
@item min_k
Minimum value of @var{k}
@item max_k
Maximum value of @var{k}
@item increment
The increment used in computing gain values
@end table

@strong{Outputs}

Plots the root locus to the screen.
@table @var 
@item rldata
Data points plotted: in column 1 real values, in column 2 the imaginary values.
@item k
Gains for real axis break points.
@end table
@end deftypefn
step
-*- texinfo -*-
@deftypefn {Function File} {[@var{y}, @var{t}] =} step (@var{sys}, @var{inp}, @var{tstop}, @var{n})
Step response for a linear system.
The system can be discrete or multivariable (or both).
If no output arguments are specified, @code{step}
produces a plot or the step response data for system @var{sys}.

@strong{Inputs}
@table @var
@item sys
System data structure.
@item inp
Index of input being excited
@item tstop
The argument @var{tstop} (scalar value) denotes the time when the
simulation should end.
@item n
the number of data values.

Both parameters @var{tstop} and @var{n} can be omitted and will be
computed from the eigenvalues of the A Matrix.
@end table
@strong{Outputs}
@table @var
@item y
Values of the step response.
@item t
Times of the step response.
@end table

When invoked with the output parameter @var{y} the plot is not displayed.
@seealso{impulse, __stepimp__}
@end deftypefn
tzero
-*- texinfo -*-
@deftypefn {Function File} {[@var{zer}, @var{gain}] =} tzero (@var{a}, @var{b}, @var{c}, @var{d}, @var{opt})
@deftypefnx {Function File} {[@var{zer}, @var{gain}] =} tzero (@var{sys}, @var{opt})
Compute transmission zeros of a continuous system:
@iftex
@tex
$$ \dot x = Ax + Bu $$
$$ y = Cx + Du $$
@end tex
@end iftex
@ifinfo
@example
.
x = Ax + Bu
y = Cx + Du
@end example
@end ifinfo
or of a discrete one:
@iftex
@tex
$$ x_{k+1} = Ax_k + Bu_k $$
$$ y_k = Cx_k + Du_k $$
@end tex
@end iftex
@ifinfo
@example
x(k+1) = A x(k) + B u(k)
y(k)   = C x(k) + D u(k)
@end example
@end ifinfo

@strong{Outputs}
@table @var
@item zer
 transmission zeros of the system
@item gain
leading coefficient (pole-zero form) of @acronym{SISO} transfer function
returns gain=0 if system is multivariable
@end table
@strong{References}
@enumerate
@item Emami-Naeini and Van Dooren, Automatica, 1982.
@item Hodel, @cite{Computation of Zeros with Balancing}, 1992 Lin. Alg. Appl.
@end enumerate
@end deftypefn
tzero2
-*- texinfo -*-
@deftypefn {Function File} {@var{zr} =} tzero2 (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal})
Compute the transmission zeros of @var{a}, @var{b}, @var{c}, @var{d}.

@var{bal} = balancing option (see balance); default is @code{"B"}.

Needs to incorporate @command{mvzero} algorithm to isolate finite zeros; 
use @command{tzero} instead.
@end deftypefn
dgkfdemo
-*- texinfo -*-
@deftypefn {Function File} {} dgkfdemo ()
Octave Controls toolbox demo: 
@iftex
@tex
$ { \cal H }_2 $/$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-2/H-infinity
@end ifinfo
options demos.
@end deftypefn
dhinfdemo
-*- texinfo -*-
@deftypefn {Function File} {} dhinfdemo ()
Demonstrate the functions available to design a discrete
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
controller.  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.

Continuous plant:
@iftex
@tex
$$ G(s) = { 1 \over (s+2) (s+1) } $$
@end tex
@end iftex
@ifinfo
@example
@group
                  1
     G(s) = --------------
            (s + 2)(s + 1)
@end group
@end example
@end ifinfo

Discretised plant with @acronym{ZOH} (Sampling period = @var{Ts} = 1 second):
@iftex
@tex
$$ G(z) = { 0.39958z + 0.14700 \over (z - 0.36788) (z - 0.13533) } $$
@end tex
@end iftex
@ifinfo
@example
@group
                0.39958z + 0.14700
     G(z) = --------------------------
            (z - 0.36788)(z - 0.13533)
@end group
@end example
@end ifinfo

@example
@group
                              +----+
         -------------------->| W1 |---> v1
     z   |                    +----+
     ----|-------------+                   || T   ||     => min.
         |             |                       vz   infty
         |    +---+    v      +----+
         *--->| G |--->O--*-->| W2 |---> v2
         |    +---+       |   +----+
         |                |
         |    +---+       |
         -----| K |<-------
              +---+
@end group
@end example

@noindent
W1 and W2 are the robustness and performancs weighting functions.
@end deftypefn
h2norm
-*- texinfo -*-
@deftypefn {Function File} {} h2norm (@var{sys})
Computes the 
@iftex
@tex
$ { \cal H }_2 $
@end tex
@end iftex
@ifinfo
H-2
@end ifinfo
norm of a system data structure (continuous time only).

Reference:
Doyle, Glover, Khargonekar, Francis, @cite{State-Space Solutions to Standard} 
@iftex
@tex
$ { \cal H }_2 $ @cite{and} $ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-2 and H-infinity}
@end ifinfo
@cite{Control Problems}, @acronym{IEEE} @acronym{TAC} August 1989.
@end deftypefn
h2syn
-*- texinfo -*-
@deftypefn {Function File} {[@var{K}, @var{gain}, @var{kc}, @var{kf}, @var{pc}, @var{pf}] = } h2syn (@var{asys}, @var{nu}, @var{ny}, @var{tol})
Design 
@iftex
@tex
$ { \cal H }_2 $
@end tex
@end iftex
@ifinfo
H-2
@end ifinfo
optimal controller per procedure in 
Doyle, Glover, Khargonekar, Francis, @cite{State-Space Solutions to Standard}
@iftex
@tex
$ { \cal H }_2 $ @cite{and} $ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-2 and H-infinity}
@end ifinfo
@cite{Control Problems}, @acronym{IEEE} @acronym{TAC} August 1989.

Discrete-time control per Zhou, Doyle, and Glover, @cite{Robust and optimal control}, Prentice-Hall, 1996.

@strong{Inputs}
@table @var
@item asys
system data structure (see ss, sys2ss)
@itemize @bullet
@item controller is implemented for continuous time systems
@item controller is @strong{not} implemented for discrete time systems
@end itemize
@item nu
number of controlled inputs
@item ny
number of measured outputs
@item tol
threshold for 0.  Default: 200*@code{eps}
@end table

@strong{Outputs}
@table @var
@item    k
system controller
@item    gain
optimal closed loop gain
@item    kc
full information control (packed)
@item    kf
state estimator (packed)
@item    pc
@acronym{ARE} solution matrix for regulator subproblem
@item    pf
@acronym{ARE} solution matrix for filter subproblem
@end table
@end deftypefn
hinf_ctr
-*- texinfo -*-
@deftypefn {Function File} {@var{K} =} hinf_ctr (@var{dgs}, @var{f}, @var{h}, @var{z}, @var{g})
Called by @code{hinfsyn} to compute the 
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
optimal controller.

@strong{Inputs}
@table @var
@item dgs
data structure returned by @code{is_dgkf}
@item f
@itemx h
feedback and filter gain (not partitioned)
@item g
final gamma value
@end table
@strong{Outputs}
@table @var
@item K
controller (system data structure)
@end table

Do not attempt to use this at home; no argument checking performed.
@end deftypefn
hinfdemo
-*- texinfo -*-
@deftypefn {Function File} {} hinfdemo ()

@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
design demos for continuous @acronym{SISO} and @acronym{MIMO} systems and a
discrete system.  The @acronym{SISO} system is difficult to control because
it is non-minimum-phase and unstable. The second design example
controls the @command{jet707} plant, the linearized state space model of a
Boeing 707-321 aircraft at @var{v}=80 m/s 
@iftex
@tex
($M = 0.26$, $G_{a0} = -3^{\circ}$, ${\alpha}_0 = 4^{\circ}$, ${\kappa}= 50^{\circ}$).
@end tex
@end iftex
@ifinfo
(@var{M} = 0.26, @var{Ga0} = -3 deg, @var{alpha0} = 4 deg, @var{kappa} = 50 deg).
@end ifinfo
Inputs: (1) thrust and (2) elevator angle
Outputs: (1) airspeed and (2) pitch angle. The discrete system is a
stable and second order.

@table @asis
@item @acronym{SISO} plant:

@iftex
@tex
$$ G(s) = { s-2 \over (s+2) (s-1) } $$
@end tex
@end iftex
@ifinfo
@example
@group
                s - 2
     G(s) = --------------
            (s + 2)(s - 1)
@end group
@end example
@end ifinfo

@example
@group

                              +----+
         -------------------->| W1 |---> v1
     z   |                    +----+
     ----|-------------+
         |             |
         |    +---+    v   y  +----+
       u *--->| G |--->O--*-->| W2 |---> v2
         |    +---+       |   +----+
         |                |
         |    +---+       |
         -----| K |<-------
              +---+
@end group
@end example

@iftex
@tex
$$ { \rm min } \Vert T_{vz} \Vert _\infty $$
@end tex
@end iftex
@ifinfo
@example
min || T   ||
        vz   infty
@end example
@end ifinfo

@var{W1} und @var{W2} are the robustness and performance weighting
functions.

@item @acronym{MIMO} plant:
The optimal controller minimizes the 
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
norm of the
augmented plant @var{P} (mixed-sensitivity problem):
@example
@group
     w
      1 -----------+
                   |                   +----+
               +---------------------->| W1 |----> z1
     w         |   |                   +----+
      2 ------------------------+
               |   |            |
               |   v   +----+   v      +----+
            +--*-->o-->| G  |-->o--*-->| W2 |---> z2
            |          +----+      |   +----+
            |                      |
            ^                      v
            u                       y (to K)
         (from controller K)
@end group
@end example

@iftex
@tex
$$ \left [ \matrix{ z_1 \cr
                    z_2 \cr
                    y   } \right ] =  
 P \left [ \matrix{ w_1 \cr
                    w_2 \cr
                    u   } \right ] $$
@end tex
@end iftex
@ifinfo
@example
@group
                  +    +           +    +
                  | z  |           | w  |
                  |  1 |           |  1 |
                  | z  | = [ P ] * | w  |
                  |  2 |           |  2 |
                  | y  |           | u  |
                  +    +           +    +
@end group
@end example
@end ifinfo

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

@item The continuous plant:
@iftex
@tex
$$ G(s) = { 1 \over (s+2)(s+1) } $$
@end tex
@end iftex

@ifinfo
@example
@group
                   1
     G (s) = --------------
      k      (s + 2)(s + 1)

@end group
@end example
@end ifinfo

is discretised with a @acronym{ZOH} (Sampling period = @var{Ts} = 1 second):
@iftex
@tex
$$ G(z) = { 0.199788z + 0.073498 \over (z - 0.36788) (z - 0.13534) } $$
@end tex
@end iftex
@ifinfo
@example
@group

               0.199788z + 0.073498
     G(z) = --------------------------
            (z - 0.36788)(z - 0.13534)
@end group
@end example
@end ifinfo

@example
@group

                              +----+
         -------------------->| W1 |---> v1
     z   |                    +----+
     ----|-------------+
         |             |
         |    +---+    v      +----+
         *--->| G |--->O--*-->| W2 |---> v2
         |    +---+       |   +----+
         |                |
         |    +---+       |
         -----| K |<-------
              +---+
@end group
@end example
@iftex
@tex
$$ { \rm min } \Vert T_{vz} \Vert _\infty $$
@end tex
@end iftex
@ifinfo
@example
min || T   ||
        vz   infty
@end example
@end ifinfo
@var{W1} and @var{W2} are the robustness and performance weighting
functions.
@end table
@end deftypefn
hinfnorm
-*- texinfo -*-
@deftypefn {Function File} {[@var{g}, @var{gmin}, @var{gmax}] =} hinfnorm (@var{sys}, @var{tol}, @var{gmin}, @var{gmax}, @var{ptol})
Computes the 
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
norm of a system data structure.

@strong{Inputs}
@table @var
@item sys
system data structure
@item tol
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
norm search tolerance (default: 0.001)
@item gmin
minimum value for norm search (default: 1e-9)
@item gmax
maximum value for norm search (default: 1e+9)
@item ptol
pole tolerance:
@itemize @bullet
@item if sys is continuous, poles with
@iftex
@tex
$ \vert {\rm real}(pole) \vert < ptol \Vert H \Vert $
@end tex
@end iftex
@ifinfo
@math{ |real(pole))| < ptol*||H|| }
@end ifinfo
(@var{H} is appropriate Hamiltonian)
are considered to be on the imaginary axis.

@item if sys is discrete, poles with
@iftex
@tex
$ \vert { \rm pole } - 1 \vert < ptol \Vert [ s_1 s_2 ] \Vert $
@end tex
@end iftex
@ifinfo
@math{|abs(pole)-1| < ptol*||[s1,s2]||}
@end ifinfo
(appropriate symplectic pencil)
are considered to be on the unit circle.

@item Default value: 1e-9
@end itemize
@end table

@strong{Outputs}
@table @var
@item g
Computed gain, within @var{tol} of actual gain.  @var{g} is returned as Inf
if the system is unstable.
@item gmin
@itemx gmax
Actual system gain lies in the interval [@var{gmin}, @var{gmax}].
@end table

References:
Doyle, Glover, Khargonekar, Francis, @cite{State-space solutions to standard}
@iftex
@tex
$ { \cal H }_2 $ @cite{and} $ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-2 and H-infinity}
@end ifinfo
@cite{control problems}, @acronym{IEEE} @acronym{TAC} August 1989;
Iglesias and Glover, @cite{State-Space approach to discrete-time}
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-infinity}
@end ifinfo
@cite{control}, Int. J. Control, vol 54, no. 5, 1991;
Zhou, Doyle, Glover, @cite{Robust and Optimal Control}, Prentice-Hall, 1996.
@end deftypefn
hinfsyn
-*- texinfo -*-
@deftypefn {Function File} {[@var{k}, @var{g}, @var{gw}, @var{xinf}, @var{yinf}] =} hinfsyn (@var{asys}, @var{nu}, @var{ny}, @var{gmin}, @var{gmax}, @var{gtol}, @var{ptol}, @var{tol})

@strong{Inputs} input system is passed as either
@table @var
@item asys
system data structure (see @command{ss}, @command{sys2ss})
@itemize @bullet
@item controller is implemented for continuous time systems
@item controller is @strong{not} implemented for discrete time systems  (see
bilinear transforms in @command{c2d}, @command{d2c})
@end itemize
@item nu
number of controlled inputs
@item ny
number of measured outputs
@item gmin
initial lower bound on 
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
optimal gain
@item gmax
initial upper bound on 
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
Optimal gain.
@item gtol
Gain threshold.  Routine quits when @var{gmax}/@var{gmin} < 1+tol.
@item ptol
poles with @code{abs(real(pole))} 
@iftex
@tex
$ < ptol \Vert H \Vert $
@end tex
@end iftex
@ifinfo
< ptol*||H|| 
@end ifinfo
(@var{H} is appropriate
Hamiltonian) are considered to be on the imaginary axis.
Default: 1e-9.
@item tol
threshold for 0.  Default: 200*@code{eps}.

@var{gmax}, @var{min}, @var{tol}, and @var{tol} must all be postive scalars.
@end table
@strong{Outputs}
@table @var
@item k
System controller.
@item g
Designed gain value.
@item gw
Closed loop system.
@item xinf
@acronym{ARE} solution matrix for regulator subproblem.
@item yinf
@acronym{ARE} solution matrix for filter subproblem.
@end table

References:
@enumerate
@item Doyle, Glover, Khargonekar, Francis, @cite{State-Space Solutions
to Standard}
@iftex
@tex
$ { \cal H }_2 $ @cite{and} $ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-2 and H-infinity}
@end ifinfo
@cite{Control Problems}, @acronym{IEEE} @acronym{TAC} August 1989.

@item Maciejowksi, J.M., @cite{Multivariable feedback design},
Addison-Wesley, 1989, @acronym{ISBN} 0-201-18243-2.

@item Keith Glover and John C. Doyle, @cite{State-space formulae for all
stabilizing controllers that satisfy an}
@iftex
@tex
$ { \cal H }_\infty $@cite{norm}
@end tex
@end iftex
@ifinfo
@cite{H-infinity-norm}
@end ifinfo
@cite{bound and relations to risk sensitivity},
Systems & Control Letters 11, Oct. 1988, pp 167--172.
@end enumerate
@end deftypefn
hinfsyn_chk
-*- texinfo -*-
@deftypefn {Function File} {[@var{retval}, @var{pc}, @var{pf}] =} hinfsyn_chk (@var{a}, @var{b1}, @var{b2}, @var{c1}, @var{c2}, @var{d12}, @var{d21}, @var{g}, @var{ptol})
Called by @code{hinfsyn} to see if gain @var{g} satisfies conditions in
Theorem 3 of
Doyle, Glover, Khargonekar, Francis, @cite{State Space Solutions to Standard}
@iftex
@tex
$ { \cal H }_2 $ @cite{and} $ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-2 and H-infinity}
@end ifinfo
@cite{Control Problems}, @acronym{IEEE} @acronym{TAC} August 1989.

@strong{Warning:} do not attempt to use this at home; no argument
checking performed.

@strong{Inputs}

As returned by @code{is_dgkf}, except for:
@table @var
@item g
candidate gain level
@item ptol
 as in @code{hinfsyn}
@end table

@strong{Outputs}
@table @var
@item retval
 1 if g exceeds optimal Hinf closed loop gain, else 0
@item pc
solution of ``regulator'' 
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
@acronym{ARE}
@item pf
solution of ``filter''
@iftex
@tex
$ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-infinity
@end ifinfo
@acronym{ARE}
@end table
Do not attempt to use this at home; no argument checking performed.
@end deftypefn
hinfsyn_ric
-*- texinfo -*-
@deftypefn {Function File} {[@var{xinf}, @var{x_ha_err}] =} hinfsyn_ric (@var{a}, @var{bb}, @var{c1}, @var{d1dot}, @var{r}, @var{ptol})
Forms
@example
xx = ([bb; -c1'*d1dot]/r) * [d1dot'*c1 bb'];
Ha = [a 0*a; -c1'*c1 - a'] - xx;
@end example
and solves associated Riccati equation.
The error code @var{x_ha_err} indicates one of the following
conditions:
@table @asis
@item 0
successful
@item 1
@var{xinf} has imaginary eigenvalues
@item 2
@var{hx} not Hamiltonian
@item 3
@var{xinf} has infinite eigenvalues (numerical overflow)
@item 4
@var{xinf} not symmetric
@item 5
@var{xinf} not positive definite
@item 6
@var{r} is singular
@end table
@end deftypefn
is_dgkf
-*- texinfo -*-
@deftypefn {Function File} {[@var{retval}, @var{dgkf_struct} ] =} is_dgkf (@var{asys}, @var{nu}, @var{ny}, @var{tol} )
Determine whether a continuous time state space system meets
assumptions of @acronym{DGKF} algorithm.
Partitions system into:
@example
[dx/dt]   [A  | Bw  Bu  ][w]
[ z   ] = [Cz | Dzw Dzu ][u]
[ y   ]   [Cy | Dyw Dyu ]
@end example
or similar discrete-time system.
If necessary, orthogonal transformations @var{qw}, @var{qz} and nonsingular
transformations @var{ru}, @var{ry} are applied to respective vectors
@var{w}, @var{z}, @var{u}, @var{y} in order to satisfy @acronym{DGKF} assumptions.
Loop shifting is used if @var{dyu} block is nonzero.

@strong{Inputs}
@table @var
@item         asys
system data structure
@item           nu
number of controlled inputs
@item        ny
number of measured outputs
@item        tol
threshold for 0; default: 200*@code{eps}.
@end table
@strong{Outputs}
@table @var
@item    retval
true(1) if system passes check, false(0) otherwise
@item    dgkf_struct
data structure of @command{is_dgkf} results.  Entries:
@table @var
@item      nw
@itemx     nz
dimensions of @var{w}, @var{z}
@item      a
system @math{A} matrix
@item      bw
(@var{n} x @var{nw}) @var{qw}-transformed disturbance input matrix
@item      bu
(@var{n} x @var{nu}) @var{ru}-transformed controlled input matrix;

@math{B = [Bw Bu]}
@item      cz
(@var{nz} x @var{n}) Qz-transformed error output matrix
@item      cy
(@var{ny} x @var{n}) @var{ry}-transformed measured output matrix

@math{C = [Cz; Cy]}
@item      dzu
@item      dyw
off-diagonal blocks of transformed system @math{D} matrix that enter
@var{z}, @var{y} from @var{u}, @var{w} respectively
@item      ru
controlled input transformation matrix
@item      ry
observed output transformation matrix
@item      dyu_nz
nonzero if the @var{dyu} block is nonzero.
@item      dyu
untransformed @var{dyu} block
@item      dflg
nonzero if the system is discrete-time
@end table
@end table
@code{is_dgkf} exits with an error if the system is mixed
discrete/continuous.

@strong{References}
@table @strong
@item [1]
Doyle, Glover, Khargonekar, Francis, @cite{State Space Solutions to Standard}
@iftex
@tex
$ { \cal H }_2 $ @cite{and} $ { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
@cite{H-2 and H-infinity}
@end ifinfo
@cite{Control Problems}, @acronym{IEEE} @acronym{TAC} August 1989.
@item [2]
Maciejowksi, J.M., @cite{Multivariable Feedback Design}, Addison-Wesley, 1989.
@end table
@end deftypefn
wgt1o
-*- texinfo -*-
@deftypefn {Function File} {@var{W} =} wgt1o (@var{vl}, @var{vh}, @var{fc})
State space description of a first order weighting function.

Weighting function are needed by the 
@iftex
@tex
$ { \cal H }_2 / { \cal H }_\infty $
@end tex
@end iftex
@ifinfo
H-2/H-infinity
@end ifinfo
design procedure.
These function are part of the augmented plant @var{P}
(see @command{hinfdemo} for an application example).

@strong{Inputs}
@table @var
@item vl
Gain at low frequencies.
@item vh
Gain at high frequencies.
@item fc
Corner frequency (in Hz, @strong{not} in rad/sec)
@end table

@strong{Output}
@table @var
@item W
Weighting function, given in form of a system data structure.
@end table
@end deftypefn
dezero
-*- texinfo -*-
@deftypefn {Functin File} {} dezero (@var{s})
Remove trailing blank entries and all zero entries from the string s.
@end deftypefn
dlqg
 O B S O L E T E * * * D O   N O T   U S E!

 Use lqg instead.

function [K,Q,P,Ee,Er] = dlqg(A,B,C,G,Sigw,Sigv,Q,R)
function [K,Q,P,Ee,Er] = dlqg(Sys,Sigw,Sigv,Q,R)

design a discrete-time linear quadratic gaussian optimal controller
for the system

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

Outputs:
   K: system data structure format LQG optimal controller
   P: Solution of control (state feedback) algebraic Riccati equation
   Q: Solution of estimation algebraic Riccati equation
   Ee: estimator poles
   Es: controller poles
inputs:
 A,B,C,G, or Sys: state space representation of system.
 Sigw, Sigv: covariance matrices of independent Gaussian noise processes
     (as above)
 Q, R: state, control weighting matrices for dlqr call respectively.

See also: lqg, dlqe, dlqr
minfo
-*- texinfo -*-
@deftypefn {Function File} {[@var{systype}, @var{nout}, @var{nin}, @var{ncstates}, @var{ndstates}] =} minfo (@var{inmat})
Determines the type of system matrix.  @var{inmat} can be a varying, 
a system, a constant, and an empty matrix.

@strong{Outputs}
@table @var
@item systype 
Can be one of: varying, system, constant, and empty.
@item nout 
The number of outputs of the system.
@item nin
The number of inputs of the system.
@item ncstates
The number of continuous states of the system.
@item ndstates 
The number of discrete states of the system.
@end table
@end deftypefn
packsys
O B S O L E T E: use ss instead.
function Asys = packsys(a,b,c[,d,dflg])

  dflg: 0 for continuous time system, 1 for discrete-time system.

defaults:
     D: 0 matrix of appropriate dimension.
  dflg: 0 (continuous time)

Note: discrete-state sampling time is not included!
qzval
-*- texinfo -*-
@deftypefn {Function File} {} qzval (@var{a}, @var{b})
Compute generalized eigenvalues of the matrix pencil
@ifinfo
@example
(A - lambda B).
@end example
@end ifinfo
@iftex
@tex
$(A - \lambda B)$.
@end tex
@end iftex

@var{a} and @var{b} must be real matrices.

@code{qzval} is obsolete; use @code{qz} instead.
@end deftypefn
rotg
function [c,s] = rotg(a,b)
givens rotation calculation

NOTE: Use [c,s] = givens(a,b) instead.
series
Forms the series connection of two systems.

Superseded by sysmult.  Do not use this routine!
used internally in zp2ss

Type of input: Transfer functions
Command:       [num,den]=series(num1,den1,num2,den2)
Forms the series representation of the two transfer functions.

Type of input: State space systems
Command:       [a,b,c,d]=series(a1,b1,c1,d1,a2,b2,c2,d2)
Forms the series representation of the two state space system arguments.
The series connected system will have the inputs of system 1 and the
outputs of system 2.

Type of input: system data structure
Command:       syst=series(syst1,syst2)
Forms the series representation of the two mu system arguments.
swapcols
-*- texinfo -*-
@deftypefn {Function File} {} swapcols (inputs)
@format
 function B = swapcols(A)
 permute columns of A into reverse order
@end format
@end deftypefn
swaprows
-*- texinfo -*-
@deftypefn {Function File} {} swaprows (inputs)
@format
 function B = swaprows(A)
 permute rows of A into reverse order
@end format
@end deftypefn
syschnames
-*- texinfo -*-
@deftypefn {Function File} {} syschnames (@var{sys}, @var{opt}, @var{list}, @var{names})
Superseded by @command{syssetsignals}.
@end deftypefn
unpacksys
[a,b,c,d] = unpacksys(sys)
Obsolete.  Use sys2ss instead.
__abcddims__
-*- texinfo -*-
@deftypefn {Function File} {[@var{y}, @var{my}, @var{ny}] =} __abcddims__ (@var{x})

Used internally in @code{abcddim}.  If @var{x} is a zero-size matrix,
both dimensions are set to 0 in @var{y}.
@var{my} and @var{ny} are the row and column dimensions of the result.
@end deftypefn
__syschnamesl__
-*- texinfo -*-
@deftypefn {Function File} {} __syschnamesl__ (@var{olist}, @var{old_names}, @var{inames}, @var{listname})
used internally in syschnames
item olist: index list
old_names: original list names
inames: new names
listname: name of index list

combines the two string lists old_names and inames
@end deftypefn
__syscont_disc__
-*- texinfo -*-
@deftypefn {Function File} {[@var{n_tot}, @var{st_c}, @var{st_d}, @var{y_c}, @var{y_d}] =} __syscont_disc__ (@var{sys})
Used internally in syscont and sysdisc.

@strong{Inputs}
@var{sys} is a system data structure.

@strong{Outputs}
@table @var
@item n_tot
total number of states
@item st_c
vector of continuous state indices (empty if none)
@item st_d
vector of discrete state indices (empty if none)
@item y_c
vector of continuous output indices
@item y_d
vector of discrete output indices
@end table
@end deftypefn
__sysdefioname__
-*- texinfo -*-
@deftypefn {Function File} {} __sysdefioname__ (@var{n}, @var{str}, @var{m})
return default input or output names given @var{n}, @var{str}, @var{m}.
@var{n} is the final value, @var{str} is the string prefix, and @var{m}
is start value

used internally, minimal argument checking

@strong{Example} @code{ioname = __sysdefioname__(5,"u",3)}
returns the cell array:
@example
ioname =
(
  [1] = u_3
  [2] = u_4
  [3] = u_5
)
@end example
@end deftypefn
__sysdefstname__
-*- texinfo -*-
@deftypefn {Function File} {} __sysdefstname__ (@var{n}, @var{nz})
return default state names given @var{n}, @var{nz}

used internally, minimal argument checking
@end deftypefn
__sysgroupn__
-*- texinfo -*-
@deftypefn {Function File} {} __sysgroupn__ (@var{names})
Locate and mark duplicate names
inputs:
names: list of signal names
kind: kind of signal name (used for diagnostic message purposes only)
outputs:
returns names with unique suffixes added; diagnostic warning
message is printed to inform the user of the new signal name

used internally in sysgroup and elsewhere.
@end deftypefn
__tf2sysl__
-*- texinfo -*-
@deftypefn {Function File} {} __tf2sysl__ (@var{vec})
used internally in tf2sys.
strip leading zero coefficients to get the true polynomial length
@end deftypefn
__tfl__
-*- texinfo -*-
@deftypefn {Function File} {} __tfl__ (@var{vec})
used internally in tf.
strip leading zero coefficients to get the true polynomial length
@end deftypefn
__zp2ssg2__
-*- texinfo -*-
@deftypefn {Function File} {[@var{poly}, @var{rvals}] =} __zp2ssg2__ (@var{rvals})
Used internally in @code{zp2ss}
Extract 2 values from @var{rvals} (if possible) and construct
a polynomial with those roots.
@end deftypefn
abcddim
-*- texinfo -*-
@deftypefn {Function File} {[@var{n}, @var{m}, @var{p}] =} abcddim (@var{a}, @var{b}, @var{c}, @var{d})
Check for compatibility of the dimensions of the matrices defining
the linear system
@iftex
@tex
$[A, B, C, D]$ corresponding to
$$
\eqalign{
 {dx\over dt} &= A x + B u\cr
            y &= C x + D u}
$$
@end tex
@end iftex
@ifinfo
[A, B, C, D] corresponding to

@example
dx/dt = a x + b u
y = c x + d u
@end example

@end ifinfo
or a similar discrete-time system.

If the matrices are compatibly dimensioned, then @code{abcddim} returns

@table @var
@item n
The number of system states.

@item m
The number of system inputs.

@item p
The number of system outputs.
@end table

Otherwise @code{abcddim} returns @var{n} = @var{m} = @var{p} = @minus{}1.

Note: n = 0 (pure gain block) is returned without warning.
@seealso{is_abcd}
@end deftypefn
buildssic
-*- texinfo -*-
@deftypefn {Function File} {} buildssic (@var{clst}, @var{ulst}, @var{olst}, @var{ilst}, @var{s1}, @var{s2}, @var{s3}, @var{s4}, @var{s5}, @var{s6}, @var{s7}, @var{s8})

Form an arbitrary complex (open or closed loop) system in
state-space form from several systems. @command{buildssic} can
easily (despite its cryptic syntax) integrate transfer functions
from a complex block diagram into a single system with one call.
This function is especially useful for building open loop
interconnections for 
@iftex
@tex
$ { \cal H }_\infty $ and $ { \cal H }_2 $
@end tex
@end iftex
@ifinfo
H-infinity and H-2
@end ifinfo
designs or for closing loops with these controllers.

Although this function is general purpose, the use of @command{sysgroup}
@command{sysmult}, @command{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 @var{s1}--@var{s8}.
Format of the lists:
@table @var
@item      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:
@code{[1 2 -1; 2 1 0]} means that:  new input 1 is old input 1
+ output 2 - output 1, and new input 2 is old input 2
+ output 1. The order of rows is arbitrary.

@item ulst
if not empty the old inputs in vector @var{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 @var{s1}--@var{s8}.

@item olst
output list, specifiy the outputs of the resulting
systems. Elements are output numbers of @var{s1}--@var{s8}.
The numbers are allowed to be negative and may
appear in any order. An empty matrix means
all outputs.

@item ilst
input list, specifiy the inputs of the resulting
systems. Elements are input numbers of @var{s1}--@var{s8}.
The numbers are allowed to be negative and may
appear in any order. An empty matrix means
all inputs.
@end table

Example:  Very simple closed loop system.
@example
@group
w        e  +-----+   u  +-----+
 --->o--*-->|  K  |--*-->|  G  |--*---> y
     ^  |   +-----+  |   +-----+  |
   - |  |            |            |
     |  |            +----------------> u
     |  |                         |
     |  +-------------------------|---> e
     |                            |
     +----------------------------+
@end group
@end example

The closed loop system @var{GW} can be optained by
@example
GW = buildssic([1 2; 2 -1], 2, [1 2 3], 2, G, K);
@end example
@table @var
@item clst
1st row: connect input 1 (@var{G}) with output 2 (@var{K}).

2nd row: connect input 2 (@var{K}) with negative output 1 (@var{G}).
@item ulst
Append input of 2 (@var{K}) to the number of outputs.
@item olst
Outputs are output of 1 (@var{G}), 2 (@var{K}) and 
appended output 3 (from @var{ulst}).
@item ilst
The only input is 2 (@var{K}).
@end table

Here is a real example:
@example
@group
                         +----+
    -------------------->| W1 |---> v1
z   |                    +----+
----|-------------+
    |             |
    |    +---+    v      +----+
    *--->| G |--->O--*-->| W2 |---> v2
    |    +---+       |   +----+
    |                |
    |                v
   u                  y
@end group
@end example
@iftex
@tex
$$ { \rm min } \Vert GW_{vz} \Vert _\infty $$  
@end tex
@end iftex
@ifinfo
@example
min || GW   ||
         vz   infty
@end example
@end ifinfo

The closed loop system @var{GW} 
@iftex
@tex
from $ [z, u]^T $ to $ [v_1, v_2, y]^T $
@end tex
@end iftex
@ifinfo
from [z, u]' to [v1, v2, y]' 
@end ifinfo
can be obtained by (all @acronym{SISO} systems):
@example
GW = buildssic([1, 4; 2, 4; 3, 1], 3, [2, 3, 5],
               [3, 4], G, W1, W2, One);
@end example
where ``One'' is a unity gain (auxillary) function with order 0.
(e.g. @code{One = ugain(1);})
@end deftypefn
c2d
-*- texinfo -*-
@deftypefn {Function File} {} c2d (@var{sys}, @var{opt}, @var{t})
@deftypefnx {Function File} {} c2d (@var{sys}, @var{t})

Converts the system data structure describing:
@iftex
@tex
$$ \dot x = A_cx + B_cu $$
@end tex
@end iftex
@ifinfo
@example
.
x = Ac x + Bc u
@end example
@end ifinfo
into a discrete time equivalent model:
@iftex
@tex
$$ x_{n+1} = A_dx_n + B_du_n $$
@end tex
@end iftex
@ifinfo
@example
x[n+1] = Ad x[n] + Bd u[n]
@end example
@end ifinfo
via the matrix exponential or bilinear transform.

@strong{Inputs}
@table @var
@item sys
system data structure (may have both continuous time and discrete
time subsystems)
@item opt
string argument; conversion option (optional argument;
may be omitted as shown above)
@table @code
@item "ex"
use the matrix exponential (default)
@item "bi"
use the bilinear transformation
@iftex
@tex
$$ s = { 2(z-1) \over T(z+1) } $$
@end tex
@end iftex
@ifinfo
@example
    2(z-1)
s = -----
    T(z+1)
@end example
@end ifinfo
FIXME: This option exits with an error if @var{sys} is not purely
continuous. (The @code{ex} option can handle mixed systems.)
@item "matched"
Use the matched pole/zero equivalent transformation (currently only
works for purely continuous @acronym{SISO} systems).
@end table
@item t
sampling time; required if @var{sys} is purely continuous.

@strong{Note} that if the second argument is not a string, @code{c2d()}
assumes that the second argument is @var{t} and performs 
appropriate argument checks.
@end table

@strong{Output}
@table @var
@item dsys 
Discrete time equivalent via zero-order hold, sample each @var{t} sec.
@end table

This function adds the suffix  @code{_d}
to the names of the new discrete states.
@end deftypefn
cellidx
-*- texinfo -*-
@deftypefn {Function File} {[@var{idxvec}, @var{errmsg}] =} cellidx (@var{listvar}, @var{strlist})
Return indices of string entries in @var{listvar} that match strings
in @var{strlist}.

Both @var{listvar} and @var{strlist} may be passed as strings or
string matrices.  If they are passed as string matrices, each entry
is processed by @code{deblank} prior to searching for the entries.

The first output is the vector of indices in @var{listvar}.

If @var{strlist} contains a string not in @var{listvar}, then
an error message is returned in @var{errmsg}.  If only one output
argument is requested, then @var{cellidx} prints @var{errmsg} to the
screen and exits with an error.
@end deftypefn
d2c
-*- texinfo -*-
@deftypefn {Function File} {} d2c (@var{sys}, @var{tol})
@deftypefnx {Function File} {} d2c (@var{sys}, @var{opt})
Convert a discrete (sub)system into a purely continuous one. 
The sampling time used is @code{sysgettsam(@var{sys})}.

@strong{Inputs}
@table @var
@item   sys
system data structure with discrete components
@item   tol
Scalar value.
Tolerance for convergence of default @code{"log"} option (see below)
@item   opt
conversion option.  Choose from:
@table @code
@item         "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
@var{a}, @var{b}, to get a better fit to the original data.

If called as @code{d2c (@var{sys}, @var{tol})}, with @var{tol}
positive scalar, the @code{"log"} option is used.  The default value
for @var{tol} is @code{1e-8}.
@item        "bi"
Conversion is performed via bilinear transform
@math{z = (1 + s T / 2)/(1 - s T / 2)} where @math{T} is the
system sampling time (see @code{sysgettsam}).

FIXME: bilinear option exits with an error if @var{sys} is not purely
discrete
@end table
@end table
@strong{Output}
@table @var
@item csys 
continuous time system (same dimensions and signal names as in @var{sys}).
@end table
@end deftypefn
dmr2d
-*- texinfo -*-
@deftypefn {Function File} {[@var{dsys}, @var{fidx}] =} dmr2d (@var{sys}, @var{idx}, @var{sprefix}, @var{ts2}, @var{cuflg})
convert a multirate digital system to a single rate digital system
states specified by @var{idx}, @var{sprefix} are sampled at @var{ts2}, all
others are assumed sampled at @var{ts1} = @code{sysgettsam (@var{sys})}.

@strong{Inputs}
@table @var
@item   sys
discrete time system;
@code{dmr2d} exits with an error if @var{sys} is not discrete
@item   idx
indices or names of states with sampling time 
@code{sysgettsam(@var{sys})} (may be empty); see @code{cellidx}
@item   sprefix
list of string prefixes of states with sampling time
@code{sysgettsam(@var{sys})} (may be empty)
@item   ts2
sampling time of states not specified by @var{idx}, @var{sprefix}
must be an integer multiple of @code{sysgettsam(@var{sys})}
@item   cuflg
"constant u flag" if @var{cuflg} is nonzero then the system inputs are
assumed to be constant over the revised sampling interval @var{ts2}.
Otherwise, since the inputs can change during the interval
@var{t} in @math{[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 @var{cuflg} = 1.
@end table

@strong{Outputs}
@table @var
@item   dsys
equivalent discrete time system with sampling time @var{ts2}.

The sampling time of sys is updated to @var{ts2}.

if @var{cuflg}=0 then a set of additional inputs is added to
the system with suffixes _d1, @dots{}, _dn to indicate their
delay from the starting time k @var{ts2}, i.e.
u = [u_1; u_1_d1; @dots{}, u_1_dn] where u_1_dk is the input
k*ts1 units of time after u_1 is sampled. (@var{ts1} is
the original sampling time of the discrete time system and
@var{ts2} = (n+1)*ts1)

@item   fidx
indices of "formerly fast" states specified by @var{idx} and @var{sprefix};
these states are updated to the new (slower) sampling interval @var{ts2}.
@end table

@strong{WARNING} Not thoroughly tested yet; especially when
@var{cuflg} == 0.
@end deftypefn
fir2sys
-*- texinfo -*-
@deftypefn {Function File} {} fir2sys (@var{num}, @var{tsam}, @var{inname}, @var{outname})
construct a system data structure from @acronym{FIR} description

@strong{Inputs}
@table @var
@item num
vector of coefficients 
@ifinfo
[c0, c1, @dots{}, cn]
@end ifinfo
@iftex
@tex
$ [c_0, c_1, \ldots, c_n ]$
@end tex
@end iftex
of the @acronym{SISO} @acronym{FIR} transfer function
@ifinfo
C(z) = c0 + c1*z^(-1) + c2*z^(-2) + @dots{} + cn*z^(-n)
@end ifinfo
@iftex
@tex
$$ C(z) = c_0 + c_1z^{-1} + c_2z^{-2} + \ldots + c_nz^{-n} $$
@end tex
@end iftex

@item tsam
sampling time (default: 1)

@item inname
name of input signal;  may be a string or a list with a single entry.

@item outname
name of output signal; may be a string or a list with a single entry.
@end table

@strong{Output}
@table @var
@item sys
system data structure
@end table

@strong{Example}
@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
@end example
@end deftypefn
is_abcd
-*- texinfo -*-
@deftypefn {Function File} {@var{retval} =} is_abcd (@var{a}, @var{b}, @var{c}, @var{d})
 Returns @var{retval} = 1 if the dimensions of @var{a}, @var{b},
@var{c}, @var{d} are compatible, otherwise @var{retval} = 0 with an
 appropriate diagnostic message printed to the screen.  The matrices
@var{b}, @var{c}, or @var{d} may be omitted.
@seealso{abcddim}
@end deftypefn
is_controllable
-*- texinfo -*-
@deftypefn {Function File} {[@var{retval}, @var{u}] =} is_controllable (@var{sys}, @var{tol})
@deftypefnx {Function File} {[@var{retval}, @var{u}] =} is_controllable (@var{a}, @var{b}, @var{tol})
Logical check for system controllability.

@strong{Inputs}
@table @var
@item sys
system data structure
@item a
@itemx b
@var{n} by @var{n}, @var{n} by @var{m} matrices, respectively
@item tol
optional roundoff parameter.  Default value: @code{10*eps}
@end table

@strong{Outputs}
@table @var
@item retval
Logical flag; returns true (1) if the system @var{sys} or the
pair (@var{a}, @var{b}) is controllable, whichever was passed as input
arguments.
@item u
@var{u} is an orthogonal basis of the controllable subspace.
@end table

@strong{Method}
Controllability is determined by applying Arnoldi iteration with
complete re-orthogonalization to obtain an orthogonal basis of the
Krylov subspace
@example
span ([b,a*b,...,a^@{n-1@}*b]).
@end example
The Arnoldi iteration is executed with @code{krylov} if the system
has a single input; otherwise a block Arnoldi iteration is performed
with @code{krylovb}.
@seealso{size, rows, columns, length, ismatrix, isscalar, isvector
is_observable, is_stabilizable, is_detectable, krylov, krylovb}
@end deftypefn
is_detectable
-*- texinfo -*-
@deftypefn {Function File} {@var{retval} =} is_detectable (@var{a}, @var{c}, @var{tol}, @var{dflg})
@deftypefnx {Function File} {@var{retval} =} is_detectable (@var{sys}, @var{tol})
Test for detactability (observability of unstable modes) of (@var{a}, @var{c}).

Returns 1 if the system @var{a} or the pair (@var{a}, @var{c}) is
detectable, 0 if not, and -1 if the system has unobservable modes at the
imaginary axis (unit circle for discrete-time systems).

@strong{See} @command{is_stabilizable} for detailed description of
arguments and computational method.
@seealso{is_stabilizable, size, rows, columns, length, ismatrix,
isscalar, isvector}
@end deftypefn
is_digital
-*- texinfo -*-
@deftypefn {Function File} {@var{digital} =} is_digital (@var{sys}, @var{eflg})
Return nonzero if system is digital.

@strong{Inputs}
@table @var
@item sys
System data structure.
@item eflg
When equal to 0 (default value), exits with an error if the system 
is mixed (continuous and discrete components); when equal to 1, print
a warning if the system is mixed (continuous and discrete); when equal
to 2, operate silently.
@end table

@strong{Output}
@table @var
@item digital
When equal to 0, the system is purely continuous; when equal to 1, the
system is purely discrete; when equal to -1, the system is mixed continuous 
and discrete.
@end table
Exits with an error if @var{sys} is a mixed (continuous and discrete) system.
@end deftypefn
is_observable
-*- texinfo -*-
@deftypefn {Function File} {[@var{retval}, @var{u}] =} is_observable (@var{a}, @var{c}, @var{tol})
@deftypefnx {Function File} {[@var{retval}, @var{u}] =} is_observable (@var{sys}, @var{tol})
Logical check for system observability.

Default: tol = @code{tol = 10*norm(a,'fro')*eps}

Returns 1 if the system @var{sys} or the pair (@var{a}, @var{c}) is
observable, 0 if not.

See @command{is_controllable} for detailed description of arguments
and default values.
@seealso{size, rows, columns, length, ismatrix, isscalar, isvector}
@end deftypefn
is_sample
-*- texinfo -*-
@deftypefn {Function File} {} is_sample (@var{ts})
Return true if @var{ts} is a valid sampling time
(real, scalar, > 0).
@end deftypefn
is_signal_list
-*- texinfo -*-
@deftypefn {Function File} {} is_signal_list (@var{mylist})
Return true if @var{mylist} is a list of individual strings.
@end deftypefn
is_siso
-*- texinfo -*-
@deftypefn {Function File} {} is_siso (@var{sys})
Returns nonzero if the system data structure
@var{sys} is single-input, single-output.
@end deftypefn
is_stabilizable
-*- texinfo -*-
@deftypefn {Function File} {@var{retval} =} is_stabilizable (@var{sys}, @var{tol})
@deftypefnx {Function File} {@var{retval} =} is_stabilizable (@var{a}, @var{b}, @var{tol}, @var{dflg})
Logical check for system stabilizability (i.e., all unstable modes are controllable). 
Returns 1 if the system is stabilizable, 0 if the system is not stabilizable, -1 
if the system has non stabilizable modes at the imaginary axis (unit circle for 
discrete-time systems.

Test for stabilizability is performed via Hautus Lemma. If 
@iftex
@tex
@var{dflg}$\neq$0
@end tex
@end iftex
@ifinfo 
@var{dflg}!=0
@end ifinfo
assume that discrete-time matrices (a,b) are supplied.
@seealso{size, rows, columns, length, ismatrix, isscalar, isvector
is_observable, is_stabilizable, is_detectable}
@end deftypefn
is_stable
-*- texinfo -*-
@deftypefn {Function File} {} is_stable (@var{a}, @var{tol}, @var{dflg})
@deftypefnx {Function File} {} is_stable (@var{sys}, @var{tol})
Returns 1 if the matrix @var{a} or the system @var{sys}
is stable, or 0 if not.

@strong{Inputs}
@table @var
@item  tol
is a roundoff parameter, set to 200*@code{eps} if omitted.
@item dflg
Digital system flag (not required for system data structure):
@table @code
@item @var{dflg} != 0
stable if eig(a) is in the unit circle

@item @var{dflg} == 0
stable if eig(a) is in the open LHP (default)
@end table
@end table
@seealso{size, rows, columns, length, ismatrix, isscalar, isvector
is_observable, is_stabilizable, is_detectable, krylov, krylovb}
@end deftypefn
jet707
-*- texinfo -*-
@deftypefn {Function File} {@var{sys} =} jet707 ()
Creates a linearized state-space model of a Boeing 707-321 aircraft
at @var{v}=80 m/s 
@iftex
@tex
($M = 0.26$, $G_{a0} = -3^{\circ}$, ${\alpha}_0 = 4^{\circ}$, ${\kappa}= 50^{\circ}$).
@end tex
@end iftex
@ifinfo
(@var{M} = 0.26, @var{Ga0} = -3 deg, @var{alpha0} = 4 deg, @var{kappa} = 50 deg).
@end ifinfo

System inputs: (1) thrust and (2) elevator angle.

System outputs:  (1) airspeed and (2) pitch angle.

@strong{Reference}: R. Brockhaus: @cite{Flugregelung} (Flight Control), Springer, 1994.
@seealso{ord2}
@end deftypefn
listidx
-*- texinfo -*-
@deftypefn {Function File} {[@var{idxvec}, @var{errmsg}] =} listidx (@var{listvar}, @var{strlist})
Return indices of string entries in @var{listvar} that match strings
in @var{strlist}.

Both @var{listvar} and @var{strlist} may be passed as strings or
string matrices.  If they are passed as string matrices, each entry
is processed by @code{deblank} prior to searching for the entries.

The first output is the vector of indices in @var{listvar}.

If @var{strlist} contains a string not in @var{listvar}, then
an error message is returned in @var{errmsg}.  If only one output
argument is requested, then @var{listidx} prints @var{errmsg} to the
screen and exits with an error.
@end deftypefn
moddemo
-*- texinfo -*-
@deftypefn {Function File} {} moddemo (@var{inputs})
Octave Control toolbox demo: Model Manipulations demo.
@end deftypefn
ord2
-*- texinfo -*-
@deftypefn {Function File} {} ord2 (@var{nfreq}, @var{damp}, @var{gain})
Creates a continuous 2nd order system with parameters:

@strong{Inputs}
@table @var
@item nfreq
natural frequency [Hz]. (not in rad/s)
@item damp
damping coefficient
@item gain
dc-gain
This is steady state value only for damp > 0.
gain is assumed to be 1.0 if ommitted.
@end table

@strong{Output}
@table @var
@item outsys
system data structure has representation with 
@ifinfo
@math{w = 2 * pi * nfreq}:
@end ifinfo
@iftex
@tex
$ w = 2  \pi  f $:
@end tex
@end iftex
@example
@group
    /                                        \
    | / -2w*damp -w \  / w \                 |
G = | |             |, |   |, [ 0  gain ], 0 |
    | \   w       0 /  \ 0 /                 |
    \                                        /
@end group
@end example
@end table
@strong{See also} @command{jet707} (@acronym{MIMO} example, Boeing 707-321
aircraft model)
@end deftypefn
parallel
-*- texinfo -*-
@deftypefn {Function File} {@var{ksys} =} parallel (@var{asys}, @var{bsys})
Forms the parallel connection of two systems.

@example
@group
             --------------------
             |      --------    |
    u  ----->|----> | asys |--->|----> y1
        |    |      --------    |
        |    |      --------    |
        |--->|----> | bsys |--->|----> y2
             |      --------    |
             --------------------
                  ksys
@end group
@end example
@end deftypefn
ss
-*- texinfo -*-
@deftypefn {Function File} {@var{outsys} =} ss (@var{a}, @var{b}, @var{c}, @var{d}, @var{tsam}, @var{n}, @var{nz}, @var{stname}, @var{inname}, @var{outname}, @var{outlist})
Create system structure from state-space data.   May be continous,
discrete, or mixed (sampled data)

@strong{Inputs}
@table @var
@item a
@itemx b
@itemx c
@itemx d
usual state space matrices.

default: @var{d} = zero matrix

@item   tsam
sampling rate.  Default: @math{tsam = 0} (continuous system)

@item n
@itemx nz
number of continuous, discrete states in the system

If @var{tsam} is 0, @math{n = @code{rows}(@var{a})}, @math{nz = 0}.

If @var{tsam} is greater than zero, @math{n = 0},
@math{nz = @code{rows}(@var{a})}

see below for system partitioning

@item  stname
cell array of strings of state signal names

default (@var{stname}=[] on input): @code{x_n} for continuous states,
@code{xd_n} for discrete states

@item inname
cell array of strings of input signal names

default (@var{inname} = [] on input): @code{u_n}

@item outname
cell array of strings of output signal names

default (@var{outname} = [] on input): @code{y_n}

@item   outlist

list of indices of outputs y that are sampled

If @var{tsam} is 0, @math{outlist = []}.

If @var{tsam} is greater than 0, @math{outlist = 1:@code{rows}(@var{c})}.
@end table

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

@code{sys2ss} returns a vector @var{yd} where
@var{yd}(@var{outlist}) = 1; all other entries of @var{yd} are 0.

@strong{Output}
@table @var
@item outsys
system data structure
@end table

@strong{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
@example
@group
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.)
@end group
@end example
with dynamic equations:
@ifinfo
@math{d/dt xc(t)     = acc*xc(t)      + acd*xd(k*tsam) + bc*u(t)}

@math{xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)}

@math{yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)}

@math{yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)}
@end ifinfo
@iftex
@tex
$$\eqalign{
{d \over dt} x_c(t)
  & =   a_{cc} x_c(t)      + a_{cd} x_d(k*t_{sam}) + bc*u(t) \cr
x_d((k+1)*t_{sam})
  & =   a_{dc} x_c(k t_{sam}) + a_{dd} x_d(k t_{sam}) + b_d u(k t_{sam}) \cr
y_c(t)
 & =  c_{cc} x_c(t) + c_{cd} x_d(k t_{sam}) + d_c u(t) \cr
y_d(k t_{sam})
  & =  c_{dc} x_c(k t_{sam}) + c_{dd} x_d(k t_{sam}) + d_d u(k t_{sam})
}$$
@end tex
@end iftex

@strong{Signal partitions}
@example
@group
        | continuous      | discrete               |
----------------------------------------------------
states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
----------------------------------------------------
outputs | outname(cout,:) | outname(outlist,:)     |
----------------------------------------------------
@end group
@end example
where @math{cout} is the list of in 1:@code{rows}(@var{p})
that are not contained in outlist. (Discrete/continuous outputs
may be entered in any order desired by the user.)

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

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

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

A matrix: 3 x 3
   1   2   3
   4   5   6
   7   8  10
B matrix: 3 x 2
  0  0
  0  1
  1  0
C matrix: 3 x 3
  1  0  0
  0  1  0
  0  0  1
D matrix: 3 x 3
  0  0
  0  0
  0  0
@end example
Notice that the @math{D} matrix is constructed  by default to the
correct dimensions.  Default input and output signals names were assigned
since none were given.
@end deftypefn
ss2sys
-*- texinfo -*-
@deftypefn {Function File} {} ss (@var{a}, @var{b}, @var{c}, @var{d}, @var{tsam}, @var{n}, @var{nz}, @var{stname}, @var{inname}, @var{outname}, @var{outlist})
Create system structure from state-space data.   May be continous,
discrete, or mixed (sampled data)

@strong{Inputs}
@table @var
@item a
@itemx b
@itemx c
@itemx d
usual state space matrices.

default: @var{d} = zero matrix

@item   tsam
sampling rate.  Default: @math{tsam = 0} (continuous system)

@item n
@itemx nz
number of continuous, discrete states in the system

If @var{tsam} is 0, @math{n = @code{rows}(@var{a})}, @math{nz = 0}.

If @var{tsam} is greater than zero, @math{n = 0},
@math{nz = @code{rows}(@var{a})}

see below for system partitioning

@item  stname
cell array of strings of state signal names

default (@var{stname}=[] on input): @code{x_n} for continuous states,
@code{xd_n} for discrete states

@item inname
cell array of strings of input signal names

default (@var{inname} = [] on input): @code{u_n}

@item outname
cell array of strings of input signal names

default (@var{outname} = [] on input): @code{y_n}

@item   outlist

list of indices of outputs y that are sampled

If @var{tsam} is 0, @math{outlist = []}.

If @var{tsam} is greater than 0, @math{outlist = 1:@code{rows}(@var{c})}.
@end table

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

@code{sys2ss} returns a vector @var{yd} where
@var{yd}(@var{outlist}) = 1; all other entries of @var{yd} are 0.

@strong{Outputs}
@var{outsys} = system data structure

@strong{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
@example
@group
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.)
@end group
@end example
with dynamic equations:
@ifinfo
@math{d/dt xc(t)     = acc*xc(t)      + acd*xd(k*tsam) + bc*u(t)}

@math{xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)}

@math{yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)}

@math{yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)}
@end ifinfo
@iftex
@tex
$$\eqalign{
{d \over dt} x_c(t)
  & =   a_{cc} x_c(t)      + a_{cd} x_d(k*t_{sam}) + bc*u(t) \cr
x_d((k+1)*t_{sam})
  & =   a_{dc} x_c(k t_{sam}) + a_{dd} x_d(k t_{sam}) + b_d u(k t_{sam}) \cr
y_c(t)
 & =  c_{cc} x_c(t) + c_{cd} x_d(k t_{sam}) + d_c u(t) \cr
y_d(k t_{sam})
  & =  c_{dc} x_c(k t_{sam}) + c_{dd} x_d(k t_{sam}) + d_d u(k t_{sam})
}$$
@end tex
@end iftex

@strong{Signal partitions}
@example
@group
        | continuous      | discrete               |
----------------------------------------------------
states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
----------------------------------------------------
outputs | outname(cout,:) | outname(outlist,:)     |
----------------------------------------------------
@end group
@end example
where @math{cout} is the list of in 1:@code{rows}(@var{p})
that are not contained in outlist. (Discrete/continuous outputs
may be entered in any order desired by the user.)

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

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

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

A matrix: 3 x 3
   1   2   3
   4   5   6
   7   8  10
B matrix: 3 x 2
  0  0
  0  1
  1  0
C matrix: 3 x 3
  1  0  0
  0  1  0
  0  0  1
D matrix: 3 x 3
  0  0
  0  0
  0  0
@end example
Notice that the @math{D} matrix is constructed  by default to the
correct dimensions.  Default input and output signals names were assigned
since none were given.
@end deftypefn
ss2tf
-*- texinfo -*-
@deftypefn {Function File} {[@var{num}, @var{den}] =} ss2tf (@var{a}, @var{b}, @var{c}, @var{d})
Conversion from tranfer function to state-space.
The state space system:
@iftex
@tex
$$ \dot x = Ax + Bu $$
$$ y = Cx + Du $$
@end tex
@end iftex
@ifinfo
@example
      .
      x = Ax + Bu
      y = Cx + Du
@end example
@end ifinfo

is converted to a transfer function:
@iftex
@tex
$$ G(s) = { { \rm num }(s) \over { \rm den }(s) } $$
@end tex
@end iftex
@ifinfo
@example

                num(s)
          G(s)=-------
                den(s)
@end example
@end ifinfo

used internally in system data structure format manipulations.
@end deftypefn
ss2zp
-*- texinfo -*-
@deftypefn {Function File} {[@var{pol}, @var{zer}, @var{k}] =} ss2zp (@var{a}, @var{b}, @var{c}, @var{d})
Converts a state space representation to a set of poles and zeros;
@var{k} is a gain associated with the zeros.

Used internally in system data structure format manipulations.
@end deftypefn
starp
-*- texinfo -*-
@deftypefn {Function File} {} starp (@var{P}, @var{K}, @var{ny}, @var{nu})

Redheffer star product or upper/lower LFT, respectively.
@example
@group

               +-------+
     --------->|       |--------->
               |   P   |
          +--->|       |---+  ny
          |    +-------+   |
          +-------------------+
                           |  |
          +----------------+  |
          |                   |
          |    +-------+      |
          +--->|       |------+ nu
               |   K   |
     --------->|       |--------->
               +-------+
@end group
@end example
If @var{ny} and @var{nu} ``consume'' all inputs and outputs of
@var{K} then the result is a lower fractional transformation. 
If @var{ny} and @var{nu} ``consume'' all inputs and outputs of 
@var{P} then the result is an upper fractional transformation.

@var{ny} and/or @var{nu} may be negative (i.e. negative feedback).
@end deftypefn
sys2fir
-*- texinfo -*-
@deftypefn {Function File} {[@var{c}, @var{tsam}, @var{input}, @var{output}] =} sys2fir (@var{sys})

Extract @acronym{FIR} data from system data structure; see @command{fir2sys} for
parameter descriptions.
@seealso{fir2sys}
@end deftypefn
sys2ss
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}, @var{tsam}, @var{n}, @var{nz}, @var{stname}, @var{inname}, @var{outname}, @var{yd}] =} sys2ss (@var{sys})
Extract state space representation from system data structure.

@strong{Input}
@table @var
@item sys
System data structure.
@end table

@strong{Outputs}
@table @var
@item a
@itemx b
@itemx c
@itemx d
State space matrices for @var{sys}.

@item tsam
Sampling time of @var{sys} (0 if continuous).

@item n
@itemx nz
Number of continuous, discrete states (discrete states come
last in state vector @var{x}).

@item stname
@itemx inname
@itemx outname
Signal names (lists of strings);  names of states,
inputs, and outputs, respectively.

@item yd
Binary vector; @var{yd}(@var{ii}) is 1 if output @var{y}(@var{ii})
is discrete (sampled); otherwise  @var{yd}(@var{ii}) is 0.

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

@strong{Example}
@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
@end example
@end deftypefn
sys2tf
-*- texinfo -*-
@deftypefn {Function File} {[@var{num}, @var{den}, @var{tsam}, @var{inname}, @var{outname}] =} sys2tf (@var{sys})
Extract transfer function data from a system data structure.

See @command{tf} for parameter descriptions.

@strong{Example}
@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
@end example
@end deftypefn
sys2zp
-*- texinfo -*-
@deftypefn {Function File} {[@var{zer}, @var{pol}, @var{k}, @var{tsam}, @var{inname}, @var{outname}] =} sys2zp (@var{sys})
Extract zero/pole/leading coefficient information from a system data
structure.

See @command{zp} for parameter descriptions.

@strong{Example}
@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
@end example
@end deftypefn
sysadd
-*- texinfo -*-
@deftypefn {Function File} {}  sysadd (@var{gsys}, @var{hsys})
returns @var{sys} = @var{gsys} + @var{hsys}.
@itemize @bullet
@item Exits with
an error if @var{gsys} and @var{hsys} are not compatibly dimensioned.
@item Prints a warning message is system states have identical names;
duplicate names are given a suffix to make them unique.
@item @var{sys} input/output names are taken from @var{gsys}.
@end itemize
@example
@group
          ________
     ----|  gsys  |---
u   |    ----------  +|
-----                (_)----> y
    |     ________   +|
     ----|  hsys  |---
          --------
@end group
@end example
@end deftypefn
sysappend
-*- texinfo -*-
@deftypefn {Function File} {@var{sys} =} sysappend (@var{syst}, @var{b}, @var{c}, @var{d}, @var{outname}, @var{inname}, @var{yd})
appends new inputs and/or outputs to a system

@strong{Inputs}
@table @var
@item syst
system data structure

@item b
matrix to be appended to sys "B" matrix (empty if none)

@item c
matrix to be appended to sys "C" matrix (empty if none)

@item d
revised sys d matrix (can be passed as [] if the revised d is all zeros)

@item outname
list of names for new outputs

@item inname
list of names for new inputs

@item yd
binary vector; @math{yd(ii)=0} indicates a continuous output;
@math{yd(ii)=1} indicates a discrete output.
@end table

@strong{Outputs}
@table @var
@item sys
@example
@group
   sys.b := [syst.b , b]
   sys.c := [syst.c  ]
            [ c     ]
   sys.d := [syst.d | D12 ]
            [ D21   | D22 ]
@end group
@end example
where @math{D12}, @math{D21}, and @math{D22} are the appropriate dimensioned
blocks of the input parameter @var{d}.
@itemize @bullet
@item The leading block @math{D11} of @var{d} is ignored.
@item If @var{inname} and @var{outname} are not given as arguments,
     the new inputs and outputs are be assigned default names.
@item @var{yd} is a binary vector of length rows(c) that indicates
     continuous/sampled outputs.  Default value for @var{yd} is:
@itemize @minus
@item @var{sys} is continuous or mixed
@var{yd} = @code{zeros(1,rows(c))}

@item @var{sys} is discrete
@var{yd} = @code{ones(1,rows(c))}
@end itemize
@end itemize
@end table
@end deftypefn
syschtsam
-*- texinfo -*-
@deftypefn {Function File} {} syschtsam (@var{sys}, @var{tsam})
This function changes the sampling time (tsam) of the system.  Exits with
an error if sys is purely continuous time.
@end deftypefn
sysconnect
-*- texinfo -*-
@deftypefn {Function File} {@var{clsys} =} sysconnect (@var{sys}, @var{out_idx}, @var{in_idx}, @var{order}, @var{tol})
Close the loop from specified outputs to respective specified inputs

@strong{Inputs}
@table @var
@item   sys
System data structure.
@item   out_idx
@itemx  in_idx
Names or indices of signals to connect (see @code{sysidx}).
The output specified by @math{out_idx(ii)} is connected to the input
specified by @math{in_idx(ii)}.
@item   order
logical flag (default = 0)
@table @code
@item        0
Leave inputs and outputs in their original order.
@item        1
Permute inputs and outputs to the order shown in the diagram below.
@end table
@item     tol
Tolerance for singularities in algebraic loops, default: 200@code{eps}.
@end table

@strong{Outputs}
@table @var
@item clsys
Resulting closed loop system.
@end table

@strong{Method}

@code{sysconnect} internally permutes selected inputs, outputs as shown
below, closes the loop, and then permutes inputs and outputs back to their
original order
@example
@group
                 --------------------
 u_1       ----->|                  |----> y_1
                 |        sys       |
         old u_2 |                  |
u_2* ---->(+)--->|                  |----->y_2
(in_idx)   ^     --------------------    | (out_idx)
           |                             |
           -------------------------------
@end group
@end example
The input that has the summing junction added to it has an * added to
the end  of the input name.
@end deftypefn
syscont
-*- texinfo -*-
@deftypefn {Function File} {[@var{csys}, @var{acd}, @var{ccd}] =} syscont (@var{sys})
Extract the purely continuous subsystem of an input system.

@strong{Input}
@table @var
@item sys
system data structure.
@end table

@strong{Outputs}
@table @var
@item csys
is the purely continuous input/output connections of @var{sys}
@item acd
@itemx ccd
connections from discrete states to continuous states,
discrete states to continuous outputs, respectively.

returns @var{csys} empty if no continuous/continous path exists
@end table
@end deftypefn
sysdimensions
-*- texinfo -*-
@deftypefn {Function File} {[@var{n}, @var{nz}, @var{m}, @var{p}, @var{yd}] =} sysdimensions (@var{sys}, @var{opt})
return the number of states, inputs, and/or outputs in the system
@var{sys}.

@strong{Inputs}
@table @var
@item sys
system data structure

@item opt
String indicating which dimensions are desired.  Values:
@table @code
@item "all"
(default) return all parameters as specified under Outputs below.

@item "cst"
return @var{n}= number of continuous states

@item "dst"
return @var{n}= number of discrete states

@item "in"
return @var{n}= number of inputs

@item "out"
return @var{n}= number of outputs
@end table
@end table

@strong{Outputs}
@table @var
@item  n
 number of continuous states (or individual requested dimension as specified
by @var{opt}).
@item  nz
 number of discrete states
@item  m
 number of system inputs
@item  p
 number of system outputs
@item  yd
 binary vector; @var{yd}(@var{ii}) is nonzero if output @var{ii} is
discrete.
@math{yd(ii) = 0} if output @var{ii} is continous
@end table
@seealso{sysgetsignals, sysgettsam}
@end deftypefn
sysdisc
-*- texinfo -*-
@deftypefn {Function File} {[@var{dsys}, @var{adc}, @var{cdc}] =} sysdisc (@var{sys})

@strong{Input}
@table @var
@item sys
System data structure.
@end table

@strong{Outputs}
@table @var
@item dsys
Purely discrete portion of sys (returned empty if there is
no purely discrete path from inputs to outputs).
@item    adc
@itemx   cdc
Connections from continuous states to discrete states and discrete.
outputs, respectively.
@end table
@end deftypefn
sysdup
-*- texinfo -*-
@deftypefn {Function File} {@var{retsys} =} sysdup (@var{asys}, @var{out_idx}, @var{in_idx})
Duplicate specified input/output connections of a system

@strong{Inputs}
@table @var
@item asys
system data structure
@item out_idx
@itemx in_idx
indices or names of desired signals (see @code{sigidx}).
duplicates are made of @code{y(out_idx(ii))} and @code{u(in_idx(ii))}.
@end table

@strong{Output}
@table @var
@item retsys
Resulting closed loop system:
duplicated i/o names are appended with a @code{"+"} suffix.
@end table

@strong{Method}

@code{sysdup} creates copies of selected inputs and outputs as
shown below.  @var{u1}, @var{y1} is the set of original inputs/outputs, and
@var{u2}, @var{y2} is the set of duplicated inputs/outputs in the order 
specified in @var{in_idx}, @var{out_idx}, respectively
@example
@group
          ____________________
u1  ----->|                  |----> y1
          |       asys       |
u2 ------>|                  |----->y2
(in_idx)  -------------------- (out_idx)
@end group
@end example
@end deftypefn
sysgetsignals
-*- texinfo -*-
@deftypefn {Function File} {[@var{stname}, @var{inname}, @var{outname}, @var{yd}] =} sysgetsignals (@var{sys})
@deftypefnx {Function File} {@var{siglist} =} sysgetsignals (@var{sys}, @var{sigid})
@deftypefnx {Function File} {@var{signame} =} sysgetsignals (@var{sys}, @var{sigid}, @var{signum}, @var{strflg})
Get signal names from a system

@strong{Inputs}
@table @var
@item sys
system data structure for the state space system

@item sigid
signal id.  String.  Must be one of
@table @code
@item "in"
input signals
@item "out"
output signals
@item "st"
stage signals
@item "yd"
value of logical vector @var{yd}
@end table

@item signum
index(indices) or name(s) or signals; see @code{sysidx}

@item strflg
flag to return a string instead of a cell array;  Values:
@table @code
@item 0
(default) return a cell array (even if signum specifies an individual signal)

@item 1
return a string.  Exits with an error if signum does not specify an 
individual signal.
@end table

@end table

@strong{Outputs}
@table @bullet
@item If @var{sigid} is not specified:
@table @var
@item stname
@itemx inname
@itemx outname
signal names (cell array of strings);  names of states,
inputs, and outputs, respectively.
@item yd
binary vector; @var{yd}(@var{ii}) is nonzero if output @var{ii} is
discrete.
@end table

@item If @var{sigid} is specified but @var{signum} is not specified:
@table @code
@item sigid="in"
@var{siglist} is set to the cell array of input names.

@item sigid="out"
@var{siglist} is set to the cell array of output names.

@item sigid="st"
@var{siglist} is set to the cell array of state names.

stage signals
@item sigid="yd"
@var{siglist} is set to logical vector indicating discrete outputs;
@var{siglist}(@var{ii}) = 0 indicates that output @var{ii} is continuous
(unsampled), otherwise it is discrete.

@end table

@item If the first three input arguments are specified:
@var{signame} is a cell array of the specified signal names (@var{sigid} is 
@code{"in"}, @code{"out"}, or @code{"st"}), or else the logical flag
indicating whether output(s) @var{signum} is(are) discrete (@var{sigval}=1)
or continuous (@var{sigval}=0).
@end table

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

  0  0  0
octave> # get only input signal names:
octave> Ain = sysgetsignals(sys,"in")
Ain =
(
  [1] = u_1
  [2] = u_2
)
octave> # get name of output 2 (in cell array):
octave> Aout = sysgetsignals(sys,"out",2)
Aout =
(
  [1] = y_2
)
octave> # get name of output 2 (as string):
octave> Aout = sysgetsignals(sys,"out",2,1)
Aout = y_2
@end example
@end deftypefn
sysgettsam
-*- texinfo -*-
@deftypefn {Function File} {} sysgettsam (@var{sys})
Return the sampling time of the system @var{sys}.
@end deftypefn
sysgettype
-*- texinfo -*-
@deftypefn {Function File} {} sysgettype (@var{sys})
return the initial system type of the system

@strong{Input}
@table @var
@item sys
System data structure.
@end table

@strong{Output}
@table @var
@item systype
String indicating how the structure was initially
constructed. Values: @code{"ss"}, @code{"zp"}, or @code{"tf"}.
@end table

@acronym{FIR} initialized systems return @code{systype="tf"}.
@end deftypefn
sysgroup
-*- texinfo -*-
@deftypefn {Function File} {@var{sys} =} sysgroup (@var{asys}, @var{bsys})
Combines two systems into a single system.

@strong{Inputs}
@table @var
@item asys
@itemx bsys
System data structures.
@end table

@strong{Output}
@table @var
@item sys
@math{sys = @r{block diag}(asys,bsys)}
@end table
@example
@group
         __________________
         |    ________    |
u1 ----->|--> | asys |--->|----> y1
         |    --------    |
         |    ________    |
u2 ----->|--> | bsys |--->|----> y2
         |    --------    |
         ------------------
              Ksys
@end group
@end example
The function also rearranges the internal state-space realization of @var{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.
@end deftypefn
sysidx
-*- texinfo -*-
@deftypefn {Function File} {} sysidx (@var{sys}, @var{sigtype}, @var{signamelist})
Return indices of signals with specified signal names
inputs given a system data structure @var{sys}, a signal type to be
selected @var{sigtype} (@code{"in"}, @code{"out"}, @code{"st"}), and
a list of desired signal names @var{signamelist}.
@end deftypefn
sysmin
-*- texinfo -*-
@deftypefn {Function File} {[@var{retsys}, @var{nc}, @var{no}] =} sysmin (@var{sys}, @var{flg})
Returns a minimal (or reduced order) system

@strong{Inputs}
@table @var
@item sys
System data structure
@item flg
When equal to 0 (default value), returns minimal system,
in which state names are lost; when equal to 1, returns system 
with physical states removed that are either uncontrollable or 
unobservable (cannot reduce further without discarding physical
meaning of states).
@end table
@strong{Outputs}
@table @var
@item retsys
Returned system.
@item nc
Number of controllable states in the returned system.
@item no
Number of observable states in the returned system.
@item cflg
@code{is_controllable(retsys)}.
@item oflg
@code{is_observable(retsys)}.
@end table
@end deftypefn
sysmult
-*- texinfo -*-
@deftypefn {Function File} {@var{sys} =} sysmult (@var{Asys}, @var{Bsys})
Compute @math{sys = Asys*Bsys} (series connection):
@example
@group
u   ----------     ----------
--->|  Bsys  |---->|  Asys  |--->
    ----------     ----------
@end group
@end example
A warning occurs if there is direct feed-through from an input 
or a continuous state of @var{Bsys}, through a discrete output 
of @var{Bsys}, to a continuous state or output in @var{Asys}
(system data structure does not recognize discrete inputs).
@end deftypefn
sysout
-*- texinfo -*-
@deftypefn {Function File} {} sysout (@var{sys}, @var{opt})
print out a system data structure in desired format
@table @var
@item  sys
system data structure
@item  opt
Display option
@table @code
@item []
primary system form (default)
@item      "ss"
state space form
@item      "tf"
transfer function form
@item      "zp"
zero-pole form
@item      "all"
all of the above
@end table
@end table
@end deftypefn
sysprune
-*- texinfo -*-
@deftypefn {Function File} {@var{retsys} =} sysprune (@var{asys}, @var{out_idx}, @var{in_idx})
Extract specified inputs/outputs from a system

@strong{Inputs}
@table @var
@item asys
system data structure
@item out_idx
@itemx 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.

@example
retsys = sysprune (Asys, [1:3,4], "u_1");
retsys = sysprune (Asys, @{"tx", "ty", "tz"@}, 4);
@end example

@end table

@strong{Output}
@table @var
@item retsys
Resulting system.
@end table
@example
@group
           ____________________
u1 ------->|                  |----> y1
 (in_idx)  |       Asys       | (out_idx)
u2 ------->|                  |----| y2
  (deleted)-------------------- (deleted)
@end group
@end example
@end deftypefn
sysreorder
-*- texinfo -*-
@deftypefn {Function File} {@var{pv} =} sysreorder (@var{vlen}, @var{list})

@strong{Inputs}
@table @var
@item vlen
Vector length.
@item list
A subset of @code{[1:vlen]}.
@end table

@strong{Output}
@table @var
@item pv
A permutation vector to order elements of @code{[1:vlen]} in
@code{list} to the end of a vector.
@end table

Used internally by @code{sysconnect} to permute vector elements to their
desired locations.
@end deftypefn
sysrepdemo
-*- texinfo -*-
@deftypefn {Function File} {} sysrepdemo
Tutorial for the use of the system data structure functions.
@end deftypefn
sysscale
-*- texinfo -*-
@deftypefn {Function File} {@var{retsys} =} sysscale (@var{sys}, @var{outscale}, @var{inscale}, @var{outname}, @var{inname})
scale inputs/outputs of a system.

@strong{Inputs}
@table @var
@item sys
Structured system.
@item outscale
@itemx inscale
Constant matrices of appropriate dimension.
@item outname
@itemx inname
Lists of strings with the names of respectively outputs and inputs.
@end table

@strong{Output}
@table @var
@item retsys
resulting open loop system:
@example
      -----------    -------    -----------
u --->| inscale |--->| sys |--->| outscale |---> y
      -----------    -------    -----------
@end example
@end table
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 @var{yd} is
set appropriately in the returned value of @var{sys}.
@end deftypefn
syssetsignals
-*- texinfo -*-
@deftypefn {Function File} {} syssetsignals (@var{sys}, @var{opt}, @var{names}, @var{sig_idx})
change the names of selected inputs, outputs and states.

@strong{Inputs}
@table @var
@item sys
System data structure.

@item opt
Change default name (output).

@table @code
@item "out"
Change selected output names.
@item "in"
Change selected input names.
@item "st"
Change selected state names.
@item "yd"
Change selected outputs from discrete to continuous or
from continuous to discrete.
@end table

@item names
@table @code
@item opt = "out", "in", "st"
string or string array containing desired signal names or values.
@item opt = "yd"
To desired output continuous/discrete flag.
Set name to 0 for continuous, or 1 for discrete.
@end table
@item 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.
@end table

@strong{Outputs}
@table @var
@item retsys
@var{sys} with appropriate signal names changed
(or @var{yd} values, where appropriate).
@end table

@strong{Example}
@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
@end example
@end deftypefn
syssub
-*- texinfo -*-
@deftypefn {Function File} {@var{sys} =} syssub (@var{Gsys}, @var{Hsys})
Return @math{sys = Gsys - Hsys}.

@strong{Method}

@var{Gsys} and @var{Hsys} are connected in parallel.
The input vector is connected to both systems; the outputs are
subtracted.  Returned system names are those of @var{Gsys}.
@example
@group
         +--------+
    +--->|  Gsys  |---+
    |    +--------+   |
    |                +|
u --+                (_)--> y
    |                -|
    |    +--------+   |
    +--->|  Hsys  |---+
         +--------+
@end group
@end example
@end deftypefn
sysupdate
-*- texinfo -*-
@deftypefn {Function File} {} sysupdate (@var{sys}, @var{opt})
Update the internal representation of a system.

@strong{Inputs}
@table @var
@item sys:
system data structure
@item opt
string:
@table @code
@item "tf"
update transfer function form
@item "zp"
update zero-pole form
@item "ss"
update state space form
@item "all"
all of the above
@end table
@end table

@strong{Outputs}
@table @var
@item retsys
Contains union of data in sys and requested data.
If requested data in @var{sys} is already up to date then @var{retsys}=@var{sys}.
@end table

Conversion to @command{tf} or @command{zp} exits with an error if the system is
mixed continuous/digital.
@seealso{tf, ss, zp, sysout, sys2ss, sys2tf, sys2zp}
@end deftypefn
tf
-*- texinfo -*-
@deftypefn {Function File} {} tf (@var{num}, @var{den}, @var{tsam}, @var{inname}, @var{outname})
build system data structure from transfer function format data

@strong{Inputs}
@table @var
@item  num
@itemx den
coefficients of numerator/denominator polynomials
@item tsam
sampling interval. default: 0 (continuous time)
@item inname
@itemx outname
input/output signal names; may be a string or cell array with a single string
entry.
@end table

@strong{Outputs}
@var{sys} = system data structure

@strong{Example}
@example
octave:1> sys=tf([2 1],[1 2 1],0.1);
octave:2> sysout(sys)
Input(s)
        1: u_1
Output(s):
        1: y_1 (discrete)
Sampling interval: 0.1
transfer function form:
2*z^1 + 1
-----------------
1*z^2 + 2*z^1 + 1
@end example
@end deftypefn
tf2ss
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}] =} tf2ss (@var{num}, @var{den})
Conversion from tranfer function to state-space.
The state space system:
@iftex
@tex
$$ \dot x = Ax + Bu $$
$$ y = Cx + Du $$
@end tex
@end iftex
@ifinfo
@example
      .
      x = Ax + Bu
      y = Cx + Du
@end example
@end ifinfo
is obtained from a transfer function:
@iftex
@tex
$$ G(s) = { { \rm num }(s) \over { \rm den }(s) } $$
@end tex
@end iftex
@ifinfo
@example
                num(s)
          G(s)=-------
                den(s)
@end example
@end ifinfo

The vector @var{den} must contain only one row, whereas the vector 
@var{num} may contain as many rows as there are outputs @var{y} of 
the system. The state space system matrices obtained from this function 
will be in controllable canonical form as described in @cite{Modern Control 
Theory}, (Brogan, 1991).
@end deftypefn
tf2sys
-*- texinfo -*-
@deftypefn {Function File} {} tf2sys (@var{num}, @var{den}, @var{tsam}, @var{inname}, @var{outname})
Build system data structure from transfer function format data.

@strong{Inputs}
@table @var
@item  num
@itemx den
Coefficients of numerator/denominator polynomials.
@item tsam
Sampling interval; default: 0 (continuous time).
@item inname
@itemx outname
Input/output signal names; may be a string or cell array with a single string
entry.
@end table

@strong{Output}
@table @var
@item sys
System data structure.
@end table

@strong{Example}
@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
@end example
@end deftypefn
tf2zp
-*- texinfo -*-
@deftypefn {Function File} {[@var{zer}, @var{pol}, @var{k}] =} tf2zp (@var{num}, @var{den})
Converts transfer functions to poles-and-zero representations.

Returns the zeros and poles of the @acronym{SISO} system defined 
by @var{num}/@var{den}.
@var{k} is a gain associated with the system zeros.
@end deftypefn
tfout
-*- texinfo -*-
@deftypefn {Function File} {} tfout (@var{num}, @var{denom}, @var{x})
Print formatted transfer function @math{n(s)/d(s)} to the screen.
@var{x} defaults to the string @code{"s"}
@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, polyinteg, polyout}
@end deftypefn
ugain
-*- texinfo -*-
@deftypefn {Function File} {} ugain (@var{n})
Creates a system with unity gain, no states.
This trivial system is sometimes needed to create arbitrary
complex systems from simple systems with @command{buildssic}.
Watch out if you are forming sampled systems since @command{ugain}
does not contain a sampling period.
@seealso{hinfdemo, jet707}
@end deftypefn
zp
-*- texinfo -*-
@deftypefn {Function File} {} zp (@var{zer}, @var{pol}, @var{k}, @var{tsam}, @var{inname}, @var{outname})
Create system data structure from zero-pole data.

@strong{Inputs}
@table @var
@item   zer
vector of system zeros
@item   pol
vector of system poles
@item   k
scalar leading coefficient
@item   tsam
sampling period. default: 0 (continuous system)
@item   inname
@itemx  outname
input/output signal names (lists of strings)
@end table

@strong{Outputs}
sys: system data structure

@strong{Example}
@example
octave:1> sys=zp([1 -1],[-2 -2 0],1);
octave:2> sysout(sys)
Input(s)
        1: u_1
Output(s):
        1: y_1
zero-pole form:
1 (s - 1) (s + 1)
-----------------
s (s + 2) (s + 2)
@end example
@end deftypefn
zp2ss
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}] =} zp2ss (@var{zer}, @var{pol}, @var{k})
Conversion from zero / pole to state space.

@strong{Inputs}
@table @var
@item zer
@itemx pol
Vectors of (possibly) complex poles and zeros of a transfer
function. Complex values must come in conjugate pairs
(i.e., @math{x+jy} in @var{zer} means that @math{x-jy} is also in @var{zer}).
The number of zeros must not exceed the number of poles.
@item k
Real scalar (leading coefficient).
@end table

@strong{Outputs}
@table @var
@item @var{a}
@itemx @var{b}
@itemx @var{c}
@itemx @var{d}
The state space system, in the form:
@iftex
@tex
$$ \dot x = Ax + Bu $$
$$ y = Cx + Du $$
@end tex
@end iftex
@ifinfo
@example
     .
     x = Ax + Bu
     y = Cx + Du
@end example
@end ifinfo
@end table
@end deftypefn
zp2sys
-*- texinfo -*-
@deftypefn {Function File} {} zp2sys (@var{zer}, @var{pol}, @var{k}, @var{tsam}, @var{inname}, @var{outname})
Create system data structure from zero-pole data.

@strong{Inputs}
@table @var
@item   zer
Vector of system zeros.
@item   pol
Vector of system poles.
@item   k
Scalar leading coefficient.
@item   tsam
Sampling period; default: 0 (continuous system).
@item   inname
@itemx  outname
Input/output signal names (lists of strings).
@end table

@strong{Output}
@table @var
@item sys
System data structure.
@end table

@strong{Example}
@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)
@end example
@end deftypefn
zp2tf
-*- texinfo -*-
@deftypefn {Function File} {[@var{num}, @var{den}] =} zp2tf (@var{zer}, @var{pol}, @var{k})
Converts zeros / poles to a transfer function.

@strong{Inputs}
@table @var
@item zer
@itemx pol
Vectors of (possibly complex) poles and zeros of a transfer
function.  Complex values must appear in conjugate pairs.
@item k
Real scalar (leading coefficient).
@end table
@end deftypefn
zpout
-*- texinfo -*-
@deftypefn {Function File} {} zpout (@var{zer}, @var{pol}, @var{k}, @var{x})
print formatted zero-pole form to the screen.
@var{x} defaults to the string @code{"s"}
@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, polyinteg, polyout}
@end deftypefn
__outlist__
-*- texinfo -*-
@deftypefn {Function File} {} __outlist__ (@var{lmat}, @var{tabchar}, @var{yd}, @var{ilist})
Prints an enumerated list of strings.
internal use only; minimal argument checking performed

@strong{Inputs}
@table @var
@item        lmat
list of strings
@item        tabchar
tab character (default: none)
@item   yd
indices of strings to append with the string "(discrete)"
(used by @var{sysout}; minimal checking of this argument)
@math{yd = []} indicates all outputs are continuous
@item ilist
index numbers to print with names.

default: @code{1:rows(lmat)}
@end table

@strong{Outputs}
prints the list to the screen, numbering each string in order.
@end deftypefn
__zgpbal__
-*- texinfo -*-
@deftypefn {Function File} {} __zgpbal__ (@var{sys})

Used internally in @command{tzero}; minimal argument checking performed.

Implementation of zero computation generalized eigenvalue problem
balancing method (Hodel and Tiller, Allerton Conference, 1991)
Based on Ward's balancing algorithm (@acronym{SIAM} J. Sci Stat. Comput., 1981).

@command{__zgpbal__} computes a state/input/output weighting that attempts to
reduced the range of the magnitudes of the nonzero elements of [@var{a}, @var{b},
@var{c}, @var{d}].
The weighting uses scalar multiplication by powers of 2, so no roundoff
will occur.

@command{__zgpbal__} should be followed by @command{zgpred}.
@end deftypefn
axis2dlim
-*- texinfo -*-
@deftypefn {Function File} {} axis2dlim (@var{axdata})
Determine axis limits for 2-D data (column vectors); leaves a 10%
margin around the plots.
Inserts margins of +/- 0.1 if data is one-dimensional 
(or a single point).

@strong{Input}
@table @var
@item axdata
@var{n} by 2 matrix of data [@var{x}, @var{y}].
@end table

@strong{Output}
@table @var
@item axvec
Vector of axis limits appropriate for call to @command{axis} function.
@end table
@end deftypefn
prompt
-*- texinfo -*-
@deftypefn {Function File} {} prompt (@var{str})
Prompt user to continue

@strong{Input}
@table @var
@item str
Input string. Its default value is: 
@example 
\n ---- Press a key to  continue ---
@end example
@end table
@end deftypefn
run_cmd
run_cmd: short script used in demos
prints string cmd to the screen, then executes after a pause
sortcom
-*- texinfo -*-
@deftypefn {Function File} {[@var{yy}, @var{idx}] =} sortcom (@var{xx}[, @var{opt}])
Sort a complex vector.

@strong{Inputs}
@table @var
@item xx
Complex vector
@item opt
sorting option:
@table @code
@item "re"
Real part (default);
@item "mag"
By magnitude;
@item "im"
By imaginary part.
@end table
if @var{opt} is not chosen as @code{"im"}, then complex conjugate pairs are grouped together,
@math{a - jb} followed by @math{a + jb}.
@end table

@strong{Outputs}
@table @var
@item yy
Sorted values
@item idx
Permutation vector: @code{yy = xx(idx)}
@end table
@end deftypefn
strappend
-*- texinfo -*-
@deftypefn {Function File} {} strappend (@var{strlist}, @var{suffix})
Append string @var{suffix} to each string in the list @var{strlist}.
@end deftypefn
swap
-*- texinfo -*-
@deftypefn {Function File} {} swap (@var{inputs})
@format
[a1,b1] = swap(a,b)
interchange a and b
@end format
@end deftypefn
zgfmul
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} zgfmul (@var{a}, @var{b}, @var{c}, @var{d}, @var{x})
Compute product of @var{zgep} incidence matrix @math{F} with vector @var{x}.
Used by @command{zgepbal} (in @command{zgscal}) as part of generalized conjugate gradient
iteration.
@end deftypefn
zgfslv
-*- texinfo -*-
@deftypefn {Function File} {} zgfslv (@var{n}, @var{m}, @var{p}, @var{b})
Solve system of equations for dense zgep problem.
@end deftypefn
zginit
-*- texinfo -*-
@deftypefn {Function File} {@var{zz} =} zginit (@var{a}, @var{b}, @var{c}, @var{d})
Construct right hand side vector @var{zz}
for the zero-computation generalized eigenvalue problem
balancing procedure.  Called by @command{zgepbal}.
@end deftypefn
zgreduce
-*- texinfo -*-
@deftypefn {Function File} {} zgreduce (@var{sys}, @var{meps})
Implementation of procedure REDUCE in (Emami-Naeini and Van Dooren,
Automatica, # 1982).
@end deftypefn
zgrownorm
-*- texinfo -*-
@deftypefn {Function File} {[@var{nonz}, @var{zer}] =} zgrownorm (@var{mat}, @var{meps})
Return @var{nonz} = number of rows of @var{mat} whose two norm
exceeds @var{meps}, and @var{zer} = number of rows of mat whose two
norm is less than @var{meps}.
@end deftypefn
zgscal
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} zgscal (@var{f}, @var{z}, @var{n}, @var{m}, @var{p})
Generalized conjugate gradient iteration to
solve zero-computation generalized eigenvalue problem balancing equation
@math{fx=z}; called by @command{zgepbal}.
@end deftypefn
zgsgiv
-*- texinfo -*-
@deftypefn {Function File} {[a, b] =} zgsgiv (@var{c}, @var{s}, @var{a}, @var{b})
Apply givens rotation c,s to row vectors @var{a}, @var{b}.
No longer used in zero-balancing (__zgpbal__); kept for backward
compatibility.
@end deftypefn
zgshsr
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} zgshsr (@var{y})
Apply householder vector based on 
@iftex
@tex
$ e^m $
@end tex
@end iftex
@ifinfo
@math{e^(m)}
@end ifinfo
to column vector @var{y}.
Called by @command{zgfslv}.
@end deftypefn
beta_cdf
-*- texinfo -*-
@deftypefn {Function File} {} beta_cdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, returns the CDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}, i.e.,
PROB (beta (@var{a}, @var{b}) <= @var{x}).
@end deftypefn
beta_inv
-*- texinfo -*-
@deftypefn {Function File} {} beta_inv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Beta distribution with parameters @var{a}
and @var{b}.
@end deftypefn
beta_pdf
-*- texinfo -*-
@deftypefn {Function File} {} beta_pdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, returns the PDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}.
@end deftypefn
beta_rnd
-*- texinfo -*-
@deftypefn {Function File} {} beta_rnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} beta_rnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or @code{size (@var{sz})} matrix of 
random samples from the Beta distribution with parameters @var{a} and
@var{b}.  Both @var{a} and @var{b} must be scalar or of size @var{r}
 by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn
binomial_cdf
-*- texinfo -*-
@deftypefn {Function File} {} binomial_cdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the CDF at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@end deftypefn
binomial_inv
-*- texinfo -*-
@deftypefn {Function File} {} binomial_inv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@end deftypefn
binomial_pdf
-*- texinfo -*-
@deftypefn {Function File} {} binomial_pdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the binomial distribution with parameters @var{n}
and @var{p}.
@end deftypefn
binomial_rnd
-*- texinfo -*-
@deftypefn {Function File} {} binomial_rnd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} binomial_rnd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of 
random samples from the binomial distribution with parameters @var{n}
and @var{p}.  Both @var{n} and @var{p} must be scalar or of size
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}.
@end deftypefn
chisquare_cdf
-*- texinfo -*-
@deftypefn {Function File} {} chisquare_cdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the chisquare distribution with @var{n}
degrees of freedom.
@end deftypefn
chisquare_inv
-*- texinfo -*-
@deftypefn {Function File} {} chisquare_inv (@var{x}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the chisquare distribution with @var{n} degrees of
freedom.
@end deftypefn
chisquare_pdf
-*- texinfo -*-
@deftypefn {Function File} {} chisquare_pdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the chisquare distribution with @var{n} degrees
of freedom. 
@end deftypefn
chisquare_rnd
-*- texinfo -*-
@deftypefn {Function File} {} chisquare_rnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} chisquare_rnd (@var{n}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of 
random samples from the chisquare distribution with @var{n} degrees 
of freedom.  @var{n} must be a scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{n}.
@end deftypefn
clearplot
-*- texinfo -*-
@deftypefn {Function File} {} clearplot ()
This function has been deprecated.  Use clf instead.
@end deftypefn
clg
-*- texinfo -*-
@deftypefn {Function File} {} clg ()
This function has been deprecated.  Use clf instead.
@end deftypefn
com2str
-*- texinfo -*-
@deftypefn {Function File} {} com2str (@var{zz}, @var{flg})
This function has been deprecated.  Use num2str instead.

Convert complex number to a string.
@strong{Inputs}
@table @var
@item zz
complex number
@item flg
format flag
0 (default):            -1, 0, 1,   1i,   1 + 0.5i
1 (for use with zpout): -1, 0, + 1, + 1i, + 1 + 0.5i
@end table
@end deftypefn
exponential_cdf
-*- texinfo -*-
@deftypefn {Function File} {} exponential_cdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the exponential distribution with
parameter @var{lambda}.

The arguments can be of common size or scalar.
@end deftypefn
exponential_inv
-*- texinfo -*-
@deftypefn {Function File} {} exponential_inv (@var{x}, @var{lambda})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the exponential distribution with parameter
@var{lambda}.
@end deftypefn
exponential_pdf
-*- texinfo -*-
@deftypefn {Function File} {} exponential_pdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function
(PDF) of the exponential distribution with parameter @var{lambda}.
@end deftypefn
exponential_rnd
-*- texinfo -*-
@deftypefn {Function File} {} exponential_rnd (@var{lambda}, @var{r}, @var{c})
@deftypefnx {Function File} {} exponential_rnd (@var{lambda}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
exponential distribution with parameter @var{lambda}, which must be a
scalar or of size @var{r} by @var{c}. Or if @var{sz} is a vector, 
create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{lambda}.
@end deftypefn
f_cdf
-*- texinfo -*-
@deftypefn {Function File} {} f_cdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the CDF at @var{x} of the F
distribution with @var{m} and @var{n} degrees of freedom, i.e.,
PROB (F (@var{m}, @var{n}) <= @var{x}). 
@end deftypefn
f_inv
-*- texinfo -*-
@deftypefn {Function File} {} f_inv (@var{x}, @var{m}, @var{n})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the F distribution with parameters @var{m} and
@var{n}.
@end deftypefn
f_pdf
-*- texinfo -*-
@deftypefn {Function File} {} f_pdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the F distribution with @var{m} and @var{n}
degrees of freedom.
@end deftypefn
f_rnd
-*- texinfo -*-
@deftypefn {Function File} {} f_rnd (@var{m}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} f_rnd (@var{m}, @var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the F
distribution with @var{m} and @var{n} degrees of freedom.  Both
@var{m} and @var{n} must be scalar or of size @var{r} by @var{c}.
If @var{sz} is a vector the random samples are in a matrix of 
size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{n}.
@end deftypefn
gamma_cdf
-*- texinfo -*-
@deftypefn {Function File} {} gamma_cdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Gamma distribution with parameters
@var{a} and @var{b}.
@end deftypefn
gamma_inv
-*- texinfo -*-
@deftypefn {Function File} {} gamma_inv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}. 
@end deftypefn
gamma_pdf
-*- texinfo -*-
@deftypefn {Function File} {} gamma_pdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, return the probability density function
(PDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}.
@end deftypefn
gamma_rnd
-*- texinfo -*-
@deftypefn {Function File} {} gamma_rnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} gamma_rnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the Gamma distribution with parameters @var{a}
and @var{b}.  Both @var{a} and @var{b} must be scalar or of size 
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn
geometric_cdf
-*- texinfo -*-
@deftypefn {Function File} {} geometric_cdf (@var{x}, @var{p})
For each element of @var{x}, compute the CDF at @var{x} of the
geometric distribution with parameter @var{p}.
@end deftypefn
geometric_inv
-*- texinfo -*-
@deftypefn {Function File} {} geometric_inv (@var{x}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
geometric distribution with parameter @var{p}.
@end deftypefn
geometric_pdf
-*- texinfo -*-
@deftypefn {Function File} {} geometric_pdf (@var{x}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the geometric distribution with parameter @var{p}.
@end deftypefn
geometric_rnd
-*- texinfo -*-
@deftypefn {Function File} {} geometric_rnd (@var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} geometric_rnd (@var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
geometric distribution with parameter @var{p}, which must be a scalar
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns. Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn
hypergeometric_cdf
-*- texinfo -*-
@deftypefn {Function File} {} hypergeometric_cdf (@var{x}, @var{m}, @var{t}, @var{n})
Compute the cumulative distribution function (CDF) at @var{x} of the
hypergeometric distribution with parameters @var{m}, @var{t}, and
@var{n}.  This is the probability of obtaining not more than @var{x}
marked items when randomly drawing a sample of size @var{n} without
replacement from a population of total size @var{t} containing
@var{m} marked items.

The parameters @var{m}, @var{t}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hypergeometric_inv
-*- texinfo -*-
@deftypefn {Function File} {} hypergeometric_inv (@var{x}, @var{m}, @var{t}, @var{n})
For each element of @var{x}, compute the quantile at @var{x} of the
hypergeometric distribution with parameters @var{m}, @var{t}, and
@var{n}.

The parameters @var{m}, @var{t}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hypergeometric_pdf
-*- texinfo -*-
@deftypefn {Function File} {} hypergeometric_pdf (@var{x}, @var{m}, @var{t}, @var{n})
Compute the probability density function (PDF) at @var{x} of the
hypergeometric distribution with parameters @var{m}, @var{t}, and
@var{n}. This is the probability of obtaining @var{x} marked items
when randomly drawing a sample of size @var{n} without replacement
from a population of total size @var{t} containing @var{m} marked items.

The arguments must be of common size or scalar.
@end deftypefn
hypergeometric_rnd
-*- texinfo -*-
@deftypefn {Function File} {} hypergeometric_rnd (@var{m}, @var{t}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} hygernd (@var{m}, @var{t}, @var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
hypergeometric distribution with parameters @var{m}, @var{t},
and @var{n}.

The parameters @var{m}, @var{t}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
intersection
-*- texinfo -*-
@deftypefn {Function File} {} intersection (@var{x}, @var{y})
This function has been deprecated.  Use intersect instead.
@end deftypefn
is_bool
-*- texinfo -*-
@deftypefn {Function File} {} is_bool (@var{a})
This function has been deprecated.  Use isbool instead.
@end deftypefn
is_complex
-*- texinfo -*-
@deftypefn {Function File} {} is_complex (@var{a})
This function has been deprecated.  Use iscomplex instead.
@end deftypefn
is_list
-*- texinfo -*-
@deftypefn {Function File} {} is_list (@var{a})
This function has been deprecated.  Use islist instead.
@end deftypefn
is_matrix
-*- texinfo -*-
@deftypefn {Function File} {} is_matrix (@var{a})
This function has been deprecated.  Use ismatrix instead.
@end deftypefn
is_scalar
-*- texinfo -*-
@deftypefn {Function File} {} is_scalar (@var{a})
This function has been deprecated.  Use isscalar instead.
@end deftypefn
is_square
-*- texinfo -*-
@deftypefn {Function File} {} is_square (@var{x})
This function has been deprecated.  Use issquare instead.
@end deftypefn
is_stream
-*- texinfo -*-
@deftypefn {Function File} {} is_stream (@var{a})
This function has been deprecated.  Use isstream instead.
@end deftypefn
is_struct
-*- texinfo -*-
@deftypefn {Function File} {} is_struct (@var{a})
This function has been deprecated.  Use isstruct instead.
@end deftypefn
is_symmetric
-*- texinfo -*-
@deftypefn {Function File} {} issymmetric (@var{x}, @var{tol})
This function has been deprecated.  Use issymmetric instead.
@end deftypefn
is_vector
-*- texinfo -*-
@deftypefn {Function File} {} is_vector (@var{a})
This function has been deprecated.  Use isvector instead.
@end deftypefn
isstr
-*- texinfo -*-
@deftypefn {Function File} {} isstr (@var{a})
This function has been deprecated.  Use ischar instead.
@end deftypefn
lognormal_cdf
-*- texinfo -*-
@deftypefn {Function File} {} lognormal_cdf (@var{x}, @var{a}, @var{v})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the lognormal distribution with
parameters @var{a} and @var{v}.  If a random variable follows this
distribution, its logarithm is normally distributed with mean
@code{log (@var{a})} and variance @var{v}.

Default values are @var{a} = 1, @var{v} = 1.
@end deftypefn
lognormal_inv
-*- texinfo -*-
@deftypefn {Function File} {} lognormal_inv (@var{x}, @var{a}, @var{v})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the lognormal distribution with parameters @var{a}
and @var{v}.  If a random variable follows this distribution, its
logarithm is normally distributed with mean @code{log (@var{a})} and
variance @var{v}.

Default values are @var{a} = 1, @var{v} = 1.
@end deftypefn
lognormal_pdf
-*- texinfo -*-
@deftypefn {Function File} {} lognormal_pdf (@var{x}, @var{a}, @var{v})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the lognormal distribution with parameters
@var{a} and @var{v}.  If a random variable follows this distribution,
its logarithm is normally distributed with mean @code{log (@var{a})}
and variance @var{v}.

Default values are @var{a} = 1, @var{v} = 1.
@end deftypefn
lognormal_rnd
-*- texinfo -*-
@deftypefn {Function File} {} lognormal_rnd (@var{a}, @var{v}, @var{r}, @var{c})
@deftypefnx {Function File} {} lognormal_rnd (@var{a}, @var{v}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
lognormal distribution with parameters @var{a} and @var{v}. Both
@var{a} and @var{v} must be scalar or of size @var{r} by @var{c}.
Or if @var{sz} is a vector, create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{v}.
@end deftypefn
meshdom
-*- texinfo -*-
@deftypefn {Function File} {} meshdom (@var{x}, @var{y})
This function has been deprecated.  Use @code{meshgrid} instead.
@end deftypefn
normal_cdf
-*- texinfo -*-
@deftypefn {Function File} {} normal_cdf (@var{x}, @var{m}, @var{v})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the normal distribution with mean
@var{m} and variance @var{v}.

Default values are @var{m} = 0, @var{v} = 1.
@end deftypefn
normal_inv
-*- texinfo -*-
@deftypefn {Function File} {} normal_inv (@var{x}, @var{m}, @var{v})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the normal distribution with mean @var{m} and
variance @var{v}.

Default values are @var{m} = 0, @var{v} = 1.
@end deftypefn
normal_pdf
-*- texinfo -*-
@deftypefn {Function File} {} normal_pdf (@var{x}, @var{m}, @var{v})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the normal distribution with mean @var{m} and
variance @var{v}.

Default values are @var{m} = 0, @var{v} = 1.
@end deftypefn
normal_rnd
-*- texinfo -*-
@deftypefn {Function File} {} normal_rnd (@var{m}, @var{v}, @var{r}, @var{c})
@deftypefnx {Function File} {} normal_rnd (@var{m}, @var{v}, @var{sz})
Return an @var{r} by @var{c}  or @code{size (@var{sz})} matrix of
random samples from the normal distribution with parameters @var{m} 
and @var{v}.  Both @var{m} and @var{v} must be scalar or of size 
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{v}.
@end deftypefn
pascal_cdf
-*- texinfo -*-
@deftypefn {Function File} {} pascal_cdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the CDF at x of the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution.
@end deftypefn
pascal_inv
-*- texinfo -*-
@deftypefn {Function File} {} pascal_inv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
Pascal (negative binomial) distribution with parameters @var{n} and
@var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution.
@end deftypefn
pascal_pdf
-*- texinfo -*-
@deftypefn {Function File} {} pascal_pdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Pascal (negative binomial) distribution with
parameters @var{n} and @var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution. 
@end deftypefn
pascal_rnd
-*- texinfo -*-
@deftypefn {Function File} {} pascal_rnd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} pascal_rnd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.
Both @var{n} and @var{p} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}. Or if @var{sz} is a vector, 
create a matrix of size @var{sz}.
@end deftypefn
poisson_cdf
-*- texinfo -*-
@deftypefn {Function File} {} poisson_cdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Poisson distribution with parameter
lambda.
@end deftypefn
poisson_inv
-*- texinfo -*-
@deftypefn {Function File} {} poisson_inv (@var{x}, @var{lambda})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Poisson distribution with parameter
@var{lambda}.
@end deftypefn
poisson_pdf
-*- texinfo -*-
@deftypefn {Function File} {} poisson_pdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the poisson distribution with parameter @var{lambda}.
@end deftypefn
poisson_rnd
-*- texinfo -*-
@deftypefn {Function File} {} poisson_rnd (@var{lambda}, @var{r}, @var{c})
Return an @var{r} by @var{c} matrix of random samples from the
Poisson distribution with parameter @var{lambda}, which must be a 
scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{lambda}.
@end deftypefn
polyinteg
-*- texinfo -*-
@deftypefn {Function File} {} polyinteg (@var{c})
Return the coefficients of the integral of the polynomial whose
coefficients are represented by the vector @var{c}.

The constant of integration is set to zero.
@seealso{poly, polyderiv, polyreduce, roots, conv, deconv, residue,
filter, polyval, and polyvalm}
@end deftypefn
setstr
-*- texinfo -*-
@deftypefn {Function File} {} setstr (@var{s})
This function has been deprecated.  Use char instead.
@end deftypefn
struct_contains
-*- texinfo -*-
@deftypefn {Function File} {} struct_contains (@var{expr}, @var{name})
This function has been deprecated.  Use isfield instead.
@end deftypefn
struct_elements
-*- texinfo -*-
@deftypefn {Function File} {} struct_elements (@var{struct})
This function has been deprecated.  Use fieldnames instead.
@end deftypefn
t_cdf
-*- texinfo -*-
@deftypefn {Function File} {} t_cdf (@var{x}, @var{n})
For each element of @var{x}, compute the CDF at @var{x} of the
t (Student) distribution with @var{n} degrees of freedom, i.e.,
PROB (t(@var{n}) <= @var{x}).
@end deftypefn
t_inv
-*- texinfo -*-
@deftypefn {Function File} {} t_inv (@var{x}, @var{n})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the t (Student) distribution with parameter
@var{n}.
@end deftypefn
t_pdf
-*- texinfo -*-
@deftypefn {Function File} {} t_pdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the @var{t} (Student) distribution with @var{n}
degrees of freedom. 
@end deftypefn
t_rnd
-*- texinfo -*-
@deftypefn {Function File} {} t_rnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} t_rnd (@var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the t
(Student) distribution with @var{n} degrees of freedom.  @var{n} must
be a scalar or of size @var{r} by @var{c}. Or if @var{sz} is a
vector create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{n}.
@end deftypefn
uniform_cdf
-*- texinfo -*-
@deftypefn {Function File} {} uniform_cdf (@var{x}, @var{a}, @var{b})
Return the CDF at @var{x} of the uniform distribution on [@var{a},
@var{b}], i.e., PROB (uniform (@var{a}, @var{b}) <= x).

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
uniform_inv
-*- texinfo -*-
@deftypefn {Function File} {} uniform_inv (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the uniform distribution on [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
uniform_pdf
-*- texinfo -*-
@deftypefn {Function File} {} uniform_pdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the PDF at @var{x} of the uniform
distribution on [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
uniform_rnd
-*- texinfo -*-
@deftypefn {Function File} {} uniform_rnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} uniform_rnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the uniform distribution on [@var{a}, @var{b}]. 
Both @var{a} and @var{b} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn
weibcdf
-*- texinfo -*-
@deftypefn {Function File} {} weibcdf (@var{x}, @var{scale}, @var{shape})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}, which is

@example
1 - exp(-(x/shape)^scale)
@end example

@noindent
for @var{x} >= 0.
@end deftypefn
weibinv
-*- texinfo -*-
@deftypefn {Function File} {} weibinv (@var{x}, @var{scale}, @var{shape})
Compute the quantile (the inverse of the CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}.
@end deftypefn
weibpdf
-*- texinfo -*-
@deftypefn {Function File} {} weibpdf (@var{x}, @var{scale}, @var{shape})
Compute the probability density function (PDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape} which is given by

@example
   scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)
@end example

@noindent
for @var{x} > 0.
@end deftypefn
weibrnd
-*- texinfo -*-
@deftypefn {Function File} {} weibrnd (@var{scale}, @var{shape}, @var{r}, @var{c})
@deftypefnx {Function File} {} weibrnd (@var{scale}, @var{shape}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{scale} and @var{shape}
which must be scalar or of size @var{r} by @var{c}. Or if @var{sz}
is a vector return a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{alpha} and @var{sigma}.
@end deftypefn
weibull_cdf
-*- texinfo -*-
@deftypefn {Function File} {} weibull_cdf (@var{x}, @var{shape}, @var{scale})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}, which is

@example
1 - exp(-(x/shape)^scale)
@end example

@noindent
for @var{x} >= 0.
@end deftypefn
weibull_inv
-*- texinfo -*-
@deftypefn {Function File} {} weibull_inv (@var{x}, @var{shape}, @var{scale})
Compute the quantile (the inverse of the CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}.
@end deftypefn
weibull_pdf
-*- texinfo -*-
@deftypefn {Function File} {} weibull_pdf (@var{x}, @var{shape}, @var{scale})
Compute the probability density function (PDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape} which is given by

@example
   scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)
@end example

@noindent
for @var{x} > 0.
@end deftypefn
weibull_rnd
-*- texinfo -*-
@deftypefn {Function File} {} weibull_rnd (@var{shape}, @var{scale}, @var{r}, @var{c})
@deftypefnx {Function File} {} weibull_rnd (@var{shape}, @var{scale}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{scale} and @var{shape}
which must be scalar or of size @var{r} by @var{c}. Or if @var{sz}
is a vector return a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{alpha} and @var{sigma}.
@end deftypefn
wiener_rnd
-*- texinfo -*-
@deftypefn {Function File} {} wiener_rnd (@var{t}, @var{d}, @var{n})
Return a simulated realization of the @var{d}-dimensional Wiener Process
on the interval [0, @var{t}].  If @var{d} is omitted, @var{d} = 1 is
used. The first column of the return matrix contains time, the
remaining columns contain the Wiener process.

The optional parameter @var{n} gives the number of summands used for
simulating the process over an interval of length 1.  If @var{n} is
omitted, @var{n} = 1000 is used.
@end deftypefn
acosd
-*- texinfo -*-
@deftypefn {Function File} {} acosd (@var{x})
Compute the inverse cosine of an angle in degrees.
@seealso{acos, cosd, asecd}
@end deftypefn
acot
-*- texinfo -*-
@deftypefn {Mapping Function} {} acot (@var{x})
Compute the inverse cotangent of each element of @var{x}.
@end deftypefn
acotd
-*- texinfo -*-
@deftypefn {Function File} {} acotd (@var{x})
Compute the inverse cotangent of an angle in degrees.
@seealso{atan, tand}
@end deftypefn
acoth
-*- texinfo -*-
@deftypefn {Mapping Function} {} acoth (@var{x})
Compute the inverse hyperbolic cotangent of each element of @var{x}.
@end deftypefn
acsc
-*- texinfo -*-
@deftypefn {Mapping Function} {} acsc (@var{x})
Compute the inverse cosecant of each element of @var{x}.
@end deftypefn
acscd
-*- texinfo -*-
@deftypefn {Function File} {} acscd (@var{x})
Compute the inverse cosecant of an angle in degrees.
@seealso{acsc, cscd, asecd}
@end deftypefn
acsch
-*- texinfo -*-
@deftypefn {Mapping Function} {} acsch (@var{x})
Compute the inverse hyperbolic cosecant of each element of @var{x}.
@end deftypefn
asec
-*- texinfo -*-
@deftypefn {Mapping Function} {} asec (@var{x})
Compute the inverse secant of each element of @var{x}.
@end deftypefn
asecd
-*- texinfo -*-
@deftypefn {Function File} {} asecd (@var{x})
Compute inverse secant in degrees.
@seealso{asec, secd, acscd}
@end deftypefn
asech
-*- texinfo -*-
@deftypefn {Mapping Function} {} asech (@var{x})
Compute the inverse hyperbolic secant of each element of @var{x}.
@end deftypefn
asind
-*- texinfo -*-
@deftypefn {Function File} {} asind (@var{x})
Compute the inverse sine of an angle in degrees.
@seealso{asin, sind, acosd}
@end deftypefn
atand
-*- texinfo -*-
@deftypefn {Function File} {} atand (@var{x})
Compute the inverse tangent of an angle in degrees.
@seealso{acot, tand}
@end deftypefn
cosd
-*- texinfo -*-
@deftypefn {Function File} {} cosd (@var{x})
Compute the cosine of an angle in degrees.  Returns zero in elements
for which @code{(@var{x}-90)/180} is an integer.
@seealso{cos, sind, tand, acosd, asind, atand}
@end deftypefn
cot
-*- texinfo -*-
@deftypefn {Mapping Function} {} cot (@var{x})
Compute the cotangent of each element of @var{x}.
@end deftypefn
cotd
-*- texinfo -*-
@deftypefn {Function File} {} cotd (@var{x})
Compute the cotangent of an angle in degrees.
@seealso{cot, tand}
@end deftypefn
coth
-*- texinfo -*-
@deftypefn {Mapping Function} {} coth (@var{x})
Compute the hyperbolic cotangent of each element of @var{x}.
@end deftypefn
csc
-*- texinfo -*-
@deftypefn {Mapping Function} {} csc (@var{x})
Compute the cosecant of each element of @var{x}.
@end deftypefn
cscd
-*- texinfo -*-
@deftypefn {Function File} {} cscd (@var{x})
Compute the cosecant of an angle in degrees.
@seealso{csc, secd, sind, cosd}
@end deftypefn
csch
-*- texinfo -*-
@deftypefn {Mapping Function} {} csch (@var{x})
Compute the hyperbolic cosecant of each element of @var{x}.
@end deftypefn
lcm
-*- texinfo -*-
@deftypefn {Mapping Function} {} lcm (@var{x}, @dots{})
Compute the least common multiple of the elements elements of @var{x}, or
the list of all the arguments.  For example,

@example
lcm (a1, ..., ak)
@end example

@noindent
is the same as

@example
lcm ([a1, ..., ak]).
@end example

All elements must be the same size or scalar.
@seealso{gcd, min, max, ceil, floor}
@end deftypefn
sec
-*- texinfo -*-
@deftypefn {Mapping Function} {} sec (@var{x})
Compute the secant of each element of @var{x}.
@end deftypefn
secd
-*- texinfo -*-
@deftypefn {Function File} {} secd (@var{x})
Compute the secant of an angle in degrees.
@seealso{sec, cscd, sind, cosd}
@end deftypefn
sech
-*- texinfo -*-
@deftypefn {Mapping Function} {} sech (@var{x})
Compute the hyperbolic secant of each element of @var{x}.
@end deftypefn
sind
-*- texinfo -*-
@deftypefn {Function File} {} sind (@var{x})
Compute the sine of each element of @var{x}.  Returns zero in elements
for which @code{@var{x}/180} is an integer.
@seealso{sin, cosd, tand, acosd, asind, atand}
@end deftypefn
tand
-*- texinfo -*-
@deftypefn {Function File} {} tand (@var{x})
Compute the tangent of an angle in degrees.  Returns zero for elements
of for which @code{@var{x}/180} is an integer and @code{Inf} for elements
where @code{(@var{x}-90)/180} is an integer.
@seealso{tan, cosd, sind, acosd, asind, atand}
@end deftypefn
fv
-*- texinfo -*-
@deftypefn {Function File} {} fv (@var{r}, @var{n}, @var{p}, @var{l}, @var{method})
Return the future value at the end of period @var{n} of an investment
which consists of @var{n} payments of @var{p} in each period,
assuming an interest rate @var{r}.

The optional argument @var{l} may be used to specify an
additional lump-sum payment.

The optional argument @var{method} may be used ot specify whether the
payments are made at the end (@code{"e"}, default) or at the
beginning (@code{"b"}) of each period.

Note that the rate @var{r} is specified as a fraction (i.e., 0.05,
not 5 percent).
@end deftypefn
fvl
-*- texinfo -*-
@deftypefn {Function File} {} fvl (@var{r}, @var{n}, @var{l})
Return the future value at the end of @var{n} periods of an initial
lump sum investment @var{l}, given a per-period interest rate
@var{r}.

Note that the rate @var{r} is specified as a fraction (i.e., 0.05,
not 5 percent).
@end deftypefn
irr
-*- texinfo -*-
@deftypefn {Function File} {} irr (@var{p}, @var{i})
Return the internal rate of return of a series of payments @var{p}
from an initial investment @var{i} (i.e., the solution of
@code{npv (r, p) = i}.  If the second argument is omitted, a value of
0 is used.
@seealso{npv, pv, rate}
@end deftypefn
nper
-*- texinfo -*-
@deftypefn {Function File} {} nper (@var{r}, @var{p}, @var{a}, @var{l}, @var{method})
Return the number of regular payments of @var{p} necessary to
amortize @var{a} loan of amount @var{a} and interest @var{r}.

The optional argument @var{l} may be used to specify an additional
lump-sum payment of @var{l} made at the end of the amortization time.

The optional argument @var{method} may be used to specify whether
payments are made at the end (@var{"e"}, default) or at the beginning
(@var{"b"}) of each period.

Note that the rate @var{r} is specified as a fraction (i.e., 0.05,
not 5 percent).
@seealso{pv, pmt, rate, npv}
@end deftypefn
npv
-*- texinfo -*-
@deftypefn {Function File} {} npv (@var{r}, @var{p}, @var{i})
Returns the net present value of a series of irregular (i.e., not
necessarily identical) payments @var{p} which occur at the ends of @var{n}
consecutive periods.  @var{r} specifies the one-period interest rates and
can either be a scalar (constant rates) or a vector of the same
length as @var{p}.

The optional argument @var{i} may be used to specify an initial
investment.

Note that the rate @var{r} is specified as a fraction (i.e., 0.05,
not 5 percent).
@seealso{irr, pv}
@end deftypefn
pmt
-*- texinfo -*-
@deftypefn {Function File} {} pmt (@var{r}, @var{n}, @var{a}, @var{l}, @var{method})
Return the amount of periodic payment necessary to amortize a loan
of amount a with interest rate @var{r} in @var{n} periods.

The optional argument @var{l} may be used to specify a terminal
lump-sum payment.

The optional argument @var{method} may be used to specify whether
payments are made at the end (@var{"e"}, default) or at the beginning
(@var{"b"}) of each period.
@seealso{pv, nper, rate}
@end deftypefn
pv
-*- texinfo -*-
@deftypefn {Function File} {} pv (@var{r}, @var{n}, @var{p}, @var{l}, @var{method})
Returns the present value of an investment that will pay off @var{p} for @var{n}
consecutive periods, assuming an interest @var{r}.

The optional argument @var{l} may be used to specify an additional
lump-sum payment made at the end of @var{n} periods.

The optional argument @var{method} may be used to specify whether
payments are made at the end (@code{"e"}, default) or at the
beginning (@code{"b"}) of each period.

Note that the rate @var{r} is specified as a fraction (i.e., 0.05,
not 5 percent).
@seealso{pmt, nper, rate, npv}
@end deftypefn
pvl
-*- texinfo -*-
@deftypefn {Function File} {} pvl (@var{r}, @var{n}, @var{p})
Return the present value of an investment that will pay off @var{p}
in one lump sum at the end of @var{n} periods, given the interest
rate @var{r}.

Note that the rate @var{r} is specified as a fraction (i.e., 0.05,
not 5 percent).
@end deftypefn
rate
-*- texinfo -*-
@deftypefn {Function File} {} rate (@var{n}, @var{p}, @var{v}, @var{l}, @var{method})
Return the rate of return on an investment of present value @var{v} which
pays @var{p} in @var{n} consecutive periods.

The optional argument @var{l} may be used to specify an additional
lump-sum payment made at the end of @var{n} periods.

The optional string argument @var{method} may be used to specify
whether payments are made at the end (@code{"e"}, default) or at the
beginning (@code{"b"}) of each period.
@seealso{pv, pmt, nper, npv}
@end deftypefn
vol
-*- texinfo -*-
@deftypefn {Function File} {} vol (@var{x}, @var{m}, @var{n})
Return the volatility of each column of the input matrix @var{x}.
The number of data sets per period is given by @var{m} (e.g. the
number of data per year if you want to compute the volatility per
year).  The optional parameter @var{n} gives the number of past
periods used for computation, if it is omitted, a value of 1 is used.
If @var{t} is the number of rows of @var{x}, @code{vol} returns the
volatility from @code{n*m} to @var{t}.
@end deftypefn
__isequal__
-*- texinfo -*-
@deftypefn {Function File} {} __isequal__ (@var{nans_compare_equal}, @var{x1}, @var{x2}, @dots{})
Return true if @var{x1}, @var{x2}, @dots{} are all equal and
@var{nans_compare_equal} evaluates to false.

If @var{nans_compare_equal} evaluates to true, then assume NaN == NaN.
@seealso{isequal, isequalwithequalnans}
@end deftypefn
__splinen__
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} = } __splinen__ (@var{x}, @var{y}, @var{xi})
Internal support function for multi-dimensional splines.
@end deftypefn
accumarray
-*- texinfo -*-
@deftypefn {Function File} {} accumarray (@var{subs}, @var{vals}, @var{sz}, @var{fun}, @var{fillval}, @var{issparse})
@deftypefnx {Function File} {} accumarray (@var{csubs}, @var{vals}, @dots{})

Creates an array by accumulating the elements of a vector into the
positions of defined by their subscripts. The subscripts are defined by
the rows of the matrix @var{subs} and the values by @var{vals}. Each row
of @var{subs} corresponds to one of the values in @var{vals}.

The size of the matrix will be determined by the subscripts themselves.
However, if @var{sz} is defined it determines the matrix size. The length
of @var{sz} must correspond to the number of columns in @var{subs}.

The default action of @code{accumarray} is to sum the elements with the
same subscripts. This behavior can be modified by defining the @var{fun}
function. This should be a function or function handle that accepts a 
column vector and returns a scalar. The result of the function should not
depend on the order of the subscripts.

The elements of the returned array that have no subscripts assoicated with
them are set to zero. Defining @var{fillval} to some other value allows
these values to be defined.

By default @code{accumarray} returns a full matrix. If @var{issparse} is
logically true, then a sparse matrix is returned instead.

An example of the use of @code{accumarray} is:

@example
@group
accumarray ([1,1,1;2,1,2;2,3,2;2,1,2;2,3,2],101:105)
@result{} ans(:,:,1) = [101, 0, 0; 0, 0, 0]
   ans(:,:,2) = [0, 0, 0; 206, 0, 208]
@end group
@end example
@end deftypefn
arrayfun
-*- texinfo -*-
@deftypefn {Function File} {@var{a} =} arrayfun (@var{name}, @var{c})
@deftypefnx {Function File} {@var{a} =} arrayfun (@var{func}, @var{c})
@deftypefnx {Function File} {@var{a} =} arrayfun (@var{func}, @var{c}, @var{d})
@deftypefnx {Function File} {@var{a} =} arrayfun (@var{func}, @var{c}, @var{options})
@deftypefnx {Function File} {[@var{a}, @var{b}, @dots{}] =} arrayfun (@var{func}, @var{c}, @dots{})
Execute a function on each element of an array.  This is useful for
functions that do not accept array arguments.  If the function does
accept array arguments it is better to call the function directly.

See @code{cellfun} for complete usage instructions.
@seealso{cellfun}
@end deftypefn
bicubic
-*- texinfo -*-
@deftypefn {Function File} {@var{zi}=} bicubic (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{extrapval})

Return a matrix @var{zi} corresponding to the bicubic
interpolations at @var{xi} and @var{yi} of the data supplied
as @var{x}, @var{y} and @var{z}. Points outside the grid are set
to @var{extrapval}

See @url{http://wiki.woodpecker.org.cn/moin/Octave/Bicubic}
for further information.
@seealso{interp2}
@end deftypefn
bitcmp
-*- texinfo -*-
@deftypefn {Function File} {} bitcmp (@var{a}, @var{k})
Return the @var{k}-bit complement of integers in @var{a}.  If
@var{k} is omitted @code{k = log2 (bitmax) + 1} is assumed.

@example
bitcmp(7,4)
@result{} 8
dec2bin(11)
@result{} 1011
dec2bin(bitcmp(11, 6))
@result{} 110100
@end example
@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
bitget
-*- texinfo -*-
@deftypefn {Function File} {@var{X} =} bitget (@var{a},@var{n})
Return the status of bit(s) @var{n} of unsigned integers in @var{a}
the lowest significant bit is @var{n} = 1.

@example
bitget (100, 8:-1:1)
@result{} 0  1  1  0  0  1  0  0 
@end example
@seealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, bitmax}
@end deftypefn
bitset
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} bitset (@var{a}, @var{n})
@deftypefnx {Function File} {@var{x} =} bitset (@var{a}, @var{n}, @var{v})
Set or reset bit(s) @var{n} of unsigned integers in @var{a}.
@var{v} = 0 resets and @var{v} = 1 sets the bits.
The lowest significant bit is: @var{n} = 1

@example
dec2bin (bitset (10, 1))
@result{} 1011
@end example
@seealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, bitmax}
@end deftypefn
blkdiag
-*- texinfo -*-
@deftypefn {Function File} {} blkdiag (@var{a}, @var{b}, @var{c}, @dots{})
Build a block diagonal matrix from @var{a}, @var{b}, @var{c}, @dots{}.
All the arguments must be numeric and are two-dimensional matrices or
scalars.
@seealso{diag, horzcat, vertcat}
@end deftypefn
cart2pol
-*- texinfo -*-
@deftypefn {Function File} {[@var{theta}, @var{r}] =} cart2pol (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{theta}, @var{r}, @var{z}] =} cart2pol (@var{x}, @var{y}, @var{z})
Transform cartesian to polar or cylindrical coordinates.
@var{x}, @var{y} (and @var{z}) must be of same shape.
@var{theta} describes the angle relative to the x - axis.
@var{r} is the distance to the z - axis (0, 0, z).
@seealso{pol2cart, cart2sph, sph2cart}
@end deftypefn
cart2sph
-*- texinfo -*-
@deftypefn {Function File} {[@var{theta}, @var{phi}, @var{r}] =} cart2sph (@var{x}, @var{y}, @var{z})
Transform cartesian to spherical coordinates.
@var{x}, @var{y} and @var{z} must be of same shape.
@var{theta} describes the angle relative to the x - axis.
@var{phi} is the angle relative to the xy - plane.
@var{r} is the distance to the origin (0, 0, 0).
@seealso{pol2cart, cart2pol, sph2cart}
@end deftypefn
cell2mat
-*- texinfo -*-
@deftypefn {Function File} {@var{m} =} cell2mat (@var{c})
Convert the cell array @var{c} into a matrix by concatenating all
elements of @var{c} into a hyperrectangle.  Elements of @var{c} must
be numeric, logical or char, and @code{cat} must be able to
concatenate them together.
@seealso{mat2cell, num2cell}
@end deftypefn
celldisp
-*- texinfo -*-
@deftypefn {Function File} {} celldisp (@var{c}, @var{name})
Recursively display the contents of a cell array. By default the values
are displayed with the name of the variable @var{c}. However, this name
can be replaced with the variable @var{name}.
@seealso{disp}
@end deftypefn
circshift
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} circshift (@var{x}, @var{n})
Circularly shifts the values of the array @var{x}. @var{n} must be
a vector of integers no longer than the number of dimensions in 
@var{x}. The values of @var{n} can be either positive or negative,
which determines the direction in which the values or @var{x} are
shifted. If an element of @var{n} is zero, then the corresponding
dimension of @var{x} will not be shifted. For example

@example
@group
x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
circshift (x, 1)
@result{}  7, 8, 9
    1, 2, 3
    4, 5, 6
circshift (x, -2)
@result{}  7, 8, 9
    1, 2, 3
    4, 5, 6
circshift (x, [0,1])
@result{}  3, 1, 2
    6, 4, 5
    9, 7, 8
@end group
@end example
@seealso {permute, ipermute, shiftdim}
@end deftypefn
common_size
-*- texinfo -*-
@deftypefn {Function File} {[@var{err}, @var{y1}, @dots{}] =} common_size (@var{x1}, @dots{})
Determine if all input arguments are either scalar or of common
size.  If so, @var{err} is zero, and @var{yi} is a matrix of the
common size with all entries equal to @var{xi} if this is a scalar or
@var{xi} otherwise.  If the inputs cannot be brought to a common size,
errorcode is 1, and @var{yi} is @var{xi}.  For example,

@example
@group
[errorcode, a, b] = common_size ([1 2; 3 4], 5)
@result{} errorcode = 0
@result{} a = [ 1, 2; 3, 4 ]
@result{} b = [ 5, 5; 5, 5 ]
@end group
@end example

@noindent
This is useful for implementing functions where arguments can either
be scalars or of common size.
@end deftypefn
cplxpair
-*- texinfo -*-
@deftypefn {Function File} {} cplxpair (@var{z}, @var{tol}, @var{dim})
Sort the numbers @var{z} into complex conjugate pairs ordered by 
increasing real part.  With identical real parts, order by increasing
imaginary magnitude. Place the negative imaginary complex number
first within each pair. Place all the real numbers after all the 
complex pairs (those with @code{abs (imag (@var{z}) / @var{z}) < 
@var{tol})}, where the default value of @var{tol} is @code{100 * 
@var{eps}}.

By default the complex pairs are sorted along the first non-singleton
dimension of @var{z}. If @var{dim} is specified, then the complex
pairs are sorted along this dimension.

Signal an error if some complex numbers could not be paired. Requires
all complex numbers to be exact conjugates within tol, or signals an 
error. Note that there are no guarantees on the order of the returned
pairs with identical real parts but differing imaginary parts.

@example
cplxpair (exp(2i*pi*[0:4]'/5)) == exp(2i*pi*[3; 2; 4; 1; 0]/5)
@end example
@end deftypefn
cumtrapz
-*- texinfo -*-
@deftypefn {Function File} {@var{z} =} cumtrapz (@var{y})
@deftypefnx {Function File} {@var{z} =} cumtrapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} cumtrapz (@dots{}, @var{dim})

Cumulative numerical intergration using trapezodial method.
@code{cumtrapz (@var{y})} computes the cummulative integral of the 
@var{y} along the first non singleton dimension. If the argument 
@var{x} is omitted a equally spaced vector is assumed. @code{cumtrapz 
(@var{x}, @var{y})} evaluates the cummulative integral with respect 
to @var{x}.
 
@seealso{trapz,cumsum}
@end deftypefn
deal
-*- texinfo -*-
@deftypefn {Function File} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a})
@deftypefnx {Function File} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a1}, @var{a2}, @dots{}, @var{an})

Copy the input parameters into the corresponding output parameters.
If only one input parameter is supplied, its value is copied to each
of the outputs.

For example,

@example
[a, b, c] = deal (x, y, z);
@end example

@noindent
is equivalent to

@example
@group
a = x;
b = y;
c = z;
@end group
@end example

@noindent
and

@example
[a, b, c] = deal (x);
@end example

@noindent
is equivalent to

@example
a = b = c = x;
@end example
@end deftypefn
del2
-*- texinfo -*-
@deftypefn {Function File} {@var{d} =} del2 (@var{m})
@deftypefnx {Function File} {@var{d} =} del2 (@var{m}, @var{h})
@deftypefnx {Function File} {@var{d} =} del2 (@var{m}, @var{dx}, @var{dy}, @dots{})

Calculates the discrete Laplace operator. If @var{m} is a matrix this is
defined as

@iftex
@tex
$d = {1 \over 4} \left( {d^2 \over dx^2} M(x,y) + {d^2 \over dy^2} M(x,y) \right)$
@end tex
@end iftex
@ifnottex
@example
@group
      1    / d^2            d^2         \
D  = --- * | ---  M(x,y) +  ---  M(x,y) | 
      4    \ dx^2           dy^2        /
@end group
@end example
@end ifnottex

The above to continued to N-dimensional arrays calculating the second
derivative over the higher dimensions.

The spacing between evaluation points may be defined by @var{h}, which is a
scalar defining the spacing in all dimensions. Or alternative, the spacing
in each dimension may be defined separately by @var{dx}, @var{dy}, etc. 
Scalar spacing values give equidistant spacing, whereas vector spacing 
values can be used to specify variable spacing. The length of the vectors
must match the respective dimension of @var{m}. The default spacing value
is 1.

You need at least 3 data points for each dimension. Boundary points are
calculated as the linear extrapolation of the interior points.

@seealso{gradient, diff}
@end deftypefn
diff
-*- texinfo -*-
@deftypefn {Function File} {} diff (@var{x}, @var{k}, @var{dim})
If @var{x} is a vector of length @var{n}, @code{diff (@var{x})} is the
vector of first differences
@iftex
@tex
 $x_2 - x_1, \ldots{}, x_n - x_{n-1}$.
@end tex
@end iftex
@ifinfo
@var{x}(2) - @var{x}(1), @dots{}, @var{x}(n) - @var{x}(n-1).
@end ifinfo

If @var{x} is a matrix, @code{diff (@var{x})} is the matrix of column
differences along the first non-singleton dimension.

The second argument is optional.  If supplied, @code{diff (@var{x},
@var{k})}, where @var{k} is a nonnegative integer, returns the
@var{k}-th differences. It is possible that @var{k} is larger than
then first non-singleton dimension of the matrix. In this case,
@code{diff} continues to take the differences along the next
non-singleton dimension.

The dimension along which to take the difference can be explicitly
stated with the optional variable @var{dim}. In this case the 
@var{k}-th order differences are calculated along this dimension.
In the case where @var{k} exceeds @code{size (@var{x}, @var{dim})}
then an empty matrix is returned.
@end deftypefn
flipdim
-*- texinfo -*-
@deftypefn {Function File} {} flipdim (@var{x}, @var{dim})
Return a copy of @var{x} flipped about the dimension @var{dim}.
For example

@example
@group
flipdim ([1, 2; 3, 4], 2)
@result{}  2  1
         4  3
@end group
@end example
@seealso{fliplr, flipud, rot90, rotdim}
@end deftypefn
fliplr
-*- texinfo -*-
@deftypefn {Function File} {} fliplr (@var{x})
Return a copy of @var{x} with the order of the columns reversed.  For
example,

@example
@group
fliplr ([1, 2; 3, 4])
@result{}  2  1
         4  3
@end group
@end example

Note that @code{fliplr} only work with 2-D arrays.  To flip N-d arrays
use @code{flipdim} instead.
@seealso{flipud, flipdim, rot90, rotdim}
@end deftypefn
flipud
-*- texinfo -*-
@deftypefn {Function File} {} flipud (@var{x})
Return a copy of @var{x} with the order of the rows reversed.  For
example,

@example
@group
flipud ([1, 2; 3, 4])
@result{}  3  4
         1  2
@end group
@end example

Due to the difficulty of defining which axis about which to flip the 
matrix @code{flipud} only work with 2-d arrays.  To flip N-d arrays
use @code{flipdim} instead.
@seealso{fliplr, flipdim, rot90, rotdim}
@end deftypefn
gradient
-*- texinfo -*-
@deftypefn {Function File} {@var{x} = } gradient (@var{M})
@deftypefnx {Function File} {[@var{x}, @var{y}, @dots{}] = } gradient (@var{M})
@deftypefnx {Function File} {[@dots{}] = } gradient (@var{M}, @var{s})
@deftypefnx {Function File} {[@dots{}] = } gradient (@var{M}, @var{dx}, @var{dy}, @dots{})

Calculates the gradient. @code{@var{x} = gradient (@var{M})}
calculates the one dimensional gradient if @var{M} is a vector. If
@var{M} is a matrix the gradient is calculated for each row.

@code{[@var{x}, @var{y}] = gradient (@var{M})} calculates the one
dimensional gradient for each direction if @var{M} if @var{M} is a
matrix. Additional return arguments can be use for multi-dimensional
matrices.

Spacing values between two points can be provided by the
@var{dx}, @var{dy} or @var{h} parameters. If @var{h} is supplied it
is assumed to be the spacing in all directions. Otherwise, seperate
values of the spacing can be supplied by the @var{dx}, etc variables.
A scalar value specifies an equidistant spacing, while a vector value
can be used to specify a variable spacing. The length must match
their respective dimension of @var{M}.

At boundary points a linear extrapolation is applied. Interior points
are calculated with the first approximation of the numerical gradient

@example
y'(i) = 1/(x(i+1)-x(i-1)) *(y(i-1)-y(i+1)).
@end example

@end deftypefn
ind2sub
-*- texinfo -*-
@deftypefn {Function File} {[@var{s1}, @var{s2}, @dots{}, @var{sN}] =} ind2sub (@var{dims}, @var{ind})
Convert a linear index into subscripts.

The following example shows how to convert the linear index @code{8}
in a 3-by-3 matrix into a subscript.

@example
[r, c] = ind2sub ([3, 3], 8)
@result{} r =  2
c =  3
@end example
@seealso{sub2ind}
@end deftypefn
int2str
-*- texinfo -*-
@deftypefn {Function File} {} int2str (@var{n})
@deftypefnx {Function File} {} int2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} int2str (@var{x}, @var{format})
Convert an integer to a string.  This function is not very flexible.
For better control over the results, use @code{sprintf}
(@pxref{Formatted Output}). 
@seealso{sprintf, num2str}
@end deftypefn
interp1
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} =} interp1 (@var{x}, @var{y}, @var{xi})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{yi} =} interp1 (@dots{}, @var{extrap})
@deftypefnx {Function File} {@var{pp} =} interp1 (@dots{}, 'pp')

One-dimensional interpolation. Interpolate @var{y}, defined at the
points @var{x}, at the points @var{xi}. The sample points @var{x} 
must be strictly monotonic. If @var{y} is an array, treat the columns
of @var{y} seperately.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbour.
@item 'linear'
Linear interpolation from nearest neighbours
@item 'pchip'
Piece-wise cubic hermite interpolating polynomial
@item 'cubic'
Cubic interpolation from four nearest neighbours
@item 'spline'
Cubic spline interpolation--smooth first and second derivatives
throughout the curve
@end table

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

If @var{extrap} is the string 'extrap', then extrapolate values beyond
the endpoints.  If @var{extrap} is a number, replace values beyond the
endpoints with that number.  If @var{extrap} is missing, assume NA.

If the string argument 'pp' is specified, then @var{xi} should not be
supplied and @code{interp1} returns the piece-wise polynomial that
can later be used with @code{ppval} to evaluate the interpolation.
There is an equivalence, such that @code{ppval (interp1 (@var{x},
@var{y}, @var{method}, 'pp'), @var{xi}) == interp1 (@var{x}, @var{y},
@var{xi}, @var{method}, 'extrap')}.

An example of the use of @code{interp1} is

@example
@group
   xf=[0:0.05:10]; yf = sin(2*pi*xf/5);
   xp=[0:10];      yp = sin(2*pi*xp/5);
   lin=interp1(xp,yp,xf);
   spl=interp1(xp,yp,xf,'spline');
   cub=interp1(xp,yp,xf,'cubic');
   near=interp1(xp,yp,xf,'nearest');
   plot(xf,yf,"r",xf,lin,"g",xf,spl,"b", ...
        xf,cub,"c",xf,near,"m",xp,yp,"r*");
   legend ("original","linear","spline","cubic","nearest")
@end group
@end example

@seealso{interpft}
@end deftypefn
interp2
-*- texinfo -*-
@deftypefn {Function File} {@var{zi}=} interp2 (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi}=} interp2 (@var{Z}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{zi}=} interp2 (@var{Z}, @var{n})
@deftypefnx {Function File} {@var{zi}=} interp2 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{zi}=} interp2 (@dots{}, @var{method}, @var{extrapval})

Two-dimensional interpolation. @var{x}, @var{y} and @var{z} describe a
surface function. If @var{x} and @var{y} are vectors their length
must correspondent to the size of @var{z}. @var{x} and @var{Yy} must be
monotonic. If they are matrices they  must have the @code{meshgrid} 
format. 

@table @code
@item interp2 (@var{x}, @var{y}, @var{Z}, @var{xi}, @var{yi}, @dots{}) 
Returns a matrix corresponding to the points described by the
matrices  @var{XI}, @var{YI}. 

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

@item  interp2 (@var{z}, @var{xi}, @var{yi})
Assumes @code{@var{x} = 1:rows (@var{z})} and @code{@var{y} = 
1:columns (@var{z})}

@item interp2 (@var{z}, @var{n}) 
Interleaves the Matrix @var{z} n-times. If @var{n} is ommited a value
of @code{@var{n} = 1} is assumed.
@end table

The variable @var{method} defines the method to use for the
interpolation. It can take one of the values

@table @asis
@item 'nearest'
Return the nearest neighbor.
@item 'linear'
Linear interpolation from nearest neighbors.
@item 'pchip'
Piece-wise cubic hermite interpolating polynomial (not implemented yet).
@item 'cubic'
Cubic interpolation from four nearest neighbors.
@item 'spline'
Cubic spline interpolation--smooth first and second derivatives
throughout the curve.
@end table

If a scalar value @var{extrapval} is defined as the final value, then
values outside the mesh as set to this value. Note that in this case 
@var{method} must be defined as well. If @var{extrapval} is not
defined then NA is assumed. 

@seealso{interp1}
@end deftypefn
interp3
-*- texinfo -*-
@deftypefn {Function File} {@var{vi} =} interp3 (@var{x}, @var{y},@var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {@var{vi} =} interp3 (@var{v}, @var{xi}, @var{yi}, @var{zi})
@deftypefnx {Function File} {@var{vi} =} interp3 (@var{v}, @var{m})
@deftypefnx {Function File} {@var{vi} =} interp3 (@var{v})
@deftypefnx {Function File} {@var{vi} =} interp3 (@dots{}, @var{method})
@deftypefnx {Function File} {@var{vi} =} interp3 (@dots{}, @var{method}, @var{extrapval})

Perform 3-dimensional interpolation. Each element of then 3-dimensional 
array @var{v} represents a value at a location given by the parameters 
@var{x}, @var{y}, and @var{z}. The parameters @var{x}, @var{x}, and 
@var{z} are either 3-dimensional arrays of the same size as the array 
@var{v} in the 'meshgrid' format or vectors. The parameters @var{xi}, etc 
respect a similar format to @var{x}, etc, and they represent the points 
at which the array @var{vi} is interpolated.

If @var{x}, @var{y}, @var{z} are ommitted, they are assumed to be 
@code{x = 1 : size (@var{v}, 2)}, @code{y = 1 : size (@var{v}, 1)} and
@code{z = 1 : size (@var{v}, 3)}. If @var{m} is specified, then
the interpolation adds a point half way between each of the interplation 
points. This process is performed @var{m} times. If only @var{v} is 
specified, then @var{m} is assumed to be @code{1}.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbour.
@item 'linear'
Linear interpolation from nearest neighbours.
@item 'cubic'
Cubic interpolation from four nearest neighbours (not implemented yet).
@item 'spline'
Cubic spline interpolation--smooth first and second derivatives
throughout the curve.
@end table

The default method is 'linear'.

If @var{extrap} is the string 'extrap', then extrapolate values beyond
the endpoints.  If @var{extrap} is a number, replace values beyond the
endpoints with that number.  If @var{extrap} is missing, assume NA.
@seealso{interp1, interp2, spline, meshgrid}
@end deftypefn
interpft
-*- texinfo -*-
@deftypefn {Function File} {} interpft (@var{x}, @var{n})
@deftypefnx {Function File} {} interpft (@var{x}, @var{n}, @var{dim})

Fourier interpolation. If @var{x} is a vector, then @var{x} is
resampled with @var{n} points. The data in @var{x} is assumed to be
equispaced. If @var{x} is an array, then operate along each column of
the array seperately. If @var{dim} is specified, then interpolate
along the dimension @var{dim}.

@code{interpft} assumes that the interpolated function is periodic,
and so assumption are made about the end points of the inetrpolation.

@seealso{interp1}
@end deftypefn
interpn
-*- texinfo -*-
@deftypefn {Function File} {@var{vi} =} interpn (@var{x1}, @var{x2}, @dots{}, @var{v}, @var{y1}, @var{y2}, @dots{})
@deftypefnx {Function File} {@var{vi} =} interpn (@var{v}, @var{y1}, @var{y2}, @dots{})
@deftypefnx {Function File} {@var{vi} =} interpn (@var{v}, @var{m})
@deftypefnx {Function File} {@var{vi} =} interpn (@var{v})
@deftypefnx {Function File} {@var{vi} =} interpn (@dots{}, @var{method})
@deftypefnx {Function File} {@var{vi} =} interpn (@dots{}, @var{method}, @var{extrapval})

Perform @var{n}-dimensional interpolation, where @var{n} is at least two. 
Each element of then @var{n}-dimensional array @var{v} represents a value 
at a location given by the parameters @var{x1}, @var{x2}, @dots{}, @var{xn}. 
The parameters @var{x1}, @var{x2}, @dots{}, @var{xn} are either 
@var{n}-dimensional arrays of the same size as the array @var{v} in 
the 'ndgrid' format or vectors. The parameters @var{y1}, etc respect a 
similar format to @var{x1}, etc, and they represent the points at which
the array @var{vi} is interpolated.

If @var{x1}, @dots{}, @var{xn} are ommitted, they are assumed to be 
@code{x1 = 1 : size (@var{v}, 1)}, etc. If @var{m} is specified, then
the interpolation adds a point half way between each of the interplation 
points. This process is performed @var{m} times. If only @var{v} is 
specified, then @var{m} is assumed to be @code{1}.

Method is one of:

@table @asis
@item 'nearest'
Return the nearest neighbour.
@item 'linear'
Linear interpolation from nearest neighbours.
@item 'cubic'
Cubic interpolation from four nearest neighbours (not implemented yet).
@item 'spline'
Cubic spline interpolation--smooth first and second derivatives
throughout the curve.
@end table

The default method is 'linear'.

If @var{extrap} is the string 'extrap', then extrapolate values beyond
the endpoints.  If @var{extrap} is a number, replace values beyond the
endpoints with that number.  If @var{extrap} is missing, assume NA.
@seealso{interp1, interp2, spline, ndgrid}
@end deftypefn
is_duplicate_entry
-*- texinfo -*-
@deftypefn {Function File} {} is_duplicate_entry (@var{x})
Return non-zero if any entries in @var{x} are duplicates of one
another.
@end deftypefn
isa
-*- texinfo -*-
@deftypefn {Function File} {} isa (@var{x}, @var{class})
Return true if @var{x} is a value from the class @var{class}.
@end deftypefn
isdefinite
-*- texinfo -*-
@deftypefn {Function File} {} isdefinite (@var{x}, @var{tol})
Return 1 if @var{x} is symmetric positive definite within the
tolerance specified by @var{tol} or 0 if @var{x} is symmetric
positive semidefinite.  Otherwise, return -1.  If @var{tol}
is omitted, use a tolerance equal to 100 times the machine precision.
@seealso{issymmetric}
@end deftypefn
isdir
-*- texinfo -*-
@deftypefn {Function File} {} isdir (@var{f})
Return true if @var{f} is a directory.
@end deftypefn
isequal
-*- texinfo -*-
@deftypefn {Function File} {} isequal (@var{x1}, @var{x2}, @dots{})
Return true if all of @var{x1}, @var{x2}, @dots{} are equal.
@seealso{isequalwithequalnans}
@end deftypefn
isequalwithequalnans
-*- texinfo -*-
@deftypefn {Function File} {} isequalwithequalnans (@var{x1}, @var{x2}, @dots{})
Assuming NaN == NaN, return true if all of @var{x1}, @var{x2}, @dots{}
are equal.
@seealso{isequal}
@end deftypefn
isscalar
-*- texinfo -*-
@deftypefn {Function File} {} isscalar (@var{a})
Return 1 if @var{a} is a scalar.  Otherwise, return 0.
@seealso{size, rows, columns, length, isscalar, ismatrix}
@end deftypefn
issquare
-*- texinfo -*-
@deftypefn {Function File} {} issquare (@var{x})
If @var{x} is a square matrix, then return the dimension of @var{x}.
Otherwise, return 0.
@seealso{size, rows, columns, length, ismatrix, isscalar, isvector}
@end deftypefn
issymmetric
-*- texinfo -*-
@deftypefn {Function File} {} issymmetric (@var{x}, @var{tol})
If @var{x} is symmetric within the tolerance specified by @var{tol},
then return the dimension of @var{x}.  Otherwise, return 0.  If
@var{tol} is omitted, use a tolerance equal to the machine precision.
@seealso{size, rows, columns, length, ismatrix, isscalar,
issquare, isvector}
@end deftypefn
isvector
-*- texinfo -*-
@deftypefn {Function File} {} isvector (@var{a})
Return 1 if @var{a} is a vector.  Otherwise, return 0.
@seealso{size, rows, columns, length, isscalar, ismatrix}
@end deftypefn
logical
-*- texinfo -*-
@deftypefn {Function File} {} logical (@var{arg})
Convert @var{arg} to a logical value.  For example,

@example
logical ([-1, 0, 1])
@end example

@noindent
is equivalent to

@example
[-1, 0, 1] != 0
@end example
@end deftypefn
logspace
-*- texinfo -*-
@deftypefn {Function File} {} logspace (@var{base}, @var{limit}, @var{n})
Similar to @code{linspace} except that the values are logarithmically
spaced from
@iftex
@tex
$10^{base}$ to $10^{limit}$.
@end tex
@end iftex
@ifinfo
10^base to 10^limit.
@end ifinfo

If @var{limit} is equal to
@iftex
@tex
$\pi$,
@end tex
@end iftex
@ifinfo
pi,
@end ifinfo
the points are between
@iftex
@tex
$10^{base}$ and $\pi$,
@end tex
@end iftex
@ifinfo
10^base and pi,
@end ifinfo
@emph{not}
@iftex
@tex
$10^{base}$ and $10^{\pi}$,
@end tex
@end iftex
@ifinfo
10^base and 10^pi,
@end ifinfo
in order to  be compatible with the corresponding @sc{Matlab}
function.

Also for compatibility, return the second argument if fewer than two
values are requested.
@seealso{linspace}
@end deftypefn
lookup
-*- texinfo -*-
@deftypefn {Function File} {@var{idx} =} lookup (@var{table}, @var{y})
Lookup values in a sorted table.  Usually used as a prelude to
interpolation.

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

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

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

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

@noindent
This expression puts values before the table into the first
interval, and values after the table into the last interval.
@end deftypefn
mod
-*- texinfo -*-
@deftypefn {Mapping Function} {} mod (@var{x}, @var{y})
Compute modulo function, using

@example
x - y .* floor (x ./ y)
@end example

Note that this handles negative numbers correctly:
@code{mod (-1, 3)} is 2, not -1 as @code{rem (-1, 3)} returns.
Also, @code{mod (@var{x}, 0)} returns @var{x}.

An error message is printed if the dimensions of the arguments do not
agree, or if either of the arguments is complex.
@seealso{rem, round}
@end deftypefn
nargchk
-*- texinfo -*-
@deftypefn {Function File} {} nargchk (@var{nargin_min}, @var{nargin_max}, @var{n})
If @var{n} is in the range @var{nargin_min} through @var{nargin_max}
inclusive, return the empty matrix.  Otherwise, return a message
indicating whether @var{n} is too large or too small.

This is useful for checking to see that the number of arguments supplied
to a function is within an acceptable range.
@end deftypefn
nextpow2
-*- texinfo -*-
@deftypefn {Function File} {} nextpow2 (@var{x})
If @var{x} is a scalar, returns the first integer @var{n} such that
@iftex
@tex
 $2^n \ge |x|$.
@end tex
@end iftex
@ifinfo
 2^n >= abs (x).
@end ifinfo

If @var{x} is a vector, return @code{nextpow2 (length (@var{x}))}.
@seealso{pow2}
@end deftypefn
perror
-*- texinfo -*-
@deftypefn {Function File} {} perror (@var{name}, @var{num})
Print the error message for function @var{name} corresponding to the
error number @var{num}.  This function is intended to be used to print
useful error messages for those functions that return numeric error
codes.
@seealso{strerror}
@end deftypefn
nthroot
-*- texinfo -*-
@deftypefn {Function File} {} nthroot (@var{x}, @var{n})

Compute the nth root of @var{x}, returning real results for real 
components of @var{x}. For example

@example
@group
nthroot (-1, 3)
@result{} -1
(-1) ^ (1 / 3)
@result{} 0.50000 - 0.86603i
@end group
@end example

@end deftypefn
num2str
-*- texinfo -*-
@deftypefn {Function File} {} num2str (@var{n})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number to a string.  This function is not very flexible.
For better control over the results, use @code{sprintf}
(@pxref{Formatted Output}).
@seealso{sprintf, int2str}
@end deftypefn
pol2cart
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{y}] =} pol2cart (@var{theta}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} pol2cart (@var{theta}, @var{r}, @var{z})
Transform polar or cylindrical to cartesian coordinates.
@var{theta}, @var{r} (and @var{z}) must be of same shape.
@var{theta} describes the angle relative to the x - axis.
@var{r} is the distance to the z - axis (0, 0, z).
@seealso{cart2pol, cart2sph, sph2cart}
@end deftypefn
polyarea
-*- texinfo -*-
@deftypefn {Function File} {} polyarea (@var{x}, @var{y})
@deftypefnx {Function File} {} polyarea (@var{x}, @var{y}, @var{dim})

Determines area of a polygon by triangle method. The variables
@var{x} and @var{y} define the vertex pairs, and must therefore have
the same shape. Then might be either vectors or arrays. If they are
arrays then the columns of @var{x} and @var{y} are treated seperately
and an area returned for each.

If the optional @var{dim} argument is given, then @code{polyarea}
works along this dimension of the arrays @var{x} and @var{y}.

@end deftypefn
postpad
-*- texinfo -*-
@deftypefn {Function File} {} postpad (@var{x}, @var{l}, @var{c})
See prepad.
@end deftypefn
prepad
-*- texinfo -*-
@deftypefn {Function File} {} prepad (@var{x}, @var{l}, @var{c})
@deftypefnx {Function File} {} postpad (@var{x}, @var{l}, @var{c})
@deftypefnx {Function File} {} postpad (@var{x}, @var{l}, @var{c}, @var{dim})

Prepends (appends) the scalar value @var{c} to the vector @var{x}
until it is of length @var{l}.  If the third argument is not
supplied, a value of 0 is used.

If @code{length (@var{x}) > @var{l}}, elements from the beginning (end) of
@var{x} are removed until a vector of length @var{l} is obtained.

If @var{x} is a matrix, elements are prepended or removed from each row.

If the optional @var{dim} argument is given, then operate along this
dimension.
@end deftypefn
quadl
-*- texinfo -*-
@deftypefn {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace}, @var{p1}, @var{p2}, @dots{})

Numerically evaluate integral using adaptive Lobatto rule.
@code{quadl (@var{f}, @var{a}, @var{b})} approximates the integral of
@code{@var{f}(@var{x})} to machine precision. @var{f} is either a
function handle, inline function or string containing the name of
the function to evaluate. The function @var{f} must return a vector
of output values if given a vector of input values.

If defined, @var{tol} defines the relative tolerance to which to
which to integrate @code{@var{f}(@var{x})}. While if @var{trace} is
defined, displays the left end point of the current interval, the 
interval length, and the partial integral.

Additional arguments @var{p1}, etc, are passed directly to @var{f}.
To use default values for @var{tol} and @var{trace}, one may pass
empty matrices.

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

@end deftypefn
randperm
-*- texinfo -*-
@deftypefn {Function File} {} randperm (@var{n})
Return a row vector containing a random permutation of the
integers from 1 to @var{n}.
@end deftypefn
rat
-*- texinfo -*-
@deftypefn {Function File} {@var{s} =} rat (@var{x}, @var{tol})
@deftypefnx {Function File} {[@var{n}, @var{d}] =} rat (@var{x}, @var{tol})

Find a rational approximation to @var{x} within tolerance defined
by @var{tol} using a continued fraction expansion. E.g,

@example
   rat(pi) = 3 + 1/(7 + 1/16) = 355/113
   rat(e) = 3 + 1/(-4 + 1/(2 + 1/(5 + 1/(-2 + 1/(-7))))) = 1457/536
@end example

Called with two arguments returns the numerator and deniminator seperately
as two matrices.
@end deftypefn
@seealso{rats}
rem
-*- texinfo -*-
@deftypefn {Mapping Function} {} rem (@var{x}, @var{y})
Return the remainder of @code{@var{x} / @var{y}}, computed using the
expression

@example
x - y .* fix (x ./ y)
@end example

An error message is printed if the dimensions of the arguments do not
agree, or if either of the arguments is complex.
@seealso{mod, round}
@end deftypefn
repmat
-*- texinfo -*-
@deftypefn {Function File} {} repmat (@var{A}, @var{m}, @var{n})
@deftypefnx {Function File} {} repmat (@var{A}, [@var{m} @var{n}])
Form a block matrix of size @var{m} by @var{n}, with a copy of matrix
@var{A} as each element.  If @var{n} is not specified, form an 
@var{m} by @var{m} block matrix.
@end deftypefn
rot90
-*- texinfo -*-
@deftypefn {Function File} {} rot90 (@var{x}, @var{n})
Return a copy of @var{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 @var{n} rotate the matrix in a clockwise direction.
For example,

@example
@group
rot90 ([1, 2; 3, 4], -1)
@result{}  3  1
         4  2
@end group
@end example

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

@example
@group
rot90 ([1, 2; 3, 4], -1)
rot90 ([1, 2; 3, 4], 3)
rot90 ([1, 2; 3, 4], 7)
@end group
@end example

Due to the difficulty of defining an axis about which to rotate the 
matrix @code{rot90} only work with 2-D arrays.  To rotate N-d arrays
use @code{rotdim} instead.
@seealso{rotdim, flipud, fliplr, flipdim}
@end deftypefn
rotdim
-*- texinfo -*-
@deftypefn {Function File} {} rotdim (@var{x}, @var{n}, @var{plane})
Return a copy of @var{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).
The third argument is also optional and defines the plane of the
rotation. As such @var{plane} is a two element vector containing two
different valid dimensions of the matrix. If @var{plane} is not given
Then the first two non-singleton dimensions are used.

Negative values of @var{n} rotate the matrix in a clockwise direction.
For example,

@example
@group
rotdim ([1, 2; 3, 4], -1, [1, 2])
@result{}  3  1
         4  2
@end group
@end example

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

@example
@group
rotdim ([1, 2; 3, 4], -1, [1, 2])
rotdim ([1, 2; 3, 4], 3, [1, 2])
rotdim ([1, 2; 3, 4], 7, [1, 2])
@end group
@end example
@seealso{rot90, flipud, fliplr, flipdim}
@end deftypefn
shift
-*- texinfo -*-
@deftypefn {Function File} {} shift (@var{x}, @var{b})
@deftypefnx {Function File} {} shift (@var{x}, @var{b}, @var{dim})
If @var{x} is a vector, perform a circular shift of length @var{b} of
the elements of @var{x}.

If @var{x} is a matrix, do the same for each column of @var{x}.
If the optional @var{dim} argument is given, operate along this 
dimension
@end deftypefn
shiftdim
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} shiftdim (@var{x}, @var{n})
@deftypefnx {Function File} {[@var{y}, @var{ns}] =} shiftdim (@var{x})
Shifts the dimension of @var{x} by @var{n}, where @var{n} must be
an integer scalar. When @var{n} is positive, the dimensions of
@var{x} are shifted to the left, with the leading dimensions
circulated to the end. If @var{n} is negative, then the dimensions
of @var{x} are shifted to the right, with @var{n} leading singleton
dimensions added.

Called with a single argument, @code{shiftdim}, removes the leading
singleton dimensions, returning the number of dimensions removed
in the second output argument @var{ns}.

For example 

@example
@group
x = ones (1, 2, 3);
size (shiftdim (x, -1))
@result{} [1, 1, 2, 3]
size (shiftdim (x, 1))
@result{} [2, 3]
[b, ns] = shiftdim (x);
@result{} b =  [1, 1, 1; 1, 1, 1]
@result{} ns = 1
@end group
@end example
@seealso {reshape, permute, ipermute, circshift, squeeze}
@end deftypefn
sortrows
-*- texinfo -*-
@deftypefn {Function File} {} sortrows (@var{a}, @var{c})
Sort the rows of the matrix @var{a} according to the order of the
columns specified in @var{c}.  If @var{c} is omitted, a
lexicographical sort is used.
@end deftypefn
sph2cart
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{y}, @var{z}] =} sph2cart (@var{theta}, @var{phi}, @var{r})
Transform spherical to cartesian coordinates.
@var{x}, @var{y} and @var{z} must be of same shape.
@var{theta} describes the angle relative to the x-axis.
@var{phi} is the angle relative to the xy-plane.
@var{r} is the distance to the origin (0, 0, 0).
@seealso{pol2cart, cart2pol, cart2sph}
@end deftypefn
strerror
-*- texinfo -*-
@deftypefn {Function File} {} strerror (@var{name}, @var{num})
Return the text of an error message for function @var{name}
corresponding to the error number @var{num}.  This function is intended
to be used to print useful error messages for those functions that
return numeric error codes.
@end deftypefn
structfun
-*- texinfo -*-
@deftypefn {Function File} {} structfun (@var{func}, @var{s})
@deftypefnx {Function File} {[@var{a}, @var{b}] =} structfun (@dots{})
@deftypefnx {Function File} {} structfun (@dots{}, 'ErrorHandler', @var{errfunc})
@deftypefnx {Function File} {} structfun (@dots{}, 'UniformOutput', @var{val})

Evaluate the function named @var{name} on the fields of the structure
@var{s}. The fields of @var{s} are passed the the function @var{func}
individually.

@code{structfun} accepts an arbitrary function @var{func} in the form of 
an inline function, function handle, or the name of a function (in a 
character string). In the case of a character string argument, the 
function must accept a single argument named @var{x}, and it must return 
a string value. If the function returns more than one argument, they are
returned as separate output variables.

If the param 'UniformOutput' is set to true (the default), then the function
must return either a single element which will be concatenated into the
return value. If 'UniformOutput is false, the outputs placed in a structure
with the same fieldnames as the input structure.

@example
@group
s.name1 = "John Smith"; 
s.name2 = "Jill Jones"; 
structfun (@{x@} regexp (x, '(\w+)$', 'matches')@{1@}, s, 
           'UniformOutput', false)
@end group
@end example

Given the parameter 'ErrorHandler', then @var{errfunc} defines a function to
call in case @var{func} generates an error. The form of the function is

@example
function [@dots{}] = errfunc (@var{se}, @dots{})
@end example

where there is an additional input argument to @var{errfunc} relative to
@var{func}, given by @var{se}. This is a structure with the elements
'identifier', 'message' and 'index', giving respectively the error
identifier, the error message, and the index into the input arguments
of the element that caused the error.
@seealso{cellfun, arrayfun}
@end deftypefn
sub2ind
-*- texinfo -*-
@deftypefn {Function File} {@var{ind} =} sub2ind (@var{dims}, @var{i}, @var{j})
@deftypefnx {Function File} {@var{ind} =} sub2ind (@var{dims}, @var{s1}, @var{s2}, @dots{}, @var{sN})
Convert subscripts into a linear index.

The following example shows how to convert the two-dimensional
index @code{(2,3)} of a 3-by-3 matrix to a linear index.

@example
linear_index = sub2ind ([3, 3], 2, 3)
@result{} 8
@end example
@seealso{ind2sub}
@end deftypefn
trapz
-*- texinfo -*-
@deftypefn {Function File} {@var{z} =} trapz (@var{y})
@deftypefnx {Function File} {@var{z} =} trapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} trapz (@dots{}, @var{dim})

Numerical intergration using trapezodial method. @code{trapz
(@var{y})} computes the integral of the @var{y} along the first
non singleton dimension. If the argument @var{x} is omitted a 
equally spaced vector is assumed. @code{trapz (@var{x}, @var{y})} 
evaluates the integral with respect to @var{x}.
 
@seealso{cumtrapz}
@end deftypefn
tril
-*- texinfo -*-
@deftypefn {Function File} {} tril (@var{a}, @var{k})
@deftypefnx {Function File} {} triu (@var{a}, @var{k})
Return a new matrix formed by extracting the lower (@code{tril})
or upper (@code{triu}) triangular part of the matrix @var{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 @var{k} is zero, so that @code{triu} and
@code{tril} normally include the main diagonal as part of the result
matrix.

If the value of @var{k} is negative, additional elements above (for
@code{tril}) or below (for @code{triu}) the main diagonal are also
selected.

The absolute value of @var{k} must not be greater than the number of
sub- or super-diagonals.

For example,

@example
@group
tril (ones (3), -1)
@result{}  0  0  0
         1  0  0
         1  1  0
@end group
@end example

@noindent
and

@example
@group
tril (ones (3), 1)
@result{}  1  1  0
         1  1  1
         1  1  1
@end group
@end example
@seealso{triu, diag}
@end deftypefn
triu
-*- texinfo -*-
@deftypefn {Function File} {} triu (@var{a}, @var{k})
See tril.
@end deftypefn
convhull
-*- texinfo -*-
@deftypefn {Function File} {@var{H} =} convhull (@var{x}, @var{y})
@deftypefnx {Function File} {@var{H} =} convhull (@var{x}, @var{y}, @var{opt})
Returns the index vector to the points of the enclosing convex hull.  The
data points are defined by the x and y vectors.

A third optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the 
Qhull library for details.

@seealso{delaunay, convhulln}
@end deftypefn
delaunay
-*- texinfo -*-
@deftypefn {Function File} {@var{tri}=} delaunay (@var{x}, @var{y})
@deftypefnx {Function File} {@var{tri}=} delaunay (@var{x}, @var{y}, @var{opt})
The return matrix of size [n, 3] contains a set triangles which are
described by the indices to the data point x and y vector.
The triangulation satisfies the Delaunay circumcircle criterion.
No other data point is in the circumcircle of the defining triangle.

A third optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the 
Qhull library for details.

@example
@group
x = rand (1, 10);
y = rand (size (x));
T = delaunay (x, y);
X = [x(T(:,1)); x(T(:,2)); x(T(:,3)); x(T(:,1))];
Y = [y(T(:,1)); y(T(:,2)); y(T(:,3)); y(T(:,1))];
axis ([0,1,0,1]);
plot (X, Y, "b", x, y, "r*");
@end group
@end example
@seealso{voronoi, delaunay3, delaunayn}
@end deftypefn
delaunay3
-*- texinfo -*-
@deftypefn {Function File} {@var{T} =} delaunay3 (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{T} =} delaunay3 (@var{x}, @var{y}, @var{z}, @var{opt})
A matrix of size [n, 4] is returned. Each row contains a 
set of tetrahedron which are
described by the indices to the data point vectors (x,y,z).

A fourth optional argument, which must be a string or cell array of strings,
contains extra options passed to the underlying qhull command.  See the 
documentation for the Qhull library for details.
@seealso{delaunay,delaunayn}
@end deftypefn
delaunayn
-*- texinfo -*-
@deftypefn {Function File} {@var{T} =} delaunayn (@var{P})
@deftypefnx {Function File} {@var{T} =} delaunayn (@var{P}, @var{opt})
Form the Delaunay triangulation for a set of points.
The Delaunay triangulation is a tessellation of the convex hull of the
points such that no n-sphere defined by the n-triangles contains
any other points from the set.
The input matrix @var{P} of size @code{[n, dim]} contains @var{n}
points in a space of dimension dim. The return matrix @var{T} has the
size @code{[m, dim+1]}.  It contains for each row a set of indices to
the points, which describes a simplex of dimension dim.  For example,
a 2d simplex is a triangle and 3d simplex is a tetrahedron.

Extra options for the underlying Qhull command can be specified by the
second argument. This argument is a cell array of strings. The default
options depend on the dimension of the input: 

@itemize 
@item  2D and 3D: @var{opt} = @code{@{"Qt", "Qbb", "Qc"@}}
@item  4D and higher: @var{opt} = @code{@{"Qt", "Qbb", "Qc", "Qz"@}} 
@end itemize

If @var{opt} is [], then the default arguments are used. If @var{opt}
is @code{@{"@w{}"@}}, then none of the default arguments are used by Qhull. 
See the Qhull documentation for the available options. 

All options can also be specified as single string, for example
@code{"Qt Qbb Qc Qz"}.

@end deftypefn
dsearch
-*- texinfo -*-
@deftypefn {Function File} {@var{idx} =} dsearch (@var{x}, @var{y}, @var{tri}, @var{xi}, @var{yi})
@deftypefnx {Function File} {@var{idx} =} dsearch (@var{x}, @var{y}, @var{tri}, @var{xi}, @var{yi}, @var{s})
Returns the index @var{idx} or the closest point in @code{@var{x}, @var{y})}
to the elements @code{[@var{xi}(:), @var{yi}(:)]}. The variable @var{s} is
accepted but ignored for compatibility.
@seealso{dsearchn, tsearch}
@end deftypefn
dsearchn
-*- texinfo -*-
@deftypefn {Function File} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi})
@deftypefnx {Function File} {@var{idx} =} dsearchn (@var{x}, @var{tri}, @var{xi}, @var{outval})
@deftypefnx {Function File} {@var{idx} =} dsearchn (@var{x}, @var{xi})
@deftypefnx {Function File} {[@var{idx}, @var{d}] =} dsearchn (@dots{})
Returns the index @var{idx} or the closest point in @var{x} to the elements
@var{xi}. If @var{outval} is supplied, then the values of @var{xi} that are
not contained within one of the simplicies @var{tri} are set to 
@var{outval}. Generally, @var{tri} is returned from @code{delaunayn 
(@var{x})}.
@seealso{dsearch, tsearch}
@end deftypefn
griddata
-*- texinfo -*-
@deftypefn {Function File} {@var{zi} =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{method})
@deftypefnx {Function File} {[@var{xi}, @var{yi}, @var{zi}] =} griddata (@var{x}, @var{y}, @var{z}, @var{xi}, @var{yi}, @var{method})

Generate a regular mesh from irregular data using interpolation.
The function is defined by @code{@var{z} = f (@var{x}, @var{y})}.
The interpolation points are all @code{(@var{xi}, @var{yi})}.  If
@var{xi}, @var{yi} are vectors then they are made into a 2D mesh.

The interpolation method can be @code{"nearest"}, @code{"cubic"} or
@code{"linear"}.  If method is omitted it defaults to @code{"linear"}.
@seealso{delaunay}
@end deftypefn
griddata3
-*- texinfo -*-
@deftypefn {Function File} {@var{vi} =} griddata3 (@var{x}, @var{y}, @var{z}, @var{v} @var{xi}, @var{yi}, @var{zi}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.
The function is defined by @code{@var{y} = f (@var{x},@var{y},@var{z})}.
The interpolation points are all @var{xi}.  

The interpolation method can be @code{"nearest"} or @code{"linear"}.
If method is omitted it defaults to @code{"linear"}.
@seealso{griddata, delaunayn}
@end deftypefn
griddatan
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} =} griddatan (@var{x}, @var{y}, @var{xi}, @var{method}, @var{options})

Generate a regular mesh from irregular data using interpolation.
The function is defined by @code{@var{y} = f (@var{x})}.
The interpolation points are all @var{xi}.  

The interpolation method can be @code{"nearest"} or @code{"linear"}.
If method is omitted it defaults to @code{"linear"}.
@seealso{griddata, delaunayn}
@end deftypefn
inpolygon
-*- texinfo -*-
@deftypefn {Function File} {[@var{in}, @var{on}] = } inpolygon (@var{x}, @var{y}, @var{xv}, @var{xy})

For a polygon defined by @code{(@var{xv}, @var{yv})} points, determine
if the points @code{(@var{x}, @var{y})} are inside or outside the polygon.
The variables @var{x}, @var{y}, must have the same dimension. The optional
output @var{on} gives the points that are on the polygon.

@end deftypefn
trimesh
-*- texinfo -*-
@deftypefn {Function File} {} trimesh (@var{tri}, @var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{h} = } trimesh (@dots{})
Plot a triangular mesh in 3D. The variable @var{tri} is the triangular
meshing of the points @code{(@var{x}, @var{y})} which is returned 
from @code{delaunay}. The variable @var{z} is value at the point 
@code{(@var{x}, @var{y})}. The output argument @var{h} is the graphic 
handle to the plot.
@seealso{triplot, delaunay3}
@end deftypefn
triplot
-*- texinfo -*-
@deftypefn {Function File} {} triplot (@var{tri}, @var{x}, @var{y})
@deftypefnx {Function File} {} triplot (@var{tri}, @var{x}, @var{y}, @var{linespec})
@deftypefnx {Function File} {@var{h} = } triplot (@dots{})
Plot a triangular mesh in 2D. The variable @var{tri} is the triangular
meshing of the points @code{(@var{x}, @var{y})} which is returned from
@code{delaunay}. If given, the @var{linespec} determines the properties
to use for the lines. The output argument @var{h} is the graphic handle
to the plot.
@seealso{plot, trimesh, delaunay}
@end deftypefn
tsearchn
-*- texinfo -*-
@deftypefn {Function File} {[@var{idx}, @var{p}] =} tsearchn (@var{x}, @var{t}, @var{xi})
Searches for the enclosing Delaunay convex hull. For @code{@var{t} =
delaunayn (@var{x})}, finds the index in @var{t} containing the
points @var{xi}. For points outside the convex hull, @var{idx} is NaN.
If requested @code{tsearchn} also returns the barycentric coorinates @var{p}
of the enclosing triangles.
@seealso{delaunay, delaunayn}
@end deftypefn
voronoi
-*- texinfo -*-
@deftypefn {Function File} {} voronoi (@var{x}, @var{y})
@deftypefnx {Function File} {} voronoi (@var{x}, @var{y}, "plotstyle")
@deftypefnx {Function File} {} voronoi (@var{x}, @var{y}, "plotstyle", @var{options})
@deftypefnx {Function File} {[@var{vx}, @var{vy}] =} voronoi (@dots{})
plots voronoi diagram of points @code{(@var{x}, @var{y})}.
The voronoi facets with points at infinity are not drawn.
[@var{vx}, @var{vy}] = voronoi(...) returns the vertices instead plotting the
diagram. plot (@var{vx}, @var{vy}) shows the voronoi diagram.

A fourth optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the
Qhull library for details.

@example
@group
  x = rand (10, 1);
  y = rand (size (x));
  h = convhull (x, y);
  [vx, vy] = voronoi (x, y);
  plot (vx, vy, "-b", x, y, "o", x(h), y(h), "-g")
  legend ("", "points", "hull");
@end group
@end example

@seealso{voronoin, delaunay, convhull}
@end deftypefn
voronoin
-*- texinfo -*-
@deftypefn {Function File} {[@var{C}, @var{F}] =} voronoin (@var{pts})
@deftypefnx {Function File} {[@var{C}, @var{F}] =} voronoin (@var{pts}, @var{options})
computes n- dimensinal voronoi facets.  The input matrix @var{pts}
of size [n, dim] contains n points of dimension dim.
@var{C} contains the points of the voronoi facets. The list @var{F}
contains for each facet the indices of the voronoi points.

A second optional argument, which must be a string, contains extra options
passed to the underlying qhull command.  See the documentation for the
Qhull library for details.
@seealso{voronoin, delaunay, convhull}
@end deftypefn
__img__
-*- texinfo -*-
@deftypefn {Function File} {} __img__ (@var{img})
@deftypefnx {Function File} {} __img__ (@var{x}, @var{y}, @var{img})
Generic image creation.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}. If you're not using gnuplot 4.2 or later, these
variables are ignored.
@end deftypefn
__img_via_file__
-*- texinfo -*-
@deftypefn {Function File} {} __img_via_file__(@var{x}, @var{y}, @var{im}, @var{zoom}, @var{command})
Display an image by saving it to a file in PPM format and launching
@var{command}.

The @var{command} must be a format string containing @code{%s} and
possibly @code{%f}.  The @code{%s} will be replaced by the filename
of the image, and the @code{%f} will be replaced by @var{zoom}. The
@var{x} and @var{y} arguments are ignored.
@seealso{image, imshow, __img__, __img_via_file__, image_viewer}
@end deftypefn
autumn
-*- texinfo -*-
@deftypefn {Function File} {} autumn (@var{n})
Create color colormap. This colormap is red through orange to yellow.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
bone
-*- texinfo -*-
@deftypefn {Function File} {} bone (@var{n})
Create color colormap. This colormap is a gray colormap with a light 
blue tone. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
brighten
-*- texinfo -*-
@deftypefn {Function File} {@var{map_out} =} brighten (@var{map}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{h}, @var{beta})
@deftypefnx {Function File} {@var{map_out} =} brighten (@var{beta})
Darkens or brightens the given colormap. If the @var{map} argument 
is omitted, the function is applied to the current colormap. The first
argument can also be a valid graphics handle @var{h}, in which case 
@code{brighten} is applied to the colormap associated with this handle.

Should the resulting colormap @var{map_out} not be assigned, it will be
written to the current colormap.

The argument @var{beta} should be a scalar between -1 and 1,
where a negative value darkens and a positive value brightens
the colormap.
@seealso{colormap}
@end deftypefn
colormap
-*- texinfo -*-
@deftypefn {Function File} {} colormap (@var{map})
@deftypefnx {Function File} {} colormap ("default")
Set the current colormap.

@code{colormap (@var{map})} sets the current colormap to @var{map}.  The
color map should be an @var{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.

@code{colormap ("default")} restores the default colormap (the
@code{jet} map with 64 entries).  The default colormap is returned.

With no arguments, @code{colormap} returns the current color map.
@seealso{jet}
@end deftypefn
cool
-*- texinfo -*-
@deftypefn {Function File} {} cool (@var{n})
Create color colormap. The colormap is cyan to magenta. The argument 
@var{n} should be a scalar.  If it is omitted, the length of the current
colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
copper
-*- texinfo -*-
@deftypefn {Function File} {} copper (@var{n})
Create color colormap. This colormap is black to a light copper tone.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
flag
-*- texinfo -*-
@deftypefn {Function File} {} flag (@var{n})
Create color colormap. This colormap cycles through red, white, blue 
and black. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
gray
-*- texinfo -*-
@deftypefn {Function File} {} gray (@var{n})
Return a gray colormap with @var{n} entries corresponding to values from
0 to @var{n}-1.  The argument @var{n} should be a scalar.  If it is
omitted, the length of the current colormap or 64 is assumed.
@end deftypefn
gray2ind
-*- texinfo -*-
@deftypefn {Function File} {[@var{img}, @var{map}] =} gray2ind (@var{})
Convert a gray scale intensity image to an Octave indexed image.
@end deftypefn
hot
-*- texinfo -*-
@deftypefn {Function File} {} hot (@var{n})
Create color colormap. This colormap is black through dark red, red, 
orange, yellow to white. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
hsv
-*- texinfo -*-
@deftypefn {Function File} {} hsv (@var{n})
Create color colormap. This colormap is red through yellow, green, cyan,
blue, magenta to red. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
hsv2rgb
-*- texinfo -*-
@deftypefn {Function File} {@var{rgb_map} =} hsv2rgb (@var{hsv_map})
Transform a colormap from the hsv space to the rgb space. 
@seealso{rgb2hsv}
@end deftypefn
image
-*- texinfo -*-
@deftypefn {Function File} {} image (@var{img})
@deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{img})
Display a matrix as a color image.  The elements of @var{x} are indices
into the current colormap and should have values between 1 and the
length of the colormap.

It first tries to use @code{gnuplot}, then @code{display} from 
@code{ImageMagick}, then @code{xv}, and then @code{xloadimage}.
The actual program used can be changed using the @code{image_viewer}
function.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}. If you're not using gnuplot 4.2 or later, these
variables are ignored.
@seealso{imshow, imagesc, colormap, image_viewer}
@end deftypefn
image_viewer
-*- texinfo -*-
@deftypefn {Function File} {[@var{fcn}, @var{default_zoom}] =} image_viewer (@var{fcn}, @var{default_zoom})
Change the program or function used for viewing images and return the
previous values.

When the @code{image} or @code{imshow} function is called it will
launch an external program to display the image.  The default behaviour
is to use gnuplot if the installed version supports image viewing,
and otherwise try the programs @code{display}, @code{xv}, and
@code{xloadimage}.  Using this function it is possible to change that
behaviour.

When called with one input argument images will be displayed by saving
the image to a file and the system command @var{command} will called
to view the image.  The @var{command} must be a string containing
@code{%s} and possibly @code{%f}. The @code{%s} will be replaced by
the filename of the image, and the @code{%f} will (if present) be
replaced by the zoom factor given to the @code{image} function.
For example,
@example
image_viewer ("eog %s");
@end example
changes the image viewer to the @code{eog} program.

With two input arguments, images will be displayed by calling
the function @var{function_handle}.  For example,
@example
image_viewer (data, @@my_image_viewer);
@end example
sets the image viewer function to @code{my_image_viewer}.  The image
viewer function is called with
@example
my_image_viewer (@var{x}, @var{y}, @var{im}, @var{zoom}, @var{data})
@end example
where @var{x} and @var{y} are the axis of the image, @var{im} is the image
variable, and @var{data} is extra user-supplied data to be passed to
the viewer function.

With three input arguments it is possible to change the zooming.
Some programs (like @code{xloadimage}) require the zoom factor to be
between 0 and 100, and not 0 and 1 like Octave assumes. This is
solved by setting the third argument to 100.

@seealso{image, imshow, __img_gnuplot__, __img_via_file__}
@end deftypefn
imagesc
-*- texinfo -*-
@deftypefn {Function File} {} imagesc (@var{A})
@deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{A})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{limits})
@deftypefnx {Function File} { @var{B} = } imagesc (@dots{})
Display a scaled version of the matrix @var{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 @var{limits} = [@var{lo}, @var{hi}] are
given, then that range maps into the full range of the colormap rather 
than the minimum and maximum values of @var{A}.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{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 @var{A}.
@seealso{image, imshow}
@end deftypefn
imshow
-*- texinfo -*-
@deftypefn {Function File} {} imshow (@var{im})
@deftypefnx {Function File} {} imshow (@var{im}, @var{limits})
@deftypefnx {Function File} {} imshow (@var{im}, @var{map})
@deftypefnx {Function File} {} imshow (@var{R}, @var{G}, @var{B}, @dots{})
@deftypefnx {Function File} {} imshow (@var{filename})
@deftypefnx {Function File} {} imshow (@dots{}, @var{string_param1}, @var{value1}, @dots{})
Display the image @var{im}, where @var{im} can be a 2-dimensional
(gray-scale image) or a 3-dimensional (RGB image) matrix. If three matrices
of the same size are given as arguments, they will be concatenated into
a 3-dimensional (RGB image) matrix.

If @var{limits} is a 2-element vector @code{[@var{low}, @var{high}]},
the image is shown using a display range between @var{low} and
@var{high}.  If an empty matrix is passed for @var{limits}, the
display range is computed as the range between the minimal and the
maximal value in the image.

If @var{map} is a valid color map, the image will be shown as an indexed
image using the supplied color map.

If a file name is given instead of an image, the file will be read and
shown.

If given, the parameter @var{string_param1} has value
@var{value1}. @var{string_param1} can be any of the following:
@table @samp
@item "displayrange"
@var{value1} is the display range as described above.
@end table
@seealso{image, imagesc, colormap, gray2ind, rgb2ind}
@end deftypefn
ind2gray
-*- texinfo -*-
@deftypefn {Function File} {} ind2gray (@var{x}, @var{map})
Convert an Octave indexed image to a gray scale intensity image.
If @var{map} is omitted, the current colormap is used to determine the
intensities.
@seealso{gray2ind, rgb2ntsc, image, colormap}
@end deftypefn
ind2rgb
-*- texinfo -*-
@deftypefn {Function File} {@var{rgb} =} ind2rgb (@var{x}, @var{map})
@deftypefnx {Function File} {[@var{r}, @var{g}, @var{b}] =} ind2rgb (@var{x}, @var{map})
Convert an indexed image to red, green, and blue color components.
If the colormap doesn't contain enough colors, pad it with the
last color in the map.
If @var{map} is omitted, the current colormap is used for the conversion.
@seealso{rgb2ind, image, imshow, ind2gray, gray2ind}
@end deftypefn
jet
-*- texinfo -*-
@deftypefn {Function File} {} jet (@var{n})
Create color colormap. This colormap is dark blue through blue, cyan, 
green, yellow, red to dark red. The argument @var{n} should be a scalar. 
If it is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
loadimage
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{map}] =} loadimage (@var{file})
Load an image file and it's associated color map from the specified
@var{file}.  The image must be stored in Octave's image format.
@seealso{saveimage, load, save}
@end deftypefn
ntsc2rgb
-*- texinfo -*-
@deftypefn {Function File} {} ntsc2rgb (@var{yiq})
Image format conversion.
@end deftypefn
ocean
-*- texinfo -*-
@deftypefn {Function File} {} ocean (@var{n})
Create color colormap.  The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@end deftypefn
pink
-*- texinfo -*-
@deftypefn {Function File} {} pink (@var{n})
Create color colormap. This colormap gives a sephia tone on black and
white images. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
prism
-*- texinfo -*-
@deftypefn {Function File} {} prism (@var{n})
Create color colormap. This colormap cycles trough red, orange, yellow,
green, blue and violet. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
rainbow
-*- texinfo -*-
@deftypefn {Function File} {} rainbow (@var{n})
Create color colormap. This colormap is red through orange, yellow, green, 
blue to violet. The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
rgb2hsv
-*- texinfo -*-
@deftypefn {Function File} {@var{hsv_map} =} rgb2hsv (@var{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.
@seealso{hsv2rgb}
@end deftypefn
rgb2ind
-*- texinfo -*-
@deftypefn  {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{rgb})
@deftypefnx {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{r}, @var{g}, @var{b})
Convert and RGB image to an Octave indexed image.
@seealso{ind2rgb, rgb2ntsc}
@end deftypefn
rgb2ntsc
-*- texinfo -*-
@deftypefn {Function File} {} rgb2ntsc (@var{rgb})
Image format conversion.
@end deftypefn
saveimage
-*- texinfo -*-
@deftypefn {Function File} {} saveimage (@var{file}, @var{x}, @var{fmt}, @var{map})
Save the matrix @var{x} to @var{file} in image format @var{fmt}.  Valid
values for @var{fmt} are

@table @code
@item "img"
Octave's image format.  The current colormap is also saved in the file.

@item "ppm"
Portable pixmap format.

@item "ps"
PostScript format.  Note that images saved in PostScript format can not
be read back into Octave with loadimage.
@end table

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.
@seealso{loadimage, save, load, colormap}
@end deftypefn
spring
-*- texinfo -*-
@deftypefn {Function File} {} spring (@var{n})
Create color colormap. This colormap is magenta to yellow.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
summer
-*- texinfo -*-
@deftypefn {Function File} {} summer (@var{n})
Create color colormap. This colormap is green to yellow.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
white
-*- texinfo -*-
@deftypefn {Function File} {} white (@var{n})
Create color colormap.  This colormap is completely white.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
winter
-*- texinfo -*-
@deftypefn {Function File} {} winter (@var{n})
Create color colormap. This colormap is blue to green.
The argument @var{n} should be a scalar.  If it
is omitted, the length of the current colormap or 64 is assumed.
@seealso{colormap}
@end deftypefn
beep
-*- texinfo -*-
@deftypefn {Function File} {} beep ()
Produce a beep from the speaker (or visual bell).
@seealso{puts, fputs, printf, fprintf}
@end deftypefn
commutation_matrix
-*- texinfo -*-
@deftypefn {Function File} {} commutation_matrix (@var{m}, @var{n})
Return the commutation matrix
@iftex
@tex
 $K_{m,n}$
@end tex
@end iftex
@ifinfo
 K(m,n)
@end ifinfo
 which is the unique
@iftex
@tex
 $m n \times m n$
@end tex
@end iftex
@ifinfo
@var{m}*@var{n} by @var{m}*@var{n}
@end ifinfo
 matrix such that
@iftex
@tex
 $K_{m,n} \cdot {\rm vec} (A) = {\rm vec} (A^T)$
@end tex
@end iftex
@ifinfo
@math{K(m,n) * vec(A) = vec(A')}
@end ifinfo
 for all
@iftex
@tex
 $m\times n$
@end tex
@end iftex
@ifinfo
@math{m} by @math{n}
@end ifinfo
 matrices
@iftex
@tex
 $A$.
@end tex
@end iftex
@ifinfo
@math{A}.
@end ifinfo

If only one argument @var{m} is given,
@iftex
@tex
 $K_{m,m}$
@end tex
@end iftex
@ifinfo
@math{K(m,m)}
@end ifinfo
 is returned.

See Magnus and Neudecker (1988), Matrix differential calculus with
applications in statistics and econometrics.
@end deftypefn
cond
-*- texinfo -*-
@deftypefn {Function File} {} cond (@var{a})
Compute the (two-norm) condition number of a matrix. @code{cond (a)} is
defined as @code{norm (a) * norm (inv (a))}, and is computed via a
singular value decomposition.
@seealso{norm, svd, rank}
@end deftypefn
cross
-*- texinfo -*-
@deftypefn {Function File} {} cross (@var{x}, @var{y}, @var{dim})
Computes the vector cross product of the two 3-dimensional vectors
@var{x} and @var{y}.

@example
@group
cross ([1,1,0], [0,1,1])
@result{} [ 1; -1; 1 ]
@end group
@end example

If @var{x} and @var{y} are matrices, the cross product is applied 
along the first dimension with 3 elements. The optional argument 
@var{dim} is used to force the cross product to be calculated along
the dimension defined by @var{dim}.
@end deftypefn
dmult
-*- texinfo -*-
@deftypefn {Function File} {} dmult (@var{a}, @var{b})
If @var{a} is a vector of length @code{rows (@var{b})}, return
@code{diag (@var{a}) * @var{b}} (but computed much more efficiently).
@end deftypefn
dot
-*- texinfo -*-
@deftypefn {Function File} {} dot (@var{x}, @var{y}, @var{dim})
Computes the dot product of two vectors. If @var{x} and @var{y}
are matrices, calculate the dot-product along the first 
non-singleton dimension. If the optional argument @var{dim} is
given, calculate the dot-product along this dimension.
@end deftypefn
duplication_matrix
-*- texinfo -*-
@deftypefn {Function File} {} duplication_matrix (@var{n})
Return the duplication matrix
@iftex
@tex
 $D_n$
@end tex
@end iftex
@ifinfo
@math{Dn}
@end ifinfo
 which is the unique
@iftex
@tex
 $n^2 \times n(n+1)/2$
@end tex
@end iftex
@ifinfo
@math{n^2} by @math{n*(n+1)/2}
@end ifinfo
 matrix such that
@iftex
@tex
 $D_n * {\rm vech} (A) = {\rm vec} (A)$
@end tex
@end iftex
@ifinfo
@math{Dn vech (A) = vec (A)}
@end ifinfo
 for all symmetric
@iftex
@tex
 $n \times n$
@end tex
@end iftex
@ifinfo
@math{n} by @math{n}
@end ifinfo
 matrices
@iftex
@tex
 $A$.
@end tex
@end iftex
@ifinfo
@math{A}.
@end ifinfo

See Magnus and Neudecker (1988), Matrix differential calculus with
applications in statistics and econometrics.
@end deftypefn
housh
-*- texinfo -*-
@deftypefn {Function File} {[@var{housv}, @var{beta}, @var{zer}] =} housh (@var{x}, @var{j}, @var{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
@end deftypefn
krylov
-*- texinfo -*-
@deftypefn {Function File} {[@var{u}, @var{h}, @var{nu}] =} krylov (@var{a}, @var{v}, @var{k}, @var{eps1}, @var{pflg})
Construct an orthogonal basis @var{u} of block Krylov subspace

@example
[v a*v a^2*v ... a^(k+1)*v]
@end example

@noindent
Using Householder reflections to guard against loss of orthogonality.

If @var{v} is a vector, then @var{h} contains the Hessenberg matrix
such that @code{a*u == u*h}.  Otherwise, @var{h} is meaningless.

The value of @var{nu} is the dimension of the span of the krylov
subspace (based on @var{eps1}).

If @var{b} is a vector and @var{k} is greater than @var{m-1}, then
@var{h} contains the Hessenberg decompostion of @var{a}.

The optional parameter @var{eps1} is the threshold for zero.  The
default value is 1e-12.

If the optional parameter @var{pflg} is nonzero, row pivoting is used
to improve numerical behavior.  The default value is 0.

Reference: Hodel and Misra, "Partial Pivoting in the Computation of
Krylov Subspaces", to be submitted to Linear Algebra and its
Applications
@end deftypefn
krylovb
-*- texinfo -*-
@deftypefn {Function File} {[@var{u}, @var{ucols}] =} krylovb (@var{a}, @var{v}, @var{k}, @var{eps1}, @var{pflg})
See @code{krylov}.
@end deftypefn
logm
-*- texinfo -*-
@deftypefn {Function File} {} logm (@var{a})
Compute the matrix logarithm of the square matrix @var{a}.  Note that
this is currently implemented in terms of an eigenvalue expansion and
needs to be improved to be more robust.
@end deftypefn
norm
-*- texinfo -*-
@deftypefn {Function File} {} norm (@var{a}, @var{p})
Compute the p-norm of the matrix @var{a}.  If the second argument is
missing, @code{p = 2} is assumed.

If @var{a} is a matrix:

@table @asis
@item @var{p} = @code{1}
1-norm, the largest column sum of the absolute values of @var{a}.

@item @var{p} = @code{2}
Largest singular value of @var{a}.

@item @var{p} = @code{Inf}
@cindex infinity norm
Infinity norm, the largest row sum of the absolute values of @var{a}.

@item @var{p} = @code{"fro"}
@cindex Frobenius norm
Frobenius norm of @var{a}, @code{sqrt (sum (diag (@var{a}' * @var{a})))}.
@end table

If @var{a} is a vector or a scalar:

@table @asis
@item @var{p} = @code{Inf}
@code{max (abs (@var{a}))}.

@item @var{p} = @code{-Inf}
@code{min (abs (@var{a}))}.

@item other
p-norm of @var{a}, @code{(sum (abs (@var{a}) .^ @var{p})) ^ (1/@var{p})}.
@end table
@seealso{cond, svd}
@end deftypefn
null
-*- texinfo -*-
@deftypefn {Function File} {} null (@var{a}, @var{tol})
Return an orthonormal basis of the null space of @var{a}.

The dimension of the null space is taken as the number of singular
values of @var{a} not greater than @var{tol}.  If the argument @var{tol}
is missing, it is computed as

@example
max (size (@var{a})) * max (svd (@var{a})) * eps
@end example
@end deftypefn
orth
-*- texinfo -*-
@deftypefn {Function File} {} orth (@var{a}, @var{tol})
Return an orthonormal basis of the range space of @var{a}.

The dimension of the range space is taken as the number of singular
values of @var{a} greater than @var{tol}.  If the argument @var{tol} is
missing, it is computed as

@example
max (size (@var{a})) * max (svd (@var{a})) * eps
@end example
@end deftypefn
qzhess
-*- texinfo -*-
@deftypefn {Function File} {[@var{aa}, @var{bb}, @var{q}, @var{z}] =} qzhess (@var{a}, @var{b})
Compute the Hessenberg-triangular decomposition of the matrix pencil
@code{(@var{a}, @var{b})}, returning
@code{@var{aa} = @var{q} * @var{a} * @var{z}},
@code{@var{bb} = @var{q} * @var{b} * @var{z}}, with @var{q} and @var{z}
orthogonal.  For example,

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

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

Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd
edition}.
@end deftypefn
rank
-*- texinfo -*-
@deftypefn {Function File} {} rank (@var{a}, @var{tol})
Compute the rank of @var{a}, using the singular value decomposition.
The rank is taken to be the number  of singular values of @var{a} that
are greater than the specified tolerance @var{tol}.  If the second
argument is omitted, it is taken to be

@example
tol = max (size (@var{a})) * sigma(1) * eps;
@end example

@noindent
where @code{eps} is machine precision and @code{sigma(1)} is the largest
singular value of @var{a}.
@end deftypefn
rref
-*- texinfo -*-
@deftypefn {Function File} {[@var{r}, @var{k}] =} rref (@var{a}, @var{tol})

Returns the reduced row echelon form of @var{a}. @var{tol} defaults
to @code{eps * max (size (@var{a})) * norm (@var{a}, inf)}.

Called with two return arguments, @var{k} returns the vector of
"bound variables", which are those columns on which elimination 
has been performed.

@end deftypefn
trace
-*- texinfo -*-
@deftypefn {Function File} {} trace (@var{a})
Compute the trace of @var{a}, @code{sum (diag (@var{a}))}.
@end deftypefn
vec
-*- texinfo -*-
@deftypefn {Function File} {} vec (@var{x})
Return the vector obtained by stacking the columns of the matrix @var{x}
one above the other.
@end deftypefn
vech
-*- texinfo -*-
@deftypefn {Function File} {} vech (@var{x})
Return the vector obtained by eliminating all supradiagonal elements of
the square matrix @var{x} and stacking the result one column above the
other.
@end deftypefn
ans
-*- texinfo -*-
@defvr {Automatic Variable} ans
The the most recently computed result that was not
explicitly assigned to a variable.  For example, after the expression

@example
3^2 + 4^2
@end example

@noindent
is evaluated, the value returned by @code{ans} is 25.
@end defvr
bincoeff
-*- texinfo -*-
@deftypefn {Mapping Function} {} bincoeff (@var{n}, @var{k})
Return the binomial coefficient of @var{n} and @var{k}, defined as
@iftex
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
$$
@end tex
@end iftex
@ifinfo

@example
@group
 /   \
 | n |    n (n-1) (n-2) ... (n-k+1)
 |   |  = -------------------------
 | k |               k!
 \   /
@end group
@end example
@end ifinfo

For example,

@example
@group
bincoeff (5, 2)
@result{} 10
@end group
@end example
@end deftypefn
bug_report
-*- texinfo -*-
@deftypefn {Function File} {} bug_report ()
Have Octave create a bug report template file, invoke your favorite
editor, and submit the report to the bug-octave mailing list when
you are finished editing.
@end deftypefn
bunzip2
-*- texinfo -*-
@deftypefn {Function File} {} bunzip2 (@var{bzfile}, @var{dir})
Unpack the bzip2 archive @var{bzfile} to the directory @var{dir}. If
@var{dir} is not specified, it defaults to the current directory.
@seealso{unpack, bzip2, tar, untar, gzip, gunzip, zip, unzip}
@end deftypefn
cast
-*- texinfo -*-
@deftypefn {Function File} {} cast (@var{val}, @var{type})
Convert @var{val} to data type @var{type}.
@seealso{int8, uint8, int16, uint16, int32, uint32, int64, uint64, double}
@end deftypefn
comma
-*- texinfo -*-
@deffn {Operator} ,
Array index, function argument, or command separator.
@seealso{semicolon}
@end deffn
compare_versions
-*- texinfo -*-
@deftypefn {Function File} {} compare_versions (@var{v1}, @var{v2}, @var{operator})
Compares to version strings using the given @var{operator}.

This function assumes that versions @var{v1} and @var{v2} are
arbitrarily long strings made of numeric and period characters
possibly followed by an arbitrary string (e.g. "1.2.3", "0.3",
"0.1.2+", or "1.2.3.4-test1").

The version is first split into the numeric and the character parts
then the parts are padded to be the same length (i.e. "1.1" would be
padded to be like "1.1.0" when being compared with "1.1.1", and
separately, the character parts of the strings are padded with
nulls).

The operator can be any logical operator from the set

@itemize @bullet
@item
"=="
equal
@item
"<"
less than
@item
"<="
less than or equal to
@item
">"
greater than
@item
">="
greater than or equal to
@item
"!="
not equal
@item
"~="
not equal
@end itemize

Note that version "1.1-test2" would compare as greater than
"1.1-test10". Also, since the numeric part is compared first, "a"
compares less than "1a" because the second string starts with a
numeric part even though double("a") is greater than double("1").
@end deftypefn
computer
-*- texinfo -*-
@deftypefn {Function File} {[@var{c}, @var{maxsize}, @var{endian}] =} computer ()
Print or return a string of the form @var{cpu}-@var{vendor}-@var{os}
that identifies the kind of computer Octave is running on.  If invoked
with an output argument, the value is returned instead of printed.  For
example,

@example
@group
computer ()
@print{} i586-pc-linux-gnu

x = computer ()
@result{} x = "i586-pc-linux-gnu"
@end group
@end example

If two output arguments are requested, also return the maximum number
of elements for an array.

If three output arguments are requested, also return the byte order
of the current system as a character (@code{"B"} for big-endian or
@code{"L"} for little-endian).
@end deftypefn
copyfile
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@var{f1}, @var{f2}, @var{force})
Copy the file @var{f1} to the new name @var{f2}.  The name @var{f1}
may contain globbing patterns.  If @var{f1} expands to multiple file
names, @var{f2} must be a directory. If @var{force} is given and equals
the string "f" the copy operation will be forced.

If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty\n\
character strings.  Otherwise, @var{status} is 0, @var{msg} contains a\n\
system-dependent error message, and @var{msgid} contains a unique\n\
message identifier.\n\
@seealso{glob, movefile}
@end deftypefn
cputime
-*- texinfo -*-
@deftypefn {Function File} {[@var{total}, @var{user}, @var{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, @code{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 @code{cputime} works by checking to see if the total
CPU time used is nonzero.
@end deftypefn
delete
-*- texinfo -*-
@deftypefn {Function File} {} delete (@var{file})
@deftypefnx {Function File} {} delete (@var{h})
Delete the named file or figure handle.
@end deftypefn
dir
-*- texinfo -*-
@deftypefn {Function File} {} dir (@var{directory})
@deftypefnx {Function File} {[@var{list}] =} dir (@var{directory})
Display file listing for directory @var{directory}.  If a return
value is requested, return a structure array with the fields

@example
@group
name
bytes
date
isdir
statinfo
@end group
@end example

@noindent
in which @code{statinfo} is the structure returned from @code{stat}.

If @var{directory} is not a directory, return information about the
named @var{filename}.  @var{directory} may be a list of directories
specified either by name or with wildcard characters (like * and ?)
which will be expanded with glob.
@seealso{ls, stat, readdir, glob, filesep}
@end deftypefn
doc
-*- texinfo -*-
@deftypefn {Command} doc @var{function_name}
Display documentation for the function @var{function_name}
directly from an on-line version of
the printed manual, using the GNU Info browser.  If invoked without
any arguments, the manual is shown from the beginning.

For example, the command @kbd{doc rand} starts the GNU Info browser
at this node in the on-line version of the manual.

Once the GNU Info browser is running, help for using it is available
using the command @kbd{C-h}.
@seealso{help}
@end deftypefn
dos
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{text}] =} dos (@var{command})
@deftypefnx {Function File} {[@var{status}, @var{text}] =} dos (@var{command}, "-echo")
Execute a system command if running under a Windows-like operating
system, otherwise do nothing.  Return the exit status of the program
in @var{status} and any output sent to the standard output in
@var{text}.  If the optional second argument @code{"-echo"} is given,
then also send the output from the command to the standard output.
@seealso{unix, isunix, ispc, system}
@end deftypefn
dump_prefs
-*- texinfo -*-
@deftypefn {Function File} {} dump_prefs (@var{file})
Have Octave dump all the current user preference variables to
@var{file} in a format that can be parsed by Octave later.  If
@var{file} is omitted, the listing is printed to stdout.
@end deftypefn
fileattrib
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} fileattrib (@var{file})
Return information about @var{file}.

If successful, @var{status} is 1, with @var{result} containing a
structure with the following fields:

@table @code
@item Name
Full name of @var{file}.
@item archive
True if @var{file} is an archive (Windows).
@item system
True if @var{file} is a system file (Windows).
@item hidden
True if @var{file} is a hidden file (Windows).
@item directory
True if @var{file} is a directory.
@item UserRead
@itemx GroupRead
@itemx OtherRead
True if the user (group; other users) has read permission for
@var{file}.
@item UserWrite
@itemx GroupWrite
@itemx OtherWrite
True if the user (group; other users) has write permission for
@var{file}.
@item UserExecute
@itemx GroupExecute
@itemx OtherExecute
True if the user (group; other users) has execute permission for
@var{file}.
@end table
If an attribute does not apply (i.e., archive on a Unix system) then
the field is set to NaN.

With no input arguments, return information about the current
directory.

If @var{file} contains globbing characters, return information about
all the matching files.
@seealso{glob}
@end deftypefn
fileparts
-*- texinfo -*-
@deftypefn {Function File} {[@var{dir}, @var{name}, @var{ext}, @var{ver}] =} fileparts (@var{filename})
Return the directory, name, extension, and version components of
@var{filename}.
@seealso{fullfile}
@end deftypefn
flops
-*- texinfo -*-
@deftypefn {Function File} {} flops ()
This function is provided for @sc{Matlab} compatibility, but it doesn't
actually do anything.
@end deftypefn
fullfile
-*- texinfo -*-
@deftypefn {Function File} {@var{filename} =} fullfile (@var{dir1}, @var{dir2}, @dots{}, @var{file})
Return a complete filename constructed from the given components.
@seealso{fileparts}
@end deftypefn
getfield
-*- texinfo -*-
@deftypefn {Function File} {[@var{v1}, @dots{}] =} getfield (@var{s}, @var{key}, @dots{}) 
Extract fields from a structure. For example

@example
@group
ss(1,2).fd(3).b=5;
getfield (ss, @{1,2@}, "fd", @{3@}, "b")
@result{} ans = 5
@end group
@end example

Note that the function call in the previous example is equivalent to
the expression

@example
         i1= @{1,2@}; i2= "fd"; i3= @{3@}; i4= "b";
         ss(i1@{:@}).(i2)(i3@{:@}).(i4)
@end example
@seealso{setfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn
gunzip
-*- texinfo -*-
@deftypefn {Function File} {} gunzip (@var{gzfile}, @var{dir})
Unpack the gzip archive @var{gzfile} to the directory @var{dir}. If
@var{dir} is not specified, it defaults to the current directory. If
the @var{gzfile} is a directory, all files in the directory will be
recursively gunzipped.
@seealso{unpack, bzip2, bunzip2, tar, untar, gzip, gunzip, zip, unzip}
@end deftypefn
gzip
-*- texinfo -*-
@deftypefn {Function File} {@var{entries} =} gzip (@var{files})
@deftypefnx {Function File} {@var{entries} =} gzip (@var{files}, @var{outdir})
Compress the list of files and/or directories specified in @var{files}.
Each file is compressed separately and a new file with a '.gz' extension
is create. The original file is not touch. If @var{rootdir} is defined 
the compressed versions of the files are placed in this directory.
@seealso{gunzip, zip, tar}
@end deftypefn
inputname
-*- texinfo -*-
@deftypefn {Function File} {} inputname (@var{n})
Return the text defining @var{n}-th input to the function.
@end deftypefn
ispc
-*- texinfo -*-
@deftypefn {Function File} {} ispc ()
Return 1 if Octave is running on a Windows system and 0 otherwise.
@end deftypefn
isunix
-*- texinfo -*-
@deftypefn {Function File} {} isunix ()
Return 1 if Octave is running on a Unix-like system and 0 otherwise.
@end deftypefn
license
-*- texinfo -*-
@deftypefn {Function File} {} license
Display the license of Octave.

@deftypefnx {Function File} {} license ("inuse")
Display a list of packages currently being used.

@deftypefnx {Function File} {@var{retval} =} license ("inuse")
Return a structure containing the fields @code{feature} and @code{user}.

@deftypefnx {Function File} {@var{retval} =} license ("test", @var{feature})
Return 1 if a license exists for the product identified by the string
@var{feature} and 0 otherwise.  The argument @var{feature} is case
insensitive and only the first 27 characters are checked.

@deftypefnx {Function File} {} license ("test", @var{feature}, @var{toggle})
Enable or disable license testing for @var{feature}, depending on
@var{toggle}, which may be one of:

@table @samp
@item "enable"
Future tests for the specified license of @var{feature} are conducted
as usual.
@item "disable"
Future tests for the specified license of @var{feature} return 0.
@end table

@deftypefnx {Function File} {@var{retval} =} license ("checkout", @var{feature})
Check out a license for @var{feature}, returning 1 on success and 0
on failure.

This function is provided for compatibility with @sc{Matlab}.
@seealso{ver, version}
@end deftypefn
list_primes
-*- texinfo -*-
@deftypefn {Function File} {} list_primes (@var{n})
List the first @var{n} primes.  If @var{n} is unspecified, the first
30 primes are listed.

The algorithm used is from page 218 of the
@iftex
@tex
 {\TeX}book.
@end tex
@end iftex
@ifinfo
 TeXbook.
@end ifinfo
@end deftypefn
ls
-*- texinfo -*-
@deffn {Command} ls options
List directory contents.  For example,

@example
ls -l
@print{} total 12
@print{} -rw-r--r--   1 jwe  users  4488 Aug 19 04:02 foo.m
@print{} -rw-r--r--   1 jwe  users  1315 Aug 17 23:14 bar.m
@end example

The @code{dir} and @code{ls} commands are implemented by calling your
system's directory listing command, so the available options may vary
from system to system.
@seealso{dir, stat, readdir, glob, filesep, ls_command}
@end deffn
ls_command
-*- texinfo -*-
@deftypefn {Function File} {[@var{old_cmd} =} ls_command (@var{cmd})
Set or return the shell command used by Octave's @code{ls} command.
The value of @var{cmd} must be a character string.
With no arguments, simply return the previous value.
@seealso{ls}
@end deftypefn
menu
-*- texinfo -*-
@deftypefn {Function File} {} menu (@var{title}, @var{opt1}, @dots{})
Print a title string followed by a series of options.  Each option will
be printed along with a number.  The return value is the number of the
option selected by the user.  This function is useful for interactive
programs.  There is no limit to the number of options that may be passed
in, but it may be confusing to present more than will fit easily on one
screen.
@seealso{disp, printf, input}
@end deftypefn
mex
-*- texinfo -*-
@deftypefn {Function File} {} mex [options] file @dots{}
Compile source code written in C, C++, or Fortran, to a MEX file.
This is equivalent to @code{mkoctfile --mex [options] file}.
@seealso{mkoctfile}
@end deftypefn
mexext
-*- texinfo -*-
@deftypefn {Function File} {} mexext ()
Return the filename extension used for MEX files.
@end deftypefn
mkoctfile
-*- texinfo -*-
@deftypefn {Function File} {} mkoctfile [-options] file @dots{}

The @code{mkoctfile} function compiles source code written in C,
C++, or Fortran.  Depending on the options used with @code{mkoctfile}, the
compiled code can be called within Octave or can be used as a stand-alone
application.

@code{mkoctfile} can be called from the shell prompt or from the Octave
prompt.

@code{mkoctfile} accepts the following options, all of which are optional
except for the file name of the code you wish to compile:

@table @samp
@item -I DIR
Add the include directory DIR to compile commands.

@item -D DEF
Add the definition DEF to the compiler call.

@item -l LIB
Add the library LIB to the link command.
         
@item -L DIR
Add the library directory DIR to the link command.

@item -M
@itemx --depend 
Generate dependency files (.d) for C and C++ source files.
         
@item -c
Compile but do not link.

@item -g
Enable debugging options for compilers.

@item -o FILE
@itemx --output FILE  
Output file name.  Default extension is .oct
(or .mex if --mex is specified) unless linking
a stand-alone executable.

@item -p VAR
@itemx --print VAR
Print the configuration variable VAR.  Recognized variables are: 

@example             
   ALL_CFLAGS                FFTW_LIBS     
   ALL_CXXFLAGS              FLIBS       
   ALL_FFLAGS                FPICFLAG      
   ALL_LDFLAGS               INCFLAGS      
   BLAS_LIBS                 LDFLAGS             
   CC                        LD_CXX              
   CFLAGS                    LD_STATIC_FLAG
   CPICFLAG                  LFLAGS              
   CPPFLAGS                  LIBCRUFT      
   CXX                       LIBOCTAVE     
   CXXFLAGS                  LIBOCTINTERP  
   CXXPICFLAG                LIBREADLINE   
   DEPEND_EXTRA_SED_PATTERN  LIBS        
   DEPEND_FLAGS              OCTAVE_LIBS   
   DL_LD                     RDYNAMIC_FLAG 
   DL_LDFLAGS                RLD_FLAG      
   F2C                       SED         
   F2CFLAGS                  XTRA_CFLAGS   
   F77                       XTRA_CXXFLAGS 
   FFLAGS
@end example

@item --link-stand-alone
Link a stand-alone executable file.

@item --mex
Assume we are creating a MEX file.  Set the default output extension 
to ".mex".

@item -s
@itemx --strip
Strip the output file.

@item -v
@itemx --verbose
Echo commands as they are executed.

@item file
The file to compile or link. Recognised file types are

@example
                  .c    C source
                  .cc   C++ source
                  .C    C++ source
                  .cpp  C++ source
                  .f    Fortran source
                  .F    Fortran source
                  .o    object file
@end example

@end table
@end deftypefn
movefile
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@var{f1}, @var{f2})
Move the file @var{f1} to the new name @var{f2}.  The name @var{f1}
may contain globbing patterns.  If @var{f1} expands to multiple file
names, @var{f2} must be a directory.

If successful, @var{status} is 1, with @var{msg} and @var{msgid} empty\n\
character strings.  Otherwise, @var{status} is 0, @var{msg} contains a\n\
system-dependent error message, and @var{msgid} contains a unique\n\
message identifier.\n\
@seealso{glob}
@end deftypefn
news
-*- texinfo -*-
@deftypefn {Function File} {} news ()
Display the current NEWS file for Octave.
@end deftypefn
orderfields
-*- texinfo -*-
@deftypefn {Function File} {[@var{t}, @var{p}] =} orderfields (@var{s1}, @var{s2})
Return a struct with fields arranged alphabetically or as specified
by @var{s2} and a corresponding permutation vector.

Given one struct, arrange field names in @var{s1} alphabetically.

Given two structs, arrange field names in @var{s1} as they appear
in @var{s2}.  The second argument may also specify the order in
a permutation vector or a cell array of strings.

@seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn
pack
-*- texinfo -*-
@deftypefn {Function File} {} pack ()
This function is provided for compatibility with @sc{Matlab}, but it
doesn't actually do anything.
@end deftypefn
paren
-*- texinfo -*-
@deffn {Operator} (
@deffnx {Operator} )
Array index or function argument delimeter.
@end deffn
parseparams
-*- texinfo -*-
@deftypefn {Function File} {[@var{reg}, @var{prop}] =} parseparams (@var{params})
Return in @var{reg} the cell elements of @var{param} up to the first
string element and in @var{prop} all remaining elements beginning
with the first string element.  For example 

@example
@group
[reg, prop] = parseparams (@{1, 2, "linewidth", 10@})
reg =
@{
  [1,1] = 1
  [1,2] = 2
@}
prop =
@{
  [1,1] = linewidth
  [1,2] = 10
@}
@end group
@end example

The parseparams function may be used to separate 'regular'
arguments and additional arguments given as property/value pairs of
the @var{varargin} cell array.
@seealso{varargin}
@end deftypefn
run
-*- texinfo -*-
@deftypefn {Function File} {} run (@var{f})
@deftypefnx {Command} {} run @var{f}
Run scripts in the current workspace that are not necessarily on the
path. If @var{f} is the script to run, including its path, then @code{run}
change the directory to the directory where @var{f} is found. @code{run}
then executes the script, and returns to the original directory.
@seealso{system}
@end deftypefn
semicolon
-*- texinfo -*-
@deffn {Operator} ;
Array row or command separator.
@seealso{comma}
@end deffn
setfield
-*- texinfo -*-
@deftypefn {Function File} {[@var{k1}, @dots{}, @var{v1}] =} setfield (@var{s}, @var{k1}, @var{v1}, @dots{})
Set field members in a structure.

@example
@group
oo(1,1).f0= 1;
oo = setfield(oo,@{1,2@},'fd',@{3@},'b', 6);
oo(1,2).fd(3).b == 6
@result{} ans = 1
@end group
@end example

Note that this function could be written

@example
         i1= @{1,2@}; i2= 'fd'; i3= @{3@}; i4= 'b';
         oo( i1@{:@} ).( i2 )( i3@{:@} ).( i4 ) == 6;
@end example
@seealso{getfield, rmfield, isfield, isstruct, fieldnames, struct}
@end deftypefn
single
-*- texinfo -*-
@deftypefn {Function File} {} single (@var{val})
Convert the numeric value @var{val} to single precision.

@strong{Note}: this function currently returns its argument converted
to double precision because Octave does not yet have a single-precision
numeric data type.
@end deftypefn
substruct
-*- texinfo -*-
@deftypefn {Function File} {} substruct (@var{type}, @var{subs}, @dots{})
Create a subscript structure for use with @code{subsref} or
@code{subsasgn}.
@seealso{subsref, subsasgn}
@end deftypefn
swapbytes
-*- texinfo -*-
@deftypefn {Function File} {} swapbytes (@var{x})
Swaps the byte order on values, converting from little endian to big 
endian and visa-versa. For example

@example
@group
swapbytes (uint16 (1:4))
@result{} [   256   512   768  1024]
@end group
@end example

@seealso{typecast, cast}
@end deftypefn
tar
-*- texinfo -*-
@deftypefn {Function File} {@var{entries} =} tar (@var{tarfile}, @var{files}, @var{root})
Pack @var{files} @var{files} into the TAR archive @var{tarfile}.  The
list of files must be a string or a cell array of strings.

The optional argument @var{root} changes the relative path of @var{files}
from the current directory.

If an output argument is requested the entries in the archive are
returned in a cell array.
@seealso{untar, gzip, gunzip, zip, unzip}
@end deftypefn
tempdir
-*- texinfo -*-
@deftypefn {Function File} {@var{dir} =} fullfile ()
Return the name of the system's directory for temporary files.
@end deftypefn
tempname
-*- texinfo -*-
@deftypefn {Function File} {filename = } tempname ()
This function is an alias for @code{tmpnam}.
@end deftypefn
texas_lotto
-*- texinfo -*-
@deftypefn {Function File} {} texas_lotto ()
Pick 6 unique numbers between 1 and 50 that are guaranteed to win
the Texas Lotto.
@seealso{rand}
@end deftypefn
unix
-*- texinfo -*-
@deftypefn {Function File} {[@var{status}, @var{text}]} unix (@var{command})
@deftypefnx {Function File} {[@var{status}, @var{text}]} unix (@var{command}, "-echo")
Execute a system command if running under a Unix-like operating
system, otherwise do nothing.  Return the exit status of the program
in @var{status} and any output sent to the standard output in
@var{text}.  If the optional second argument @code{"-echo"} is given,
then also send the output from the command to the standard output.
@seealso{isunix, ispc, system}
@end deftypefn
unpack
-*- texinfo -*-
@deftypefn {Function File} {@var{files} =} unpack (@var{file}, @var{dir})
@deftypefnx {Function File} {@var{files} =} unpack (@var{file}, @var{dir}, @var{filetype})
Unpack the archive @var{file} based on its extension to the directory
@var{dir}.  If @var{file} is a cellstr, then all files will be
handled individually.  If @var{dir} is not specified, it defaults to
the current directory.  It returns a list of @var{files}
unpacked. If a directory is in the file list, then the
@var{filetype} to unpack must also be specified.

The @var{files} includes the entire path to the output files.
@seealso{bzip2,bunzip2,tar,untar,gzip,gunzip,zip,unzip}
@end deftypefn
untar
-*- texinfo -*-
@deftypefn {Function File} {} untar (@var{tarfile}, @var{dir})
Unpack the TAR archive @var{tarfile} to the directory @var{dir}.
If @var{dir} is not specified, it defaults to the current directory.
@seealso{unpack, bzip2, bunzip2, tar, gzip, gunzip, zip, unzip}
@end deftypefn
unzip
-*- texinfo -*-
@deftypefn {Function File} {} unzip (@var{zipfile}, @var{dir})
Unpack the ZIP archive @var{zipfile} to the directory @var{dir}.
If @var{dir} is not specified, it defaults to the current directory.
@seealso{unpack, bzip2, bunzip2, tar, untar, gzip, gunzip, zip}
@end deftypefn
ver
-*- texinfo -*-
@deftypefn {Function File} {} ver ()
Display a header containing the current Octave version
number, license string and operating system.
@seealso{license, version}
@end deftypefn
version
-*- texinfo -*-
@deftypefn {Function File} {} version ()
Return Octave's version number as a string.  This is also the value of
the built-in variable @code{OCTAVE_VERSION}.
@end deftypefn
warning_ids
-*- texinfo -*-
@table @code
@item Octave:array-to-scalar
If the @code{Octave:array-to-scalar} warning is enabled, Octave will
warn when an implicit conversion from an array to a scalar value is
attempted.  By default, the @code{Octave:array-to-scalar} warning is
disabled.

@item Octave:array-to-vector
If the @code{Octave:array-to-vector} warning is enabled, Octave will
warn when an implicit conversion from an array to a vector value is
attempted.  By default, the @code{Octave:array-to-vector} warning is
disabled.

@item Octave:assign-as-truth-value
If the @code{Octave:assign-as-truth-value} warning is
enabled, a warning is issued for statements like

@example
if (s = t)
  ...
@end example

@noindent
since such statements are not common, and it is likely that the intent
was to write

@example
if (s == t)
  ...
@end example

@noindent
instead.

There are times when it is useful to write code that contains
assignments within the condition of a @code{while} or @code{if}
statement.  For example, statements like

@example
while (c = getc())
  ...
@end example

@noindent
are common in C programming.

It is possible to avoid all warnings about such statements by
disabling the @code{Octave:assign-as-truth-value} warning,
but that may also let real errors like

@example
if (x = 1)  # intended to test (x == 1)!
  ...
@end example

@noindent
slip by.

In such cases, it is possible suppress errors for specific statements by
writing them with an extra set of parentheses.  For example, writing the
previous example as

@example
while ((c = getc()))
  ...
@end example

@noindent
will prevent the warning from being printed for this statement, while
allowing Octave to warn about other assignments used in conditional
contexts.

By default, the @code{Octave:assign-as-truth-value} warning is enabled.

@item Octave:associativity-change
If the @code{Octave:associativity-change} warning is
enabled, Octave will warn about possible changes in the meaning of
some code due to changes in associativity for some operators.
Associativity changes have typically been made for @sc{Matlab}
compatibility.  By default, the @code{Octave:associativity-change}
warning is enabled.

@item Octave:divide-by-zero
If the @code{Octave:divide-by-zero} warning is enabled, a
warning is issued when Octave encounters a division by zero.  By
default, the @code{Octave:divide-by-zero} warning is enabled.

@item Octave:empty-list-elements
If the @code{Octave:empty-list-elements} warning is enabled, a
warning is issued when an empty matrix is found in a matrix list.
For example,

@example
a = [1, [], 3, [], 5]
@end example

@noindent
By default, the @code{Octave:empty-list-elements} warning is enabled.

@item Octave:fortran-indexing
If the @code{Octave:fortran-indexing} warning is enabled, a warning is
printed for expressions which select elements of a two-dimensional matrix
using a single index.  By default, the @code{Octave:fortran-indexing}
warning is disabled.

@item Octave:function-name-clash
If the @code{Octave:function-name-clash} warning is enabled, a
warning is issued when Octave finds that the name of a function
defined in a function file differs from the name of the file.  (If
the names disagree, the name declared inside the file is ignored.)
By default, the @code{Octave:function-name-clash} warning is enabled.

@item Octave:future-time-stamp
If the @code{Octave:future-time-stamp} warning is enabled, Octave
will print a warning if it finds a function file with a time stamp
that is in the future.  By default, the
@code{Octave:future-time-stamp} warning is enabled.

@item Octave:imag-to-real
If the @code{Octave:imag-to-real} warning is enabled, a warning is
printed for implicit conversions of complex numbers to real numbers.
By default, the @code{Octave:imag-to-real} warning is disabled.

@item Octave:matlab-incompatible
Print warnings for Octave language features that may cause
compatibility problems with @sc{Matlab}.

@item Octave:missing-semicolon
If the @code{Octave:missing-semicolon} warning is enabled, Octave
will warn when statements in function definitions don't end in
semicolons.  By default the @code{Octave:missing-semicolon} warning
is disabled.

@item Octave:neg-dim-as-zero
If the @code{Octave:neg-dim-as-zero} warning is enabled, print a warning
for expressions like

@example
eye (-1)
@end example

@noindent
By default, the @code{Octave:neg-dim-as-zero} warning is disabled.

@item Octave:num-to-str
If the @code{Octave:num-to-str} warning is enable, a warning is
printed for implicit conversions of numbers to their ASCII character
equivalents when strings are constructed using a mixture of strings and
numbers in matrix notation.  For example,

@example
@group
[ "f", 111, 111 ]
@result{} "foo"
@end group
@end example
elicits a warning if the @code{Octave:num-to-str} warning is
enabled.  By default, the @code{Octave:num-to-str} warning is enabled.

@item Octave:precedence-change
If the @code{Octave:precedence-change} warning is enabled, Octave
will warn about possible changes in the meaning of some code due to
changes in precedence for some operators.  Precedence changes have
typically been made for @sc{Matlab} compatibility.  By default, the
@code{Octave:precedence-change} warning is enabled.

@item Octave:reload-forces-clear
If several functions have been loaded from the same file, Octave must
clear all the functions before any one of them can be reloaded.  If
the @code{Octave:reload-forces-clear} warning is enabled, Octave will
warn you when this happens, and print a list of the additional
functions that it is forced to clear.  By default, the
@code{Octave:reload-forces-clear} warning is enabled.

@item Octave:resize-on-range-error
If the @code{Octave:resize-on-range-error} warning is enabled, print a
warning when a matrix is resized by an indexed assignment with
indices outside the current bounds.  By default, the
@code{Octave:resize-on-range-error} warning is disabled.

@item Octave:separator-insert
Print warning if commas or semicolons might be inserted
automatically in literal matrices.

@item Octave:single-quote-string
Print warning if a signle quote character is used to introduce a
string constant.

@item Octave:str-to-num
If the @code{Octave:str-to-num} warning is enabled, a warning is printed
for implicit conversions of strings to their numeric ASCII equivalents.
For example,
@example
@group
"abc" + 0
@result{} 97 98 99
@end group
@end example
elicits a warning if the @code{Octave:str-to-num} warning is enabled.
By default, the @code{Octave:str-to-num} warning is disabled.

@item Octave:string-concat
If the @code{Octave:string-concat} warning is enabled, print a
warning when concatenating a mixture of double and single quoted strings.
By default, the @code{Octave:string-concat} warning is disabled.

@item Octave:undefined-return-values
If the @code{Octave:undefined-return-values} warning is disabled,
print a warning if a function does not define all the values in
the return list which are expected.  By default, the
@code{Octave:undefined-return-values} warning is enabled.

@item Octave:variable-switch-label
If the @code{Octave:variable-switch-label} warning is enabled, Octave
will print a warning if a switch label is not a constant or constant
expression.  By default, the @code{Octave:variable-switch-label}
warning is disabled.
@end table
xor
-*- texinfo -*-
@deftypefn {Mapping Function} {} xor (@var{x}, @var{y})
Return the `exclusive or' of the entries of @var{x} and @var{y}.
For boolean expressions @var{x} and @var{y},
@code{xor (@var{x}, @var{y})} is true if and only if @var{x} or @var{y}
is true, but not if both @var{x} and @var{y} are true.
@end deftypefn
zip
-*- texinfo -*-
@deftypefn {Function File} {@var{entries} =} zip (@var{zipfile}, @var{files})
@deftypefnx {Function File} {@var{entries} =} zip (@var{zipfile}, @var{files}, @var{rootdir})
Compress the list of files and/or directories specified in @var{files} 
into the archive @var{zipfiles} in the same directory. If @var{rootdir} 
is defined the @var{files} is located relative to @var{rootdir} rather 
than the current directory
@seealso{unzip,tar}
@end deftypefn
__fsolve_defopts__
-*- texinfo -*-
@deftypefn {Function File} {} __fsolve_defopts__ ()
@end deftypefn
glpk
-*- texinfo -*-
@deftypefn {Function File} {[@var{xopt}, @var{fmin}, @var{status}, @var{extra}] =} glpk (@var{c}, @var{a}, @var{b}, @var{lb}, @var{ub}, @var{ctype}, @var{vartype}, @var{sense}, @var{param})
Solve a linear program using the GNU GLPK library.  Given three
arguments, @code{glpk} solves the following standard LP:

@iftex
@tex
$$
  \min_x C^T x
$$
@end tex
@end iftex
@ifnottex
@example
min C'*x
@end example
@end ifnottex

subject to

@iftex
@tex
$$
  Ax = b \qquad x \geq 0
$$
@end tex
@end iftex
@ifnottex
@example
@group
A*x  = b
  x >= 0
@end group
@end example
@end ifnottex

but may also solve problems of the form

@iftex
@tex
$$
  [ \min_x | \max_x ] C^T x
$$
@end tex
@end iftex
@ifnottex
@example
[ min | max ] C'*x
@end example
@end ifnottex

subject to

@iftex
@tex
$$
 Ax [ = | \leq | \geq ] b \qquad  LB \leq x \leq UB
$$
@end tex
@end iftex
@ifnottex
@example
@group
A*x [ "=" | "<=" | ">=" ] b
  x >= LB
  x <= UB
@end group
@end example
@end ifnottex

Input arguments:

@table @var
@item c
A column array containing the objective function coefficients.

@item a
A matrix containing the constraints coefficients.

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

@item lb
An array containing the lower bound on each of the variables.  If
@var{lb} is not supplied, the default lower bound for the variables is
zero.

@item ub
An array containing the upper bound on each of the variables.  If
@var{ub} is not supplied, the default upper bound is assumed to be
infinite.

@item ctype
An array of characters containing the sense of each constraint in the
constraint matrix.  Each element of the array may be one of the
following values
@table @code
@item "F"
Free (unbounded) variable (the constraint is ignored).
@item "U"
Variable with upper bound (@code{A(i,:)*x <= b(i)}).
@item "S"
Fixed Variable (@code{A(i,:)*x = b(i)}).
@item "L"
Variable with lower bound (@code{A(i,:)*x >= b(i)}).
@item "D"
Double-bounded variable (@code{A(i,:)*x >= -b(i)} @emph{and}
(@code{A(i,:)*x <= b(i)}).
@end table

@item vartype
A column array containing the types of the variables.
@table @code
@item "F"
"C"
Continuous variable.
"I"
Integer variable
@end table

@item sense
If @var{sense} is 1, the problem is a minimization.  If @var{sense} is
-1, the problem is a maximization.  The default value is 1.

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

Integer parameters:

@table @code
@item msglev (@code{LPX_K_MSGLEV}, default: 1)
Level of messages output by solver routines:
@table @asis
@item 0
No output.
@item 1
Error messages only.
@item 2
Normal output .
@item 3
Full output (includes informational messages).
@end table

@item scale (@code{LPX_K_SCALE}, default: 1)
Scaling option: 
@table @asis
@item 0
No scaling .
@item 1
Equilibration scaling .
@item 2
Geometric mean scaling, then equilibration scaling.
@end table

@item dual	 (@code{LPX_K_DUAL}, default: 0)
Dual simplex option:
@table @asis
@item 0
Do not use the dual simplex.
@item 1
If initial basic solution is dual feasible, use the dual simplex.
@end table

@item price	 (@code{LPX_K_PRICE}, default: 1)
Pricing option (for both primal and dual simplex):
@table @asis
@item 0
Textbook pricing.
@item 1
Steepest edge pricing.
@end table
  
@item round	 (@code{LPX_K_ROUND}, default: 0)
Solution rounding option:
@table @asis
@item 0
Report all primal and dual values "as is".
@item 1
Replace tiny primal and dual values by exact zero.
@end table

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

@item itcnt (@code{LPX_K_OUTFRQ}, default: 200)
Output frequency, in iterations.  This parameter specifies how
frequently the solver sends information about the solution to the
standard output.

@item branch (@code{LPX_K_BRANCH}, default: 2)
Branching heuristic option (for MIP only):
@table @asis
@item 0
Branch on the first variable.
@item 1
Branch on the last variable.
@item 2
Branch using a heuristic by Driebeck and Tomlin.
@end table

@item btrack (@code{LPX_K_BTRACK}, default: 2)
Backtracking heuristic option (for MIP only):
@table @asis
@item 0
Depth first search.
@item 1
Breadth first search.
@item 2
Backtrack using the best projection heuristic.
@end table        

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

@item lpsolver (default: 1)
Select which solver to use.  If the problem is a MIP problem this flag
will be ignored.
@table @asis
@item 1
Revised simplex method.
@item 2
Interior point method.
@end table
@item save (default: 0)
If this parameter is nonzero, save a copy of the problem problem in
CPLEX LP format to the file @file{"outpb.lp"}.  There is currently no
way to change the name of the output file.
@end table

Real parameters:

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

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

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

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

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

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

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

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

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

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

Output values:

@table @var
@item xopt
The optimizer (the value of the decision variables at the optimum).
@item fopt
The optimum value of the objective function.
@item status
Status of the optimization.

Simplex Method:
@table @asis
@item 180 (@code{LPX_OPT})
Solution is optimal.
@item 181 (@code{LPX_FEAS})
Solution is feasible.
@item 182 (@code{LPX_INFEAS})
Solution is infeasible.
@item 183 (@code{LPX_NOFEAS})
Problem has no feasible solution.
@item 184 (@code{LPX_UNBND})
Problem has no unbounded solution.
@item 185 (@code{LPX_UNDEF})
Solution status is undefined.
@end table
Interior Point Method:
@table @asis
@item 150 (@code{LPX_T_UNDEF})
The interior point method is undefined.
@item 151 (@code{LPX_T_OPT})
The interior point method is optimal.
@end table
Mixed Integer Method:
@table @asis
@item 170 (@code{LPX_I_UNDEF})
The status is undefined.
@item 171 (@code{LPX_I_OPT})
The solution is integer optimal.
@item 172 (@code{LPX_I_FEAS})
Solution integer feasible but its optimality has not been proven
@item 173 (@code{LPX_I_NOFEAS})
No integer feasible solution.
@end table
@noindent
If an error occurs, @var{status} will contain one of the following
codes:

@table @asis
@item 204 (@code{LPX_E_FAULT})
Unable to start the search.
@item 205 (@code{LPX_E_OBJLL})
Objective function lower limit reached.
@item 206 (@code{LPX_E_OBJUL})
Objective function upper limit reached.
@item 207 (@code{LPX_E_ITLIM})
Iterations limit exhausted.
@item 208 (@code{LPX_E_TMLIM})
Time limit exhausted.
@item 209 (@code{LPX_E_NOFEAS})
No feasible solution.
@item 210 (@code{LPX_E_INSTAB})
Numerical instability.
@item 211 (@code{LPX_E_SING})
Problems with basis matrix.
@item 212 (@code{LPX_E_NOCONV})
No convergence (interior).
@item 213 (@code{LPX_E_NOPFS})
No primal feasible solution (LP presolver).
@item 214 (@code{LPX_E_NODFS})
No dual feasible solution (LP presolver).
@end table
@item extra
A data structure containing the following fields:
@table @code
@item lambda
Dual variables.
@item redcosts
Reduced Costs.
@item time
Time (in seconds) used for solving LP/MIP problem.
@item mem
Memory (in bytes) used for solving LP/MIP problem (this is not 
available if the version of GLPK is 4.15 or later).
@end table
@end table

Example:

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

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

[xmin, fmin, status, extra] = ...
   glpk (c, a, b, lb, ub, ctype, vartype, s, param);
@end group
@end example
@end deftypefn
glpkmex
-*- texinfo -*-
@deftypefn {Function File} {[@var{xopt}, @var{fmin}, @var{status}, @var{extra}] =} glpkmex (@var{sense}, @var{c}, @var{a}, @var{b}, @var{ctype}, @var{lb}, @var{ub}, @var{vartype}, @var{param}, @var{lpsolver}, @var{save_pb})
This function is provided for compatibility with the old @sc{Matlab}
interface to the GNU GLPK library.  For Octave code, you should use
the @code{glpk} function instead.
@end deftypefn
optimset
-*- texinfo -*-
@deftypefn {Function File} {} optimset ()
@deftypefnx {Function File} {} optimset (@var{par}, @var{val}, @dots{})
@deftypefnx {Function File} {} optimset (@var{old}, @var{par}, @var{val}, @dots{})
@deftypefnx {Function File} {} optimset (@var{old}, @var{new})
Create options struct for optimization functions.
@end deftypefn
qp
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qp (@var{x0}, @var{H}, @var{q}, @var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb}, @var{A_in}, @var{A_ub})
Solve the quadratic program
@iftex
@tex
$$
 \min_x {1 \over 2} x^T H x + x^T q
$$
@end tex
@end iftex
@ifnottex

@example
     min 0.5 x'*H*x + x'*q
      x
@end example

@end ifnottex
subject to
@iftex
@tex
$$
 Ax = b \qquad lb \leq x \leq ub \qquad A_{lb} \leq A_{in} \leq A_{ub}
$$
@end tex
@end iftex
@ifnottex

@example
     A*x = b
     lb <= x <= ub
     A_lb <= A_in*x <= A_ub
@end example
@end ifnottex

@noindent
using a null-space active-set method.

Any bound (@var{A}, @var{b}, @var{lb}, @var{ub}, @var{A_lb},
@var{A_ub}) may be set to the empty matrix (@code{[]}) if not
present.  If the initial guess is feasible the algorithm is faster.

The value @var{info} is a structure with the following fields:
@table @code
@item solveiter
The number of iterations required to find the solution.
@item info
An integer indicating the status of the solution, as follows:
@table @asis
@item 0
The problem is feasible and convex.  Global solution found.
@item 1
The problem is not convex.  Local solution found.
@item 2
The problem is not convex and unbounded.
@item 3
Maximum number of iterations reached.
@item 6
The problem is infeasible.
@end table
@end table
@end deftypefn
sqp
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{obj}, @var{info}, @var{iter}, @var{nf}, @var{lambda}] =} sqp (@var{x}, @var{phi}, @var{g}, @var{h})
Solve the nonlinear program
@iftex
@tex
$$
\min_x \phi (x)
$$
@end tex
@end iftex
@ifnottex

@example
     min phi (x)
      x
@end example

@end ifnottex
subject to
@iftex
@tex
$$
 g(x) = 0 \qquad h(x) \geq 0
$$
@end tex
@end iftex
@ifnottex

@example
     g(x)  = 0
     h(x) >= 0
@end example
@end ifnottex

@noindent
using a successive quadratic programming method.

The first argument is the initial guess for the vector @var{x}.

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

@example
     y = phi (x)
@end example

@noindent
in which @var{x} is a vector and @var{y} is a scalar.

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

If supplied, the gradient function must be of the form

@example
     g = gradient (x)
@end example

@noindent
in which @var{x} is a vector and @var{g} is a vector.

If supplied, the hessian function must be of the form

@example
     h = hessian (x)
@end example

@noindent
in which @var{x} is a vector and @var{h} is a matrix.

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

If your problem does not have equality (or inequality) constraints,
you may pass an empty matrix for @var{cef} (or @var{cif}).

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

@example
     r = f (x)
@end example

@noindent
in which @var{x} is a vector and @var{r} is a vector.

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

@iftex
@tex
$$
 \Bigg( {\partial f(x) \over \partial x_1}, 
        {\partial f(x) \over \partial x_2}, \ldots,
        {\partial f(x) \over \partial x_N} \Bigg)^T
$$
@end tex
@end iftex
@ifnottex
@example
                [ d f(x)   d f(x)        d f(x) ]
    transpose ( [ ------   -----   ...   ------ ] )
                [  dx_1     dx_2          dx_N  ]
@end example
@end ifnottex

Here is an example of calling @code{sqp}:

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

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

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

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

     x =
     
       -1.71714
        1.59571
        1.82725
       -0.76364
       -0.76364
     
     obj = 0.053950
     info = 101
     iter = 8
     nf = 10
     lambda =
     
       -0.0401627
        0.0379578
       -0.0052227
@end example

The value returned in @var{info} may be one of the following:
@table @asis
@item 101
The algorithm terminated because the norm of the last step was less
than @code{tol * norm (x))} (the value of tol is currently fixed at
@code{sqrt (eps)}---edit @file{sqp.m} to modify this value.
@item 102
The BFGS update failed.
@item 103
The maximum number of iterations was reached (the maximum number of
allowed iterations is currently fixed at 100---edit @file{sqp.m} to
increase this value).
@end table
@seealso{qp}
@end deftypefn
savepath
-*- texinfo -*-
@deftypefn {Function File} {} savepath (@var{file})
Save the current function search path to @var{file}.  If @var{file}
is omitted, @file{~/.octaverc} is used.  If successful,
@code{savepath} returns 0.
@seealso{path, addpath, rmpath, genpath, pathdef, pathsep}
@end deftypefn
pkg
-*- texinfo -*-
@deftypefn  {Command} pkg @var{command} @var{pkg_name}
@deftypefnx {Command} pkg @var{command} @var{option} @var{pkg_name}
This command interacts with the package manager. Different actions will
be taken depending on the value of @var{command}.

@table @samp
@item install
Install named packages.  For example,
@example
pkg install image-1.0.0.tar.gz
@end example
@noindent
installs the package found in the file @code{image-1.0.0.tar.gz}.

The @var{option} variable can contain options that affect the manner
in which a package is installed. These options can be one or more of

@table @code
@item -nodeps
The package manager will disable the dependency checking. That way it 
is possible to install a package even if it depends on another package 
that's not installed on the system. @strong{Use this option with care.}

@item -noauto
The package manager will not automatically load the installed package 
when starting Octave, even if the package requests that it is.

@item -auto
The package manager will automatically load the installed package when 
starting Octave, even if the package requests that it isn't.

@item -local
A local installation is forced, even if the user has system privileges.

@item -global
A global installation is forced, even if the user doesn't normally have
system privileges

@item -verbose
The package manager will print the output of all of the commands that are 
performed.
@end table

@item uninstall
Uninstall named packages.  For example,
@example
pkg uninstall image
@end example
@noindent
removes the @code{image} package from the system. If another installed
package depends on the @code{image} package an error will be issued.
The package can be uninstalled anyway by using the @code{-nodeps} option.
@item load
Add named packages to the path. After loading a package it is
possible to use the functions provided by the package. For example,
@example
pkg load image
@end example
@noindent
adds the @code{image} package to the path. It is possible to load all
installed packages at once with the command
@example
pkg load all
@end example
@item unload
Removes named packages from the path. After unloading a package it is
no longer possible to use the functions provided by the package.
This command behaves like the @code{load} command.
@item list
Show a list of the currently installed packages. By requesting one or two
output argument it is possible to get a list of the currently installed
packages. For example,
@example
installed_packages = pkg list;
@end example
@noindent
returns a cell array containing a structure for each installed package.
The command
@example
[@var{user_packages}, @var{system_packages}] = pkg list
@end example
@noindent
splits the list of installed packages into those who are installed by
the current user, and those installed by the system administrator.
@item prefix
Set the installation prefix directory. For example,
@example
pkg prefix ~/my_octave_packages
@end example
@noindent
sets the installation prefix to @code{~/my_octave_packages}.
Packages will be installed in this directory.

It is possible to get the current installation prefix by requesting an
output argument.  For example,
@example
p = pkg prefix
@end example
@item local_list
Set the file in which to look for information on the locally
installed packages. Locally installed packages are those that are
typically available only to the current user. For example
@example
pkg local_list ~/.octave_packages
@end example
It is possible to get the current value of local_list with the following
@example
pkg local_list
@end example
@item global_list
Set the file in which to look for, for information on the globally
installed packages. Globally installed packages are those that are
typically available to all users. For example
@example
pkg global_list /usr/share/octave/octave_packages
@end example
It is possible to get the current value of global_list with the following
@example
pkg global_list
@end example
@item rebuild
Rebuilds the package database from the installed directories. This can 
be used in cases where for some reason the package database is corrupted.
It can also take the @code{-auto} and @code{-noauto} options to allow the
autolaoding state of a package to be changed. For example

@example
pkg rebuild -noauto image
@end example

will remove the autoloading status of the image package.
@item build
Builds a binary form of a package or packages. The binary file produced
will itself be an Octave package that can be installed normally with
@code{pkg}. The form of the command to build a binary package is

@example
pkg build builddir image-1.0.0.tar.gz @dots{}
@end example

@noindent
where @code{buiddir} is the name of a directory where the temporary
installation will be produced and the binary packages will be found.
The options @code{-verbose} and @code{-nodeps} are respected, while 
the other options are ignored.
@end table
@end deftypefn
__axis_label__
Undocumented internal function.
__bar__
Undocumented internal function.
__default_plot_options__
Undocumented internal function.
__errcomm__
Undocumented internal function.
__errplot__
Undocumented internal function.
__gnuplot_version__
Undocumented internal function.
__go_close_all__
Undocumented internal function.
__go_draw_axes__
Undocumented internal function.
__go_draw_figure__
Undocumented internal function.
__line__
Undocumented internal function.
__next_line_color__
Undocumented internal function.
__patch__
Undocumented internal function.
__plr1__
Undocumented internal function.
__plr2__
Undocumented internal function.
__plt1__
Undocumented internal function.
__plt2__
Undocumented internal function.
__plt2mm__
Undocumented internal function.
__plt2mv__
Undocumented internal function.
__plt2ss__
Undocumented internal function.
__plt2vm__
Undocumented internal function.
__plt2vv__
Undocumented internal function.
__plt__
Undocumented internal function.
__plt_get_axis_arg__
Undocumented internal function.
__pltopt1__
Undocumented internal function.
__pltopt__
Undocumented internal function.
ancestor
-*- texinfo -*-
@deftypefn {Function File} {@var{parent} =} ancestor (@var{h}, @var{type})
@deftypefnx {Function File} {@var{parent} =} ancestor (@var{h}, @var{type}, 'toplevel')
Return the first ancestor of handle object @var{h} whose type matches
@var{type}, where @var{type} is a character string. If @var{type} is a
cell array of strings, return the first parent whose type matches
any of the given type strings.

If the handle object @var{h} is of type @var{type}, return @var{h}.

If @code{"toplevel"} is given as a 3rd argument, return the highest
parent in the object hierarchy that matches the condition, instead
of the first (nearest) one.
@seealso{get, set}
@end deftypefn
axes
-*- texinfo -*-
@deftypefn {Function File} {} axes ()
@deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} axes (@var{h})
Create an axes object and return a handle to it.
@end deftypefn
axis
-*- texinfo -*-
@deftypefn {Function File} {} axis (@var{limits})
Set axis limits for plots.

The argument @var{limits} should be a 2, 4, or 6 element vector.  The
first and second elements specify the lower and upper limits for the x
axis.  The third and fourth specify the limits for the y axis, and the
fifth and sixth specify the limits for the z axis.

Without any arguments, @code{axis} turns autoscaling on.  

With one output argument, @code{x=axis} returns the current axes 
(this is not yet implemented for automatic axes).

The vector argument specifying limits is optional, and additional
string arguments may be used to specify various axis properties.  For
example,

@example
axis ([1, 2, 3, 4], "square");
@end example

@noindent
forces a square aspect ratio, and

@example
axis ("labely", "tic");
@end example

@noindent
turns tic marks on for all axes and tic mark labels on for the y-axis
only.

@noindent
The following options control the aspect ratio of the axes.

@table @code
@item "square"
Force a square aspect ratio.
@item "equal"
Force x distance to equal y-distance.
@item "normal"
Restore the balance.
@end table

@noindent
The following options control the way axis limits are interpreted.

@table @code
@item "auto" 
Set the specified axes to have nice limits around the data
or all if no axes are specified.
@item "manual" 
Fix the current axes limits.
@item "tight"
Fix axes to the limits of the data (not implemented).
@end table

@noindent
The option @code{"image"} is equivalent to @code{"tight"} and
@code{"equal"}.

@noindent
The following options affect the appearance of tic marks.

@table @code
@item "on" 
Turn tic marks and labels on for all axes.
@item "off"
Turn tic marks off for all axes.
@item "tic[xyz]"
Turn tic marks on for all axes, or turn them on for the
specified axes and off for the remainder.
@item "label[xyz]"
Turn tic labels on for all axes, or turn them on for the 
specified axes and off for the remainder.
@item "nolabel"
Turn tic labels off for all axes.
@end table
Note, if there are no tic marks for an axis, there can be no labels.

@noindent
The following options affect the direction of increasing values on
the axes.

@table @code
@item "ij"
Reverse y-axis, so lower values are nearer the top.
@item "xy" 
Restore y-axis, so higher values are nearer the top. 
@end table

@end deftypefn
bar
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} bar (@var{x}, @var{y}, @var{style})
@deftypefnx {Function File} {[@var{xb}, @var{yb}] =} bar (@dots{})
Given two vectors of x-y data, @code{bar} produce 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 @var{y} is a matrix, then each column of @var{y} is taken to be a
separate bar graph plotted on the same graph. By default the columns
are plotted side-by-side. This behavior can be changed by the @var{style}
argument, which can take the values 'group' (the default), or 'stack'.

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

@example
bar (x, y);
@end example

@noindent
and

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

@noindent
are equivalent.
@seealso{hbar, plot}
@end deftypefn
barh
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} barh (@var{x}, @var{y}, @var{style})
@deftypefnx {Function File} {[@var{xb}, @var{yb}] =} barh (@dots{})
Given two vectors of x-y data, @code{bar} produce a horizontal 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 @var{y} is a matrix, then each column of @var{y} is taken to be a
separate bar graph plotted on the same graph. By default the columns
are plotted side-by-side. This behavior can be changed by the @var{style}
argument, which can take the values 'group' (the default), or 'stack'.

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

@example
barh (x, y);
@end example

@noindent
and

@example
[xb, yb] = barh (x, y);
plot (xb, yb);
@end example

@noindent
are equivalent.
@seealso{bar, plot}
@end deftypefn
box
-*- texinfo -*-
@deftypefn {Function File} {} box (@var{arg})
@deftypefnx {Function File} {} box (@var{h}, @dots{})
Control the display of a border around the plot.
The argument may be either @code{"on"} or @code{"off"}.  If it is
omitted, the current box state is toggled.
@seealso{grid}
@end deftypefn
clf
-*- texinfo -*-
@deftypefn {Function File} {} clf ()
Clear the current figure.
@seealso{close, delete}
@end deftypefn
close
-*- texinfo -*-
@deftypefn {Command} {} close
@deftypefnx {Command} {} close (@var{n})
@deftypefnx {Command} {} close all
@deftypefnx {Command} {} close all hidden
Close figure window(s) by calling the function specified by the
@code{"closerequestfcn"} property for each figure.  By default, the
function @code{closereq} is used.
@seealso{closereq}
@end deftypefn
closereq
-*- texinfo -*-
@deftypefn {Function File} {} closereq ()
Close the current figure and delete all graphics objects associated
with it.
@seealso{close, delete}
@end deftypefn
contour
-*- texinfo -*-
@deftypefn {Function File} {@var{c} =} contour (@var{z})
@deftypefnx {Function File} {@var{c} =} contour (@var{z}, @var{vn})
@deftypefnx {Function File} {@var{c} =} contour (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {@var{c} =} contour (@var{x}, @var{y}, @var{z}, @var{vn})
Plot level curves (contour lines) of the matrix @var{z}, using the
contour matrix @var{c} computed by @code{contourc} from the same
arguments; see the latter for their interpretation.  The set of
contour levels, @var{c}, is only returned if requested.  For example:

@example
@group
x = 0:2;
y = x;
z = x' * y;
contour (x, y, z, 2:3)

@end group
@end example
@seealso{contourc, line, plot}
@end deftypefn
contourc
-*- texinfo -*-
@deftypefn {Function File} {[@var{c}, @var{lev}] =}  contourc (@var{x}, @var{y}, @var{z}, @var{vn})
Compute isolines (countour lines) of the matrix @var{z}. 
Parameters @var{x}, @var{y} and @var{vn} are optional.

The return value @var{lev} is a vector of the contour levels.
The return value @var{c} is a 2 by @var{n} matrix containing the
contour lines in the following format

@example
@var{c} = [lev1, x1, x2, ..., levn, x1, x2, ... 
     len1, y1, y2, ..., lenn, y1, y2, ...]
@end example

@noindent
in which contour line @var{n} has a level (height) of @var{levn} and
length of @var{lenn}.

If @var{x} and @var{y} are omitted they are taken as the row/column 
index of @var{z}.  @var{vn} is either a scalar denoting the number of lines 
to compute or a vector containing the values of the lines. If only one 
value is wanted, set @code{@var{vn} = [val, val]};
If @var{vn} is omitted it defaults to 10.

For example,
@example
@group
x = 0:2;
y = x;
z = x' * y;
contourc (x, y, z, 2:3)
@result{}   2.0000   2.0000   1.0000   3.0000   1.5000   2.0000
     2.0000   1.0000   2.0000   2.0000   2.0000   1.5000

@end group
@end example
@seealso{contour}
@end deftypefn
drawnow
-*- texinfo -*-
@deftypefn {Function File} {} drawnow ()
Update and display the current graphics.

Octave automatically calls drawnow just before printing a prompt,
when @code{sleep} or @code{pause} is called, or while waiting for
command-line input.
@end deftypefn
errorbar
-*- texinfo -*-
@deftypefn {Function File} {} errorbar (@var{args})
This function produces two-dimensional plots with errorbars. Many
different combinations of arguments are possible.  The simplest form is

@example
errorbar (@var{y}, @var{ey})
@end example

@noindent
where the first argument is taken as the set of @var{y} coordinates
and the second argument @var{ey} is taken as the errors of the
@var{y} values. @var{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

@example
errorbar (@var{x}, @var{y}, @dots{}, @var{fmt}, @dots{})
@end example

@noindent
where after @var{x} and @var{y} there can be up to four error
parameters such as @var{ey}, @var{ex}, @var{ly}, @var{uy} etc.,
depending on the plot type. Any number of argument sets may appear,
as long as they are separated with a format string @var{fmt}.

If @var{y} is a matrix, @var{x} and error parameters must also be matrices
having same dimensions. The columns of @var{y} are plotted versus the
corresponding columns of @var{x} and errorbars are drawn from
the corresponding columns of error parameters.

If @var{fmt} is missing, yerrorbars ("~") plot style is assumed.

If the @var{fmt} argument is supplied, it is interpreted as in
normal plots. In addition the following plot styles are supported by
errorbar:

@table @samp
@item ~
Set yerrorbars plot style (default).

@item >
Set xerrorbars plot style.

@item ~>
Set xyerrorbars plot style.

@item #
Set boxes plot style.

@item #~
Set boxerrorbars plot style.

@item #~>
Set boxxyerrorbars plot style.
@end table

Examples:

@example
errorbar (@var{x}, @var{y}, @var{ex}, ">")
@end example

produces an xerrorbar plot of @var{y} versus @var{x} with @var{x}
errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}.

@example
errorbar (@var{x}, @var{y1}, @var{ey}, "~",
@var{x}, @var{y2}, @var{ly}, @var{uy})
@end example

produces yerrorbar plots with @var{y1} and @var{y2} versus @var{x}.
Errorbars for @var{y1} are drawn from @var{y1}-@var{ey} to
@var{y1}+@var{ey}, errorbars for @var{y2} from @var{y2}-@var{ly} to
@var{y2}+@var{uy}.

@example
errorbar (@var{x}, @var{y}, @var{lx}, @var{ux},
@var{ly}, @var{uy}, "~>")
@end example

produces an xyerrorbar plot of @var{y} versus @var{x} in which
@var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux}
and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}.
@seealso{semilogxerr, semilogyerr, loglogerr}
@end deftypefn
figure
-*- texinfo -*-
@deftypefn {Function File} {} figure (@var{n})
@deftypefnx {Function File} {} figure (@var{n}, @var{property}, @var{value}, @dots{})
Set the current plot window to plot window @var{n}.  If no arguments are
specified, the next available window number is chosen.

Multiple property-value pairs may be specified for the figure, but they
must appear in pairs.
@end deftypefn
fplot
-*- texinfo -*-
@deftypefn {Function File} {} fplot (@var{fn}, @var{limits})
@deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{tol})
@deftypefnx {Function File} {} fplot (@var{fn}, @var{limits}, @var{n})
@deftypefnx {Function File} {} fplot (@dots{}, @var{fmt})
Plot a function @var{fn}, within the defined limits.  @var{fn}
an be either a string, a function handle or an inline function.
The limits of the plot are given by @var{limits} of the form
@code{[@var{xlo}, @var{xhi}]} or @code{[@var{xlo}, @var{xhi},
@var{ylo}, @var{yhi}]}. @var{tol} is the default tolerance to use for the
plot, and if @var{tol} is an integer it is assumed that it defines the 
number points to use in the plot.  The @var{fmt} argument is passed
to the plot command.

@example
   fplot ("cos", [0, 2*pi])
   fplot ("[cos(x), sin(x)]", [0, 2*pi])
@end example
@seealso{plot}
@end deftypefn
gca
-*- texinfo -*-
@deftypefn {Function File} {} gca ()
Return a handle to the current axis object.  If no axis object
exists, create one and return its handle.  The handle may then be
used to examine or set properties of the axes.  For example,

@example
@group
ax = gca ();
set (ax, "position", [0.5, 0.5, 0.5, 0.5]);
@end group
@end example

@noindent
creates an empty axes object, then changes its location and size in
the figure window.
@seealso{get, set}
@end deftypefn
gcf
-*- texinfo -*-
@deftypefn {Function File} {} gcf ()
Return the current figure handle.  If a figure does not exist, create
one and return its handle.  The handle may then be used to examine or
set properties of the figure.  For example,

@example
@group
fplot (@@sin, [-10, 10]);
fig = gcf ();
set (fig, "visible", "off");
@end group
@end example

@noindent
plots a sine wave, finds the handle of the current figure, and then
makes that figure invisible.  Setting the visible property of the
figure to @code{"on"} will cause it to be displayed again.
@seealso{get, set}
@end deftypefn
grid
-*- texinfo -*-
@deftypefn {Function File} {} grid (@var{arg})
@deftypefnx {Function File} {} grid ("minor", @var{arg2})
Force the display of a grid on the plot.
The argument may be either @code{"on"} or @code{"off"}.  If it is
omitted, the current grid state is toggled.

If @var{arg} is @code{"minor"} then the minor grid is toggled.  When
using a minor grid a second argument @var{arg2} is allowed, which can
be either @code{"on"} or @code{"off"} to explicitly set the state of
the minor grid.
@seealso{plot}
@end deftypefn
hist
-*- texinfo -*-
@deftypefn {Function File} {} hist (@var{y}, @var{x}, @var{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 @var{norm}.

Extreme values are lumped in the first and last bins.

With two output arguments, produce the values @var{nn} and @var{xx} such
that @code{bar (@var{xx}, @var{nn})} will plot the histogram.
@seealso{bar}
@end deftypefn
hold
-*- texinfo -*-
@deftypefn {Function File} {} hold @var{args}
Tell Octave to `hold' the current data on the plot when executing
subsequent plotting commands.  This allows you to execute a series of
plot commands and have all the lines end up on the same figure.  The
default is for each new plot command to clear the plot device first.
For example, the command

@example
hold on
@end example

@noindent
turns the hold state on.  An argument of @code{"off"} turns the hold
state off, and @code{hold} with no arguments toggles the current hold
state.
@end deftypefn
isfigure
-*- texinfo -*-
@deftypefn {Function File} {} isfigure (@var{h})
Return true if @var{h} is a graphics handle that contains a figure
object and false otherwise.
@end deftypefn
ishold
-*- texinfo -*-
@deftypefn {Function File} {} ishold
Return true if the next line will be added to the current plot, or
false if the plot device will be cleared before drawing the next line.
@end deftypefn
legend
-*- texinfo -*-
@deftypefn {Function File} {} legend (@var{st1}, @var{st2}, @dots{})
@deftypefnx {Function File} {} legend (@var{st1}, @var{st2}, @dots{}, @var{pos})
@deftypefnx {Function File} {} legend (@var{matstr})
@deftypefnx {Function File} {} legend (@var{matstr}, @var{pos})
@deftypefnx {Function File} {} legend (@var{cell})
@deftypefnx {Function File} {} legend (@var{cell}, @var{pos})
@deftypefnx {Function File} {} legend ('@var{func}')

Display a legend for the current axes using the specified strings
as labels.  Legend entries may be specified as individual character
string arguments, a character array, or a cell array of character
strings.  Legend works on line graphs, bar graphs, etc.  A plot must
exist before legend is called.

The optional parameter @var{pos} specifies the location of the legend
as follows:

@multitable @columnfractions 0.1 0.1 0.8
@item @tab -1 @tab
  To the top right of the plot
@item @tab 0 @tab
  Don't move the legend box (default)
@item @tab 1 @tab
  Upper right-hand corner
@item @tab 2 @tab
  Upper left-hand corner
@item @tab 3 @tab
  Lower left-hand corner
@item @tab 4 @tab
  Lower right-hand corner
@end multitable

Some specific functions are directely avaliable using @var{func}:

@table @code
@item "show"
  Show legends from the plot
@item "hide"
@itemx off
  Hide legends from the plot
@item "boxon"
  Draw a box around legends
@item "boxoff"
  Withdraw the box around legends
@item "left"
  Text is to the left of the keys
@item "right"
  Text is to the right of the keys
@end table
@end deftypefn
line
-*- texinfo -*-
@deftypefn {Function File} {} line ()
@deftypefnx {Function File} {} line (@var{x}, @var{y})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {} line (@var{x}, @var{y}, @var{z}, @var{property}, @var{value}, @dots{})
Create line object from @var{x} and @var{y} and insert in current
axes object.  Return a handle (or vector of handles) to the line
objects created.

Multiple property-value pairs may be specified for the line, but they
must appear in pairs.
@end deftypefn
loglog
-*- texinfo -*-
@deftypefn {Function File} {} loglog (@var{args})
Produce a two-dimensional plot using log scales for both axes.  See
the description of @code{plot} for a description of the arguments
that @code{loglog} will accept.
@seealso{plot, semilogx, semilogy}
@end deftypefn
loglogerr
-*- texinfo -*-
@deftypefn {Function File} {} loglogerr (@var{args})
Produce two-dimensional plots on double logarithm axis with
errorbars.  Many different combinations of arguments are possible.
The most used form is

@example
loglogerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a double logarithm plot of @var{y} versus @var{x} 
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}. See errorbar for available formats and 
additional information.
@seealso{errorbar, semilogxerr, semilogyerr}
@end deftypefn
mesh
-*- texinfo -*-
@deftypefn {Function File} {} mesh (@var{x}, @var{y}, @var{z})
Plot a mesh given matrices @var{x}, and @var{y} from @code{meshgrid} and
a matrix @var{z} corresponding to the @var{x} and @var{y} coordinates of
the mesh.  If @var{x} and @var{y} are vectors, then a typical vertex
is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, columns of @var{z}
correspond to different @var{x} values and rows of @var{z} correspond
to different @var{y} values.
@seealso{meshgrid, contour}
@end deftypefn
meshc
-*- texinfo -*-
@deftypefn {Function File} {} meshc (@var{x}, @var{y}, @var{z})
Plot a mesh and contour given matrices @var{x}, and @var{y} from 
@code{meshgrid} and a matrix @var{z} corresponding to the @var{x} and 
@var{y} coordinates of the mesh.  If @var{x} and @var{y} are vectors, 
then a typical vertex is (@var{x}(j), @var{y}(i), @var{z}(i,j)).  Thus, 
columns of @var{z} correspond to different @var{x} values and rows of 
@var{z} correspond to different @var{y} values.
@seealso{meshgrid, mesh, contour}
@end deftypefn
meshgrid
-*- texinfo -*-
@deftypefn {Function File} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z})
@deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y})
@deftypefnx {Function File} {[@var{xx}, @var{yy}] =} meshgrid (@var{x})
Given vectors of @var{x} and @var{y} and @var{z} coordinates, and
returning 3 arguments, return three dimensional arrays corresponding
to the @var{x}, @var{y}, and @var{z} coordinates of a mesh.  When
returning only 2 arguments, return matrices corresponding to the
@var{x} and @var{y} coordinates of a mesh.  The rows of @var{xx} are
copies of @var{x}, and the columns of @var{yy} are copies of @var{y}.
If @var{y} is omitted, then it is assumed to be the same as @var{x},
and @var{z} is assumed the same as @var{y}.
@seealso{mesh, contour}
@end deftypefn
ndgrid
-*- texinfo -*-
@deftypefn {Function File} {[@var{y1}, @var{y2}, @dots{},  @var{y}n] =} ndgrid (@var{x1}, @var{x2}, @dots{}, @var{x}n)
@deftypefnx {Function File} {[@var{y1}, @var{y2}, @dots{},  @var{y}n] =} ndgrid (@var{x})
Given n vectors @var{x1}, @dots{} @var{x}n, @code{ndgrid} returns
n arrays of dimension n.  The elements of the ith output argument
contains the elements of the vector @var{x}i repeated over all
dimensions different from the ith dimension.  Calling ndgrid with
only one input argument @var{x} is equivalent of calling ndgrid with
all n input arguments equal to @var{x}:

[@var{y1}, @var{y2}, @dots{},  @var{y}n] = ndgrid (@var{x}, @dots{}, @var{x})
@seealso{meshgrid}
@end deftypefn
newplot
-*- texinfo -*-
@deftypefn {Function File} {} newplot ()
Prepare graphics engine to produce a new plot.  This function should
be called at the beginning of all high-level plotting functions.
@end deftypefn
orient
-*- texinfo -*-
@deftypefn {Function File} {} orient (@var{orientation})
Set the default print orientation.  Valid values for
@var{orientation} include @code{"landscape"} and @code{"portrait"}.
If called with no arguments, return the default print orientation.
@end deftypefn
patch
-*- texinfo -*-
@deftypefn {Function File} {} patch ()
@deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{c})
@deftypefnx {Function File} {} patch (@var{x}, @var{y}, @var{c}, @var{opts})
Create patch object from @var{x} and @var{y} with color @var{c} and
insert in the current axes object.  Return handle to patch object.

For a uniform colored patch, @var{c} can be given as an RGB vector,
scalar value referring to the current colormap, or string value (for
example, "r" or "red"). 
@end deftypefn
peaks
-*- texinfo -*-
@deftypefn {Function File} {} peaks ()
@deftypefnx {Function File} {} peaks (@var{n})
@deftypefnx {Function File} {} peaks (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} peaks (@dots{})
@deftypefnx {Function File} {[@var{x}, @var{y}, @var{z}] =} peaks (@dots{})
Generate a function with lots of local maxima and minima. The function
has the form

@iftex
@tex
$f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5)\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$
@end tex
@end iftex
@ifnottex
@verbatim
f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ...
         - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ...
         - 1/3*exp(-(x+1)^2 - y^2)
@end verbatim
@end ifnottex

Called without a return argument, @code{peaks} plots the surface of the 
above function using @code{mesh}. If @var{n} is a scalar, the @code{peaks}
returns the values of the above funxtion on a @var{n}-by-@var{n} mesh over
the range @code{[-3,3]}. The default value for @var{n} is 49.

If @var{n} is a vector, then it represents the @var{x} and @var{y} values
of the grid on which to calculate the above function. The @var{x} and 
@var{y} values can be specified separately.
@seealso{mesh}
@end deftypefn
plot
-*- texinfo -*-
@deftypefn {Function File} {} plot (@var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@deftypefnx {Function File} {} plot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} plot (@var{h}, @dots{})
Produces two-dimensional plots.  Many different combinations of
arguments are possible.  The simplest form is

@example
plot (@var{y})
@end example

@noindent
where the argument is taken as the set of @var{y} coordinates and the
@var{x} coordinates are taken to be the indices of the elements,
starting with 1.

To save a plot, in one of several image formats such as PostScript
or PNG, use the @code{print} command.

If more than one argument is given, they are interpreted as

@example
plot (@var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{})
@end example

@noindent
or

@example
plot (@var{x}, @var{y}, @var{fmt}, @dots{})
@end example

@noindent
and so on.  Any number of argument sets may appear.  The @var{x} and
@var{y} values are interpreted as follows:

@itemize @bullet
@item
If a single data argument is supplied, it is taken as the set of @var{y}
coordinates and the @var{x} coordinates are taken to be the indices of
the elements, starting with 1.

@item
If the @var{x} is a vector and @var{y} is a matrix, then
the columns (or rows) of @var{y} are plotted versus @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If the @var{x} is a matrix and @var{y} is a vector,
@var{y} is plotted versus the columns (or rows) of @var{x}.
(using whichever combination matches, with columns tried first.)

@item
If both arguments are vectors, the elements of @var{y} are plotted versus
the elements of @var{x}.

@item
If both arguments are matrices, the columns of @var{y} are plotted
versus the columns of @var{x}.  In this case, both matrices must have
the same number of rows and columns and no attempt is made to transpose
the arguments to make the number of rows match.

If both arguments are scalars, a single point is plotted.
@end itemize

Multiple property-value pairs may be specified, but they must appear
in pairs.  These arguments are applied to the lines drawn by
@code{plot}.

If the @var{fmt} argument is supplied, it is interpreted as
follows.  If @var{fmt} is missing, the default gnuplot line style
is assumed.

@table @samp
@item -
Set lines plot style (default).

@item .
Set dots plot style.

@item ^
Set impulses plot style.

@item L
Set steps plot style.

@item @var{n}
Interpreted as the plot color if @var{n} is an integer in the range 1 to
6.

@item @var{nm}
If @var{nm} is a two digit integer and @var{m} is an integer in the
range 1 to 6, @var{m} is interpreted as the point style.  This is only
valid in combination with the @code{@@} or @code{-@@} specifiers.

@item @var{c}
If @var{c} is one of @code{"k"} (black), @code{"r"} (red), @code{"g"}
(green), @code{"b"} (blue), @code{"m"} (magenta), @code{"c"} (cyan),
or @code{"w"} (white), it is interpreted as the line plot color.

@item ";title;"
Here @code{"title"} is the label for the key.

@item +
@itemx *
@itemx o
@itemx x
Used in combination with the points or linespoints styles, set the point
style.
@end table

The @var{fmt} argument may also be used to assign key titles.
To do so, include the desired title between semi-colons after the
formatting sequence described above, e.g. "+3;Key Title;"
Note that the last semi-colon is required and will generate an error if
it is left out.

Here are some plot examples:

@example
plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+")
@end example

This command will plot @code{y} with points of type 2 (displayed as
@samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of
color 4 (magenta) and @code{y4} with points displayed as @samp{+}.

@example
plot (b, "*", "markersize", 3)
@end example

This command will plot the data in the variable @code{b},
with points displayed as @samp{*} with a marker size of 3.

@example
t = 0:0.1:6.3;
plot (t, cos(t), "-;cos(t);", t, sin(t), "+3;sin(t);");
@end example

This will plot the cosine and sine functions and label them accordingly
in the key.

If the first argument is an axis handle, then plot into these axes, 
rather than the current axis handle returned by @code{gca}. 
@seealso{semilogx, semilogy, loglog, polar, mesh, contour, bar,
stairs, errorbar, xlabel, ylabel, title, print}
@end deftypefn
plot3
-*- texinfo -*-
@deftypefn {Function File} {} plot3 (@var{args})
Produce three-dimensional plots.  Many different combinations of
arguments are possible.  The simplest form is

@example
plot3 (@var{x}, @var{y}, @var{z})
@end example

@noindent
in which the arguments are taken to be the vertices of the points to
be plotted in three dimensions. If all arguments are vectors of the
same length, then a single continuous line is drawn. If all arguments
are matrices, then each column of the matrices is treated as a
seperate line.  No attempt is made to transpose the arguments to make
the number of rows match.

If only two arguments are given, as

@example
plot3 (@var{x}, @var{c})
@end example

@noindent
the real and imaginary parts of the second argument are used
as the @var{y} and @var{z} coordinates, respectively.

If only one argument is given, as

@example
plot3 (@var{c})
@end example

@noindent
the real and imaginary parts of the argument are used as the @var{y}
and @var{z} values, and they are plotted versus their index.

Arguments may also be given in groups of three as

@example
plot3 (@var{x1}, @var{y1}, @var{z1}, @var{x2}, @var{y2}, @var{z2}, @dots{})
@end example

@noindent
in which each set of three arguments is treated as a seperate line or
set of lines in three dimensions.

To plot multiple one- or two-argument groups, separate each group
with an empty format string, as

@example
plot3 (@var{x1}, @var{c1}, "", @var{c2}, "", @dots{})
@end example

An example of the use of @code{plot3} is

@example
@group
   z = [0:0.05:5];
   plot3 (cos(2*pi*z), sin(2*pi*z), z, ";helix;");
   plot3 (z, exp(2i*pi*z), ";complex sinusoid;");
@end group
@end example
@seealso{plot}
@end deftypefn
polar
-*- texinfo -*-
@deftypefn {Function File} {} polar (@var{theta}, @var{rho}, @var{fmt})
Make a two-dimensional plot given polar the coordinates @var{theta} and
@var{rho}.

The optional third argument specifies the line type.
@seealso{plot}
@end deftypefn
print
-*- texinfo -*-
@deftypefn {Function File} {} print (@var{filename}, @var{options})
Print a graph, or save it to a file

@var{filename} defines the file name of the output file. If no
filename is specified, output is sent to the printer.

@var{options}:
@table @code
@item -P@var{printer}
  Set the @var{printer} name to which the graph is sent if no
@var{filename} is specified.
@item -color
@itemx -mono
  Monochrome or colour lines.
@item -solid
@itemx -dashed
  Solid or dashed lines.
@item -portrait
@itemx -landscape
  Plot orientation, as returned by "orient".
@item -d@var{device}
  Output device, where @var{device} is one of:
@table @code
@item ps
@itemx ps2
@itemx psc
@itemx psc2
    Postscript (level 1 and 2, mono and color)
@item eps
@itemx eps2
@itemx epsc
@itemx epsc2
    Encapsulated postscript (level 1 and 2, mono and color)
@item tex
@itemx epslatex
@itemx epslatexstandalone
@itemx pstex
@itemx pslatex
    Generate a LaTeX (or TeX) file for labels, and eps/ps for
    graphics.  The file produced by @code{epslatexstandalone} can be
    processed directly by LaTeX.  The other formats are intended to
    be included in a LaTeX (or TeX) document.  The @code{tex} device
    is the same as the @code{epslatex} device.
@item ill
@itemx aifm
    Adobe Illustrator
@item cdr
@itemx corel
    CorelDraw
@item hpgl
    HP plotter language
@item fig
    XFig
@item dxf
    AutoCAD
@item mf
    Metafont
@item png
    Portable network graphics
@item pbm
    PBMplus
@item emf
    Microsoft Enhanced Metafile
@end table

  Other devices are supported by "convert" from ImageMagick.  Type
  system("convert") to see what formats are available.

  If the device is omitted, it is inferred from the file extension,
  or if there is no filename it is sent to the printer as postscript.

@item -F@var{fontname}
@itemx -F@var{fontname}:@var{size}
@itemx -F:@var{size}
@var{fontname} set the postscript font (for use with postscript,
  aifm, corel and fig). By default, 'Helvetica' is set for PS/Aifm,
  and 'SwitzerlandLight' for Corel. It can also be 'Times-Roman'.
@var{size} is given in points. @var{fontname} is ignored for the
  fig device.
@end table

The filename and options can be given in any order.
@end deftypefn
replot
-*- texinfo -*-
@deftypefn {Function File} {} replot ()
Refresh the plot window.
@end deftypefn
semilogx
-*- texinfo -*-
@deftypefn {Function File} {} semilogx (@var{args})
Produce a two-dimensional plot using a log scale for the @var{x}
axis.  See the description of @code{plot} for a description of the
arguments that @code{semilogx} will accept.
@seealso{plot, semilogy, loglog}
@end deftypefn
semilogxerr
-*- texinfo -*-
@deftypefn {Function File} {} semilogxerr (@var{args})
Produce two-dimensional plots on a semilogarithm axis with errorbars.
Many different combinations of arguments are possible.  The most used
form is

@example
semilogxerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithm plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}. See errorbar for available formats and 
additional information.
@seealso{errorbar, loglogerr semilogyerr}
@end deftypefn
semilogy
-*- texinfo -*-
@deftypefn {Function File} {} semilogy (@var{args})
Produce a two-dimensional plot using a log scale for the @var{y}
axis.  See the description of @code{plot} for a description of the
arguments that @code{semilogy} will accept.
@seealso{plot, semilogx, loglog}
@end deftypefn
semilogyerr
-*- texinfo -*-
@deftypefn {Function File} {} semilogyerr (@var{args})
Produce two-dimensional plots on a semilogarithm axis with errorbars.
Many different combinations of arguments are possible.  The most used
form is

@example
semilogyerr (@var{x}, @var{y}, @var{ey}, @var{fmt})
@end example

@noindent
which produces a semi-logarithm plot of @var{y} versus @var{x}
with errors in the @var{y}-scale defined by @var{ey} and the plot
format defined by @var{fmt}.  See errorbar for available formats and 
additional information.
@seealso{errorbar, loglogerr semilogxerr}
@end deftypefn
shg
-*- texinfo -*-
@deftypefn {Function File} {} shg
Show the graph window.  Currently, this is the same as executing
@code{drawnow}.
@seealso{drawnow, figure}
@end deftypefn
sombrero
-*- texinfo -*-
@deftypefn {Function File} {} sombrero (@var{n})
Produce the familiar three-dimensional sombrero plot using @var{n}
grid lines.  If @var{n} is omitted, a value of 41 is assumed.

The function plotted is

@example
z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example
@seealso{mesh, meshgrid}
@end deftypefn
stairs
-*- texinfo -*-
@deftypefn {Function File} {} stairs (@var{x}, @var{y})
Produce a stairstep plot.  The arguments may be vectors or matrices.

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,

@example
stairs (x, y);
@end example

@noindent
and

@example
@group
[xs, ys] = stairs (x, y);
plot (xs, ys);
@end group
@end example

@noindent
are equivalent.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, xlabel, ylabel, title}
@end deftypefn
stem
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} stem (@var{x}, @var{y}, @var{linespec})
Plot a stem graph and return the handles of the line and marker
objects used to draw the stems.  The default color is @code{"r"}
(red).  The default line style is @code{"-"} and the default marker is
@code{"o"}.

For example,
@example
x = 1:10;
stem (x);
@end example
@noindent
plots 10 stems with heights from 1 to 10;

@example
x = 1:10;
y = ones (1, length (x))*2.*x;
stem (x, y);
@end example
@noindent
plots 10 stems with heights from 2 to 20;

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "b");
@end example
@noindent
plots 10 bars with heights from 2 to 20
(the color is blue, and @var{h} is a 2-by-10 array of handles in
which the first row holds the line handles and the 
the second row holds the marker handles);

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "-.k");
@end example
@noindent
plots 10 stems with heights from 2 to 20
(the color is black, line style is @code{"-."}, and @var{h} is a 2-by-10
array of handles in which the first row holds the line handles and
the second rows holds the marker handles);

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "-.k.");
@end example
@noindent
plots 10 stems with heights from 2 to 20
(the color is black, line style is @code{"-."} and the marker style
is @code{"."}, and @var{h} is a 2-by-10 array of handles in which the
first row holds the line handles and the second row holds the marker
handles);

@example
x = 1:10;
y = ones (size (x))*2.*x;
h = stem (x, y, "fill");
@end example
@noindent
plots 10 stems with heights from 2 to 20
(the color is rgb-triple defined, the line style is @code{"-"},
the marker style is @code{"o"}, and @var{h} is a 2-by-10 array of
handles in which the first row holds the line handles and the second
row holds the marker handles).

Color definitions with rgb-triples are not valid!
@seealso{bar, barh, plot}
@end deftypefn
subplot
-*- texinfo -*-
@deftypefn {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {Function File} {} subplot (@var{rcn})
Set up a plot grid with @var{cols} by @var{rows} subwindows and plot
in location given by @var{index}.

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 2 by 3 grid will have plot indices running as
follows:
@iftex
@tex
\vskip 10pt
\hfil\vbox{\offinterlineskip\hrule
\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr
height13pt&1&2&3&4\cr height12pt&&&&\cr\noalign{\hrule}
height13pt&5&6&7&8\cr height12pt&&&&\cr\noalign{\hrule}}}
\hfil
\vskip 10pt
@end tex
@end iftex
@ifinfo
@display
@group
@example

+-----+-----+-----+-----+
|  1  |  2  |  3  |  4  |
+-----+-----+-----+-----+
|  5  |  6  |  7  |  8  |
+-----+-----+-----+-----+
@end example
@end group
@end display
@end ifinfo
@seealso{plot}
@end deftypefn
text
-*- texinfo -*-
@deftypefn {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{label}, @var{p1}, @var{v1}, @dots{})
@deftypefnx {Function File} {@var{h} =} text (@var{x}, @var{y}, @var{z}, @var{label}, @var{p1}, @var{v1}, @dots{})
Create a text object with text @var{label} at position @var{x},
@var{y}, @var{z} on the current axes.  Property-value pairs following
@var{label} may be used to specify the appearance of the text.
@end deftypefn
title
-*- texinfo -*-
@deftypefn {Function File} {} title (@var{title})
Create a title object and return a handle to it.
@end deftypefn
view
-*- texinfo -*-
@deftypefn {Function File} {} view (@var{azimuth}, @var{elevation})
@deftypefnx {Function File} {} view (@var{dims})
@deftypefnx {Function File} {[@var{azimuth}, @var{elevation}] =} view ()
Set or get the viewpoint for the current axes.
@end deftypefn
xlabel
-*- texinfo -*-
@deftypefn {Function File} {} xlabel (@var{string})
@deftypefnx {Function File} {} ylabel (@var{string})
@deftypefnx {Function File} {} zlabel (@var{string})
Specify x, y, and z axis labels for the current figure.
@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs,  ylabel, title}
@end deftypefn
ylabel
-*- texinfo -*-
@deftypefn {Function File} {} ylabel (@var{string})
See xlabel.
@end deftypefn
zlabel
-*- texinfo -*-
@deftypefn {Function File} {} zlabel (@var{string})
See xlabel.
@end deftypefn
compan
-*- texinfo -*-
@deftypefn {Function File} {} compan (@var{c})
Compute the companion matrix corresponding to polynomial coefficient
vector @var{c}.

The companion matrix is
@iftex
@tex
$$
A = \left[\matrix{
 -c_2/c_1 & -c_3/c_1 & \cdots & -c_N/c_1 & -c_{N+1}/c_1\cr
     1    &     0    & \cdots &     0    &         0   \cr
     0    &     1    & \cdots &     0    &         0   \cr
  \vdots  &   \vdots & \ddots &  \vdots  &      \vdots \cr
     0    &     0    & \cdots &     1    &         0}\right].
$$
@end tex
@end iftex
@ifnottex

@smallexample
     _                                                        _
    |  -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     _|
@end smallexample
@end ifnottex

The eigenvalues of the companion matrix are equal to the roots of the
polynomial.
@seealso{poly, roots, residue, conv, deconv, polyval, polyderiv,
polyinteg}
@end deftypefn
conv
-*- texinfo -*-
@deftypefn {Function File} {} conv (@var{a}, @var{b})
Convolve two vectors.

@code{y = conv (a, b)} returns a vector of length equal to
@code{length (a) + length (b) - 1}.
If @var{a} and @var{b} are polynomial coefficient vectors, @code{conv}
returns the coefficients of the product polynomial.
@seealso{deconv, poly, roots, residue, polyval, polyderiv, polyinteg}
@end deftypefn
deconv
-*- texinfo -*-
@deftypefn {Function File} {} deconv (@var{y}, @var{a})
Deconvolve two vectors.

@code{[b, r] = deconv (y, a)} solves for @var{b} and @var{r} such that
@code{y = conv (a, b) + r}.

If @var{y} and @var{a} are polynomial coefficient vectors, @var{b} will
contain the coefficients of the polynomial quotient and @var{r} will be
a remander polynomial of lowest order.
@seealso{conv, poly, roots, residue, polyval, polyderiv, polyinteg}
@end deftypefn
mkpp
-*- texinfo -*-
@deftypefn {Function File} {@var{pp} = } mkpp (@var{x}, @var{p})
@deftypefnx {Function File} {@var{pp} = } mkpp (@var{x}, @var{p}, @var{d})

Construct a piece-wise polynomial structure from sample points
@var{x} and coefficients @var{p}.  The ith row of @var{p},
@code{@var{p} (@var{i},:)}, contains the coefficients for the polynomial
over the @var{i}-th interval, ordered from highest to 
lowest. There must be one row for each interval in @var{x}, so 
@code{rows (@var{p}) == length (@var{x}) - 1}.  

You can concatenate multiple polynomials of the same order over the 
same set of intervals using @code{@var{p} = [ @var{p1}; @var{p2}; 
@dots{}; @var{pd} ]}.  In this case, @code{rows (@var{p}) == @var{d} 
* (length (@var{x}) - 1)}.

@var{d} specifies the shape of the matrix @var{p} for all except the
last dimension. If @var{d} is not specified it will be computed as
@code{round (rows (@var{p}) / (length (@var{x}) - 1))} instead.

@seealso{unmkpp, ppval, spline}
@end deftypefn
pchip
-*- texinfo -*-
@deftypefn {Function File} {@var{pp} = } pchip (@var{x}, @var{y})
@deftypefnx {Function File} {@var{yi} = } pchip (@var{x}, @var{y}, @var{xi})

Piecewise Cubic Hermite interpolating polynomial. Called with two
arguments, the piece-wise polynomial @var{pp} is returned, that may
later be used with @code{ppval} to evaluate the polynomial at
specific points.

The variable @var{x} must be a strictly monotonic vector (either
increasing or decreasing). While @var{y} can be either a vector or
array. In the case where @var{y} is a vector, it must have a length
of @var{n}. If @var{y} is an array, then the size of @var{y} must
have the form
@iftex
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@end iftex
@ifinfo
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifinfo
The array is then reshaped internally to a matrix where to leading
dimension is given by 
@iftex
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@end iftex
@ifinfo
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifinfo
and each row this matrix is then treated seperately. Note that this
is exactly the opposite treatment than @code{interp1} and is done
for compatiability.

Called with a third input argument, @code{pchip} evaluates the 
piece-wise polynomial at the points @var{xi}. There is an equivalence
between @code{ppval (pchip (@var{x}, @var{y}), @var{xi})} and
@code{pchip (@var{x}, @var{y}, @var{xi})}.

@seealso{spline, ppval, mkpp, unmkpp}
@end deftypefn
poly
-*- texinfo -*-
@deftypefn {Function File} {} poly (@var{a})
If @var{a} is a square @math{N}-by-@math{N} matrix, @code{poly (@var{a})}
is the row vector of the coefficients of @code{det (z * eye (N) - a)},
the characteristic polynomial of @var{a}.  As an example we can use
this to find the eigenvalues of @var{a} as the roots of @code{poly (@var{a})}.
@example
roots(poly(eye(3)))
@result{} 1.00000 + 0.00000i
@result{} 1.00000 - 0.00000i
@result{} 1.00000 + 0.00000i
@end example
In real-life examples you should, however, use the @code{eig} function
for computing eigenvalues.

If @var{x} is a vector, @code{poly (@var{x})} is a vector of coefficients
of the polynomial whose roots are the elements of @var{x}.  That is,
of @var{c} is a polynomial, then the elements of 
@code{@var{d} = roots (poly (@var{c}))} are contained in @var{c}.
The vectors @var{c} and @var{d} are, however, not equal due to sorting
and numerical errors.
@seealso{eig, roots}
@end deftypefn
polyder
-*- texinfo -*-
@deftypefn {Function File} {} polyder (@var{c})
@deftypefnx {Function File} {[@var{q}] =} polyder (@var{b}, @var{a})
@deftypefnx {Function File} {[@var{q}, @var{r}] =} polyder (@var{b}, @var{a})
See polyderiv.
@end deftypefn
polyderiv
-*- texinfo -*-
@deftypefn {Function File} {} polyderiv (@var{c})
@deftypefnx {Function File} {[@var{q}] =} polyderiv (@var{b}, @var{a})
@deftypefnx {Function File} {[@var{q}, @var{r}] =} polyderiv (@var{b}, @var{a})
Return the coefficients of the derivative of the polynomial whose
coefficients are given by vector @var{c}.  If a pair of polynomials
is given @var{b} and @var{a}, the derivative of the product is
returned in @var{q}, or the quotient numerator in @var{q} and the
quotient denominator in @var{r}.
@seealso{poly, polyinteg, polyreduce, roots, conv, deconv, residue,
filter, polygcd, polyval, polyvalm}
@end deftypefn
polyfit
-*- texinfo -*-
@deftypefn {Function File} {[@var{p}, @var{s}] =} polyfit (@var{x}, @var{y}, @var{n})
Return the coefficients of a polynomial @var{p}(@var{x}) of degree
@var{n} that minimizes
@iftex
@tex
$$
\sum_{i=1}^N (p(x_i) - y_i)^2
$$
@end tex
@end iftex
@ifinfo
@code{sumsq (p(x(i)) - y(i))},
@end ifinfo
 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:

@table @code
@item R
The Cholesky factor of the Vandermonde matrix used to compute the
polynomial coefficients.
@item X
The Vandermonde matrix used to compute the polynomial coefficients.
@item df
The degrees of freedom.
@item normr
The norm of the residuals.
@item yf
The values of the polynomial for each value of @var{x}.
@end table
@end deftypefn
polygcd
-*- texinfo -*-
@deftypefn {Function File} {@var{q} =} polygcd (@var{b}, @var{a}, @var{tol})

Find greatest common divisor of two polynomials.  This is equivalent
to the polynomial found by multiplying together all the common roots.
Together with deconv, you can reduce a ratio of two polynomials.
Tolerance defaults to 
@example 
sqrt(eps).
@end example
 Note that this is an unstable
algorithm, so don't try it on large polynomials.

Example
@example
polygcd (poly(1:8), poly(3:12)) - poly(3:8)
@result{} [ 0, 0, 0, 0, 0, 0, 0 ]
deconv (poly(1:8), polygcd (poly(1:8), poly(3:12))) - poly(1:2)
@result{} [ 0, 0, 0 ]
@end example
@seealso{poly, polyinteg, polyderiv, polyreduce, roots, conv, deconv,
residue, filter, polyval, and polyvalm}
@end deftypefn
polyint
-*- texinfo -*-
@deftypefn {Function File} {} polyint (@var{c}, @var{k})
Return the coefficients of the integral of the polynomial whose
coefficients are represented by the vector @var{c}. The variable
@var{k} is the constant of integration, which by default is set to zero.
@seealso{poly, polyderiv, polyreduce, roots, conv, deconv, residue,
filter, polyval, and polyvalm}
@end deftypefn
polyout
-*- texinfo -*-
@deftypefn {Function File} {} polyout (@var{c}, @var{x})
Write formatted polynomial
@iftex
@tex
$$ c(x) = c_1 x^n + \ldots + c_n x + c_{n+1} $$
@end tex
@end iftex
@ifinfo
@example
   c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
@end example
@end ifinfo
 and return it as a string or write it to the screen (if
@var{nargout} is zero).
@var{x} defaults to the string @code{"s"}.
@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, and polyinteg}
@end deftypefn
polyreduce
-*- texinfo -*-
@deftypefn {Function File} {} polyreduce (@var{c})
Reduces a polynomial coefficient vector to a minimum number of terms by
stripping off any leading zeros.
@seealso{poly, roots, conv, deconv, residue, filter, polyval,
polyvalm, polyderiv, polyinteg}
@end deftypefn
polyval
-*- texinfo -*-
@deftypefn {Function File} {} polyval (@var{c}, @var{x})
Evaluate a polynomial.

@code{polyval (@var{c}, @var{x})} will evaluate the polynomial at the
specified value of @var{x}.

If @var{x} is a vector or matrix, the polynomial is evaluated at each of
the elements of @var{x}.
@seealso{polyvalm, poly, roots, conv, deconv, residue, filter,
polyderiv, polyinteg}
@end deftypefn
polyvalm
-*- texinfo -*-
@deftypefn {Function File} {} polyvalm (@var{c}, @var{x})
Evaluate a polynomial in the matrix sense.

@code{polyvalm (@var{c}, @var{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 @var{x} must be a square matrix.
@seealso{polyval, poly, roots, conv, deconv, residue, filter,
polyderiv, and polyinteg}
@end deftypefn
ppval
-*- texinfo -*-
@deftypefn {Function File} {@var{yi} =} ppval (@var{pp}, @var{xi})
Evaluate piece-wise polynomial @var{pp} at the points @var{xi}.  
If @code{@var{pp}.d} is a scalar greater than 1, or an array,
then the returned value @var{yi} will be an array that is 
@code{d1, d1, @dots{}, dk, length (@var{xi})]}.
@seealso{mkpp, unmkpp, spline}
@end deftypefn 
residue
-*- texinfo -*-
@deftypefn {Function File} {} residue (@var{b}, @var{a}, @var{tol})
If @var{b} and @var{a} are vectors of polynomial coefficients, then
residue calculates the partial fraction expansion corresponding to the
ratio of the two polynomials.
@cindex partial fraction expansion

The function @code{residue} returns @var{r}, @var{p}, @var{k}, and
@var{e}, where the vector @var{r} contains the residue terms, @var{p}
contains the pole values, @var{k} contains the coefficients of a direct
polynomial term (if it exists) and @var{e} is a vector containing the
powers of the denominators in the partial fraction terms.

Assuming @var{b} and @var{a} represent polynomials
@iftex
@tex
$P(s)$ and $Q(s)$
@end tex
@end iftex
@ifinfo
 P (s) and Q(s)
@end ifinfo
 we have:
@iftex
@tex
$$
{P(s)\over Q(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m}
  + \sum_{i=1}^N k_i s^{N-i}.
$$
@end tex
@end iftex
@ifinfo

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

@noindent
where @math{M} is the number of poles (the length of the @var{r},
@var{p}, and @var{e} vectors) and @math{N} is the length of the
@var{k} vector.

The argument @var{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 @var{tol}, the
imaginary part is discarded.  If two poles are farther apart than
@var{tol} they are distinct.  For example,

@example
@group
 b = [1, 1, 1];
 a = [1, -5, 8, -4];
 [r, p, k, e] = residue (b, a);
@result{} r = [-2, 7, 3]
@result{} p = [2, 2, 1]
@result{} k = [](0x0)
@result{} e = [1, 2, 1]
@end group
@end example

@noindent
which implies the following partial fraction expansion
@iftex
@tex
$$
{s^2+s+1\over s^3-5s^2+8s-4} = {-2\over s-2} + {7\over (s-2)^2} + {3\over s-1}
$$
@end tex
@end iftex
@ifinfo

@example
        s^2 + s + 1       -2        7        3
   ------------------- = ----- + ------- + -----
   s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)
@end example
@end ifinfo
@seealso{poly, roots, conv, deconv, polyval, polyderiv, and polyinteg}
@end deftypefn
roots
-*- texinfo -*-
@deftypefn {Function File} {} roots (@var{v})

For a vector @var{v} with @math{N} components, return
the roots of the polynomial
@iftex
@tex
$$
v_1 z^{N-1} + \cdots + v_{N-1} z + v_N.
$$
@end tex
@end iftex
@ifnottex

@example
v(1) * z^(N-1) + ... + v(N-1) * z + v(N)
@end example
@end ifnottex

As an example, the following code finds the roots of the quadratic
polynomial
@iftex
@tex
$$ p(x) = x^2 - 5. $$
@end tex
@end iftex
@ifnottex
@example
p(x) = x^2 - 5.
@end example
@end ifnottex
@example
c = [1, 0, -5];
roots(c)
@result{}  2.2361
@result{} -2.2361
@end example
Note that the true result is
@iftex
@tex
$\pm \sqrt{5}$
@end tex
@end iftex
@ifnottex
@math{+/- sqrt(5)}
@end ifnottex
which is roughly
@iftex
@tex
$\pm 2.2361$.
@end tex
@end iftex
@ifnottex
@math{+/- 2.2361}.
@end ifnottex
@seealso{compan}
@end deftypefn
spline
-*- texinfo -*-
@deftypefn {Function File} {@var{pp} = } spline (@var{x}, @var{y})
@deftypefnx {Function File} {@var{yi} = } spline (@var{x}, @var{y}, @var{xi})

Returns the cubic spline interpolation of @var{y} at the point
@var{x}. Called with two arguments the piece-wise polynomial @var{pp}
that may later be used with @code{ppval} to evaluate the polynomial
at specific points.

The variable @var{x} must be a vector of length @var{n}, and @var{y}
can be either a vector or array. In the case where @var{y} is a
vector, it can have a length of either @var{n} or @code{@var{n} + 2}.
If the length of @var{y} is @var{n}, then the 'not-a-knot' end
condition is used. If the length of @var{y} is @code{@var{n} + 2},
then the first and last values of the vector @var{y} are the first
derivative of the cubic spline at the end-points.

If @var{y} is an array, then the size of @var{y} must have the form
@iftex
@tex
$$[s_1, s_2, \cdots, s_k, n]$$
@end tex
@end iftex
@ifinfo
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n}]}
@end ifinfo
or
@iftex
@tex
$$[s_1, s_2, \cdots, s_k, n + 2]$$.
@end tex
@end iftex
@ifinfo
@code{[@var{s1}, @var{s2}, @dots{}, @var{sk}, @var{n} + 2]}.
@end ifinfo
The array is then reshaped internally to a matrix where to leading
dimension is given by 
@iftex
@tex
$$s_1 s_2 \cdots s_k$$
@end tex
@end iftex
@ifinfo
@code{@var{s1} * @var{s2} * @dots{} * @var{sk}}
@end ifinfo
and each row this matrix is then treated seperately. Note that this
is exactly the opposite treatment than @code{interp1} and is done
for compatiability.

Called with a third input argument, @code{spline} evaluates the 
piece-wise spline at the points @var{xi}. There is an equivalence
between @code{ppval (spline (@var{x}, @var{y}), @var{xi})} and
@code{spline (@var{x}, @var{y}, @var{xi})}.

@seealso{ppval, mkpp, unmkpp}
@end deftypefn
unmkpp
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{p}, @var{n}, @var{k}, @var{d}] =} unmkpp (@var{pp})

Extract the components of a piece-wise polynomial structure @var{pp}.
These are as follows:

@table @asis
@item @var{x}
Samples points.
@item @var{p}
Polynomial coefficients for points in sample interval. @code{@var{p}
(@var{i}, :)} contains the coefficients for the polynomial over
interval @var{i} ordered from highest to lowest. If @code{@var{d} >
1}, @code{@var{p} (@var{r}, @var{i}, :)} contains the coeffients for 
the r-th polynomial defined on interval @var{i}. However, this is 
stored as a 2-D array such that @code{@var{c} = reshape (@var{p} (:,
@var{j}), @var{n}, @var{d})} gives @code{@var{c} (@var{i},  @var{r})}
is the j-th coefficient of the r-th polynomial over the i-th interval.
@item @var{n}
Number of polynomial pieces.
@item @var{k}
Order of the polynomial plus 1.
@item @var{d}
Number of polynomials defined for each interval.
@end table

@seealso{mkpp, ppval, spline}
@end deftypefn
demoquat
-*- texinfo -*-
@deftypefn {Function File} {} demoquat ()
Demonstrate the functions available for manipulating quaternions.

Thanks to Mr. Charles Hall, Dr. Don Krupp and Dr. Larry Mullins at
NASA's Marshall Space Flight Center for notes and instruction in
use and conventions with quaternions.  - A. S. Hodel
@end deftypefn
qconj
-*- texinfo -*-
@deftypefn {Function File} {} qconj (@var{q})
Conjugate of a quaternion.

@example
q = [w, x, y, z] = w*i + x*j + y*k + z
qconj (q) = -w*i -x*j -y*k + z
@end example
@end deftypefn
qcoordinate_plot
-*- texinfo -*-
@deftypefn {Function File} {} qcoordinate_plot (@var{qf}, @var{qb}, @var{qv})
Plot in the current figure a set of coordinate axes as viewed from 
the orientation specified by quaternion @var{qv}.  Inertial axes are
also plotted:

@table @var
@item qf
Quaternion from reference (x,y,z) to inertial.
@item qb
Quaternion from reference to body.
@item qv
Quaternion from reference to view angle.
@end table
@end deftypefn
qderiv
-*- texinfo -*-
@deftypefn {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

@example
Q' = qderivmat (omega) * Q
@end example

If the passive convention is used (rotate the frame, not the vector),
then

@example
Q' = -qderivmat (omega) * Q
@end example
@end deftypefn
qderivmat
-*- texinfo -*-
@deftypefn {Function File} {} qderivmat (@var{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

@example
Q' = qderivmat (omega) * Q
@end example

If the passive convention is used (rotate the frame, not the vector),
then

@example
Q' = -qderivmat (omega) * Q.
@end example
@end deftypefn
qinv
-*- texinfo -*-
@deftypefn {Function File} {} qinv (@var{q})
Return the inverse of a quaternion.

@example
q = [w, x, y, z] = w*i + x*j + y*k + z
qmult (q, qinv (q)) = 1 = [0 0 0 1]
@end example
@end deftypefn
qmult
-*- texinfo -*-
@deftypefn {Function File} {} qmult (@var{a}, @var{b})
Multiply two quaternions.

@example
[w, x, y, z] = w*i + x*j + y*k + z
@end example

@noindent
identities:

@example
i^2 = j^2 = k^2 = -1
ij = k                 jk = i
ki = j                 kj = -i
ji = -k                ik = -j
@end example
@end deftypefn
qtrans
-*- texinfo -*-
@deftypefn {Function File} {} qtrans (@var{v}, @var{q})
Transform the unit quaternion @var{v} by the unit quaternion @var{q}.
Returns @code{@var{v} = @var{q}*@var{v}/@var{q}}.
@end deftypefn
qtransv
-*- texinfo -*-
@deftypefn {Function File} {} qtransv (@var{v}, @var{q})
Transform the 3-D vector @var{v} by the unit quaternion @var{q}.
Return a column vector.

@example
vi = (2*real(q)^2 - 1)*vb + 2*imag(q)*(imag(q)'*vb) 
   + 2*real(q)*cross(imag(q),vb)
@end example

@noindent
Where imag(q) is a column vector of length 3.
@end deftypefn
qtransvmat
-*- texinfo -*-
@deftypefn {Function File} {} qtransvmat (@var{qib})
Construct a 3x3 transformation matrix from quaternion @var{qib} that
is equivalent to rotation of th radians about axis @var{vv}, where
@code{[@var{vv}, @var{th}] = quaternion (@var{qib})}.
@end deftypefn
quaternion
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}] =} quaternion (w)
@deftypefnx {Function File} {[@var{vv}, @var{theta}] =} quaternion (w)
@deftypefnx {Function File} {@var{w} =} quaternion (@var{a}, @var{b}, @var{c}, @var{d})
@deftypefnx {Function File} {@var{w} =} quaternion (@var{vv}, @var{theta})
Construct or extract a quaternion

@example
w = a*i + b*j + c*k + d
@end example

@noindent
from given data.
@end deftypefn
complement
-*- texinfo -*-
@deftypefn {Function File} {} complement (@var{x}, @var{y})
Return the elements of set @var{y} that are not in set @var{x}.  For
example,

@example
@group
complement ([ 1, 2, 3 ], [ 2, 3, 5 ])
@result{} 5
@end group
@end example
@seealso{create_set, union, intersection}
@end deftypefn
create_set
-*- texinfo -*-
@deftypefn {Function File} {} create_set (@var{x})
Return a row vector containing the unique values in @var{x}, sorted in
ascending order.  For example,

@example
@group
create_set ([ 1, 2; 3, 4; 4, 2 ])
@result{} [ 1, 2, 3, 4 ]
@end group
@end example
@seealso{union, intersection, complement}
@end deftypefn
intersect
-*- texinfo -*-
@deftypefn {Function File} {} intersect (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{c}, @var{ia}, @var{ib}] =} intersect (@var{a}, @var{b})

Return the elements in both @var{a} and @var{b}, sorted in ascending
order. If @var{a} and @var{b} are both column vectors return a column
vector, otherwise return a row vector.

Return index vectors @var{ia} and @var{ib} such that @code{a(ia)==c} and
@code{b(ib)==c}.

@end deftypefn
@seealso{unique, union, setxor, setdiff, ismember}
ismember
-*- texinfo -*-
@deftypefn {Function File} {} ismember (@var{A}, @var{S})
Return a matrix the same shape as @var{A} which has 1 if
@code{A(i,j)} is in @var{S} or 0 if it isn't.
@seealso{unique, union, intersection, setxor, setdiff}
@end deftypefn
setdiff
-*- texinfo -*-
@deftypefn {Function File} {} setdiff (@var{a}, @var{b})
@deftypefnx {Function File} {} setdiff (@var{a}, @var{b}, "rows")
Return the elements in @var{a} that are not in @var{b}, sorted in
ascending order.  If @var{a} and @var{b} are both column vectors
return a column vector, otherwise return a row vector.

Given the optional third argument @samp{"rows"}, return the rows in
@var{a} that are not in @var{b}, sorted in ascending order by rows.
@seealso{unique, union, intersect, setxor, ismember}
@end deftypefn
setxor
-*- texinfo -*-
@deftypefn {Function File} {} setxor (@var{a}, @var{b})

Return the elements exclusive to @var{a} or @var{b}, sorted in ascending
order. If @var{a} and @var{b} are both column vectors return a column
vector, otherwise return a row vector.

@seealso{unique, union, intersect, setdiff, ismember}
@end deftypefn
union
-*- texinfo -*-
@deftypefn {Function File} {} union (@var{x}, @var{y})
Return the set of elements that are in either of the sets @var{x} and
@var{y}.  For example,

@example
@group
union ([ 1, 2, 4 ], [ 2, 3, 5 ])
@result{} [ 1, 2, 3, 4, 5 ]
@end group
@end example
@seealso{create_set, intersection, complement}
@end deftypefn
unique
-*- texinfo -*-
@deftypefn {Function File} {} unique (@var{x})

Return the unique elements of @var{x}, sorted in ascending order.
If @var{x} is a row vector, return a row vector, but if @var{x}
is a column vector or a matrix return a column vector.

@deftypefnx {Function File} {} unique (@var{A}, 'rows')

Return the unique rows of @var{A}, sorted in ascending order.

@deftypefnx {Function File} {[@var{y}, @var{i}, @var{j}] = } unique (@var{x})

Return index vectors @var{i} and @var{j} such that @code{x(i)==y} and
@code{y(j)==x}.
@seealso{union, intersect, setdiff, setxor, ismember}
@end deftypefn
arch_fit
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{b}] =} arch_fit (@var{y}, @var{x}, @var{p}, @var{iter}, @var{gamma}, @var{a0}, @var{b0})
Fit an ARCH regression model to the time series @var{y} using the
scoring algorithm in Engle's original ARCH paper.  The model is

@example
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
@end example

@noindent
in which @math{e(t)} is @math{N(0, h(t))}, given a time-series vector
@var{y} up to time @math{t-1} and a matrix of (ordinary) regressors
@var{x} up to @math{t}.  The order of the regression of the residual
variance is specified by @var{p}.

If invoked as @code{arch_fit (@var{y}, @var{k}, @var{p})} with a
positive integer @var{k}, fit an ARCH(@var{k}, @var{p}) process,
i.e., do the above with the @math{t}-th row of @var{x} given by

@example
[1, y(t-1), ..., y(t-k)]
@end example

Optionally, one can specify the number of iterations @var{iter}, the
updating factor @var{gamma}, and initial values @math{a0} and
@math{b0} for the scoring algorithm.
@end deftypefn
arch_rnd
-*- texinfo -*-
@deftypefn {Function File} {} arch_rnd (@var{a}, @var{b}, @var{t})
Simulate an ARCH sequence of length @var{t} with AR
coefficients @var{b} and CH coefficients @var{a}.  I.e., the result
@math{y(t)} follows the model

@example
y(t) = b(1) + b(2) * y(t-1) + @dots{} + b(lb) * y(t-lb+1) + e(t),
@end example

@noindent
where @math{e(t)}, given @var{y} up to time @math{t-1}, is
@math{N(0, h(t))}, with

@example
h(t) = a(1) + a(2) * e(t-1)^2 + @dots{} + a(la) * e(t-la+1)^2
@end example
@end deftypefn
arch_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{lm}] =} arch_test (@var{y}, @var{x}, @var{p})
For a linear regression model

@example
y = x * b + e
@end example

@noindent
perform a Lagrange Multiplier (LM) test of the null hypothesis of no
conditional heteroscedascity against the alternative of CH(@var{p}).

I.e., the model is

@example
y(t) = b(1) * x(t,1) + @dots{} + b(k) * x(t,k) + e(t),
@end example

@noindent
given @var{y} up to @math{t-1} and @var{x} up to @math{t},
@math{e}(t) is @math{N(0, h(t))} with

@example
h(t) = v + a(1) * e(t-1)^2 + @dots{} + a(p) * e(t-p)^2,
@end example

@noindent
and the null is @math{a(1)} == @dots{} == @math{a(p)} == 0.

If the second argument is a scalar integer, @math{k}, perform the same
test in a linear autoregression model of order @math{k}, i.e., with

@example
[1, y(t-1), @dots{}, y(t-@var{k})]
@end example

@noindent
as the @math{t}-th row of @var{x}.

Under the null, LM approximately has a chisquare distribution with
@var{p} degrees of freedom and @var{pval} is the @math{p}-value (1
minus the CDF of this distribution at LM) of the test.

If no output argument is given, the @math{p}-value is displayed.
@end deftypefn
arma_rnd
-*- texinfo -*-
@deftypefn {Function File} {} arma_rnd (@var{a}, @var{b}, @var{v}, @var{t}, @var{n})
Return a simulation of the ARMA model

@example
x(n) = a(1) * x(n-1) + ... + a(k) * x(n-k)
     + e(n) + b(1) * e(n-1) + ... + b(l) * e(n-l)
@end example

@noindent
in which @var{k} is the length of vector @var{a}, @var{l} is the
length of vector @var{b} and @var{e} is gaussian white noise with
variance @var{v}.  The function returns a vector of length @var{t}.

The optional parameter @var{n} gives the number of dummy
@var{x}(@var{i}) used for initialization, i.e., a sequence of length
@var{t}+@var{n} is generated and @var{x}(@var{n}+1:@var{t}+@var{n})
is returned.  If @var{n} is omitted, @var{n} = 100 is used. 
@end deftypefn
autocor
-*- texinfo -*-
@deftypefn {Function File} {} autocor (@var{x}, @var{h})
Return the autocorrelations from lag 0 to @var{h} of vector @var{x}.
If @var{h} is omitted, all autocorrelations are computed.
If @var{x} is a matrix, the autocorrelations of each column are
computed.
@end deftypefn
autocov
-*- texinfo -*-
@deftypefn {Function File} {} autocov (@var{x}, @var{h})
Return the autocovariances from lag 0 to @var{h} of vector @var{x}.
If @var{h} is omitted, all autocovariances are computed.
If @var{x} is a matrix, the autocovariances of each column are
computed.
@end deftypefn
autoreg_matrix
-*- texinfo -*-
@deftypefn {Function File} {} autoreg_matrix (@var{y}, @var{k})
Given a time series (vector) @var{y}, return a matrix with ones in the
first column and the first @var{k} lagged values of @var{y} in the
other columns.  I.e., for @var{t} > @var{k}, @code{[1,
@var{y}(@var{t}-1), @dots{}, @var{y}(@var{t}-@var{k})]} is the t-th row
of the result.  The resulting matrix may be used as a regressor matrix
in autoregressions.
@end deftypefn
bartlett
-*- texinfo -*-
@deftypefn {Function File} {} bartlett (@var{m})
Return the filter coefficients of a Bartlett (triangular) window of
length @var{m}.

For a definition of the Bartlett window, see e.g. A. V. Oppenheim &
R. W. Schafer, "Discrete-Time Signal Processing".
@end deftypefn
blackman
-*- texinfo -*-
@deftypefn {Function File} {} blackman (@var{m})
Return the filter coefficients of a Blackman window of length @var{m}.

For a definition of the  Blackman window, see e.g. A. V. Oppenheim &
R. W. Schafer, "Discrete-Time Signal Processing".
@end deftypefn
detrend
-*- texinfo -*-
@deftypefn {Function File} {} detrend (@var{x}, @var{p})
If @var{x} is a vector, @code{detrend (@var{x}, @var{p})} removes the
best fit of a polynomial of order @var{p} from the data @var{x}.

If @var{x} is a matrix, @code{detrend (@var{x}, @var{p})} does the same
for each column in @var{x}.

The second argument is optional.  If it is not specified, a value of 1
is assumed.  This corresponds to removing a linear trend.
@end deftypefn
diffpara
-*- texinfo -*-
@deftypefn {Function File} {[@var{d}, @var{dd}] =} diffpara (@var{x}, @var{a}, @var{b})
Return the estimator @var{d} for the differencing parameter of an
integrated time series.

The frequencies from @math{[2*pi*a/t, 2*pi*b/T]} are used for the
estimation.  If @var{b} is omitted, the interval
@math{[2*pi/T, 2*pi*a/T]} is used.  If both @var{b} and @var{a} are
omitted then @math{a = 0.5 * sqrt (T)} and @math{b = 1.5 * sqrt (T)}
is used, where @math{T} is the sample size.  If @var{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 @var{dd}.  The value of @var{d} is
simply the mean of @var{dd}.

Reference: Brockwell, Peter J. & Davis, Richard A. Time Series:
Theory and Methods Springer 1987.
@end deftypefn
durbinlevinson
-*- texinfo -*-
@deftypefn {Function File} {} durbinlevinson (@var{c}, @var{oldphi}, @var{oldv})
Perform one step of the Durbin-Levinson algorithm.

The vector @var{c} specifies the autocovariances @code{[gamma_0, @dots{},
gamma_t]} from lag 0 to @var{t}, @var{oldphi} specifies the
coefficients based on @var{c}(@var{t}-1) and @var{oldv} specifies the
corresponding error.

If @var{oldphi} and @var{oldv} are omitted, all steps from 1 to
@var{t} of the algorithm are performed.
@end deftypefn
fftconv
-*- texinfo -*-
@deftypefn {Function File} {} fftconv (@var{a}, @var{b}, @var{n})
Return the convolution of the vectors @var{a} and @var{b}, as a vector
with length equal to the @code{length (a) + length (b) - 1}.  If @var{a}
and @var{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 @code{fftfilt}.  If
the optional argument @var{n} is specified, an N-point FFT is used.
@end deftypefn
fftfilt
-*- texinfo -*-
@deftypefn {Function File} {} fftfilt (@var{b}, @var{x}, @var{n})

With two arguments, @code{fftfilt} filters @var{x} with the FIR filter
@var{b} using the FFT.

Given the optional third argument, @var{n}, @code{fftfilt} uses the
overlap-add method to filter @var{x} with @var{b} using an N-point FFT.

If @var{x} is a matrix, filter each column of the matrix.
@end deftypefn
fftshift
-*- texinfo -*-
@deftypefn {Function File} {} fftshift (@var{v})
@deftypefnx {Function File} {} fftshift (@var{v}, @var{dim})
Perform a shift of the vector @var{v}, for use with the @code{fft}
and @code{ifft} functions, in order the move the frequency 0 to the
center of the vector or matrix.

If @var{v} is a vector of @math{N} elements corresponding to @math{N}
time samples spaced of @math{Dt} each, then @code{fftshift (fft
(@var{v}))} corresponds to frequencies

@example
f = ((1:N) - ceil(N/2)) / N / Dt
@end example

If @var{v} is a matrix, the same holds for rows and columns. If 
@var{v} is an array, then the same holds along each dimension.

The optional @var{dim} argument can be used to limit the dimension
along which the permutation occurs.
@end deftypefn
filter2
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} filter2 (@var{b}, @var{x})
@deftypefnx {Function File} {@var{y} =} filter2 (@var{b}, @var{x}, @var{shape})
Apply the 2-D FIR filter @var{b} to @var{x}. If the argument
@var{shape} is specified, return an array of the desired shape.
Possible values are: 

@table @asis
@item 'full'
pad @var{x} with zeros on all sides before filtering.
@item 'same'
unpadded @var{x} (default)
@item 'valid'
trim @var{x} after filtering so edge effects are no included.
@end table

Note this is just a variation on convolution, with the parameters
reversed and @var{b} rotated 180 degrees.
@seealso{conv2}
@end deftypefn
fractdiff
-*- texinfo -*-
@deftypefn {Function File} {} fractdiff (@var{x}, @var{d})
Compute the fractional differences @math{(1-L)^d x} where @math{L}
denotes the lag-operator and @math{d} is greater than -1.
@end deftypefn
freqz
-*- texinfo -*-
@deftypefn {Function File} {[@var{h}, @var{w}] =} freqz (@var{b}, @var{a}, @var{n}, "whole")
Return the complex frequency response @var{h} of the rational IIR filter
whose numerator and denominator coefficients are @var{b} and @var{a},
respectively.  The response is evaluated at @var{n} angular frequencies
between 0 and
@ifinfo
 2*pi.
@end ifinfo
@iftex
@tex
 $2\pi$.
@end tex
@end iftex

@noindent
The output value @var{w} is a vector of the frequencies.

If the fourth argument is omitted, the response is evaluated at
frequencies between 0 and
@ifinfo
 pi.
@end ifinfo
@iftex
@tex
 $\pi$.
@end tex
@end iftex

If @var{n} is omitted, a value of 512 is assumed.

If @var{a} is omitted, the denominator is assumed to be 1 (this
corresponds to a simple FIR filter).

For fastest computation, @var{n} should factor into a small number of
small primes.

@deftypefnx {Function File} {@var{h} =} freqz (@var{b}, @var{a}, @var{w})
Evaluate the response at the specific frequencies in the vector @var{w}.
The values for @var{w} are measured in radians.

@deftypefnx {Function File} {[@dots{}] =} freqz (@dots{}, @var{Fs})
Return frequencies in Hz instead of radians assuming a sampling rate
@var{Fs}.  If you are evaluating the response at specific frequencies 
@var{w}, those frequencies should be requested in Hz rather than radians.

@deftypefnx {Function File} {} freqz (@dots{})
Plot the pass band, stop band and phase response of @var{h} rather
than returning them.
@end deftypefn
freqz_plot
-*- texinfo -*-
@deftypefn {Function File} {} freqz_plot (@var{w}, @var{h})
Plot the pass band, stop band and phase response of @var{h}.
@end deftypefn
hamming
-*- texinfo -*-
@deftypefn {Function File} {} hamming (@var{m})
Return the filter coefficients of a Hamming window of length @var{m}.

For a definition of the Hamming window, see e.g. A. V. Oppenheim &
R. W. Schafer, "Discrete-Time Signal Processing".
@end deftypefn
hanning
-*- texinfo -*-
@deftypefn {Function File} {} hanning (@var{m})
Return the filter coefficients of a Hanning window of length @var{m}.

For a definition of this window type, see e.g. A. V. Oppenheim &
R. W. Schafer, "Discrete-Time Signal Processing".
@end deftypefn
hurst
-*- texinfo -*-
@deftypefn {Function File} {} hurst (@var{x})
Estimate the Hurst parameter of sample @var{x} via the rescaled range
statistic.  If @var{x} is a matrix, the parameter is estimated for
every single column.
@end deftypefn
ifftshift
-*- texinfo -*-
@deftypefn {Function File} {} ifftshift (@var{v})
@deftypefnx {Function File} {} ifftshift (@var{v}, @var{dim})
Undo the action of the @code{fftshift} function.  For even length 
@var{v}, @code{fftshift} is its own inverse, but odd lengths differ 
slightly.
@end deftypefn
periodogram
-*- texinfo -*-
@deftypefn {Function File} {} periodogram (@var{x})
For a data matrix @var{x} from a sample of size @var{n}, return the
periodogram.
@end deftypefn
rectangle_lw
-*- texinfo -*-
@deftypefn {Function File} {} rectangle_lw (@var{n}, @var{b})
Rectangular lag window. Subfunction used for spectral density
estimation.
@end deftypefn
rectangle_sw
-*- texinfo -*-
@deftypefn {Function File} {} rectangle_sw (@var{n}, @var{b})
Rectangular spectral window.  Subfunction used for spectral density
estimation.
@end deftypefn
sinc
-*- texinfo -*-
@deftypefn {Function File} {} sinc (@var{x})
Return
@iftex
@tex
$ \sin (\pi x)/(\pi x)$.
@end tex
@end iftex
@ifinfo
 sin(pi*x)/(pi*x).
@end ifinfo
@end deftypefn
sinetone
-*- texinfo -*-
@deftypefn {Function File} {} sinetone (@var{freq}, @var{rate}, @var{sec}, @var{ampl})
Return a sinetone of frequency @var{freq} with length of @var{sec}
seconds at sampling rate @var{rate} and with amplitude @var{ampl}.
The arguments @var{freq} and @var{ampl} may be vectors of common size.

Defaults are @var{rate} = 8000, @var{sec} = 1 and @var{ampl} = 64.
@end deftypefn
sinewave
-*- texinfo -*-
@deftypefn {Function File} {} sinewave (@var{m}, @var{n}, @var{d})
Return an @var{m}-element vector with @var{i}-th element given by
@code{sin (2 * pi * (@var{i}+@var{d}-1) / @var{n})}.

The default value for @var{d} is 0 and the default value for @var{n}
is @var{m}.
@end deftypefn
spectral_adf
-*- texinfo -*-
@deftypefn {Function File} {} spectral_adf (@var{c}, @var{win}, @var{b})
Return the spectral density estimator given a vector of
autocovariances @var{c}, window name @var{win}, and bandwidth,
@var{b}.

The window name, e.g., @code{"triangle"} or @code{"rectangle"} is
used to search for a function called @code{@var{win}_sw}.

If @var{win} is omitted, the triangle window is used.  If @var{b} is
omitted, @code{1 / sqrt (length (@var{x}))} is used.
@end deftypefn
spectral_xdf
-*- texinfo -*-
@deftypefn {Function File} {} spectral_xdf (@var{x}, @var{win}, @var{b})
Return the spectral density estimator given a data vector @var{x},
window name @var{win}, and bandwidth, @var{b}.

The window name, e.g., @code{"triangle"} or @code{"rectangle"} is
used to search for a function called @code{@var{win}_sw}.

If @var{win} is omitted, the triangle window is used.  If @var{b} is
omitted, @code{1 / sqrt (length (@var{x}))} is used.
@end deftypefn
spencer
-*- texinfo -*-
@deftypefn {Function File} {} spencer (@var{x})
Return Spencer's 15 point moving average of every single column of
@var{x}.
@end deftypefn
stft
-*- texinfo -*-
@deftypefn {Function File} {[@var{y}, @var{c}] =} stft (@var{x}, @var{win_size}, @var{inc}, @var{num_coef}, @var{w_type})
Compute the short-term Fourier transform of the vector @var{x} with
@var{num_coef} coefficients by applying a window of @var{win_size} data
points and an increment of @var{inc} points.

Before computing the Fourier transform, one of the following windows
is applied:

@table @asis
@item hanning
w_type = 1
@item hamming
w_type = 2
@item rectangle
w_type = 3
@end table

The window names can be passed as strings or by the @var{w_type} number.

If not all arguments are specified, the following defaults are used:
@var{win_size} = 80, @var{inc} = 24, @var{num_coef} = 64, and
@var{w_type} = 1.

@code{@var{y} = stft (@var{x}, @dots{})} returns the absolute values
of the Fourier coefficients according to the @var{num_coef} positive
frequencies.

@code{[@var{y}, @var{c}] = stft (@code{x}, @dots{})} returns the
entire STFT-matrix @var{y} and a 3-element vector @var{c} containing
the window size, increment, and window type, which is needed by the
synthesis function.
@end deftypefn
synthesis
-*- texinfo -*-
@deftypefn {Function File} {} synthesis (@var{y}, @var{c})
Compute a signal from its short-time Fourier transform @var{y} and a
3-element vector @var{c} specifying window size, increment, and
window type.

The values @var{y} and @var{c} can be derived by

@example
[@var{y}, @var{c}] = stft (@var{x} , @dots{})
@end example
@end deftypefn
triangle_lw
-*- texinfo -*-
@deftypefn {Function File} {} triangle_lw (@var{n}, @var{b})
Triangular lag window. Subfunction used for spectral density
estimation.
@end deftypefn
triangle_sw
-*- texinfo -*-
@deftypefn {Function File} {} triangle_sw (@var{n}, @var{b})
Triangular spectral window.  Subfunction used for spectral density
estimation.
@end deftypefn
unwrap
-*- texinfo -*-
@deftypefn {Function File} {@var{b} =} unwrap (@var{a}, @var{tol}, @var{dim})

Unwrap radian phases by adding multiples of 2*pi as appropriate to
remove jumps greater than @var{tol}.  @var{tol} defaults to pi.

Unwrap will unwrap along the first non-singleton dimension of
@var{a}, unless the optional argument @var{dim} is given, in 
which case the data will be unwrapped along this dimension
@end deftypefn
yulewalker
-*- texinfo -*-
@deftypefn {Function File} {[@var{a}, @var{v}] =} yulewalker (@var{c})
Fit an AR (p)-model with Yule-Walker estimates given a vector @var{c}
of autocovariances @code{[gamma_0, ..., gamma_p]}.

Returns the AR coefficients, @var{a}, and the variance of white
noise, @var{v}.
@end deftypefn
colperm
-*- texinfo -*-
@deftypefn {Function File} {@var{p} =} colperm (@var{s})
Returns the column permutations such that the columns of
@code{@var{s} (:, @var{p})} are ordered in terms of increase number
of non-zero elements. If @var{s} is symmetric, then @var{p} is chosen
such that @code{@var{s} (@var{p}, @var{p})} orders the rows and
columns with increasing number of non zeros elements.
@end deftypefn
etreeplot
-*- texinfo -*-
@deftypefn {Function File} {} etreeplot (@var{tree})
@deftypefnx {Function File} {} etreeplot (@var{tree}, @var{node_style}, @var{edge_style})
Plot the elimination tree of the matrix @var{s} or
@code{@var{s}+@var{s}'}  if @var{s} in non-symmetric.  The optional
parameters @var{line_style} and @var{edge_style} define the output
style.
@seealso{treeplot, gplot}
@end deftypefn
gplot
-*- texinfo -*-
@deftypefn {Function File} {} gplot (@var{a}, @var{xy})
@deftypefnx {Function File} {} gplot (@var{a}, @var{xy}, @var{line_style})
@deftypefnx {Function File} {[@var{x}, @var{y}] =} gplot (@var{a}, @var{xy})
Plot a graph defined by @var{A} and @var{xy} in the graph theory
sense.  @var{A} is the adjacency matrix of the array to be plotted
and @var{xy} is an @var{n}-by-2 matrix containing the coordinates of
the nodes of the graph.

The optional parameter @var{line_style} defines the output style for
the plot.  Called with no output arguments the graph is plotted
directly.  Otherwise, return the coordinates of the plot in @var{x}
and @var{y}.
@seealso{treeplot, etreeplot, spy}
@end deftypefn
nonzeros
-*- texinfo -*-
@deftypefn {Function File} {} nonzeros (@var{s})
Returns a vector of the non-zero values of the sparse matrix @var{s}.
@end deftypefn
normest
-*- texinfo -*-
@deftypefn {Function File} {[@var{n}, @var{c}] =} normest (@var{a}, @var{tol})
Estimate the 2-norm of the matrix @var{a} using a power series
analysis. This is typically used for large matrices, where the cost
of calculating the @code{norm (@var{a})} is prohibitive and an approximation
to the 2-norm is acceptable.

@var{tol} is the tolerance to which the 2-norm is calculated. By default
@var{tol} is 1e-6. @var{c} returns the number of iterations needed for
@code{normest} to converge.
@end deftypefn
pcg
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} pcg (@var{a}, @var{b}, @var{tol}, @var{maxit}, @var{m1}, @var{m2}, @var{x0}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}, @var{eigest}] =} pcg (@dots{})

Solves the linear system of equations @code{@var{a} * @var{x} =
@var{b}} by means of the  Preconditioned Conjugate Gradient iterative
method. The input arguments are

@itemize
@item
@var{a} can be either a square (preferably sparse) matrix or a
function handle, inline function or string containing the name
of a function which computes @code{@var{a} * @var{x}}. In principle
@var{a} should be symmetric and positive definite; if @code{pcg}
finds @var{a} to not be positive definite, you will get a warning
message and the @var{flag} output parameter will be set.

@item
@var{b} is the right hand side vector.

@item
@var{tol} is the required relative tolerance for the residual error,
@code{@var{b} - @var{a} * @var{x}}. The iteration stops if @code{norm
(@var{b} - @var{a} * @var{x}) <= @var{tol} * norm (@var{b} - @var{a} *
@var{x0})}. If @var{tol} is empty or is omitted, the function sets
@code{@var{tol} = 1e-6} by default.

@item
@var{maxit} is the maximum allowable number of iterations; if
@code{[]} is supplied for @code{maxit}, or @code{pcg} has less
arguments, a default value equal to 20 is used.

@item
@var{m} = @var{m1} * @var{m2} is the (left) preconditioning matrix, so that the iteration is
(theoretically) equivalent to solving by @code{pcg} @code{@var{P} *
@var{x} = @var{m} \ @var{b}}, with @code{@var{P} = @var{m} \ @var{a}}.
Note that a proper choice of the preconditioner may dramatically
improve the overall performance of the method. Instead of matrices
@var{m1} and @var{m2}, the user may pass two functions which return 
the results of applying the inverse of @var{m1} and @var{m2} to 
a vector (usually this is the preferred way of using the preconditioner). 
If @code{[]} is supplied for @var{m1}, or @var{m1} is omitted, no 
preconditioning is applied. If @var{m2} is omitted, @var{m} = @var{m1}
will be used as preconditioner.

@item
@var{x0} is the initial guess. If @var{x0} is empty or omitted, the 
function sets @var{x0} to a zero vector by default.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and
passed in a proper way to any of the functions (@var{a} or @var{m})
which are passed to @code{pcg}. See the examples below for further
details. The output arguments are

@itemize
@item
@var{x} is the computed approximation to the solution of
@code{@var{a} * @var{x} = @var{b}}.

@item
@var{flag} reports on the convergence. @code{@var{flag} = 0} means
the solution converged and the tolerance criterion given by @var{tol}
is satisfied. @code{@var{flag} = 1} means that the @var{maxit} limit
for the iteration count was reached. @code{@var{flag} = 3} reports that
the (preconditioned) matrix was found not positive definite.

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} is the actual number of iterations performed.

@item 
@var{resvec} describes the convergence history of the method.
@code{@var{resvec} (i,1)} is the Euclidean norm of the residual, and
@code{@var{resvec} (i,2)} is the preconditioned residual norm,
after the (@var{i}-1)-th iteration, @code{@var{i} =
1, 2, @dots{}, @var{iter}+1}. The preconditioned residual norm
is defined as
@code{norm (@var{r}) ^ 2 = @var{r}' * (@var{m} \ @var{r})} where
@code{@var{r} = @var{b} - @var{a} * @var{x}}, see also the
description of @var{m}. If @var{eigest} is not required, only
@code{@var{resvec} (:,1)} is returned.

@item
@var{eigest} returns the estimate for the smallest @code{@var{eigest}
(1)} and largest @code{@var{eigest} (2)} eigenvalues of the
preconditioned matrix @code{@var{P} = @var{m} \ @var{a}}. In 
particular, if no preconditioning is used, the extimates for the
extreme eigenvalues of @var{a} are returned. @code{@var{eigest} (1)}
is an overestimate and @code{@var{eigest} (2)} is an underestimate, 
so that @code{@var{eigest} (2) / @var{eigest} (1)} is a lower bound
for @code{cond (@var{P}, 2)}, which nevertheless in the limit should
theoretically be equal to the actual value of the condition number. 
The method which computes @var{eigest} works only for symmetric positive
definite @var{a} and @var{m}, and the user is responsible for
verifying this assumption. 
@end itemize

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

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

@sc{Example 1:} Simplest use of @code{pcg}

@example
  x = pcg(A,b)
@end example

@sc{Example 2:} @code{pcg} with a function which computes
@code{@var{a} * @var{x}}

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

  x = pcg ("applyA", b)
@end group
@end example

@sc{Example 3:} @code{pcg} with a preconditioner: @var{l} * @var{u}

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

@sc{Example 4:} @code{pcg} with a preconditioner: @var{l} * @var{u}.
Faster than @sc{Example 3} since lower and upper triangular matrices 
are easier to invert

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

@sc{Example 5:} Preconditioned iteration, with full diagnostics. The
preconditioner (quite strange, because even the original matrix
@var{a} is trivial) is defined as a function

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

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

@sc{Example 6:} Finally, a preconditioner which depends on a
parameter @var{k}.

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

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

@sc{References}

	[1] C.T.Kelley, 'Iterative methods for linear and nonlinear equations',
	SIAM, 1995 (the base PCG algorithm) 
	
	[2] Y.Saad, 'Iterative methods for sparse linear systems', PWS 1996
	(condition number estimate from PCG) Revised version of this book is
	available online at http://www-users.cs.umn.edu/~saad/books.html


@seealso{sparse, pcr}
@end deftypefn
pcr
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} pcr (@var{a}, @var{b}, @var{tol}, @var{maxit}, @var{m}, @var{x0}, @dots{})
@deftypefnx {Function File} {[@var{x}, @var{flag}, @var{relres}, @var{iter}, @var{resvec}] =} pcr (@dots{})

Solves the linear system of equations @code{@var{a} * @var{x} =
@var{b}} by means of the  Preconditioned Conjugate Residuals iterative
method. The input arguments are

@itemize
@item
@var{a} can be either a square (preferably sparse) matrix or a
function handle, inline function or string containing the name
of a function which computes @code{@var{a} * @var{x}}. In principle
@var{a} should be symmetric and non-singular; if @code{pcr}
finds @var{a} to be numerically singular, you will get a warning
message and the @var{flag} output parameter will be set.

@item
@var{b} is the right hand side vector.

@item
@var{tol} is the required relative tolerance for the residual error,
@code{@var{b} - @var{a} * @var{x}}. The iteration stops if @code{norm
(@var{b} - @var{a} * @var{x}) <= @var{tol} * norm (@var{b} - @var{a} *
@var{x0})}. If @var{tol} is empty or is omitted, the function sets
@code{@var{tol} = 1e-6} by default.

@item
@var{maxit} is the maximum allowable number of iterations; if
@code{[]} is supplied for @code{maxit}, or @code{pcr} has less
arguments, a default value equal to 20 is used.

@item
@var{m} is the (left) preconditioning matrix, so that the iteration is
(theoretically) equivalent to solving by @code{pcr} @code{@var{P} *
@var{x} = @var{m} \ @var{b}}, with @code{@var{P} = @var{m} \ @var{a}}.
Note that a proper choice of the preconditioner may dramatically
improve the overall performance of the method. Instead of matrix
@var{m}, the user may pass a function which returns the results of 
applying the inverse of @var{m} to a vector (usually this is the
preferred way of using the preconditioner). If @code{[]} is supplied
for @var{m}, or @var{m} is omitted, no preconditioning is applied.

@item
@var{x0} is the initial guess. If @var{x0} is empty or omitted, the 
function sets @var{x0} to a zero vector by default.
@end itemize

The arguments which follow @var{x0} are treated as parameters, and
passed in a proper way to any of the functions (@var{a} or @var{m})
which are passed to @code{pcr}. See the examples below for further
details. The output arguments are

@itemize
@item
@var{x} is the computed approximation to the solution of
@code{@var{a} * @var{x} = @var{b}}.

@item
@var{flag} reports on the convergence. @code{@var{flag} = 0} means
the solution converged and the tolerance criterion given by @var{tol}
is satisfied. @code{@var{flag} = 1} means that the @var{maxit} limit
for the iteration count was reached. @code{@var{flag} = 3} reports t
@code{pcr} breakdown, see [1] for details.

@item
@var{relres} is the ratio of the final residual to its initial value,
measured in the Euclidean norm.

@item
@var{iter} is the actual number of iterations performed.

@item 
@var{resvec} describes the convergence history of the method,
so that @code{@var{resvec} (i)} contains the Euclidean norms of the 
residualafter the (@var{i}-1)-th iteration, @code{@var{i} =
1,2, @dots{}, @var{iter}+1}.
@end itemize

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

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

@sc{Example 1:} Simplest use of @code{pcr}

@example
  x = pcr(A, b)
@end example

@sc{Example 2:} @code{pcr} with a function which computes
@code{@var{a} * @var{x}}.

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

  x = pcr('applyA',b)
@end group
@end example

@sc{Example 3:}  Preconditioned iteration, with full diagnostics. The
preconditioner (quite strange, because even the original matrix
@var{a} is trivial) is defined as a function

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

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

@sc{Example 4:} Finally, a preconditioner which depends on a
parameter @var{k}.

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

  [x, flag, relres, iter, resvec] = pcr(A,b,[],[],'applyM',[],3)
@end group
@end example

@sc{References}

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

@seealso{sparse, pcg}
@end deftypefn
spalloc
-*- texinfo -*-
@deftypefn {Function File} {@var{s} =} spalloc (@var{r}, @var{c}, @var{nz})
Returns an empty sparse matrix of size @var{r}-by-@var{c}. As Octave
resizes sparse matrices at the first opportunity, so that no additional 
space is needed, the argument @var{nz} is ignored. This function is 
provided only for compatiability reasons.

It should be noted that this means that code like

@example
k = 5;
nz = r * k;
s = spalloc (r, c, nz)
for j = 1:c
  idx = randperm (r);
  s (:, j) = [zeros(r - k, 1); rand(k, 1)] (idx);
endfor
@end example

will reallocate memory at each step. It is therefore vitally important
that code like this is vectorized as much as possible.
@seealso{sparse, nzmax}
@end deftypefn
spconvert
-*- texinfo -*-
@deftypefn {Function File} {@var{x} =} spconvert (@var{m})
This function converts for a simple sparse matrix format easily
produced by other programs into Octave's internal sparse format. The
input @var{x} is either a 3 or 4 column real matrix, containing
the row, column, real and imaginary parts of the elements of the
sparse matrix. An element with a zero real and imaginay part can
be used to force a particular matrix size.
@end deftypefn
spdiags
-*- texinfo -*-
@deftypefn {function File} {[@var{b}, @var{c}] =} spdiags (@var{a})
@deftypefnx {function File} {@var{b} =} spdiags (@var{a}, @var{c})
@deftypefnx {function File} {@var{b} =} spdiags (@var{v}, @var{c}, @var{a})
@deftypefnx {function File} {@var{b} =} spdiags (@var{v}, @var{c}, @var{m}, @var{n})
A generalization of the function @code{spdiag}. Called with a single
input argument, the non-zero diagonals @var{c} of @var{A} are extracted.
With two arguments the diagonals to extract are given by the vector 
@var{c}.

The other two forms of @code{spdiags} modify the input matrix by
replacing the diagonals. They use the columns of @var{v} to replace
the columns represented by the vector @var{c}. If the sparse matrix
@var{a} is defined then the diagonals of this matrix are replaced.
Otherwise a matrix of @var{m} by @var{n} is created with the
diagonals given by @var{v}.

Negative values of @var{c} representive diagonals below the main
diagonal, and positive values of @var{c} diagonals above the main
diagonal.

For example

@example
@group
spdiags (reshape (1:12, 4, 3), [-1 0 1], 5, 4)
@result{}    5 10  0  0
      1  6 11  0
      0  2  7 12
      0  0  3  8
      0  0  0  4
@end group
@end example

@end deftypefn
speye
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} speye (@var{m})
@deftypefnx {Function File} {@var{y} =} speye (@var{m}, @var{n})
@deftypefnx {Function File} {@var{y} =} speye (@var{sz})
Returns a sparse identity matrix. This is significantly more
efficient than @code{sparse (eye (@var{m}))} as the full matrix
is not constructed.

Called with a single argument a square matrix of size @var{m} by
@var{m} is created. Otherwise a matrix of @var{m} by @var{n} is
created. If called with a single vector argument, this argument 
is taken to be the size of the matrix to create.
@end deftypefn
spfun
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} spfun (@var{f},@var{x})
Compute @code{f(@var{x})} for the non-zero values of @var{x}.
This results in a sparse matrix with the same structure as 
@var{x}. The function @var{f} can be passed as a string, a
function handle or an inline function.
@end deftypefn
sphcat
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} sphcat (@var{a1}, @var{a2}, @dots{}, @var{aN})
Return the horizontal concatenation of sparse matrices. This function
is obselete and @code{horzcat} should be used.
@seealso {spvcat, vertcat, horzcat, cat}
@end deftypefn
spones
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} spones (@var{x})
Replace the non-zero entries of @var{x} with ones. This creates a
sparse matrix with the same structure as @var{x}.
@end deftypefn
sprand
-*- texinfo -*-
@deftypefn {Function File} {} sprand (@var{m}, @var{n}, @var{d})
@deftypefnx {Function File} {} sprand (@var{s})
Generate a random sparse matrix. The size of the matrix will be
@var{m} by @var{n}, with a density of values given by @var{d}.
@var{d} should be between 0 and 1. Values will be uniformly
distributed between 0 and 1.

Note: sometimes the actual density  may be a bit smaller than @var{d}. 
This is unlikely to happen for large really sparse matrices.

If called with a single matrix argument, a random sparse matrix is
generated wherever the matrix @var{S} is non-zero.
@seealso{sprandn}
@end deftypefn
sprandn
-*- texinfo -*-
@deftypefn {Function File} {} sprandn (@var{m}, @var{n}, @var{d})
@deftypefnx {Function File} {} sprandn (@var{s})
Generate a random sparse matrix. The size of the matrix will be
@var{m} by @var{n}, with a density of values given by @var{d}.
@var{d} should be between 0 and 1. Values will be normally
distributed with mean of zero and variance 1.

Note: sometimes the actual density  may be a bit smaller than @var{d}. 
This is unlikely to happen for large really sparse matrices.

If called with a single matrix argument, a random sparse matrix is
generated wherever the matrix @var{S} is non-zero.
@seealso{sprand}
@end deftypefn
sprandsym
-*- texinfo -*-
@deftypefn {Function File} {} sprandsym (@var{n}, @var{d})
@deftypefnx {Function File} {} sprandsym (@var{s})
Generate a symmetric random sparse matrix. The size of the matrix will be
@var{n} by @var{n}, with a density of values given by @var{d}.
@var{d} should be between 0 and 1. Values will be normally
distributed with mean of zero and variance 1.

Note: sometimes the actual density  may be a bit smaller than @var{d}. 
This is unlikely to happen for large really sparse matrices.

If called with a single matrix argument, a random sparse matrix is
generated wherever the matrix @var{S} is non-zero in its lower
triangular part.
@seealso{sprand, sprandn}
@end deftypefn
spstats
-*- texinfo -*-
@deftypefn {Function File} {[@var{count}, @var{mean}, @var{var}] =} spstats (@var{s})
@deftypefnx {Function File} {[@var{count}, @var{mean}, @var{var}] =} spstats (@var{s}, @var{j})
Return the stats for the non-zero elements of the sparse matrix @var{s}.
@var{count} is the number of non-zeros in each column, @var{mean}
is the mean of the non-zeros in each column, and @var{var} is the  
variance of the non-zeros in each column.

Called with two input arguments, if @var{s} is the data and @var{j}
is the bin number for the data, compute the stats for each bin.  In 
this case, bins can contain data values of zero, whereas with 
@code{spstats (@var{s})} the zeros may disappear.
@end deftypefn
spvcat
-*- texinfo -*-
@deftypefn {Function File} {@var{y} =} spvcat (@var{a1}, @var{a2}, @dots{}, @var{aN})
Return the vertical concatenation of sparse matrices. This function
is obselete and @code{vertcat} should be used
@seealso{sphcat, vertcat, horzcat, cat}
@end deftypefn
spy
-*- texinfo -*-
@deftypefn {Function File} {} spy (@var{x})
@deftypefnx {Function File} {} spy (@dots{}, @var{markersize})
@deftypefnx {Function File} {} spy (@dots{}, @var{LineSpec})
Plot the sparsity pattern of the sparse matrix @var{x}. If the argument
@var{markersize} is given as an scalar value, it is used to determine the
point size in the plot. If the string @var{LineSpec} is given it is
passed to @code{plot} and determines the appearance of the plot.
@seealso{plot}
@end deftypefn
treeplot
-*- texinfo -*-
@deftypefn {Function File} {} treeplot (@var{Tree})
@deftypefnx {Function File} {} treeplot (@var{Tree}, @var{LineStyle}, @var{EdgeStyle})
Produces a graph of tree or forest. The first argument is vector of
predecessors, optional parametres @var{LineStyle} and @var{EdgeStyle}
define the output style. The complexity of the algorithm is O(n) in
terms of is time and memory requirements.
@seealso{etreeplot, gplot}
@end deftypefn
bessel
-*- texinfo -*-
@deftypefn {Mapping Function} {} besseli (@var{alpha}, @var{x})
@deftypefnx {Mapping Function} {} besselj (@var{alpha}, @var{x})
@deftypefnx {Mapping Function} {} besselk (@var{alpha}, @var{x})
@deftypefnx {Mapping Function} {} bessely (@var{alpha}, @var{x})
Compute Bessel functions of the following types:

@table @code
@item besselj
Bessel functions of the first kind.

@item bessely
Bessel functions of the second kind.

@item besseli
Modified Bessel functions of the first kind.

@item besselk
Modified Bessel functions of the second kind.
@end table

The second argument, @var{x}, must be a real matrix, vector, or scalar.

The first argument, @var{alpha}, must be greater than or equal to zero.
If @var{alpha} is a range, it must have an increment equal to one.

If @var{alpha} is a scalar, the result is the same size as @var{x}.

If @var{alpha} is a range, @var{x} must be a vector or scalar, and the
result is a matrix with @code{length(@var{x})} rows and
@code{length(@var{alpha})} columns.
@end deftypefn
beta
-*- texinfo -*-
@deftypefn {Mapping Function} {} beta (@var{a}, @var{b})
Return the Beta function,
@iftex
@tex
$$
 B (a, b) = {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}.
$$
@end tex
@end iftex
@ifinfo

@example
beta (a, b) = gamma (a) * gamma (b) / gamma (a + b).
@end example
@end ifinfo
@end deftypefn
betai
-*- texinfo -*-
@deftypefn {Function File} {} betai (@var{a}, @var{b}, @var{x})
This function is provided for compatibility with older versions of
Octave.  New programs should use betainc instead.

@code{betai (@var{a}, @var{b}, @var{x})} is the same as @code{betainc
(@var{x}, @var{a}, @var{b})}. 
@end deftypefn
betaln
-*- texinfo -*-
@deftypefn {Mapping Function} {} betaln (@var{a}, @var{b})
Return the log of the Beta function,
@iftex
@tex
$$
 B (a, b) = \log {\Gamma (a) \Gamma (b) \over \Gamma (a + b)}.
$$
@end tex
@end iftex
@ifinfo

@example
betaln (a, b) = gammaln (a) + gammaln (b) - gammaln (a + b)
@end example
@end ifinfo
@seealso{beta, betai, gammaln}
@end deftypefn
erfinv
-*- texinfo -*-
@deftypefn {Mapping Function} {} erfinv (@var{z})
Computes the inverse of the error function.
@seealso{erf, erfc}
@end deftypefn
factor
-*- texinfo -*-
@deftypefn {Function File} {@var{p} =} factor (@var{q})
@deftypefnx {Function File} {[@var{p}, @var{n}] =} factor (@var{q})

Return prime factorization of @var{q}. That is @code{prod (@var{p})
== @var{q}}. If @code{@var{q} == 1}, returns 1. 

With two output arguments, returns the uniques primes @var{p} and
their mulyiplicities. That is @code{prod (@var{p} .^ @var{n}) ==
@var{q}}.

@end deftypefn
factorial
-*- texinfo -*-
@deftypefn {Function File} {} factorial (@var{n})
Return the factorial of @var{n}. If @var{n} is scalar, this is
equivalent to @code{prod (1:@var{n})}.  If @var{n} is an array,
the factorial of the elements of the array are returned.
@end deftypefn
gammai
-*- texinfo -*-
@deftypefn {Function File} {} gammai (@var{a}, @var{x})
This function is provided for compatibility with older versions of
Octave.  New programs should use @code{gammainc} instead.

@code{gammai (@var{a}, @var{x})} is the same as @code{gammainc
(@var{x}, @var{a})}.
@end deftypefn
isprime
-*- texinfo -*-
@deftypefn {Function File} {} isprime (@var{n})

Return true if @var{n} is a prime number, false otherwise.

Something like the following is much faster if you need to test a lot
of small numbers:

@example
@var{t} = ismember (@var{n}, primes (max (@var{n} (:))));
@end example

If max(n) is very large, then you should be using special purpose 
factorization code.

@seealso{primes, factor, gcd, lcm}
@end deftypefn
legendre
-*- texinfo -*-
@deftypefn {Function File} {@var{L} =} legendre (@var{n}, @var{X})

Legendre Function of degree n and order m
where all values for m = 0..@var{n} are returned.
@var{n} must be a scalar in the range [0..255].
The return value has one dimension more than @var{x}.

@example
The Legendre Function of degree n and order m

@group
 m        m       2  m/2   d^m
P(x) = (-1) * (1-x  )    * ----  P (x)
 n                         dx^m   n
@end group

with:
Legendre Polynom of degree n

@group
          1     d^n   2    n
P (x) = ------ [----(x - 1)  ] 
 n      2^n n!  dx^n
@end group

legendre(3,[-1.0 -0.9 -0.8]) returns the matrix

@group
 x  |   -1.0   |   -0.9   |  -0.8
------------------------------------
m=0 | -1.00000 | -0.47250 | -0.08000
m=1 |  0.00000 | -1.99420 | -1.98000
m=2 |  0.00000 | -2.56500 | -4.32000
m=3 |  0.00000 | -1.24229 | -3.24000 
@end group
@end example
@end deftypefn
log2
-*- texinfo -*-
@deftypefn {Mapping Function} {} log2 (@var{x})
@deftypefnx {Mapping Function} {[@var{f}, @var{e}] =} log2 (@var{x})
Compute the base-2 logarithm of @var{x}.  With two outputs, returns
@var{f} and @var{e} such that
@iftex
@tex
 $1/2 <= |f| < 1$ and $x = f \cdot 2^e$.
@end tex
@end iftex
@ifinfo
 1/2 <= abs(f) < 1 and x = f * 2^e.
@end ifinfo
@seealso{log, log10, logspace, exp}
@end deftypefn
nchoosek
-*- texinfo -*-
@deftypefn {Function File} {@var{c} =} nchoosek (@var{n}, @var{k})

Compute the binomial coefficient or all combinations of @var{n}.
If @var{n} is a scalar then, calculate the binomial coefficient
of @var{n} and @var{k}, defined as

@iftex
@tex
$$
 {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
               = {n! \over k! (n-k)!}
$$
@end tex
@end iftex
@ifinfo

@example
@group
 /   \
 | n |    n (n-1) (n-2) ... (n-k+1)       n!
 |   |  = ------------------------- =  ---------
 | k |               k!                k! (n-k)!
 \   /
@end group
@end example
@end ifinfo

If @var{n} is a vector generate all combinations of the elements
of @var{n}, taken @var{k} at a time, one row per combination. The 
resulting @var{c} has size @code{[nchoosek (length (@var{n}), 
@var{k}), @var{k}]}.

@seealso{bincoeff}
@end deftypefn
perms
-*- texinfo -*-
@deftypefn {Function File} {} perms (@var{v})

Generate all permutations of @var{v}, one row per permutation. The
result has size @code{factorial (@var{n}) * @var{n}}, where @var{n}
is the length of @var{v}.

As an example, @code{perms([1, 2, 3])} returns the matrix
@example
  1   2   3
  2   1   3
  1   3   2
  2   3   1
  3   1   2
  3   2   1
@end example
@end deftypefn
pow2
-*- texinfo -*-
@deftypefn {Mapping Function} {} pow2 (@var{x})
@deftypefnx {Mapping Function} {} pow2 (@var{f}, @var{e})
With one argument, computes
@iftex
@tex
 $2^x$
@end tex
@end iftex
@ifinfo
 2 .^ x
@end ifinfo
for each element of @var{x}.  With two arguments, returns
@iftex
@tex
 $f \cdot 2^e$.
@end tex
@end iftex
@ifinfo
 f .* (2 .^ e).
@end ifinfo
@seealso{nextpow2}
@end deftypefn
primes
-*- texinfo -*-
@deftypefn {Function File} {} primes (@var{n})

Return all primes up to @var{n}.  

Note that if you need a specific number of primes, you can use the
fact the distance from one prime to the next is on average
proportional to the logarithm of the prime.  Integrating, you find
that there are about @math{k} primes less than @math{k \log ( 5 k )}.

The algorithm used is called the Sieve of Erastothenes.
@end deftypefn
hadamard
-*- texinfo -*-
@deftypefn {Function File} {} hadamard (@var{n})
Construct a Hadamard matrix @var{Hn} of size @var{n}-by-@var{n}. The 
size @var{n} must be of the form @code{2 ^ @var{k} * @var{p}} in which
@var{p} is one of 1, 12, 20 or 28. The returned matrix is normalized,
meaning @code{Hn(:,1) == 1} and @code{H(1,:) == 1}.

Some of the properties of Hadamard matrices are:

@itemize @bullet
@item
@code{kron (@var{Hm}, @var{Hn})} is a Hadamard matrix of size 
@var{m}-by-@var{n}.
@item
@code{Hn * Hn' == @var{n} * eye (@var{n})}.
@item
The rows of @var{Hn} are orthogonal.
@item
@code{det (@var{A}) <= det (@var{Hn})} for all @var{A} with 
@code{abs (@var{A} (@var{i}, @var{j})) <= 1}.
@item
Multiply any row or column by -1 and still have a Hadamard matrix.
@end itemize

@end deftypefn
hankel
-*- texinfo -*-
@deftypefn {Function File} {} hankel (@var{c}, @var{r})
Return the Hankel matrix constructed given the first column @var{c}, and
(optionally) the last row @var{r}.  If the last element of @var{c} is
not the same as the first element of @var{r}, the last element of
@var{c} is used.  If the second argument is omitted, it is assumed to
be a vector of zeros with the same size as @var{c}.

A Hankel matrix formed from an m-vector @var{c}, and an n-vector
@var{r}, has the elements
@iftex
@tex
$$
H (i, j) = \cases{c_{i+j-1},&$i+j-1\le m$;\cr r_{i+j-m},&otherwise.\cr}
$$
@end tex
@end iftex
@ifinfo

@example
@group
H(i,j) = c(i+j-1),  i+j-1 <= m;
H(i,j) = r(i+j-m),  otherwise
@end group
@end example
@end ifinfo
@seealso{vander, sylvester_matrix, hilb, invhilb, toeplitz}
@end deftypefn
hilb
-*- texinfo -*-
@deftypefn {Function File} {} hilb (@var{n})
Return the Hilbert matrix of order @var{n}.  The
@iftex
@tex
$i,\,j$
@end tex
@end iftex
@ifinfo
i, j
@end ifinfo
element of a Hilbert matrix is defined as
@iftex
@tex
$$
H (i, j) = {1 \over (i + j - 1)}
$$
@end tex
@end iftex
@ifinfo

@example
H (i, j) = 1 / (i + j - 1)
@end example
@end ifinfo
@seealso{hankel, vander, sylvester_matrix, invhilb, toeplitz}
@end deftypefn
invhilb
-*- texinfo -*-
@deftypefn {Function File} {} invhilb (@var{n})
Return the inverse of a Hilbert matrix of order @var{n}.  This can be 
computed exactly using
@tex
$$\eqalign{
  A_{ij} &= -1^{i+j} (i+j-1)
             \left( \matrix{n+i-1 \cr n-j } \right)
             \left( \matrix{n+j-1 \cr n-i } \right)
             \left( \matrix{i+j-2 \cr i-2 } \right)^2 \cr
         &= { p(i)p(j) \over (i+j-1) }
}$$
where
$$
  p(k) = -1^k \left( \matrix{ k+n-1 \cr k-1 } \right)
              \left( \matrix{ n \cr k } \right)
$$
@end tex
@ifinfo
@example

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

@end example
where
@example
             k  /k+n-1\   /n\
    p(k) = -1  (       ) (   )
                \ k-1 /   \k/
@end example
@end ifinfo

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 @code{inverse (hilb (n))},
which suffers from the ill-conditioning of the Hilbert matrix, and the
finite precision of your computer's floating point arithmetic.
@seealso{hankel, vander, sylvester_matrix, hilb, toeplitz}
@end deftypefn
magic
-*- texinfo -*-
@deftypefn {Function File} {} magic (@var{n})

Create an @var{n}-by-@var{n} magic square. Note that @code{magic
(@var{2})} is undefined since there is no 2-by-2 magic square.

@end deftypefn
pascal
-*- texinfo -*-
@deftypefn {Function File} {} pascal (@var{n}, @var{t})

Return the Pascal matrix of order @var{n} if @code{@var{t} = 0}.
@var{t} defaults to 0. Return lower triangular Cholesky factor of 
the Pascal matrix if @code{@var{t} = 1}. This matrix is its own
inverse, that is @code{pascal (@var{n}, 1) ^ 2 == eye (@var{n})}.
If @code{@var{t} = 2}, return a transposed and  permuted version of
@code{pascal (@var{n}, 1)}, which is the cube-root of the identity
matrix. That is @code{pascal (@var{n}, 2) ^ 3 == eye (@var{n})}.

@seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz
          hadamard, wilkinson, compan, rosser}
@end deftypefn
rosser
-*- texinfo -*-
@deftypefn {Function File} {} rosser ()

Returns the Rosser matrix. This is a difficult test case used to test
eigenvalue algorithms.

@seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz
          hadamard, wilkinson, compan, pascal}
@end deftypefn
sylvester_matrix
-*- texinfo -*-
@deftypefn {Function File} {} sylvester_matrix (@var{k})
Return the Sylvester matrix of order
@iftex
@tex
$n = 2^k$.
@end tex
@end iftex
@ifinfo
n = 2^k.
@end ifinfo
@seealso{hankel, vander, hilb, invhilb, toeplitz}
@end deftypefn
toeplitz
-*- texinfo -*-
@deftypefn {Function File} {} toeplitz (@var{c}, @var{r})
Return the Toeplitz matrix constructed given the first column @var{c},
and (optionally) the first row @var{r}.  If the first element of @var{c}
is not the same as the first element of @var{r}, the first element of
@var{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:
@iftex
@tex
$$
\left[\matrix{c_0    & r_1     & r_2      & \cdots & r_n\cr
              c_1    & c_0     & r_1      & \cdots & r_{n-1}\cr
              c_2    & c_1     & c_0      & \cdots & r_{n-2}\cr
              \vdots & \vdots  & \vdots   & \ddots & \vdots\cr
              c_n    & c_{n-1} & c_{n-2} & \ldots & c_0}\right]
$$
@end tex
@end iftex
@ifinfo

@example
@group
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)
@end group
@end example
@end ifinfo
@seealso{hankel, vander, sylvester_matrix, hilb, invhilb}
@end deftypefn
vander
-*- texinfo -*-
@deftypefn {Function File} {} vander (@var{c})
Return the Vandermonde matrix whose next to last column is @var{c}.

A Vandermonde matrix has the form:
@iftex
@tex
$$
\left[\matrix{c_1^{n-1}  & \cdots & c_1^2  & c_1    & 1      \cr
              c_2^{n-1}  & \cdots & c_2^2  & c_2    & 1      \cr
              \vdots     & \ddots & \vdots & \vdots & \vdots \cr
              c_n^{n-1}  & \cdots & c_n^2  & c_n    & 1      }\right]
$$
@end tex
@end iftex
@ifinfo

@example
@group
c(1)^(n-1) ... c(1)^2  c(1)  1
c(2)^(n-1) ... c(2)^2  c(2)  1
    .     .      .      .    .
    .       .    .      .    .
    .         .  .      .    .
c(n)^(n-1) ... c(n)^2  c(n)  1
@end group
@end example
@end ifinfo
@seealso{hankel, sylvester_matrix, hilb, invhilb, toeplitz}
@end deftypefn
wilkinson
-*- texinfo -*-
@deftypefn {Function File} {} wilkinson (@var{n})

Return the Wilkinson matrix of order @var{n}.

@seealso{hankel, vander, sylvester_matrix, hilb, invhilb, toeplitz
          hadamard, rosser, compan, pascal}
@end deftypefn
center
-*- texinfo -*-
@deftypefn {Function File} {} center (@var{x})
@deftypefnx {Function File} {} center (@var{x}, @var{dim})
If @var{x} is a vector, subtract its mean.
If @var{x} is a matrix, do the above for each column.
If the optional argument @var{dim} is given, perform the above
operation along this dimension
@end deftypefn
cloglog
-*- texinfo -*-
@deftypefn {Function File} {} cloglog (@var{x})
Return the complementary log-log function of @var{x}, defined as

@iftex
@tex
$$
{\rm cloglog}(x) = - \log (- \log (x))
$$
@end tex
@end iftex
@ifnottex
@example
cloglog(x) = - log (- log (@var{x}))
@end example
@end ifnottex
@end deftypefn
cor
-*- texinfo -*-
@deftypefn {Function File} {} cor (@var{x}, @var{y})
Compute correlation.

The (@var{i}, @var{j})-th entry of @code{cor (@var{x}, @var{y})} is
the correlation between the @var{i}-th variable in @var{x} and the
@var{j}-th variable in @var{y}.

@iftex
@tex
$$
{\rm corrcoef}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) {\rm std}(y)}
$$
@end tex
@end iftex
@ifnottex
@example
corrcoef(x,y) = cov(x,y)/(std(x)*std(y))
@end example
@end ifnottex

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

@code{cor (@var{x})} is equivalent to @code{cor (@var{x}, @var{x})}.

Note that the @code{corrcoef} function does the same as @code{cor}.
@end deftypefn
corrcoef
-*- texinfo -*-
@deftypefn {Function File} {} corrcoef (@var{x}, @var{y})
Compute correlation.

If each row of @var{x} and @var{y} is an observation and each column is
a variable, the (@var{i}, @var{j})-th entry of
@code{corrcoef (@var{x}, @var{y})} is the correlation between the
@var{i}-th variable in @var{x} and the @var{j}-th variable in @var{y}.

@iftex
@tex
$$
{\rm corrcoef}(x,y) = {{\rm cov}(x,y) \over {\rm std}(x) {\rm std}(y)}
$$
@end tex
@end iftex
@ifnottex
@example
corrcoef(x,y) = cov(x,y)/(std(x)*std(y))
@end example
@end ifnottex

If called with one argument, compute @code{corrcoef (@var{x}, @var{x})}.
@end deftypefn
cov
-*- texinfo -*-
@deftypefn {Function File} {} cov (@var{x}, @var{y})
Compute covariance.

If each row of @var{x} and @var{y} is an observation and each column is
a variable, the (@var{i}, @var{j})-th entry of
@code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th
variable in @var{x} and the @var{j}-th variable in @var{y}.
@iftex
@tex
$$
\sigma_{ij} = {1 \over N-1} \sum_{i=1}^N (x_i - \bar{x})(y_i - \bar{y})
$$
where $\bar{x}$ and $\bar{y}$ are the mean values of $x$ and $y$.
@end tex
@end iftex
If called with one argument, compute @code{cov (@var{x}, @var{x})}.
@end deftypefn
cut
-*- texinfo -*-
@deftypefn {Function File} {} cut (@var{x}, @var{breaks})
Create categorical data out of numerical or continuous data by
cutting into intervals.

If @var{breaks} is a scalar, the data is cut into that many
equal-width intervals.  If @var{breaks} is a vector of break points,
the category has @code{length (@var{breaks}) - 1} groups.

The returned value is a vector of the same size as @var{x} telling
which group each point in @var{x} belongs to.  Groups are labelled
from 1 to the number of groups; points outside the range of
@var{breaks} are labelled by @code{NaN}.
@end deftypefn
gls
-*- texinfo -*-
@deftypefn {Function File} {[@var{beta}, @var{v}, @var{r}] =} gls (@var{y}, @var{x}, @var{o})
Generalized least squares estimation for the multivariate model
@iftex
@tex
$y = x b + e$
with $\bar{e} = 0$ and cov(vec($e$)) = $(s^2)o$,
@end tex
@end iftex
@ifinfo
@math{y = x b + e} with @math{mean (e) = 0} and
@math{cov (vec (e)) = (s^2) o},
@end ifinfo
 where
@iftex
@tex
$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix, $b$ is a $k
\times p$ matrix, $e$ is a $t \times p$ matrix, and $o$ is a $tp \times
tp$ matrix.
@end tex
@end iftex
@ifinfo
@math{y} is a @math{t} by @math{p} matrix, @math{x} is a @math{t} by
@math{k} matrix, @math{b} is a @math{k} by @math{p} matrix, @math{e}
is a @math{t} by @math{p} matrix, and @math{o} is a @math{t p} by
@math{t p} matrix.
@end ifinfo

@noindent
Each row of @var{y} and @var{x} is an observation and each column a
variable.  The return values @var{beta}, @var{v}, and @var{r} are
defined as follows.

@table @var
@item beta
The GLS estimator for @math{b}.

@item v
The GLS estimator for @math{s^2}.

@item r
The matrix of GLS residuals, @math{r = y - x beta}.
@end table
@end deftypefn
iqr
-*- texinfo -*-
@deftypefn {Function File} {} iqr (@var{x}, @var{dim})
If @var{x} is a vector, return the interquartile range, i.e., the
difference between the upper and lower quartile, of the input data.

If @var{x} is a matrix, do the above for first non singleton
dimension of @var{x}. If the option @var{dim} argument is given,
then operate along this dimension.
@end deftypefn
kendall
-*- texinfo -*-
@deftypefn {Function File} {} kendall (@var{x}, @var{y})
Compute Kendall's @var{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.

@code{kendall (@var{x})} is equivalent to @code{kendall (@var{x},
@var{x})}.

For two data vectors @var{x}, @var{y} of common length @var{n},
Kendall's @var{tau} is the correlation of the signs of all rank
differences of @var{x} and @var{y};  i.e., if both @var{x} and
@var{y} have distinct entries, then

@iftex
@tex
$$ \tau = {1 \over n(n-1)} \sum_{i,j} {\rm sign}(q_i-q_j) {\rm sign}(r_i-r_j) $$
@end tex
@end iftex
@ifinfo
@example
         1    
tau = -------   SUM sign (q(i) - q(j)) * sign (r(i) - r(j))
      n (n-1)   i,j
@end example
@end ifinfo

@noindent
in which the
@iftex
@tex
$q_i$ and $r_i$
@end tex
@end iftex
@ifinfo
@var{q}(@var{i}) and @var{r}(@var{i})
@end ifinfo
 are the ranks of
@var{x} and @var{y}, respectively.

If @var{x} and @var{y} are drawn from independent distributions,
Kendall's @var{tau} is asymptotically normal with mean 0 and variance
@iftex
@tex
${2 (2n+5) \over 9n(n-1)}$.
@end tex
@end iftex
@ifnottex
@code{(2 * (2@var{n}+5)) / (9 * @var{n} * (@var{n}-1))}.
@end ifnottex
@end deftypefn
kurtosis
-*- texinfo -*-
@deftypefn {Function File} {} kurtosis (@var{x}, @var{dim})
If @var{x} is a vector of length @math{N}, return the kurtosis
@iftex
@tex
$$
 {\rm kurtosis} (x) = {1\over N \sigma(x)^4} \sum_{i=1}^N (x_i-\bar{x})^4 - 3
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@end iftex
@ifinfo

@example
kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3
@end example
@end ifinfo

@noindent
of @var{x}.  If @var{x} is a matrix, return the kurtosis over the
first non-singleton dimension. The optional argument @var{dim}
can be given to force the kurtosis to be given over that 
dimension.
@end deftypefn
logit
-*- texinfo -*-
@deftypefn {Function File} {} logit (@var{p})
For each component of @var{p}, return the logit of @var{p} defined as
@iftex
@tex
$$
{\rm logit}(p) = \log\Big({p \over 1-p}\Big)
$$
@end tex
@end iftex
@ifnottex
@example
logit(@var{p}) = log (@var{p} / (1-@var{p}))
@end example
@end ifnottex
@end deftypefn
mahalanobis
-*- texinfo -*-
@deftypefn {Function File} {} mahalanobis (@var{x}, @var{y})
Return the Mahalanobis' D-square distance between the multivariate
samples @var{x} and @var{y}, which must have the same number of
components (columns), but may have a different number of observations
(rows).
@end deftypefn
mean
-*- texinfo -*-
@deftypefn {Function File} {} mean (@var{x}, @var{dim}, @var{opt})
If @var{x} is a vector, compute the mean of the elements of @var{x}
@iftex
@tex
$$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$
@end tex
@end iftex
@ifinfo

@example
mean (x) = SUM_i x(i) / N
@end example
@end ifinfo
If @var{x} is a matrix, compute the mean for each column and return them
in a row vector.

With the optional argument @var{opt}, the kind of mean computed can be
selected.  The following options are recognized:

@table @code
@item "a"
Compute the (ordinary) arithmetic mean.  This is the default.

@item "g"
Computer the geometric mean.

@item "h"
Compute the harmonic mean.
@end table

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.

Both @var{dim} and @var{opt} are optional.  If both are supplied,
either may appear first.
@end deftypefn
meansq
-*- texinfo -*-
@deftypefn {Function File} {} meansq (@var{x})
@deftypefnx {Function File} {} meansq (@var{x}, @var{dim})
For vector arguments, return the mean square of the values.
For matrix arguments, return a row vector contaning the mean square
of each column. With the optional @var{dim} argument, returns the
mean squared of the values along this dimension.
@end deftypefn
median
-*- texinfo -*-
@deftypefn {Function File} {} median (@var{x}, @var{dim})
If @var{x} is a vector, compute the median value of the elements of
@var{x}. If the elements of @var{x} are sorted, the median is defined
as
@iftex
@tex
$$
{\rm median} (x) =
  \cases{x(\lceil N/2\rceil), & $N$ odd;\cr
          (x(N/2)+x(N/2+1))/2, & $N$ even.}
$$
@end tex
@end iftex
@ifinfo

@example
@group
            x(ceil(N/2)),             N odd
median(x) =
            (x(N/2) + x((N/2)+1))/2,  N even
@end group
@end example
@end ifinfo
If @var{x} is a matrix, compute the median value for each
column and return them in a row vector. If the optional @var{dim}
argument is given, operate along this dimension.
@seealso{std, mean}
@end deftypefn
mode
-*- texinfo -*-
@deftypefn {Function File} {[@var{m}, @var{f}, @var{c}] =} mode (@var{x}, @var{dim})
Count the most frequently appearing value. @code{mode} counts the 
frequency along the first non-singleton dimension and if two or more
values have te same frequency returns the smallest of the two in
@var{m}. The dimension along which to count can be specified by the
@var{dim} parameter.

The variable @var{f} counts the frequency of each of the most frequently 
occuring ellements. The cell array @var{c} contains all of the elements
with the maximum frequency .
@end deftypefn
moment
-*- texinfo -*-
@deftypefn {Function File} {} moment (@var{x}, @var{p}, @var{opt}, @var{dim})
If @var{x} is a vector, compute the @var{p}-th moment of @var{x}.

If @var{x} is a matrix, return the row vector containing the
@var{p}-th moment of each column.

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

@example
moment (x, 3, "ac")
@end example

@noindent
computes the third central absolute moment of @var{x}.

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.
@end deftypefn
ols
-*- texinfo -*-
@deftypefn {Function File} {[@var{beta}, @var{sigma}, @var{r}] =} ols (@var{y}, @var{x})
Ordinary least squares estimation for the multivariate model
@iftex
@tex
$y = x b + e$
with
$\bar{e} = 0$, and cov(vec($e$)) = kron ($s, I$)
@end tex
@end iftex
@ifinfo
@math{y = x b + e} with
@math{mean (e) = 0} and @math{cov (vec (e)) = kron (s, I)}.
@end ifinfo
 where
@iftex
@tex
$y$ is a $t \times p$ matrix, $x$ is a $t \times k$ matrix,
$b$ is a $k \times p$ matrix, and $e$ is a $t \times p$ matrix.
@end tex
@end iftex
@ifinfo
@math{y} is a @math{t} by @math{p} matrix, @math{x} is a @math{t} by
@math{k} matrix, @math{b} is a @math{k} by @math{p} matrix, and
@math{e} is a @math{t} by @math{p} matrix.
@end ifinfo

Each row of @var{y} and @var{x} is an observation and each column a
variable.

The return values @var{beta}, @var{sigma}, and @var{r} are defined as
follows.

@table @var
@item beta
The OLS estimator for @var{b}, @code{@var{beta} = pinv (@var{x}) *
@var{y}}, where @code{pinv (@var{x})} denotes the pseudoinverse of
@var{x}.

@item sigma
The OLS estimator for the matrix @var{s},

@example
@group
@var{sigma} = (@var{y}-@var{x}*@var{beta})'
  * (@var{y}-@var{x}*@var{beta})
  / (@var{t}-rank(@var{x}))
@end group
@end example

@item r
The matrix of OLS residuals, @code{@var{r} = @var{y} - @var{x} *
@var{beta}}.
@end table
@end deftypefn
ppplot
-*- texinfo -*-
@deftypefn {Function File} {[@var{p}, @var{y}] =} ppplot (@var{x}, @var{dist}, @var{params})
Perform a PP-plot (probability plot).

If F is the CDF of the distribution @var{dist} with parameters
@var{params} and @var{x} a sample vector of length @var{n}, the
PP-plot graphs ordinate @var{y}(@var{i}) = F (@var{i}-th largest
element of @var{x}) versus abscissa @var{p}(@var{i}) = (@var{i} -
0.5)/@var{n}.  If the sample comes from F, the pairs will
approximately follow a straight line.

The default for @var{dist} is the standard normal distribution.  The
optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, for a probability plot of the uniform
distribution on [2,4] and @var{x}, use

@example
ppplot (x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_cdf}
that calculates the CDF of distribution @var{dist} exists.

If no output arguments are given, the data are plotted directly.
@end deftypefn
probit
-*- texinfo -*-
@deftypefn {Function File} {} probit (@var{p})
For each component of @var{p}, return the probit (the quantile of the
standard normal distribution) of @var{p}.
@end deftypefn
qqplot
-*- texinfo -*-
@deftypefn {Function File} {[@var{q}, @var{s}] =} qqplot (@var{x}, @var{dist}, @var{params})
Perform a QQ-plot (quantile plot).

If F is the CDF of the distribution @var{dist} with parameters
@var{params} and G its inverse, and @var{x} a sample vector of length
@var{n}, the QQ-plot graphs ordinate @var{s}(@var{i}) = @var{i}-th
largest element of x versus abscissa @var{q}(@var{i}f) = G((@var{i} -
0.5)/@var{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 @var{dist} is the standard normal distribution.  The
optional argument @var{params} contains a list of parameters of
@var{dist}.  For example, for a quantile plot of the uniform
distribution on [2,4] and @var{x}, use

@example
qqplot (x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_inv}
that calculates the inverse CDF of distribution @var{dist} exists.

If no output arguments are given, the data are plotted directly.
@end deftypefn
range
-*- texinfo -*-
@deftypefn {Function File} {} range (@var{x})
@deftypefnx {Function File} {} range (@var{x}, @var{dim})
If @var{x} is a vector, return the range, i.e., the difference
between the maximum and the minimum, of the input data.

If @var{x} is a matrix, do the above for each column of @var{x}.

If the optional argument @var{dim} is supplied, work along dimension
@var{dim}.
@end deftypefn
ranks
-*- texinfo -*-
@deftypefn {Function File} {} ranks (@var{x}, @var{dim})
If @var{x} is a vector, return the (column) vector of ranks of
@var{x} adjusted for ties.

If @var{x} is a matrix, do the above for along the first 
non-singleton dimension. If the optional argument @var{dim} is
given, operate along this dimension.
@end deftypefn
run_count
-*- texinfo -*-
@deftypefn {Function File} {} run_count (@var{x}, @var{n})
Count the upward runs along the first non-singleton dimension of
@var{x} of length 1, 2, @dots{}, @var{n}-1 and greater than or equal 
to @var{n}. If the optional argument @var{dim} is given operate
along this dimension
@end deftypefn
skewness
-*- texinfo -*-
@deftypefn {Function File} {} skewness (@var{x}, @var{dim})
If @var{x} is a vector of length @math{n}, return the skewness
@iftex
@tex
$$
{\rm skewness} (x) = {1\over N \sigma(x)^3} \sum_{i=1}^N (x_i-\bar{x})^3
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@end iftex
@ifinfo

@example
skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)
@end example
@end ifinfo

@noindent
of @var{x}.  If @var{x} is a matrix, return the skewness along the
first non-singleton dimension of the matrix. If the optional
@var{dim} argument is given, operate along this dimension.
@end deftypefn
spearman
-*- texinfo -*-
@deftypefn {Function File} {} spearman (@var{x}, @var{y})
Compute Spearman's rank correlation coefficient @var{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.

@code{spearman (@var{x})} is equivalent to @code{spearman (@var{x},
@var{x})}.

For two data vectors @var{x} and @var{y}, Spearman's @var{rho} is the
correlation of the ranks of @var{x} and @var{y}.

If @var{x} and @var{y} are drawn from independent distributions,
@var{rho} has zero mean and variance @code{1 / (n - 1)}, and is
asymptotically normally distributed.
@end deftypefn
statistics
-*- texinfo -*-
@deftypefn {Function File} {} statistics (@var{x})
If @var{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 @var{x} as its rows.

If @var{x} is a vector, treat it as a column vector.
@end deftypefn
std
-*- texinfo -*-
@deftypefn {Function File} {} std (@var{x})
@deftypefnx {Function File} {} std (@var{x}, @var{opt})
@deftypefnx {Function File} {} std (@var{x}, @var{opt}, @var{dim})
If @var{x} is a vector, compute the standard deviation of the elements
of @var{x}.
@iftex
@tex
$$
{\rm std} (x) = \sigma (x) = \sqrt{{\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1}}
$$
where $\bar{x}$ is the mean value of $x$.
@end tex
@end iftex
@ifnottex

@example
@group
std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
@end group
@end example
@end ifnottex
If @var{x} is a matrix, compute the standard deviation for
each column and return them in a row vector.

The argument @var{opt} determines the type of normalization to use. Valid values
are

@table @asis 
@item 0:
  normalizes with @math{N-1}, provides the square root of best unbiased estimator of 
  the variance [default]
@item 1:
  normalizes with @math{N}, this provides the square root of the second moment around 
  the mean
@end table

The third argument @var{dim} determines the dimension along which the standard
deviation is calculated.
@seealso{mean, median}
@end deftypefn
studentize
-*- texinfo -*-
@deftypefn {Function File} {} studentize (@var{x}, @var{dim})
If @var{x} is a vector, subtract its mean and divide by its standard
deviation.

If @var{x} is a matrix, do the above along the first non-singleton
dimension. If the optional argument @var{dim} is given then operate
along this dimension.
@end deftypefn
table
-*- texinfo -*-
@deftypefn {Function File} {[@var{t}, @var{l_x}] =} table (@var{x})
@deftypefnx {Function File} {[@var{t}, @var{l_x}, @var{l_y}] =} table (@var{x}, @var{y})
Create a contingency table @var{t} from data vectors.  The @var{l}
vectors are the corresponding levels.

Currently, only 1- and 2-dimensional tables are supported.
@end deftypefn
values
-*- texinfo -*-
@deftypefn {Function File} {} values (@var{x})
Return the different values in a column vector, arranged in ascending
order.

As an example, @code{values([1, 2, 3, 1])} returns the vector
@code{[1, 2, 3]}.
@end deftypefn
var
-*- texinfo -*-
@deftypefn {Function File} {} var (@var{x})
For vector arguments, return the (real) variance of the values.
For matrix arguments, return a row vector contaning the variance for
each column.

The argument @var{opt} determines the type of normalization to use.
Valid values are

@table @asis 
@item 0:
Normalizes with @math{N-1}, provides the best unbiased estimator of the
variance [default].
@item 1:
Normalizes with @math{N}, this provides the second moment around the mean.
@end table

The third argument @var{dim} determines the dimension along which the 
variance is calculated.
@end deftypefn
betacdf
-*- texinfo -*-
@deftypefn {Function File} {} betacdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, returns the CDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}, i.e.,
PROB (beta (@var{a}, @var{b}) <= @var{x}).
@end deftypefn
betainv
-*- texinfo -*-
@deftypefn {Function File} {} betainv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Beta distribution with parameters @var{a}
and @var{b}.
@end deftypefn
betapdf
-*- texinfo -*-
@deftypefn {Function File} {} betapdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, returns the PDF at @var{x} of the beta
distribution with parameters @var{a} and @var{b}.
@end deftypefn
betarnd
-*- texinfo -*-
@deftypefn {Function File} {} betarnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} betarnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or @code{size (@var{sz})} matrix of 
random samples from the Beta distribution with parameters @var{a} and
@var{b}.  Both @var{a} and @var{b} must be scalar or of size @var{r}
 by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn
binocdf
-*- texinfo -*-
@deftypefn {Function File} {} binocdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the CDF at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@end deftypefn
binoinv
-*- texinfo -*-
@deftypefn {Function File} {} binoinv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
binomial distribution with parameters @var{n} and @var{p}.
@end deftypefn
binopdf
-*- texinfo -*-
@deftypefn {Function File} {} binopdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the binomial distribution with parameters @var{n}
and @var{p}.
@end deftypefn
binornd
-*- texinfo -*-
@deftypefn {Function File} {} binornd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} binornd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of 
random samples from the binomial distribution with parameters @var{n}
and @var{p}.  Both @var{n} and @var{p} must be scalar or of size
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}.
@end deftypefn
cauchy_cdf
-*- texinfo -*-
@deftypefn {Function File} {} cauchy_cdf (@var{x}, @var{lambda}, @var{sigma})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Cauchy distribution with location
parameter @var{lambda} and scale parameter @var{sigma}.  Default
values are @var{lambda} = 0, @var{sigma} = 1. 
@end deftypefn
cauchy_inv
-*- texinfo -*-
@deftypefn {Function File} {} cauchy_inv (@var{x}, @var{lambda}, @var{sigma})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the Cauchy distribution with location parameter
@var{lambda} and scale parameter @var{sigma}.  Default values are
@var{lambda} = 0, @var{sigma} = 1. 
@end deftypefn
cauchy_pdf
-*- texinfo -*-
@deftypefn {Function File} {} cauchy_pdf (@var{x}, @var{lambda}, @var{sigma})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Cauchy distribution with location parameter
@var{lambda} and scale parameter @var{sigma} > 0.  Default values are
@var{lambda} = 0, @var{sigma} = 1. 
@end deftypefn
cauchy_rnd
-*- texinfo -*-
@deftypefn {Function File} {} cauchy_rnd (@var{lambda}, @var{sigma}, @var{r}, @var{c})
@deftypefnx {Function File} {} cauchy_rnd (@var{lambda}, @var{sigma}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the Cauchy distribution with parameters @var{lambda} 
and @var{sigma} which must both be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{lambda} and @var{sigma}.
@end deftypefn
chi2cdf
-*- texinfo -*-
@deftypefn {Function File} {} chi2cdf (@var{x}, @var{n})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the chisquare distribution with @var{n}
degrees of freedom.
@end deftypefn
chi2inv
-*- texinfo -*-
@deftypefn {Function File} {} chi2inv (@var{x}, @var{n})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the chisquare distribution with @var{n} degrees of
freedom.
@end deftypefn
chi2pdf
-*- texinfo -*-
@deftypefn {Function File} {} chisquare_pdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the chisquare distribution with @var{n} degrees
of freedom.
@end deftypefn
chi2rnd
-*- texinfo -*-
@deftypefn {Function File} {} chi2rnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} chi2rnd (@var{n}, @var{sz})
Return an @var{r} by @var{c}  or a @code{size (@var{sz})} matrix of 
random samples from the chisquare distribution with @var{n} degrees 
of freedom.  @var{n} must be a scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{n}.
@end deftypefn
discrete_cdf
-*- texinfo -*-
@deftypefn {Function File} {} discrete_cdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of a univariate discrete distribution which
assumes the values in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_inv
-*- texinfo -*-
@deftypefn {Function File} {} discrete_inv (@var{x}, @var{v}, @var{p})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the univariate distribution which assumes the
values in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_pdf
-*- texinfo -*-
@deftypefn {Function File} {} discrete_pdf (@var{x}, @var{v}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of a univariate discrete distribution which assumes
the values in @var{v} with probabilities @var{p}.
@end deftypefn
discrete_rnd
-*- texinfo -*-
@deftypefn {Function File} {} discrete_rnd (@var{n}, @var{v}, @var{p})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} discrete_rnd (@var{v}, @var{p}, @var{sz})
Generate a row vector containing a random sample of size @var{n} from
the univariate distribution which assumes the values in @var{v} with
probabilities @var{p}. @var{n} must be a scalar.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns. Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn
empirical_cdf
-*- texinfo -*-
@deftypefn {Function File} {} empirical_cdf (@var{x}, @var{data})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the empirical distribution obtained from
the univariate sample @var{data}.
@end deftypefn
empirical_inv
-*- texinfo -*-
@deftypefn {Function File} {} empirical_inv (@var{x}, @var{data})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn
empirical_pdf
-*- texinfo -*-
@deftypefn {Function File} {} empirical_pdf (@var{x}, @var{data})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the empirical distribution obtained from the
univariate sample @var{data}.
@end deftypefn
empirical_rnd
-*- texinfo -*-
@deftypefn {Function File} {} empirical_rnd (@var{n}, @var{data})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{r}, @var{c})
@deftypefnx {Function File} {} empirical_rnd (@var{data}, @var{sz})
Generate a bootstrap sample of size @var{n} from the empirical
distribution obtained from the univariate sample @var{data}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns. Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn
expcdf
-*- texinfo -*-
@deftypefn {Function File} {} expcdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the exponential distribution with
parameter @var{lambda}.

The arguments can be of common size or scalar.
@end deftypefn
expinv
-*- texinfo -*-
@deftypefn {Function File} {} expinv (@var{x}, @var{lambda})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the exponential distribution with parameter
@var{lambda}.
@end deftypefn
exppdf
-*- texinfo -*-
@deftypefn {Function File} {} exppdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function
(PDF) of the exponential distribution with parameter @var{lambda}.
@end deftypefn
exprnd
-*- texinfo -*-
@deftypefn {Function File} {} exprnd (@var{lambda}, @var{r}, @var{c})
@deftypefnx {Function File} {} exprnd (@var{lambda}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
exponential distribution with parameter @var{lambda}, which must be a
scalar or of size @var{r} by @var{c}. Or if @var{sz} is a vector, 
create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{lambda}.
@end deftypefn
fcdf
-*- texinfo -*-
@deftypefn {Function File} {} fcdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the CDF at @var{x} of the F
distribution with @var{m} and @var{n} degrees of freedom, i.e.,
PROB (F (@var{m}, @var{n}) <= @var{x}). 
@end deftypefn
finv
-*- texinfo -*-
@deftypefn {Function File} {} finv (@var{x}, @var{m}, @var{n})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the F distribution with parameters @var{m} and
@var{n}.
@end deftypefn
fpdf
-*- texinfo -*-
@deftypefn {Function File} {} fpdf (@var{x}, @var{m}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the F distribution with @var{m} and @var{n}
degrees of freedom.
@end deftypefn
frnd
-*- texinfo -*-
@deftypefn {Function File} {} frnd (@var{m}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} frnd (@var{m}, @var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the F
distribution with @var{m} and @var{n} degrees of freedom.  Both
@var{m} and @var{n} must be scalar or of size @var{r} by @var{c}.
If @var{sz} is a vector the random samples are in a matrix of 
size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{n}.
@end deftypefn
gamcdf
-*- texinfo -*-
@deftypefn {Function File} {} gamcdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Gamma distribution with parameters
@var{a} and @var{b}.
@seealso{gamma, gammaln, gammainc, gampdf, gaminv, gamrnd}
@end deftypefn
gaminv
-*- texinfo -*-
@deftypefn {Function File} {} gaminv (@var{x}, @var{a}, @var{b})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}.
@seealso{gamma, gammaln, gammainc, gampdf, gamcdf, gamrnd}
@end deftypefn
gampdf
-*- texinfo -*-
@deftypefn {Function File} {} gampdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, return the probability density function
(PDF) at @var{x} of the Gamma distribution with parameters @var{a}
and @var{b}.
@seealso{gamma, gammaln, gammainc, gamcdf, gaminv, gamrnd}
@end deftypefn
gamrnd
-*- texinfo -*-
@deftypefn {Function File} {} gamrnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} gamrnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the Gamma distribution with parameters @var{a}
and @var{b}.  Both @var{a} and @var{b} must be scalar or of size 
@var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@seealso{gamma, gammaln, gammainc, gampdf, gamcdf, gaminv}
@end deftypefn
geocdf
-*- texinfo -*-
@deftypefn {Function File} {} geocdf (@var{x}, @var{p})
For each element of @var{x}, compute the CDF at @var{x} of the
geometric distribution with parameter @var{p}.
@end deftypefn
geoinv
-*- texinfo -*-
@deftypefn {Function File} {} geoinv (@var{x}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
geometric distribution with parameter @var{p}.
@end deftypefn
geopdf
-*- texinfo -*-
@deftypefn {Function File} {} geopdf (@var{x}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the geometric distribution with parameter @var{p}.
@end deftypefn
geornd
-*- texinfo -*-
@deftypefn {Function File} {} geornd (@var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} geornd (@var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
geometric distribution with parameter @var{p}, which must be a scalar
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are given create a matrix with @var{r} rows and
@var{c} columns. Or if @var{sz} is a vector, create a matrix of size
@var{sz}.
@end deftypefn
hygecdf
-*- texinfo -*-
@deftypefn {Function File} {} hygecdf (@var{x}, @var{m}, @var{t}, @var{n})
Compute the cumulative distribution function (CDF) at @var{x} of the
hypergeometric distribution with parameters @var{m}, @var{t}, and
@var{n}.  This is the probability of obtaining not more than @var{x}
marked items when randomly drawing a sample of size @var{n} without
replacement from a population of total size @var{t} containing
@var{m} marked items.

The parameters @var{m}, @var{t}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hygeinv
-*- texinfo -*-
@deftypefn {Function File} {} hygeinv (@var{x}, @var{m}, @var{t}, @var{n})
For each element of @var{x}, compute the quantile at @var{x} of the
hypergeometric distribution with parameters @var{m}, @var{t}, and
@var{n}.

The parameters @var{m}, @var{t}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
hygepdf
-*- texinfo -*-
@deftypefn {Function File} {} hygepdf (@var{x}, @var{m}, @var{t}, @var{n})
Compute the probability density function (PDF) at @var{x} of the
hypergeometric distribution with parameters @var{m}, @var{t}, and
@var{n}. This is the probability of obtaining @var{x} marked items
when randomly drawing a sample of size @var{n} without replacement
from a population of total size @var{t} containing @var{m} marked items.

The arguments must be of common size or scalar.
@end deftypefn
hygernd
-*- texinfo -*-
@deftypefn {Function File} {} hygernd (@var{m}, @var{t}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} hygernd (@var{m}, @var{t}, @var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
hypergeometric distribution with parameters @var{m}, @var{t},
and @var{n}.

The parameters @var{m}, @var{t}, and @var{n} must positive integers
with @var{m} and @var{n} not greater than @var{t}.
@end deftypefn
kolmogorov_smirnov_cdf
-*- texinfo -*-
@deftypefn {Function File} {} kolmogorov_smirnov_cdf (@var{x}, @var{tol})
Return the CDF at @var{x} of the Kolmogorov-Smirnov distribution,
@iftex
@tex
$$ Q(x) = \sum_{k=-\infty}^\infty (-1)^k \exp(-2 k^2 x^2) $$
@end tex
@end iftex
@ifinfo
@example
         Inf
Q(x) =   SUM    (-1)^k exp(-2 k^2 x^2)
       k = -Inf
@end example
@end ifinfo

@noindent
for @var{x} > 0.

The optional parameter @var{tol} specifies the precision up to which
the series should be evaluated;  the default is @var{tol} = @code{eps}.
@end deftypefn
laplace_cdf
-*- texinfo -*-
@deftypefn {Function File} {} laplace_cdf (@var{x})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Laplace distribution.
@end deftypefn
laplace_inv
-*- texinfo -*-
@deftypefn {Function File} {} laplace_inv (@var{x})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the Laplace distribution.
@end deftypefn
tcdf
-*- texinfo -*-
@deftypefn {Function File} {} tcdf (@var{x}, @var{n})
For each element of @var{x}, compute the CDF at @var{x} of the
t (Student) distribution with @var{n} degrees of freedom, i.e.,
PROB (t(@var{n}) <= @var{x}).
@end deftypefn
laplace_pdf
-*- texinfo -*-
@deftypefn {Function File} {} laplace_pdf (@var{x})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Laplace distribution.
@end deftypefn
laplace_rnd
-*- texinfo -*-
@deftypefn {Function File} {} laplace_rnd (@var{r}, @var{c})
@deftypefnx {Function File} {} laplace_rnd (@var{sz});
Return an @var{r} by @var{c} matrix of random numbers from the
Laplace distribution.  Or if @var{sz} is a vector, create a matrix of
@var{sz}.
@end deftypefn
logistic_cdf
-*- texinfo -*-
@deftypefn {Function File} {} logistic_cdf (@var{x})
For each component of @var{x}, compute the CDF at @var{x} of the
logistic distribution.
@end deftypefn
logistic_inv
-*- texinfo -*-
@deftypefn {Function File} {} logistic_inv (@var{x})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the logistic distribution.
@end deftypefn
logistic_pdf
-*- texinfo -*-
@deftypefn {Function File} {} logistic_pdf (@var{x})
For each component of @var{x}, compute the PDF at @var{x} of the
logistic distribution.
@end deftypefn
logistic_rnd
-*- texinfo -*-
@deftypefn {Function File} {} logistic_rnd (@var{r}, @var{c})
@deftypefnx {Function File} {} logistic_rnd (@var{sz})
Return an @var{r} by @var{c} matrix of random numbers from the
logistic distribution. Or if @var{sz} is a vector, create a matrix of
@var{sz}.
@end deftypefn
logncdf
-*- texinfo -*-
@deftypefn {Function File} {} logncdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the lognormal distribution with
parameters @var{mu} and @var{sigma}.  If a random variable follows this
distribution, its logarithm is normally distributed with mean
@var{mu} and standard deviation @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn
logninv
-*- texinfo -*-
@deftypefn {Function File} {} logninv (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the lognormal distribution with parameters @var{mu}
and @var{sigma}.  If a random variable follows this distribution, its
logarithm is normally distributed with mean @code{log (@var{mu})} and
variance @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn
lognpdf
-*- texinfo -*-
@deftypefn {Function File} {} lognpdf (@var{x}, @var{mu}, @var{sigma})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the lognormal distribution with parameters
@var{mu} and @var{sigma}.  If a random variable follows this distribution,
its logarithm is normally distributed with mean @var{mu}
and standard deviation @var{sigma}.

Default values are @var{mu} = 1, @var{sigma} = 1.
@end deftypefn
lognrnd
-*- texinfo -*-
@deftypefn {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{r}, @var{c})
@deftypefnx {Function File} {} lognrnd (@var{mu}, @var{sigma}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
lognormal distribution with parameters @var{mu} and @var{sigma}. Both
@var{mu} and @var{sigma} must be scalar or of size @var{r} by @var{c}.
Or if @var{sz} is a vector, create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{mu} and @var{sigma}.
@end deftypefn
nbincdf
-*- texinfo -*-
@deftypefn {Function File} {} nbincdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the CDF at x of the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution.
@end deftypefn
nbininv
-*- texinfo -*-
@deftypefn {Function File} {} nbininv (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the quantile at @var{x} of the
Pascal (negative binomial) distribution with parameters @var{n} and
@var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution.
@end deftypefn
nbinpdf
-*- texinfo -*-
@deftypefn {Function File} {} nbinpdf (@var{x}, @var{n}, @var{p})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the Pascal (negative binomial) distribution with
parameters @var{n} and @var{p}.

The number of failures in a Bernoulli experiment with success
probability @var{p} before the @var{n}-th success follows this
distribution. 
@end deftypefn
nbinrnd
-*- texinfo -*-
@deftypefn {Function File} {} nbinrnd (@var{n}, @var{p}, @var{r}, @var{c})
@deftypefnx {Function File} {} nbinrnd (@var{n}, @var{p}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the Pascal
(negative binomial) distribution with parameters @var{n} and @var{p}.
Both @var{n} and @var{p} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{n} and @var{p}. Or if @var{sz} is a vector, 
create a matrix of size @var{sz}.
@end deftypefn
normcdf
-*- texinfo -*-
@deftypefn {Function File} {} normcdf (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the normal distribution with mean
@var{m} and standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn
norminv
-*- texinfo -*-
@deftypefn {Function File} {} norminv (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the normal distribution with mean @var{m} and
standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn
normpdf
-*- texinfo -*-
@deftypefn {Function File} {} normpdf (@var{x}, @var{m}, @var{s})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the normal distribution with mean @var{m} and
standard deviation @var{s}.

Default values are @var{m} = 0, @var{s} = 1.
@end deftypefn
normrnd
-*- texinfo -*-
@deftypefn {Function File} {} normrnd (@var{m}, @var{s}, @var{r}, @var{c})
@deftypefnx {Function File} {} normrnd (@var{m}, @var{s}, @var{sz})
Return an @var{r} by @var{c}  or @code{size (@var{sz})} matrix of
random samples from the normal distribution with parameters mean @var{m} 
and standard deviation @var{s}.  Both @var{m} and @var{s} must be scalar 
or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{m} and @var{s}.
@end deftypefn
poisscdf
-*- texinfo -*-
@deftypefn {Function File} {} poisscdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of the Poisson distribution with parameter
lambda.
@end deftypefn
poissinv
-*- texinfo -*-
@deftypefn {Function File} {} poissinv (@var{x}, @var{lambda})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the Poisson distribution with parameter
@var{lambda}.
@end deftypefn
poisspdf
-*- texinfo -*-
@deftypefn {Function File} {} poisspdf (@var{x}, @var{lambda})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the poisson distribution with parameter @var{lambda}.
@end deftypefn
poissrnd
-*- texinfo -*-
@deftypefn {Function File} {} poissrnd (@var{lambda}, @var{r}, @var{c})
Return an @var{r} by @var{c} matrix of random samples from the
Poisson distribution with parameter @var{lambda}, which must be a 
scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{lambda}.
@end deftypefn
stdnormal_cdf
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_cdf (@var{x})
For each component of @var{x}, compute the CDF of the standard normal
distribution at @var{x}.
@end deftypefn
stdnormal_inv
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_inv (@var{x})
For each component of @var{x}, compute compute the quantile (the
inverse of the CDF) at @var{x} of the standard normal distribution.
@end deftypefn
stdnormal_pdf
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_pdf (@var{x})
For each element of @var{x}, compute the probability density function
(PDF) of the standard normal distribution at @var{x}.
@end deftypefn
stdnormal_rnd
-*- texinfo -*-
@deftypefn {Function File} {} stdnormal_rnd (@var{r}, @var{c})
@deftypefnx {Function File} {} stdnormal_rnd (@var{sz})
Return an @var{r} by @var{c} or @code{size (@var{sz})} matrix of 
random numbers from the standard normal distribution.
@end deftypefn
tinv
-*- texinfo -*-
@deftypefn {Function File} {} tinv (@var{x}, @var{n})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the t (Student) distribution with parameter
@var{n}.
@end deftypefn
tpdf
-*- texinfo -*-
@deftypefn {Function File} {} tpdf (@var{x}, @var{n})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of the @var{t} (Student) distribution with @var{n}
degrees of freedom. 
@end deftypefn
trnd
-*- texinfo -*-
@deftypefn {Function File} {} trnd (@var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} trnd (@var{n}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the t
(Student) distribution with @var{n} degrees of freedom.  @var{n} must
be a scalar or of size @var{r} by @var{c}. Or if @var{sz} is a
vector create a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the size of @var{n}.
@end deftypefn
unidcdf
-*- texinfo -*-
@deftypefn {Function File} {} unidcdf (@var{x}, @var{v})
For each element of @var{x}, compute the cumulative distribution
function (CDF) at @var{x} of a univariate discrete distribution which
assumes the values in @var{v} with equal probability.
@end deftypefn
unidinv
-*- texinfo -*-
@deftypefn {Function File} {} unidinv (@var{x}, @var{v})
For each component of @var{x}, compute the quantile (the inverse of
the CDF) at @var{x} of the univariate discrete distribution which assumes the
values in @var{v} with equal probability
@end deftypefn
unidpdf
-*- texinfo -*-
@deftypefn {Function File} {} unidpdf (@var{x}, @var{v})
For each element of @var{x}, compute the probability density function
(PDF) at @var{x} of a univariate discrete distribution which assumes
the values in @var{v} with equal probability.
@end deftypefn
unidrnd
-*- texinfo -*-
@deftypefn {Function File} {} unidrnd (@var{mx});
@deftypefnx {Function File} {} unidrnd (@var{mx}, @var{v});
@deftypefnx {Function File} {} unidrnd (@var{mx}, @var{m}, @var{n}, @dots{});
Return random values from discrete uniform distribution, with maximum
value(s) given by the integer @var{mx}, which may be a scalar or
multidimensional array.

If @var{mx} is a scalar, the size of the result is specified by
the vector @var{v}, or by the optional arguments @var{m}, @var{n},
@dots{}.  Otherwise, the size of the result is the same as the size
of @var{mx}.
@end deftypefn
unifcdf
-*- texinfo -*-
@deftypefn {Function File} {} unifcdf (@var{x}, @var{a}, @var{b})
Return the CDF at @var{x} of the uniform distribution on [@var{a},
@var{b}], i.e., PROB (uniform (@var{a}, @var{b}) <= x).

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
unifinv
-*- texinfo -*-
@deftypefn {Function File} {} unifinv (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the quantile (the inverse of the
CDF) at @var{x} of the uniform distribution on [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
unifpdf
-*- texinfo -*-
@deftypefn {Function File} {} unifpdf (@var{x}, @var{a}, @var{b})
For each element of @var{x}, compute the PDF at @var{x} of the uniform
distribution on [@var{a}, @var{b}].

Default values are @var{a} = 0, @var{b} = 1.
@end deftypefn
unifrnd
-*- texinfo -*-
@deftypefn {Function File} {} unifrnd (@var{a}, @var{b}, @var{r}, @var{c})
@deftypefnx {Function File} {} unifrnd (@var{a}, @var{b}, @var{sz})
Return an @var{r} by @var{c} or a @code{size (@var{sz})} matrix of 
random samples from the uniform distribution on [@var{a}, @var{b}]. 
Both @var{a} and @var{b} must be scalar or of size @var{r} by @var{c}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{a} and @var{b}.
@end deftypefn
wblcdf
-*- texinfo -*-
@deftypefn {Function File} {} wblcdf (@var{x}, @var{scale}, @var{shape})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}, which is

@iftex
@tex
$$ 1 - \exp(-(x/shape)^{scale}) $$
for $x\geq 0$.
@end tex
@end iftex
@ifnottex
@example
1 - exp(-(x/shape)^scale)
@end example
for @var{x} >= 0.
@end ifnottex
@end deftypefn
wblinv
-*- texinfo -*-
@deftypefn {Function File} {} wblinv (@var{x}, @var{scale}, @var{shape})
Compute the quantile (the inverse of the CDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape}.
@end deftypefn
wblpdf
-*- texinfo -*-
@deftypefn {Function File} {} wblpdf (@var{x}, @var{scale}, @var{shape})
Compute the probability density function (PDF) at @var{x} of the
Weibull distribution with shape parameter @var{scale} and scale
parameter @var{shape} which is given by

@iftex
@tex
$$  scale \cdot shape^{-scale} x^{scale-1} \exp(-(x/shape)^{scale}) $$
@end tex
@end iftex
@ifnottex
@example
   scale * shape^(-scale) * x^(scale-1) * exp(-(x/shape)^scale)
@end example
@end ifnottex

@noindent
for @var{x} > 0.
@end deftypefn
wblrnd
-*- texinfo -*-
@deftypefn {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{r}, @var{c})
@deftypefnx {Function File} {} wblrnd (@var{scale}, @var{shape}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{scale} and @var{shape}
which must be scalar or of size @var{r} by @var{c}. Or if @var{sz}
is a vector return a matrix of size @var{sz}.

If @var{r} and @var{c} are omitted, the size of the result matrix is
the common size of @var{alpha} and @var{sigma}.
@end deftypefn
wienrnd
-*- texinfo -*-
@deftypefn {Function File} {} wienrnd (@var{t}, @var{d}, @var{n})
Return a simulated realization of the @var{d}-dimensional Wiener Process
on the interval [0, @var{t}].  If @var{d} is omitted, @var{d} = 1 is
used. The first column of the return matrix contains time, the
remaining columns contain the Wiener process.

The optional parameter @var{n} gives the number of summands used for
simulating the process over an interval of length 1.  If @var{n} is
omitted, @var{n} = 1000 is used.
@end deftypefn
logistic_regression
-*- texinfo -*-
@deftypefn {Function File} {[@var{theta}, @var{beta}, @var{dev}, @var{dl}, @var{d2l}, @var{p}] =} logistic_regression (@var{y}, @var{x}, @var{print}, @var{theta}, @var{beta})
Perform ordinal logistic regression.

Suppose @var{y} takes values in @var{k} ordered categories, and let
@code{gamma_i (@var{x})} be the cumulative probability that @var{y}
falls in one of the first @var{i} categories given the covariate
@var{x}.  Then

@example
[theta, beta] = logistic_regression (y, x)
@end example

@noindent
fits the model

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

The number of ordinal categories, @var{k}, is taken to be the number
of distinct values of @code{round (@var{y})}.  If @var{k} equals 2,
@var{y} is binary and the model is ordinary logistic regression.  The
matrix @var{x} is assumed to have full column rank.

Given @var{y} only, @code{theta = logistic_regression (y)}
fits the model with baseline logit odds only.

The full form is

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

@noindent
in which all output arguments and all input arguments except @var{y}
are optional.

Setting @var{print} to 1 requests summary information about the fitted
model to be displayed.  Setting @var{print} to 2 requests information
about convergence at each iteration.  Other values request no
information to be displayed.  The input arguments @var{theta} and
@var{beta} give initial estimates for @var{theta} and @var{beta}.

The returned value @var{dev} holds minus twice the log-likelihood.

The returned values @var{dl} and @var{d2l} are the vector of first
and the matrix of second derivatives of the log-likelihood with
respect to @var{theta} and @var{beta}.

@var{p} holds estimates for the conditional distribution of @var{y}
given @var{x}.
@end deftypefn
logistic_regression_derivatives
-*- texinfo -*-
@deftypefn {Function File} {[@var{dl}, @var{d2l}] =} logistic_regression_derivatives (@var{x}, @var{z}, @var{z1}, @var{g}, @var{g1}, @var{p})
Called by logistic_regression.  Calculates derivates of the
log-likelihood for ordinal logistic regression model.
@end deftypefn
logistic_regression_likelihood
-*- texinfo -*-
@deftypefn {Function File} {[@var{g}, @var{g1}, @var{p}, @var{dev}] =} logistic_regression_likelihood (@var{y}, @var{x}, @var{beta}, @var{z}, @var{z1})
Calculates likelihood for the ordinal logistic regression model.
Called by logistic_regression.
@end deftypefn
anova
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_b}, @var{df_w}] =} anova (@var{y}, @var{g})
Perform a one-way analysis of variance (ANOVA).  The goal is to test
whether the population means of data taken from @var{k} different
groups are all equal.

Data may be given in a single vector @var{y} with groups specified by
a corresponding vector of group labels @var{g} (e.g., numbers from 1
to @var{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 @var{y} is a matrix and @var{g} is omitted, each column of @var{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 @var{f} follows an F
distribution with @var{df_b} and @var{df_w} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{f}) is
returned in @var{pval}.

If no output argument is given, the standard one-way ANOVA table is
printed.
@end deftypefn
bartlett_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} bartlett_test (@var{x1}, @dots{}) 
Perform a Bartlett test for the homogeneity of variances in the data
vectors @var{x1}, @var{x2}, @dots{}, @var{xk}, where @var{k} > 1.

Under the null of equal variances, the test statistic @var{chisq}
approximately follows a chi-square distribution with @var{df} degrees of
freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
chisquare_test_homogeneity
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} chisquare_test_homogeneity (@var{x}, @var{y}, @var{c})
Given two samples @var{x} and @var{y}, perform a chisquare test for
homogeneity of the null hypothesis that @var{x} and @var{y} come from
the same distribution, based on the partition induced by the
(strictly increasing) entries of @var{c}.

For large samples, the test statistic @var{chisq} approximately follows a
chisquare distribution with @var{df} = @code{length (@var{c})}
degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
chisquare_test_independence
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} chisquare_test_independence (@var{x})
Perform a chi-square test for indepence based on the contingency
table @var{x}.  Under the null hypothesis of independence,
@var{chisq} approximately has a chi-square distribution with
@var{df} degrees of freedom.

The p-value (1 minus the CDF of this distribution at chisq) of the
test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
cor_test
-*- texinfo -*-
@deftypefn {Function File} {} cor_test (@var{x}, @var{y}, @var{alt}, @var{method})
Test whether two samples @var{x} and @var{y} come from uncorrelated
populations.

The optional argument string @var{alt} describes the alternative
hypothesis, and can be @code{"!="} or @code{"<>"} (non-zero),
@code{">"} (greater than 0), or @code{"<"} (less than 0).  The
default is the two-sided case.

The optional argument string @var{method} specifies on which
correlation coefficient the test should be based.  If @var{method} is
@code{"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 @var{method} is
@code{"kendall"}, then Kendall's rank correlation tau is used.  If
@var{method} is @code{"spearman"}, then Spearman's rank correlation
rho is used.  Only the first character is necessary.

The output is a structure with the following elements:

@table @var
@item pval
The p-value of the test.
@item stat
The value of the test statistic.
@item dist
The distribution of the test statistic.
@item params
The parameters of the null distribution of the test statistic.
@item alternative
The alternative hypothesis.
@item method
The method used for testing.
@end table

If no output argument is given, the p-value is displayed.
@end deftypefn
f_test_regression
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_num}, @var{df_den}] =} f_test_regression (@var{y}, @var{x}, @var{rr}, @var{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 @var{f} follows an F distribution
with @var{df_num} and @var{df_den} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{f}) is
returned in @var{pval}.

If not given explicitly, @var{r} = 0.

If no output argument is given, the p-value is displayed.
@end deftypefn
hotelling_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{tsq}] =} hotelling_test (@var{x}, @var{m})
For a sample @var{x} from a multivariate normal distribution with unknown
mean and covariance matrix, test the null hypothesis that @code{mean
(@var{x}) == @var{m}}.

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

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
hotelling_test_2
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{tsq}] =} hotelling_test_2 (@var{x}, @var{y})
For two samples @var{x} from multivariate normal distributions with
the same number of variables (columns), unknown means and unknown
equal covariance matrices, test the null hypothesis @code{mean
(@var{x}) == mean (@var{y})}.

Hotelling's two-sample @math{T^2} is returned in @var{tsq}.  Under the null,

@iftex
@tex
$$
{n_x+n_y-p-1) T^2 \over p(n_x+n_y-2)}
$$
@end tex
@end iftex
@ifnottex
@example
(n_x+n_y-p-1) T^2 / (p(n_x+n_y-2))
@end example
@end ifnottex

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

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
kolmogorov_smirnov_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{ks}] =} kolmogorov_smirnov_test (@var{x}, @var{dist}, @var{params}, @var{alt})
Perform a Kolmogorov-Smirnov test of the null hypothesis that the
sample @var{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 @var{params} contains a list of parameters of
@var{dist}.  For example, to test whether a sample @var{x} comes from
a uniform distribution on [2,4], use

@example
kolmogorov_smirnov_test(x, "uniform", 2, 4)
@end example

@noindent
@var{dist} can be any string for which a function @var{dist_cdf}
that calculates the CDF of distribution @var{dist} exists.

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

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
kolmogorov_smirnov_test_2
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{ks}, @var{d}] =} kolmogorov_smirnov_test_2 (@var{x}, @var{y}, @var{alt})
Perform a 2-sample Kolmogorov-Smirnov test of the null hypothesis
that the samples @var{x} and @var{y} come from the same (continuous)
distribution.  I.e., if F and G are the CDFs corresponding to the
@var{x} and @var{y} samples, respectively, then the null is that F ==
G.

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

The p-value of the test is returned in @var{pval}.

The third returned value, @var{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.
@end deftypefn
kruskal_wallis_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{k}, @var{df}] =} kruskal_wallis_test (@var{x1}, @dots{})
Perform a Kruskal-Wallis one-factor "analysis of variance".

Suppose a variable is observed for @var{k} > 1 different groups, and
let @var{x1}, @dots{}, @var{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 @var{k} is
approximately chi-square with @var{df} = @var{k} - 1 degrees of
freedom.

The p-value (1 minus the CDF of this distribution at @var{k}) is
returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
manova
-*- texinfo -*-
@deftypefn {Function File} {} manova (@var{y}, @var{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 @var{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 @var{y}.  As usual, rows are observations
and columns are variables.  The vector @var{g} specifies the
corresponding group labels (e.g., numbers from 1 to @var{k}).

The LR test statistic (Wilks' Lambda) and approximate p-values are
computed and displayed.
@end deftypefn
mcnemar_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}, @var{df}] =} mcnemar_test (@var{x})
For a square contingency table @var{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, @var{chisq} is approximately distributed as chisquare
with @var{df} degrees of freedom.

The p-value (1 minus the CDF of this distribution at @var{chisq}) is
returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
prop_test_2
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} prop_test_2 (@var{x1}, @var{n1}, @var{x2}, @var{n2}, @var{alt})
If @var{x1} and @var{n1} are the counts of successes and trials in
one sample, and @var{x2} and @var{n2} those in a second one, test the
null hypothesis that the success probabilities @var{p1} and @var{p2}
are the same.  Under the null, the test statistic @var{z}
approximately follows a standard normal distribution.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@var{p1} != @var{p2}.  If @var{alt} is @code{">"}, the one-sided
alternative @var{p1} > @var{p2} is used.  Similarly for @code{"<"},
the one-sided alternative @var{p1} < @var{p2} is used.
The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
run_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{chisq}] =} run_test (@var{x})
Perform a chi-square test with 6 degrees of freedom based on the
upward runs in the columns of @var{x}.  Can be used to test whether
@var{x} contains independent data.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value is displayed.
@end deftypefn
sign_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{b}, @var{n}] =} sign_test (@var{x}, @var{y}, @var{alt})
For two matched-pair samples @var{x} and @var{y}, perform a sign test
of the null hypothesis PROB (@var{x} > @var{y}) == PROB (@var{x} <
@var{y}) == 1/2.  Under the null, the test statistic @var{b} roughly
follows a binomial distribution with parameters @code{@var{n} = sum
(@var{x} != @var{y})} and @var{p} = 1/2.

With the optional argument @code{alt}, the alternative of interest
can be selected.  If @var{alt} is @code{"!="} or @code{"<>"}, the
null hypothesis is tested against the two-sided alternative PROB
(@var{x} < @var{y}) != 1/2.  If @var{alt} is @code{">"}, the
one-sided alternative PROB (@var{x} > @var{y}) > 1/2 ("x is
stochastically greater than y") is considered.  Similarly for
@code{"<"}, the one-sided alternative PROB (@var{x} > @var{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 @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
t_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test (@var{x}, @var{m}, @var{alt})
For a sample @var{x} from a normal distribution with unknown mean and
variance, perform a t-test of the null hypothesis @code{mean
(@var{x}) == @var{m}}.  Under the null, the test statistic @var{t}
follows a Student distribution with @code{@var{df} = length (@var{x})
- 1} degrees of freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > @var{m}} is considered.
Similarly for @var{"<"}, the one-sided alternative @code{mean
(@var{x}) < @var{m}} is considered,  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
t_test_2
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test_2 (@var{x}, @var{y}, @var{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
@var{t} follows a Student distribution with @var{df} degrees of
freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If @var{alt} is @code{">"},
the one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is
used.  Similarly for @code{"<"}, the one-sided alternative @code{mean
(@var{x}) < mean (@var{y})} is used.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
t_test_regression
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} t_test_regression (@var{y}, @var{x}, @var{rr}, @var{r}, @var{alt})
Perform an t test for the null hypothesis @code{@var{rr} * @var{b} =
@var{r}} in a classical normal regression model @code{@var{y} =
@var{x} * @var{b} + @var{e}}.  Under the null, the test statistic @var{t}
follows a @var{t} distribution with @var{df} degrees of freedom.

If @var{r} is omitted, a value of 0 is assumed.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{@var{rr} * @var{b} != @var{r}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{@var{rr} * @var{b} > @var{r}} is used.
Similarly for @var{"<"}, the one-sided alternative @code{@var{rr} *
@var{b} < @var{r}} is used.  The default is the two-sided case. 

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
u_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} u_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{y}, perform a Mann-Whitney U-test of
the null hypothesis PROB (@var{x} > @var{y}) == 1/2 == PROB (@var{x}
< @var{y}).  Under the null, the test statistic @var{z} approximately
follows a standard normal distribution.  Note that this test is
equivalent to the Wilcoxon rank-sum test.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If @var{alt} is @code{">"}, the
one-sided alternative PROB (@var{x} > @var{y}) > 1/2 is considered.
Similarly for @code{"<"}, the one-sided alternative PROB (@var{x} >
@var{y}) < 1/2 is considered,  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
var_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{f}, @var{df_num}, @var{df_den}] =} var_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{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
@var{f} follows an F-distribution with @var{df_num} and @var{df_den}
degrees of freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{var (@var{x}) != var (@var{y})}.  If @var{alt} is @code{">"},
the one-sided alternative @code{var (@var{x}) > var (@var{y})} is
used.  Similarly for "<", the one-sided alternative @code{var
(@var{x}) > var (@var{y})} is used.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
welch_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{t}, @var{df}] =} welch_test (@var{x}, @var{y}, @var{alt})
For two samples @var{x} and @var{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 @var{t} approximately follows a
Student distribution with @var{df} degrees of freedom.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative mean(x) > @var{m} is considered.  Similarly for
@code{"<"}, the one-sided alternative mean(x) < @var{m} is
considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
wilcoxon_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} wilcoxon_test (@var{x}, @var{y}, @var{alt})
For two matched-pair sample vectors @var{x} and @var{y}, perform a
Wilcoxon signed-rank test of the null hypothesis PROB (@var{x} >
@var{y}) == 1/2.  Under the null, the test statistic @var{z}
approximately follows a standard normal distribution when @var{n} > 25.

@strong{Warning}: This function assumes a normal distribution for @var{z}
and thus is invalid for @var{n} <= 25.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
PROB (@var{x} > @var{y}) != 1/2.  If alt is @code{">"}, the one-sided
alternative PROB (@var{x} > @var{y}) > 1/2 is considered.  Similarly
for @code{"<"}, the one-sided alternative PROB (@var{x} > @var{y}) <
1/2 is considered.  The default is the two-sided case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed.
@end deftypefn
z_test
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} z_test (@var{x}, @var{m}, @var{v}, @var{alt})
Perform a Z-test of the null hypothesis @code{mean (@var{x}) ==
@var{m}} for a sample @var{x} from a normal distribution with unknown
mean and known variance @var{v}.  Under the null, the test statistic
@var{z} follows a standard normal distribution.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != @var{m}}.  If @var{alt} is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > @var{m}} is considered.
Similarly for @code{"<"}, the one-sided alternative @code{mean
(@var{x}) < @var{m}} is considered.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed
along with some information.
@end deftypefn
z_test_2
-*- texinfo -*-
@deftypefn {Function File} {[@var{pval}, @var{z}] =} z_test_2 (@var{x}, @var{y}, @var{v_x}, @var{v_y}, @var{alt})
For two samples @var{x} and @var{y} from normal distributions with
unknown means and known variances @var{v_x} and @var{v_y}, perform a
Z-test of the hypothesis of equal means.  Under the null, the test
statistic @var{z} follows a standard normal distribution.

With the optional argument string @var{alt}, the alternative of
interest can be selected.  If @var{alt} is @code{"!="} or
@code{"<>"}, the null is tested against the two-sided alternative
@code{mean (@var{x}) != mean (@var{y})}.  If alt is @code{">"}, the
one-sided alternative @code{mean (@var{x}) > mean (@var{y})} is used.
Similarly for @code{"<"}, the one-sided alternative @code{mean
(@var{x}) < mean (@var{y})} is used.  The default is the two-sided
case.

The p-value of the test is returned in @var{pval}.

If no output argument is given, the p-value of the test is displayed
along with some information.
@end deftypefn
base2dec
-*- texinfo -*-
@deftypefn {Function File} {} base2dec (@var{s}, @var{b})
Convert @var{s} from a string of digits of base @var{b} into an
integer.

@example
base2dec ("11120", 3)
@result{} 123
@end example

If @var{s} is a matrix, returns a column vector with one value per
row of @var{s}.  If a row contains invalid symbols then the
corresponding value will be NaN.  Rows are right-justified before
converting so that trailing spaces are ignored.

If @var{b} is a string, the characters of @var{b} are used as the
symbols for the digits of @var{s}. Space (' ') may not be used as a
symbol.

@example
base2dec ("yyyzx", "xyz")
@result{} 123
@end example
@seealso{dec2base, dec2bin, bin2dec, hex2dec, dec2hex}
@end deftypefn
bin2dec
-*- texinfo -*-
@deftypefn {Function File} {} bin2dec (@var{s})
Return the decimal number corresponding to the binary number stored
in the string @var{s}.  For example,

@example
bin2dec ("1110")
@result{} 14
@end example

If @var{s} is a string matrix, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@seealso{dec2hex, base2dec, dec2base, hex2dec, dec2bin}
@end deftypefn
blanks
-*- texinfo -*-
@deftypefn {Function File} {} blanks (@var{n})
Return a string of @var{n} blanks.
@seealso{repmat}
@end deftypefn
deblank
-*- texinfo -*-
@deftypefn {Function File} {} deblank (@var{s})
Remove trailing blanks and nulls from @var{s}.  If @var{s}
is a matrix, @var{deblank} trims each row to the length of longest
string.  If @var{s} is a cell array, operate recursively on each
element of the cell array.
@end deftypefn
dec2base
-*- texinfo -*-
@deftypefn {Function File} {} dec2base (@var{n}, @var{b}, @var{len})
Return a string of symbols in base @var{b} corresponding to the
the nonnegative integer @var{n}.

@example
dec2base (123, 3)
@result{} "11120"
@end example

If @var{n} is a vector, return a string matrix with one row per value,
padded with leading zeros to the width of the largest value.

If @var{b} is a string then the characters of @var{b} are used as
the symbols for the digits of @var{n}.  Space (' ') may not be used
as a symbol.

@example
dec2base (123, "aei")
@result{} "eeeia"
@end example

The optional third argument, @var{len}, specifies the minimum
number of digits in the result.
@seealso{base2dec, dec2bin, bin2dec, hex2dec, dec2hex}
@end deftypefn
dec2bin
-*- texinfo -*-
@deftypefn {Function File} {} dec2bin (@var{n}, @var{len})
Return a binary number corresponding the nonnegative decimal number
@var{n}, as a string of ones and zeros.  For example,

@example
dec2bin (14)
@result{} "1110"
@end example

If @var{n} is a vector, returns a string matrix, one row per value,
padded with leading zeros to the width of the largest value.

The optional second argument, @var{len}, specifies the minimum
number of digits in the result.
@seealso{bin2dec, dec2base, base2dec, hex2dec, dec2hex}
@end deftypefn
dec2hex
-*- texinfo -*-
@deftypefn {Function File} {} dec2hex (@var{n}, @var{len})
Return the hexadecimal string corresponding to the nonnegative 
integer @var{n}.  For example,

@example
dec2hex (2748)
@result{} "ABC"
@end example

If @var{n} is a vector, returns a string matrix, one row per value,
padded with leading zeros to the width of the largest value.

The optional second argument, @var{len}, specifies the minimum
number of digits in the result.
@seealso{hex2dec, dec2base, base2dec, bin2dec, dec2bin}
@end deftypefn
findstr
-*- texinfo -*-
@deftypefn {Function File} {} findstr (@var{s}, @var{t}, @var{overlap})
Return the vector of all positions in the longer of the two strings
@var{s} and @var{t} where an occurrence of the shorter of the two starts.
If the optional argument @var{overlap} is nonzero, the returned vector
can include overlapping positions (this is the default).  For example,

@example
findstr ("ababab", "a")
@result{} [ 1, 3, 5 ]
findstr ("abababa", "aba", 0)
@result{} [ 1, 5 ]
@end example
@end deftypefn
hex2dec
-*- texinfo -*-
@deftypefn {Function File} {} hex2dec (@var{s})
Return the integer corresponding to the hexadecimal number stored
in the string @var{s}.  For example,

@example
hex2dec ("12B")
@result{} 299
hex2dec ("12b")
@result{} 299
@end example

If @var{s} is a string matrix, returns a column vector of converted
numbers, one per row of @var{s}.  Invalid rows evaluate to NaN.
@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}
@end deftypefn
index
-*- texinfo -*-
@deftypefn {Function File} {} index (@var{s}, @var{t})
@deftypefnx {Function File} {} index (@var{s}, @var{t}, @var{direction})
Return the position of the first occurrence of the string @var{t} in the
string @var{s}, or 0 if no occurrence is found.  For example,

@example
index ("Teststring", "t")
@result{} 4
@end example

If @var{direction} is @samp{"first"}, return the first element found.
If @var{direction} is @samp{"last"}, return the last element found.
The @code{rindex} function is equivalent to @code{index} with
@var{direction} set to @samp{"last"}.

@strong{Caution:}  This function does not work for arrays of
character strings.
@seealso{find, rindex}
@end deftypefn
isletter
-*- texinfo -*-
@deftypefn {Function File} {} isletter (@var{s})
Returns true if @var{s} is a letter false otherwise.
@seealso{isalpha}
@end deftypefn
lower
-*- texinfo -*-
@deftypefn {Function File} {} lower (@var{s})
Transform all letters in the character string (or cell array of
character strings) @var{s} to lower case.
@seealso{upper, tolower, toupper}
@end deftypefn
mat2str
-*- texinfo -*-
@deftypefn {Function File} {@var{s} =} mat2str (@var{x}, @var{n})
@deftypefnx {Function File} {@var{s} =} mat2str (@dots{}, 'class')

Format real/complex numerial matrices as strings. This function
returns values that are suitable for the use of the @code{eval}
function.

The precision of the values is given by @var{n}. If @var{n} is a
scalar then both real and imaginary parts of the matrix are printed
to the same precision. Otherwise @code{@var{n} (1)} defines the
precision of the real part and @code{@var{n} (2)} defines the
precision of the imaginary part. The default for @var{n} is 17.

If the argument 'class' is given, then the class of @var{x} is
included in the string in such a way that the eval will result in the
construction of a matrix of the same class.

@example
@group
   mat2str( [ -1/3 + i/7; 1/3 - i/7 ], [4 2] )
@result{} '[-0.3333+0.14i;0.3333-0.14i]'
   mat2str( [ -1/3 +i/7; 1/3 -i/7 ], [4 2] )
@result{} '[-0.3333+0i,0+0.14i;0.3333+0i,-0-0.14i]'
   mat2str( int16([1 -1]), 'class')
@result{} 'int16([1,-1])'
@end group
@end example

@seealso{sprintf, int2str}
@end deftypefn
rindex
-*- texinfo -*-
@deftypefn {Function File} {} rindex (@var{s}, @var{t})
Return the position of the last occurrence of the character string
@var{t} in the character string @var{s}, or 0 if no occurrence is
found.  For example,

@example
rindex ("Teststring", "t")
@result{} 6
@end example

@strong{Caution:}  This function does not work for arrays of
character strings.
@seealso{find, index}
@end deftypefn
split
-*- texinfo -*-
@deftypefn {Function File} {} split (@var{s}, @var{t}, @var{n})
Divides the string @var{s} into pieces separated by @var{t}, returning
the result in a string array (padded with blanks to form a valid
matrix).  If the optional input @var{n} is supplied, split @var{s}
into at most @var{n} different pieces.

For example,

@example
split ("Test string", "t")
@result{} "Tes "
        " s  "
        "ring"
@end example

@example
split ("Test string", "t", 2)
@result{} "Tes    "
        " string"
@end example
@end deftypefn
str2double
-*- texinfo -*-
@deftypefn {Function File} {[@var{num}, @var{status}, @var{strarray}] =} str2double (@var{str}, @var{cdelim}, @var{rdelim}, @var{ddelim})
Convert strings into numeric values.

@code{str2double} can replace @code{str2num}, but avoids the use of
@code{eval} on unknown data.

@var{str} can be the form @samp{[+-]d[.]dd[[eE][+-]ddd]} in which
@samp{d} can be any of digit from 0 to 9, and @samp{[]} indicate
optional elements.

@var{num} is the corresponding numeric value.  If the conversion
fails, status is -1 and @var{num} is NaN.

@var{status} is 0 if the conversion was successful and -1 otherwise.

@var{strarray} is a cell array of strings.

Elements which are not defined or not valid return NaN and the
@var{status} becomes -1.

If @var{str} is a character array or a cell array of strings, then
@var{num} and @var{status} return matrices of appropriate size. 

@var{str} can also contain multiple elements separated by row and
column delimiters (@var{cdelim} and @var{rdelim}).

The parameters @var{cdelim}, @var{rdelim}, and @var{ddelim} are
optional column, row, and decimal delimiters.

The default row-delimiters are newline, carriage return and semicolon
(ASCII 10, 13 and 59).  The default column-delimiters are tab, space
and comma (ASCII 9, 32, and 44).  The default decimal delimiter is
@samp{.} (ASCII 46).

@var{cdelim}, @var{rdelim}, and @var{ddelim} must contain only nul,
newline, carriage return, semicolon, colon, slash, tab, space, comma,
or @samp{()[]@{@}} (ASCII 0, 9, 10, 11, 12, 13, 14, 32, 33, 34, 40,
41, 44, 47, 58, 59, 91, 93, 123, 124, 125).

Examples:

@example
str2double ("-.1e-5")
@result{} -1.0000e-006

str2double (".314e1, 44.44e-1, .7; -1e+1")
@result{}
   3.1400    4.4440    0.7000
 -10.0000       NaN       NaN

line = "200,300,400,NaN,-inf,cd,yes,no,999,maybe,NaN";
[x, status] = str2double (line)
x =
   200   300   400   NaN  -Inf   NaN   NaN   NaN   999   NaN   NaN
status =
    0     0     0     0     0    -1    -1    -1     0    -1     0
@end example
@end deftypefn
str2mat
-*- texinfo -*-
@deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n})
Return a matrix containing the strings @var{s_1}, @dots{}, @var{s_n} as
its rows.  Each string is padded with blanks in order to form a valid
matrix.

This function is modelled after @sc{Matlab}.  In Octave, you can create
a matrix of strings by @code{[@var{s_1}; @dots{}; @var{s_n}]} even if
the strings are not all the same length.
@end deftypefn
str2num
-*- texinfo -*-
@deftypefn {Function File} {} str2num (@var{s})
Convert the string @var{s} to a number.
@end deftypefn
strcat
-*- texinfo -*-
@deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{})
Return a string containing all the arguments concatenated.  For example,

@example
@group
s = [ "ab"; "cde" ];
strcat (s, s, s)
@result{} "ab ab ab "
        "cdecdecde"
@end group
@end example
@end deftypefn
strcmpi
-*- texinfo -*-
@deftypefn {Function File} {} strcmpi (@var{s1}, @var{s2})
Ignoring case, return 1 if the character strings @var{s1} and @var{s2}
are the same, and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array. The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{Matlab}, Octave's strcmpi
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strcmp, strncmp, strncmpi}
@end deftypefn
strfind
-*- texinfo -*-
@deftypefn {Function File} {@var{idx} =} strfind (@var{str}, @var{pattern})
@deftypefnx {Function File} {@var{idx} =} strfind (@var{cellstr}, @var{pattern})
Search for @var{pattern} in the string @var{str} and return the
starting index of every such occurrence in the vector @var{idx}.
If there is no such occurrence, or if @var{pattern} is longer
than @var{str}, then @var{idx} is the empty array @code{[]}.

If the cell array of strings @var{cellstr} is specified instead of the
string @var{str}, then @var{idx} is a cell array of vectors, as specified
above.
@seealso{findstr, strmatch, strcmp, strncmp, strcmpi, strncmpi}
@end deftypefn
strjust
-*- texinfo -*-
@deftypefn {Function File} {} strjust (@var{s}, ["left"|"right"|"center"])
Shift the non-blank text of @var{s} to the left, right or center of
the string.  If @var{s} is a string array, justify each string in the
array.  Null characters are replaced by blanks.  If no justification
is specified, then all rows are right-justified.
@end deftypefn
strmatch
-*- texinfo -*-
@deftypefn {Function File} {} strmatch (@var{s}, @var{a}, "exact")
Return indices of entries of @var{a} that match the string @var{s}.
The second argument @var{a} may be a string matrix or a cell array of
strings.  If the third argument @code{"exact"} is not given, then
@var{s} only needs to match @var{a} up to the length of @var{s}.  Nul
characters match blanks.  Results are returned as a column vector.
@end deftypefn
strncmpi
-*- texinfo -*-
@deftypefn {Function File} {} strncmpi (@var{s1}, @var{s2}, @var{n})
Ignoring case, return 1 if the first @var{n} characters of character
strings @var{s1} and @var{s2} are the same, and 0 otherwise.

If either @var{s1} or @var{s2} is a cell array of strings, then an array
of the same size is returned, containing the values described above for
every member of the cell array. The other argument may also be a cell
array of strings (of the same size or with only one element), char matrix
or character string.

@strong{Caution:} For compatibility with @sc{Matlab}, Octave's strncmpi
function returns 1 if the character strings are equal, and 0 otherwise.
This is just the opposite of the corresponding C library function.
@seealso{strcmp, strcmpi, strncmp}
@end deftypefn
strrep
-*- texinfo -*-
@deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y})
Replaces all occurrences of the substring @var{x} of the string @var{s}
with the string @var{y}.  For example,

@example
strrep ("This is a test string", "is", "&%$")
@result{} "Th&%$ &%$ a test string"
@end example
@end deftypefn
strtok
-*- texinfo -*-
@deftypefn {Function File} {[@var{tok}, @var{rem}] =} strtok (@var{str}, @var{delim})

Find all characters up to but not including the first character which
is in the string delim.  If @var{rem} is requested, it contains the
remainder of the string, starting at the first deliminator. Leading
delimiters are ignored.  If @var{delim} is not specified, space is assumed.

@end deftypefn
strtrunc
-*- texinfo -*-
@deftypefn {Function File} {} strtrunc (@var{s}, @var{n})
Truncate the character string @var{s} to length @var{n}. If @var{s}
is a char matrix, then the number of columns are adjusted.

If @var{s} is a cell array of strings, then the operation is performed
on its members and the new cell array is returned.
@end deftypefn
strvcat
-*- texinfo -*-
@deftypefn {Function File} {} strvcat (@var{s_1}, @dots{}, @var{s_n})
Return a matrix containing the strings (and cell-strings) 
@var{s_1}, @dots{}, @var{s_n} as
its rows.  Each string is padded with blanks in order to form a valid
matrix.  Unlike @var{str2mat}, empty strings are ignored.
@seealso{strcat, str2mat}
@end deftypefn
substr
-*- texinfo -*-
@deftypefn {Function File} {} substr (@var{s}, @var{offset}, @var{len})
Return the substring of @var{s} which starts at character number
@var{offset} and is @var{len} characters long.

If @var{offset} is negative, extraction starts that far from the end of
the string.  If @var{len} is omitted, the substring extends to the end
of S.

For example,

@example
substr ("This is a test string", 6, 9)
@result{} "is a test"
@end example

This function is patterned after AWK.  You can get the same result by
@code{@var{s} (@var{offset} : (@var{offset} + @var{len} - 1))}.
@end deftypefn
upper
-*- texinfo -*-
@deftypefn {Function File} {} upper (@var{s})
Transform all letters in the character string (or cell array of
character strings) @var{s} to upper case.
@seealso{lower, tolower, toupper}
@end deftypefn
assert
-*- texinfo -*-
@deftypefn {Function File} {} assert (@var{cond})
@deftypefnx {Function File} {} assert (@var{observed},@var{expected})
@deftypefnx {Function File} {} assert (@var{observed},@var{expected},@var{tol})

Produces an error if the condition is not met. @code{assert} can be
called in three different ways.

@table @code
@item assert (@var{cond})
Called with a single argument @var{cond}, @code{assert} produces an
error if @var{cond} is zero.

@item assert (@var{observed}, @var{expected})
Produce an error if observed is not the same as expected. Note that 
observed and expected can be strings, scalars, vectors, matrices, 
lists or structures.

@item assert(@var{observed}, @var{expected}, @var{tol})
Produce an error if relative error is less than tolerance. That is, 
@code{abs(@var{observed} - @var{expected}) > @var{tol} * @var{expected}}.  
Absolute error @code{abs(@var{observed} - @var{expected}) > abs(@var{tol})} 
will be used when tolerance is negative or when the expected value is zero.
@end table
@seealso{test}
@end deftypefn
demo
-*- texinfo -*-
@deftypefn {Function File} {} demo ('@var{name}',@var{n})

Runs any examples associated with the function '@var{name}'.  
Examples are stored in the script file, or in a file with the same 
name but no extension somewhere on your path.  To keep them separate 
from the usual script code, all lines are prefixed by @code{%!}. Each
example is introduced by the keyword 'demo' flush left to the prefix,
with no intervening spaces.  The remainder of the example can contain 
arbitrary octave code. For example:

@example
   %!demo
   %! t=0:0.01:2*pi; x = sin(t);
   %! plot(t,x)
   %! %-------------------------------------------------
   %! % the figure window shows one cycle of a sine wave
@end example

Note that the code is displayed before it is executed, so a simple
comment at the end suffices.  It is generally not necessary to use
disp or printf within the demo.

Demos are run in a function environment with no access to external
variables. This means that all demos in your function must use
separate initialization code. Alternatively, you can combine your
demos into one huge demo, with the code:

@example
   %! input("Press <enter> to continue: ","s");
@end example

between the sections, but this is discouraged.  Other techniques
include using multiple plots by saying figure between each, or
using subplot to put multiple plots in the same window.

Also, since demo evaluates inside a function context, you cannot
define new functions inside a demo.  Instead you will have to
use @code{eval(example('function',n))} to see them.  Because eval only
evaluates one line, or one statement if the statement crosses
multiple lines, you must wrap your demo in "if 1 <demo stuff> endif"
with the 'if' on the same line as 'demo'. For example,

@example
  %!demo if 1
  %!  function y=f(x)
  %!    y=x;
  %!  endfunction
  %!  f(3)
  %! endif
@end example
@seealso{test, example}
@end deftypefn
example
-*- texinfo -*-
@deftypefn {Function File} {} example ('@var{name}',@var{n})
@deftypefnx {Function File} {[@var{x}, @var{idx}] =} example ('@var{name}',@var{n})

 Display the code for example @var{n} associated with the function 
'@var{name}', but do not run it. If @var{n} is not given, all examples 
are displayed.

Called with output arguments, the examples are returned in the form of
a string @var{x}, with @var{idx} indicating the ending position of the 
various examples.

See @code{demo} for a complete explanation.
@seealso{demo, test}
@end deftypefn
fail
-*- texinfo -*-
@deftypefn {Function File} {} fail (@var{code},@var{pattern})
@deftypefnx {Function File} {} fail (@var{code},'warning',@var{pattern})

Return true if @var{code} fails with an error message matching
@var{pattern}, otherwise produce an error. Note that @var{code}
is a string and if @var{code} runs successfully, the error produced is:

@example
          expected error but got none  
@end example

If the code fails with a different error, the message produced is:

@example
          expected <pattern>
          but got <text of actual error>
@end example

The angle brackets are not part of the output.

Called with three arguments, the behavior is similar to 
@code{fail(@var{code}, @var{pattern})}, but produces an error if no 
warning is given during code execution or if the code fails.

@end deftypefn
speed
-*- texinfo -*-
@deftypefn {Function File} {} speed (@var{f}, @var{init}, @var{max_n}, @var{f2}, @var{tol})
@deftypefnx {Function File} {[@var{order}, @var{n}, @var{T_f}, @var{T_f2}] =} speed (@dots{})

Determine the execution time of an expression for various @var{n}.
The @var{n} are log-spaced from 1 to @var{max_n}.  For each @var{n},
an initialization expression is computed to create whatever data
are needed for the test.  If a second expression is given, the
execution times of the two expressions will be compared.  Called 
without output arguments the results are presented graphically.

@table @code
@item @var{f}
The expression to evaluate.

@item @var{max_n}
The maximum test length to run. Default value is 100.  Alternatively,
use @code{[min_n,max_n]} or for complete control, @code{[n1,n2,@dots{},nk]}.

@item @var{init}
Initialization expression for function argument values.  Use @var{k} 
for the test number and @var{n} for the size of the test.  This should
compute values for all variables listed in args.  Note that init will
be evaluated first for k=0, so things which are constant throughout
the test can be computed then. The default value is @code{@var{x} =
randn (@var{n}, 1);}.

@item @var{f2}
An alternative expression to evaluate, so the speed of the two
can be compared. Default is @code{[]}.

@item @var{tol}
If @var{tol} is @code{Inf}, then no comparison will be made between the
results of expression @var{f} and expression @var{f2}.  Otherwise,
expression @var{f} should produce a value @var{v} and expression @var{f2} 
should produce a value @var{v2}, and these shall be compared using 
@code{assert(@var{v},@var{v2},@var{tol})}. If @var{tol} is positive,
the tolerance is assumed to be absolutr. If @var{tol} is negative,
the tolerance is assumed to be relative. The default is @code{eps}.

@item @var{order}
The time complexity of the expression @code{O(a n^p)}.  This
is a structure with fields @code{a} and @code{p}.

@item @var{n}
The values @var{n} for which the expression was calculated and the
the execution time was greater than zero.

@item @var{T_f}
The nonzero execution times recorded for the expression @var{f} in seconds.

@item @var{T_f2}
The nonzero execution times recorded for the expression @var{f2} in seconds.
If it is needed, the mean time ratio is just @code{mean(T_f./T_f2)}.

@end table

The slope of the execution time graph shows the approximate
power of the asymptotic running time @code{O(n^p)}.  This
power is plotted for the region over which it is approximated
(the latter half of the graph).  The estimated power is not
very accurate, but should be sufficient to determine the
general order of your algorithm.  It should indicate if for 
example your implementation is unexpectedly @code{O(n^2)} 
rather than @code{O(n)} because it extends a vector each 
time through the loop rather than preallocating one which is 
big enough.  For example, in the current version of Octave,
the following is not the expected @code{O(n)}:

@example
  speed("for i=1:n,y@{i@}=x(i); end", "", [1000,10000])
@end example

but it is if you preallocate the cell array @code{y}:

@example
  speed("for i=1:n,y@{i@}=x(i);end", ...
        "x=rand(n,1);y=cell(size(x));", [1000,10000])
@end example

An attempt is made to approximate the cost of the individual 
operations, but it is wildly inaccurate.  You can improve the
stability somewhat by doing more work for each @code{n}.  For
example:

@example
  speed("airy(x)", "x=rand(n,10)", [10000,100000])
@end example

When comparing a new and original expression, the line on the
speedup ratio graph should be larger than 1 if the new expression
is faster.  Better algorithms have a shallow slope.  Generally, 
vectorizing an algorithm will not change the slope of the execution 
time graph, but it will shift it relative to the original.  For
example:

@example
  speed("v=sum(x)", "", [10000,100000], ...
        "v=0;for i=1:length(x),v+=x(i);end")
@end example

A more complex example, if you had an original version of @code{xcorr}
using for loops and another version using an FFT, you could compare the
run speed for various lags as follows, or for a fixed lag with varying
vector lengths as follows:

@example
  speed("v=xcorr(x,n)", "x=rand(128,1);", 100, ...
        "v2=xcorr_orig(x,n)", -100*eps)
  speed("v=xcorr(x,15)", "x=rand(20+n,1);", 100, ...
        "v2=xcorr_orig(x,n)", -100*eps)
@end example

Assuming one of the two versions is in @var{xcorr_orig}, this would
would compare their speed and their output values.  Note that the
FFT version is not exact, so we specify an acceptable tolerance on
the comparison @code{100*eps}, and the errors should be computed
relatively, as @code{abs((@var{x} - @var{y})./@var{y})} rather than 
absolutely as @code{abs(@var{x} - @var{y})}.

Type @code{example('speed')} to see some real examples. Note for 
obscure reasons, you can't run examples 1 and 2 directly using 
@code{demo('speed')}. Instead use, @code{eval(example('speed',1))}
and @code{eval(example('speed',2))}.
@end deftypefn
test
-*- texinfo -*-
@deftypefn {Function File} {} test @var{name}
@deftypefnx {Function File} {} test @var{name} quiet|normal|verbose
@deftypefnx {Function File} {} test ('@var{name}', 'quiet|normal|verbose', @var{fid})
@deftypefnx {Function File} {} test ([], 'explain', @var{fid})
@deftypefnx {Function File} {@var{success} =} test (@dots{})
@deftypefnx {Function File} {[@var{n}, @var{max}] =} test (@dots{})
@deftypefnx {Function File} {[@var{code}, @var{idx}] =} test ('@var{name}','grabdemo')

Perform tests from the first file in the loadpath matching @var{name}.
@code{test} can be called as a command or as a function. Called with 
a single argument @var{name}, the tests are run interactively and stop
after the first error is encountered.

With a second argument the tests which are performed and the amount of
output is selected.

@table @asis
@item 'quiet'
 Don't report all the tests as they happen, just the errors.

@item 'normal'
Report all tests as they happen, but don't do tests which require 
user interaction.

@item 'verbose'
Do tests which require user interaction.
@end table

The argument @var{fid} can be used to allow batch processing. Errors
can be written to the already open file defined by @var{fid}, and 
hopefully when octave crashes this file will tell you what was happening
when it did. You can use @code{stdout} if you want to see the results as
they happen.  You can also give a file name rather than an @var{fid}, in
which case the contents of the file will be replaced with the log from 
the current test.

Called with a single output argument @var{success}, @code{test} returns
true if all of the tests were successful. Called with two output arguments
@var{n} and @var{max}, the number of sucessful test and the total number
of tests in the file @var{name} are returned.

If the second argument is the string 'grabdemo', the contents of the demo
blocks are extracted but not executed. Code for all code blocks is
concatented and returned as @var{code} with @var{idx} being a vector of
positions of the ends of the demo blocks.

If the second argument is 'explain', then @var{name} is ignored and an
explanation of the line markers used is written to the file @var{fid}.
@seealso{error, assert, fail, demo, example}
@end deftypefn
asctime
-*- texinfo -*-
@deftypefn {Function File} {} asctime (@var{tm_struct})
Convert a time structure to a string using the following five-field
format: Thu Mar 28 08:40:14 1996.  For example,

@example
@group
asctime (localtime (time ())
@result{} "Mon Feb 17 01:15:06 1997\n"
@end group
@end example

This is equivalent to @code{ctime (time ())}.
@end deftypefn
calendar
-*- texinfo -*-
@deftypefn {Function File} {} calendar (@dots{})
@deftypefnx {Function File} {@var{c} =} calendar ()
@deftypefnx {Function File} {@var{c} =} calendar (@var{d})
@deftypefnx {Function File} {@var{c} =} calendar (@var{y}, @var{m})
If called with no arguments, return the current monthly calendar in
a 6x7 matrix.

If @var{d} is specified, return the calendar for the month containing
the day @var{d}, which must be a serial date number or a date string.

If @var{y} and @var{m} are specified, return the calendar for year @var{y}
and month @var{m}.

If no output arguments are specified, print the calendar on the screen
instead of returning a matrix.
@seealso{datenum}
@end deftypefn
clock
-*- texinfo -*-
@deftypefn {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,

@example
@group
clock ()
@result{} [ 1993, 8, 20, 4, 56, 1 ]
@end group
@end example

The function clock is more accurate on systems that have the
@code{gettimeofday} function.
@end deftypefn
ctime
-*- texinfo -*-
@deftypefn {Function File} {} ctime (@var{t})
Convert a value returned from @code{time} (or any other nonnegative
integer), to the local time and return a string of the same form as
@code{asctime}.  The function @code{ctime (time)} is equivalent to
@code{asctime (localtime (time))}.  For example,

@example
@group
ctime (time ())
@result{} "Mon Feb 17 01:15:06 1997\n"
@end group
@end example
@end deftypefn
date
-*- texinfo -*-
@deftypefn {Function File} {} date ()
Return the date as a character string in the form DD-MMM-YY.  For
example,

@example
@group
date ()
@result{} "20-Aug-93"
@end group
@end example
@end deftypefn
datenum
-*- texinfo -*-
@deftypefn {Function File} {} datenum (@var{year}, @var{month}, @var{day})
@deftypefnx {Function File} {} datenum (@var{year}, @var{month}, @var{day}, @var{hour})
@deftypefnx {Function File} {} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute})
@deftypefnx {Function File} {} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute}, @var{second})
@deftypefnx {Function File} {} datenum (@code{"date"})
@deftypefnx {Function File} {} datenum (@code{"date"}, @var{p})
Returns the specified local time as a day number, with Jan 1, 0000
being day 1.  By this reckoning, Jan 1, 1970 is day number 719529.  
The fractional portion, @var{p}, corresponds to the portion of the
specified day.

Notes:

@itemize
@item
Years can be negative and/or fractional.
@item
Months below 1 are considered to be January.
@item
Days of the month start at 1.
@item
Days beyond the end of the month go into subsequent months.
@item
Days before the beginning of the month go to the previous month.
@item
Days can be fractional.
@end itemize

@strong{Warning:} this function does not attempt to handle Julian
calendars so dates before Octave 15, 1582 are wrong by as much
as eleven days.  Also be aware that only Roman Catholic countries
adopted the calendar in 1582.  It took until 1924 for it to be 
adopted everywhere.  See the Wikipedia entry on the Gregorian 
calendar for more details.

@strong{Warning:} leap seconds are ignored.  A table of leap seconds
is available on the Wikipedia entry for leap seconds.
@seealso{date, clock, now, datestr, datevec, calendar, weekday}
@end deftypefn
datestr
-*- texinfo -*-
@deftypefn {Function File} {@var{str} =} datestr (@var{date}, [@var{f}, [@var{p}]])
Format the given date/time according to the format @code{f} and return
the result in @var{str}. @var{date} is a serial date number (see
@code{datenum}) or a date vector (see @code{datevec}).  The value of
@var{date} may also be a string or cell array of strings.

@var{f} can be an integer which corresponds to one of the codes in
the table below, or a date format string.

@var{p} is the year at the start of the century in which two-digit years
are to be interpreted in. If not specified, it defaults to the current
year minus 50.

For example, the date 730736.65149 (2000-09-07 15:38:09.0934) would be
formatted as follows:

@multitable @columnfractions 0.1 0.45 0.35
@headitem Code @tab Format @tab Example
@item  0 @tab dd-mmm-yyyy HH:MM:SS   @tab 07-Sep-2000 15:38:09
@item  1 @tab dd-mmm-yyyy            @tab 07-Sep-2000
@item  2 @tab mm/dd/yy               @tab 09/07/00
@item  3 @tab mmm                    @tab Sep
@item  4 @tab m                      @tab S
@item  5 @tab mm                     @tab 09
@item  6 @tab mm/dd                  @tab 09/07
@item  7 @tab dd                     @tab 07
@item  8 @tab ddd                    @tab Thu
@item  9 @tab d                      @tab T
@item 10 @tab yyyy                   @tab 2000
@item 11 @tab yy                     @tab 00
@item 12 @tab mmmyy                  @tab Sep00
@item 13 @tab HH:MM:SS               @tab 15:38:09
@item 14 @tab HH:MM:SS PM            @tab 03:38:09 PM
@item 15 @tab HH:MM                  @tab 15:38
@item 16 @tab HH:MM PM               @tab 03:38 PM
@item 17 @tab QQ-YY                  @tab Q3-00
@item 18 @tab QQ                     @tab Q3
@item 19 @tab dd/mm                  @tab 13/03
@item 20 @tab dd/mm/yy               @tab 13/03/95
@item 21 @tab mmm.dd.yyyy HH:MM:SS   @tab Mar.03.1962 13:53:06
@item 22 @tab mmm.dd.yyyy            @tab Mar.03.1962
@item 23 @tab mm/dd/yyyy             @tab 03/13/1962
@item 24 @tab dd/mm/yyyy             @tab 12/03/1962
@item 25 @tab yy/mm/dd               @tab 95/03/13
@item 26 @tab yyyy/mm/dd             @tab 1995/03/13
@item 27 @tab QQ-YYYY                @tab Q4-2132
@item 28 @tab mmmyyyy                @tab Mar2047
@item 29 @tab yyyymmdd               @tab 20470313
@item 30 @tab yyyymmddTHHMMSS        @tab 20470313T132603
@item 31 @tab yyyy-mm-dd HH:MM:SS    @tab 1047-03-13 13:26:03
@end multitable

If @var{f} is a format string, the following symbols are recognised:

@multitable @columnfractions 0.1 0.7 0.2
@headitem Symbol @tab Meaning @tab Example
@item yyyy @tab Full year                                    @tab 2005
@item yy   @tab Two-digit year                               @tab 2005
@item mmmm @tab Full month name                              @tab December
@item mmm  @tab Abbreviated month name                       @tab Dec
@item mm   @tab Numeric month number (padded with zeros)     @tab 01, 08, 12
@item m    @tab First letter of month name (capitalized)     @tab D
@item dddd @tab Full weekday name                            @tab Sunday
@item ddd  @tab Abbreviated weekday name                     @tab Sun
@item dd   @tab Numeric day of month (padded with zeros)     @tab 11
@item d    @tab First letter of weekday name (capitalized)   @tab S
@item HH   @tab Hour of day, padded with zeros if PM is set  @tab 09:00
@item      @tab and not padded with zeros otherwise          @tab 9:00 AM
@item MM   @tab Minute of hour (padded with zeros)           @tab 10:05
@item SS   @tab Second of minute (padded with zeros)         @tab 10:05:03
@item PM   @tab Use 12-hour time format                      @tab 11:30 PM
@end multitable

If @var{f} is not specified or is @code{-1}, then use 0, 1 or 16,
depending on whether the date portion or the time portion of
@var{date} is empty.

If @var{p} is nor specified, it defaults to the current year minus 50.

If a matrix or cell array of dates is given, a vector of date strings is
returned.

@seealso{datenum, datevec, date, clock, now, datetick}
@end deftypefn
datevec
-*- texinfo -*-
@deftypefn {Function File} {@var{v} =} datevec (@var{date})
@deftypefnx {Function File} {@var{v} =} datevec (@var{date}, @var{f})
@deftypefnx {Function File} {@var{v} =} datevec (@var{date}, @var{p})
@deftypefnx {Function File} {@var{v} =} datevec (@var{date}, @var{f}, @var{p})
@deftypefnx {Function File} {[@var{y}, @var{m}, @var{d}, @var{h}, @var{mi}, @var{s}] =} datevec (@dots{})
Convert a serial date number (see @code{datenum}) or date string (see
@code{datestr}) into a date vector.

A date vector is a row vector with six members, representing the year,
month, day, hour, minute, and seconds respectively.

@var{f} is the format string used to interpret date strings
(see @code{datestr}).

@var{p} is the year at the start of the century in which two-digit years
are to be interpreted in. If not specified, it defaults to the current
year minus 50.
@seealso{datenum, datestr, date, clock, now}
@end deftypefn
eomday
-*- texinfo -*-
@deftypefn {Function File} {@var{e} =} eomday (@var{y}, @var{m})
Return the last day of the month @var{m} for the year @var{y}.
@seealso{datenum, datevec, weekday}
@end deftypefn
etime
-*- texinfo -*-
@deftypefn {Function File} {} etime (@var{t1}, @var{t2})
Return the difference (in seconds) between two time values returned from
@code{clock}.  For example:

@example
t0 = clock ();
 many computations later...
elapsed_time = etime (clock (), t0);
@end example

@noindent
will set the variable @code{elapsed_time} to the number of seconds since
the variable @code{t0} was set.
@seealso{tic, toc, clock, cputime}
@end deftypefn
is_leap_year
-*- texinfo -*-
@deftypefn {Function File} {} is_leap_year (@var{year})
Return 1 if the given year is a leap year and 0 otherwise.  If no
arguments are provided, @code{is_leap_year} will use the current year.
For example,

@example
@group
is_leap_year (2000)
@result{} 1
@end group
@end example
@end deftypefn
now
-*- texinfo -*-
@deftypefn {Function File} {t =} now ()
Returns the current local time as the number of days since Jan 1, 0000.
By this reckoning, Jan 1, 1970 is day number 719529.

The integral part, @code{floor (now)} corresponds to 00:00:00 today.

The fractional part, @code{rem (now, 1)} corresponds to the current
time on Jan 1, 0000.

The returned value is also called a "serial date number"
(see @code{datenum}).
@seealso{clock, date, datenum}
@end deftypefn
tic
-*- texinfo -*-
@deftypefn {Function File} {} tic ()
@deftypefnx {Function File} {} toc ()
These functions set and check a wall-clock timer.  For example,

@example
tic ();
 many computations later...
elapsed_time = toc ();
@end example

@noindent
will set the variable @code{elapsed_time} to the number of seconds since
the most recent call to the function @code{tic}.

Nested timing with @code{tic} and @code{toc} is not supported.
Therefore @code{toc} will always return the elapsed time from the most
recent call to @code{tic}.

If you are more interested in the CPU time that your process used, you
should use the @code{cputime} function instead.  The @code{tic} and
@code{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,

@example
@group
tic (); sleep (5); toc ()
@result{} 5
t = cputime (); sleep (5); cputime () - t
@result{} 0
@end group
@end example

@noindent
(This example also illustrates that the CPU timer may have a fairly
coarse resolution.)
@end deftypefn
toc
-*- texinfo -*-
@deftypefn {Function File} {} toc ()
See tic.
@end deftypefn
weekday
-*- texinfo -*-
@deftypefn {Function File} {[@var{n}, @var{s}] =} weekday (@var{d}, [@var{form}])
Return the day of week as a number in @var{n} and a string in @var{s},
for example @code{[1, "Sun"]}, @code{[2, "Mon"]}, @dots{}, or
@code{[7, "Sat"]}.

@var{d} is a serial date number or a date string.

If the string @var{form} is given and is @code{"long"}, @var{s} will
contain the full name of the weekday; otherwise (or if @var{form} is
@code{"short"}), @var{s} will contain the abbreviated name of the weekday.
@seealso{datenum, datevec, eomday}
@end deftypefn
