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}.
@end deftypefn

@seealso{mu2lin, loadaudio, saveaudio, playaudio, setaudio, and record}
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.
@end deftypefn

@seealso{lin2mu, mu2lin, saveaudio, playaudio, setaudio, and record}
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.
@end deftypefn

@seealso{lin2mu, loadaudio, saveaudio, playaudio, setaudio, and record}
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}.
@end deftypefn

@seealso{lin2mu, mu2lin, loadaudio, saveaudio, setaudio, and record}
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.
@end deftypefn

@seealso{lin2mu, mu2lin, loadaudio, saveaudio, playaudio, and setaudio}
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.
@end deftypefn

@seealso{lin2mu, mu2lin, loadaudio, playaudio, setaudio, and record}
setaudio
-*- texinfo -*-
@deftypefn {Function File} setaudio ([@var{w_type} [, @var{value}]])
Execute the shell command @samp{mixer [@var{w_type} [, @var{value}]]}
@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.
@end deftypefn

@seealso{Demo Programs: bddemo.m, frdemo.m, analdemo.m,
moddmeo.m, rldemo.m}
__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.
@end deftypefn

@seealso{step, impulse}
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.

@end deftypefn

@seealso{balance and dare}
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.
@end deftypefn

@seealso{Demo programs: bddemo, frdemo, analdemo, moddmeo, rldemo}
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.
@end deftypefn

@seealso{eig}
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.

@end deftypefn

@seealso{balance and are}
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
@var{m} (@var{n} by @var{n}) satisfies
@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
@end deftypefn

@seealso{step, __stepimp__}
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 + B u
$$
$$
 y = C x + D u
$$
@end tex
@end iftex
@ifinfo

@example
dx
-- = a x + b u
dt

y = c x + d u
@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
@end deftypefn

@seealso{h2syn, lqe, and lqr}
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}, @command{title}, and @command{replot}.

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

Displays 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.
@end deftypefn

@seealso{impulse and __stepimp__}
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
__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.

@end deftypefn

@seealso{is_abcd}
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:} 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
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, ..., _dn to indicate their
delay from the starting time k @var{ts2}, i.e.
u = [u_1; u_1_d1; ..., u_1_dn] where u_1_dk is the input
k*ts1 units of time after u_1 is sampled. (@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, ..., 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) + ... + 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.
@end deftypefn

@seealso{abcddim}
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 paramter.  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}.
@end deftypefn

@seealso{size, rows, columns, length, ismatrix, isscalar, isvector
is_observable, is_stabilizable, is_detectable, krylov, and krylovb}
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.


@end deftypefn

@seealso{is_stabilizable, size, rows, columns, length, ismatrix,
isscalar, and isvector}
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.
@end deftypefn

@seealso{size, rows, columns, length, ismatrix, isscalar, and isvector}
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 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.
@end deftypefn

@seealso{size, rows, columns, length, ismatrix, isscalar, isvector
is_observable, is_stabilizable, is_detectable}
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
@end deftypefn

@seealso{size, rows, columns, length, ismatrix, isscalar, isvector
is_observable, is_stabilizable, is_detectable, krylov, and krylovb}
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.
@end deftypefn

@seealso{ord2}
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
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.
@end deftypefn

@seealso{fir2sys}
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
@end deftypefn

@seealso{sysgetsignals and sysgettsam}
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.
@end deftypefn

@seealso{tf, ss, zp, sysout, sys2ss, sys2tf, and sys2zp}
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"}
@end deftypefn

@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, polyinteg, and polyout}
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.
@end deftypefn

@seealso{hinfdemo and jet707}
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"}
@end deftypefn

@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, polyinteg, and polyout}
__tfl__
-*- texinfo -*-
@deftypefn {Function File} {} __tfl__ (@var{vec})
used internally in tf.
strip leading zero coefficients to get the true polynomial length
@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
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 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{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
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
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
__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
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_global
-*- texinfo -*-
@deftypefn {Function File} {} is_global (@var{a})
This function has been deprecated.  Use isglobal 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
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
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
acot
-*- texinfo -*-
@deftypefn {Mapping Function} {} acot (@var{x})
Compute the inverse cotangent of each element of @var{x}.
@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
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
asech
-*- texinfo -*-
@deftypefn {Mapping Function} {} asech (@var{x})
Compute the inverse hyperbolic secant of each element of @var{x}.
@end deftypefn
cot
-*- texinfo -*-
@deftypefn {Mapping Function} {} cot (@var{x})
Compute the cotangent of each element of @var{x}.
@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
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}, @code{...})
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.
@end deftypefn

@seealso{gcd, min, max, ceil, and floor}
sec
-*- texinfo -*-
@deftypefn {Mapping Function} {} sec (@var{x})
Compute the secant of each element of @var{x}.
@end deftypefn
sech
-*- texinfo -*-
@deftypefn {Mapping Function} {} sech (@var{x})
Compute the hyperbolic secant of each element of @var{x}.
@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.
@end deftypefn

@seealso{npv, pv, and rate}
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).
@end deftypefn

@seealso{pv, pmt, rate, and npv}
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).
@end deftypefn

@seealso{irr and pv}
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.
@end deftypefn

@seealso{pv, nper, and rate}
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).
@end deftypefn

@seealso{pmt, nper, rate, and npv}
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.
@end deftypefn

@seealso{pv, pmt, nper, and npv}
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
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).
@end deftypefn

@seealso{pol2cart, cart2sph, sph2cart}
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).
@end deftypefn

@seealso{pol2cart, cart2pol, sph2cart}
columns
-*- texinfo -*-
@deftypefn {Function File} {} columns (@var{a})
Return the number of columns of @var{a}.
@end deftypefn

@seealso{size, rows, length, isscalar, isvector, and ismatrix}
common_size
-*- texinfo -*-
@deftypefn {Function File} {[@var{err}, @var{y1}, ...] =} common_size (@var{x1}, ...)
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
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
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 workw with 2-D arrays.  To flip N-d arrays
use @code{flipdim} instead.
@end deftypefn

@seealso{flipud, flipdim, rot90 and rotdim}
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.
@end deftypefn

@seealso{fliplr, flipdim, rot90 and rotdim}
int2str
-*- texinfo -*-
@deftypefn {Function File} {} int2str (@var{n})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number to a string.  These functions are not very flexible,
but are provided for compatibility with @sc{Matlab}.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).
@end deftypefn

@seealso{sprintf and num2str}
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
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.  
@end deftypefn

@seealso{issymmetric}
isscalar
-*- texinfo -*-
@deftypefn {Function File} {} isscalar (@var{a})
Return 1 if @var{a} is a scalar.  Otherwise, return 0.
@end deftypefn

@seealso{size, rows, columns, length, isscalar, and ismatrix}
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.
@end deftypefn

@seealso{size, rows, columns, length, ismatrix, isscalar, and isvector}
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.
@end deftypefn

@seealso{size, rows, columns, length, ismatrix, isscalar,
issquare, and isvector}
isvector
-*- texinfo -*-
@deftypefn {Function File} {} isvector (@var{a})
Return 1 if @var{a} is a vector.  Otherwise, return 0.
@end deftypefn

@seealso{size, rows, columns, length, isscalar, and ismatrix}
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.
@end deftypefn

@seealso{linspace}
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.
@end deftypefn

@seealso{rem, round}
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}))}.
@end deftypefn

@seealso{pow2}
num2str
-*- texinfo -*-
@deftypefn {Function File} {} int2str (@var{n})
@deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
@deftypefnx {Function File} {} num2str (@var{x}, @var{format})
Convert a number to a string.  These functions are not very flexible,
but are provided for compatibility with @sc{Matlab}.  For better control
over the results, use @code{sprintf} (@pxref{Formatted Output}).
@end deftypefn

@seealso{sprintf and int2str}
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.
@end deftypefn

@seealso{strerror}
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).
@end deftypefn

@seealso{cart2pol, cart2sph, sph2cart}
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
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
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.
@end deftypefn

@seealso{mod, round}
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)
@equiv{}
rot90 ([1, 2; 3, 4], 3)
@equiv{}
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.
@end deftypefn

@seealso{rotdim, flipud, fliplr and flipdim}
rows
-*- texinfo -*-
@deftypefn {Function File} {} rows (@var{a})
Return the number of rows of @var{a}.
@end deftypefn

@seealso{size, columns, length, isscalar, isvector, and ismatrix}
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
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).
@end deftypefn

@seealso{pol2cart, cart2pol, cart2sph}
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
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 extract 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
@end deftypefn

@seealso{triu and diag}
triu
-*- texinfo -*-
@deftypefn {Function File} {} triu (@var{a}, @var{k})
See tril.
@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.
@end deftypefn

@seealso{sub2ind}
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.
@end deftypefn

@seealso{ind2sub}
deal
-*- texinfo -*-
@deftypefn {Mapping Function} {[@var{r1}, @var{r2}, @dots{}, @var{rn}] =} deal (@var{a})
@deftypefnx {Mapping Function} {[@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
bitcmp
-*- texinfo -*-
@deftypefn {Function File} {@var{X} =} 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))
@result{} 11111111111111111111111111110100
@end example
@end deftypefn

@seealso{bitand,bitor,bitxor,bitset,bitget,bitcmp,bitshift,bitmax}
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
@end deftypefn

@seealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, bitmax}
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
@end deftypefn

@seealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, bitmax}
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
@end deftypefn

@seealso {permute, ipermute, shiftdim}
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
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{} [2, 3, 1]
size (shiftdim (x, 1))
@result{} [1, 1, 2, 3]
[b, ns] = shiftdim (x);
@result{} b =  [1, 1, 1; 1, 1, 1]
@result{} ns = 1
@end group
@end example
@end deftypefn

@seealso {reshape, permute, ipermute, circshift, squeeze}
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
@end deftypefn

@seealso{fliplr, flipud, rot90 and rotdim}
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
rot90 ([1, 2; 3, 4], -1, [1, 2])
@equiv{}
rot90 ([1, 2; 3, 4], 3, [1, 2])
@equiv{}
rot90 ([1, 2; 3, 4], 7, [1, 2])
@end group
@end example
@end deftypefn

@seealso{rot90, flipud, fliplr and flipdim}
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 (a gray scale
colormap with 64 entries).  The default colormap is returned.

With no arguments, @code{colormap} returns the current color map.
@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, 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
hsv2rgb
-*- texinfo -*-
@deftypefn {Function File} {} @var{rgb_map} = hsv2rgb (@var{hsv_map})
Transform a colormap from the hsv space to the rgb space. 
@end deftypefn

@seealso{rgb2hsv}
image
-*- texinfo -*-
@deftypefn {Function File} {} image (@var{x}, @var{zoom})
@deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{A}, @var{zoom})
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.  If @var{zoom} is omitted, the image will be
scaled to fit within 600x350 (to a max of 4).

It first tries to use @code{display} from @code{ImageMagick} then
@code{xv} and then @code{xloadimage}.

The axis values corresponding to the matrix elements are specified in
@var{x} and @var{y}. At present they are ignored.
@end deftypefn

@seealso{imshow, imagesc, and colormap}
imagesc
-*- texinfo -*-
@deftypefn {Function File} {} imagesc (@var{A})
@deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{A})
@deftypefnx {Function File} {} imagesc (@dots{}, @var{zoom})
@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{zoom} is omitted, a
comfortable size is chosen.  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}.  At present they are ignored.
@end deftypefn

@seealso{image and imshow}
imshow
-*- texinfo -*-
@deftypefn {Function File} {} imshow (@var{i})
@deftypefnx {Function File} {} imshow (@var{x}, @var{map})
@deftypefnx {Function File} {} imshow (@var{i}, @var{n})
@deftypefnx {Function File} {} imshow (@var{r}, @var{g}, @var{b})
Display an image.

@code{imshow (@var{x})} displays an image @var{x}.
The numerical class of the image determines its bit-depth: 1 for
@code{logical}, 8 for @code{uint8} and @code{logical}, and 16 for
@code{double} or @code{uint16}.  If @var{x} has dimensions MxNx3, the
three matrices represent the red, green and blue components of the
image.

@code{imshow (@var{x}, @var{map})} displays an indexed image using the
specified colormap.

@code{imshow (@var{i}, @var{n})} displays a gray scale intensity image of
N levels.

@code{imshow (@var{r}, @var{g}, @var{b})} displays an RGB image.

The character string @code{"truesize"} can always be used as an
optional final argument to prevent automatic zooming of the image.
@end deftypefn
@seealso{image, imagesc, colormap, gray2ind, and rgb2ind}
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.
@end deftypefn

@seealso{gray2ind, rgb2ntsc, image, and colormap}
ind2rgb
-*- texinfo -*-
@deftypefn {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 @var{map} is omitted, the current colormap is used for the conversion.
@end deftypefn

@seealso{rgb2ind, image, imshow, ind2gray, and gray2ind}
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.
@end deftypefn

@seealso{saveimage, load, and save}
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, 64 is assumed.
@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. 
@end deftypefn

@seealso{hsv2rgb}
rgb2ind
-*- texinfo -*-
@deftypefn {Function File} {[@var{x}, @var{map}] =} rgb2ind (@var{r}, @var{g}, @var{b})
Convert and RGB image to an Octave indexed image.
@end deftypefn

@seealso{ind2rgb and rgb2ntsc}
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.
@end deftypefn

@seealso{loadimage, save, load, and colormap}
beep
-*- texinfo -*-
@deftypefn {Function File} {} puts (@var{string})
Produce a beep from the speaker (or visual bell).
@end deftypefn

@seealso{puts, fputs, printf and fprintf}
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.
@end deftypefn

@seealso{norm, svd, and rank}
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 defiend 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 orthogonal basis U of block Krylov subspace;
 [v a*v a^2*v ... a^(k+1)*v];
method used: householder reflections to guard against loss of
orthogonality
eps1: threshhold for 0 (default: 1e-12)
pflg: flag to use row pivoting  (improves numerical behavior)
  0 [default]: no pivoting; prints a warning message if trivial
               null space is corrupted
  1          : pivoting performed

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

Reference: Hodel and Misra, "Partial Pivoting in the Computation of
    Krylov Subspaces", to be submitted to Linear Algebra and its
    Applications
@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
@end deftypefn

@seealso{cond and svd}
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
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
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
comma
-*- texinfo -*-
@deffn {Operator} ,
Array index, function argument, or command separator.
@end deffn

@seealso{semicolon}
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
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
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.
@end deftypefn

@seealso{tic, toc, clock, and cputime}
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}.
@end deftypefn
flops
-*- texinfo -*-
@deftypefn {Function File} {} flops ()
This function is provided for 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.
@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
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
 \TeXbook.
@end tex
@end iftex
@ifinfo
 TeXbook.
@end ifinfo
@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.
@end deftypefn

@seealso{disp, printf, and input}
pack
-*- texinfo -*-
@deftypefn {Function File} {} pack ()
This function is provided for compatibility with Matlab, but it
doesn't actually do anything.
@end deftypefn
paren
-*- texinfo -*-
@deffn {Operator} (
@deffnx {Operator} )
Array index or function argument delimeter.
@end deffn
path
-*- texinfo -*-
@deftypefn {Function File} {} path (@dots{})
Modify or display Octave's @code{LOADPATH}.

If @var{nargin} and @var{nargout} are zero, display the elements of
Octave's @code{LOADPATH} in an easy to read format.

If @var{nargin} is zero and nargout is greater than zero, return the
current value of @code{LOADPATH}.

If @var{nargin} is greater than zero, concatenate the arguments,
separating them with @code{":"}.  Set @code{LOADPATH} to the result
and also return it.

No checks are made for duplicate elements.
@end deftypefn
popen2
-*- texinfo -*-
@deftypefn {Function File} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args})
Start a subprocess with two-way communication.  The name of the process
is given by @var{command}, and @var{args} is an array of strings
containing options for the command.  The file identifiers for the input
and output streams of the subprocess are returned in @var{in} and
@var{out}.  If execution of the command is successful, @var{pid}
contains the process ID of the subprocess.  Otherwise, @var{pid} is
@minus{}1.

For example,

@example
@group
[in, out, pid] = popen2 ("sort", "-nr");
fputs (in, "these\nare\nsome\nstrings\n");
fclose (in);
while (isstr (s = fgets (out)))
  fputs (stdout, s);
endwhile
fclose (out);
@print{} are
@print{} some
@print{} strings
@print{} these
@end group
@end example
@end deftypefn
semicolon
-*- texinfo -*-
@deffn {Operator} ;
Array row or command separator.
@end deffn

@seealso{comma}
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.
@end deftypefn

@seealso{rand}
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}.

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
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
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
computer
-*- texinfo -*-
@deftypefn {Function File} {} 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
@end deftypefn
delete
-*- texinfo -*-
@deftypefn {Function File} {} delete (file)
Delete the named file.  Delete is a wrapper for @code{unlink}.
@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 file.
@var{filename}.
@end deftypefn

@seealso{stat}
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
not
-*- texinfo -*-
@deftypefn {Function File} {} not (@var{val})
Return the logical negation of val.  This function is equivalent to
@code{! val}.
@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.
@end deftypefn

@seealso{isunix, ispc, system}
__axis_label__
-*- texinfo -*-
@deftypefn {Function File} {} __axis_label__ (@var{caller}, @var{text})
Utility function for @code{xlabel}, @code{ylabel}, and @code{zlabel}.
@end deftypefn
__errcomm__
-*- texinfo -*-
@deftypefn {Function File} {} __errcomm__ (@var{args})
Common argument handling code for all error plots (errorbar, loglogerr,
semilogyerr, semilogxerr).

@end deftypefn

@seealso{errorbar, semilogxerr, semilogyerr, loglogerr, __pltopt__}
__errplot__
-*- texinfo -*-
@deftypefn {Function File} {} __errplot__ (@var{args})
Really plot errorbar plots. User interface in function errorbar.

@example
__errplot__ (@var{arg1}, @var{arg2}, ..., @var{fmt})
@end example

@end deftypefn

@seealso{semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__
bar, stairs, errorbar, replot, xlabel, ylabel, and title}
__plr1__
-*- texinfo -*-
@deftypefn {Function File} {} __plr1__ (@var{theta}, @var{fmt})
@end deftypefn
__plr2__
-*- texinfo -*-
@deftypefn {Function File} {} __plr2__ (@var{theta}, @var{rho}, @var{fmt})
@end deftypefn
__plr__
-*- texinfo -*-
@deftypefn {Function File} {} __plr__ (@var{theta}, @var{rho}, @var{fmt})
@end deftypefn
__plt1__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt1__ (@var{x1}, @var{fmt})
@end deftypefn
__plt2__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt2__ (@var{x1}, @var{x2}, @var{fmt})
@end deftypefn
__plt2mm__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt2mm__ (@var{x}, @var{y}, @var{fmt})
@end deftypefn
__plt2mv__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt2mv__ (@var{x}, @var{y}, @var{fmt})
@end deftypefn
__plt2ss__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt2ss__ (@var{x}, @var{y}, @var{fmt})
@end deftypefn
__plt2vm__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt2vm__ (@var{x}, @var{y}, @var{fmt})
@end deftypefn
__plt2vv__
-*- texinfo -*-
@deftypefn {Function File} {[data, fmtstr] =} __plt2vv__ (@var{x}, @var{y}, @var{fmt})
@end deftypefn
__plt__
-*- texinfo -*-
@deftypefn {Function File} {} __plt__ (@code{caller}, @dots{})
@end deftypefn
__pltopt1__
-*- texinfo -*-
@deftypefn {Function File} {} __pltopt1__ (@var{caller}, @var{opt})
Really decode plot option strings.
@end deftypefn

@seealso{__pltopt__}
__pltopt__
-*- texinfo -*-
@deftypefn {Function File} {} __pltopt__ (@var{caller}, @var{opt})
Decode plot option strings.

If @var{opt} is a valid option string, return a string of the form
@code{"w l 2"} ("with lines 2").  Uses abbreviations for the options
to avoid overrunning gnuplot's command line buffer unnecessarily.

@var{opt} can currently be some combination of the following:

@table @code
@item "-"
For lines plot style (default).

@item "."
For dots plot style.

@item "@@"
For points plot style.

@item "-@@"
For linespoints plot style.

@item "^"
For impulses plot style.

@item "L"
For steps plot style.

@item "#"
For boxes plot style.

@item "~"
For yerrorbars plot style.

@item ">"
For xerrorbars plot style.

@item "~>"
For xyerrorbars plot style.

@item "#~"
For boxerrorbars plot style.

@item "#~>"
For boxxyerrorbars plot style.

@item "n"
With @code{n} in 1-6 (wraps at 8), plot color

@item "nm"
With @code{m} in 1-6 (wraps at 6), point style (only valid for @code{"@@"} or
@code{"-@@"})

@item @var{c}
Where @var{c} is one of @code{"r"}, @code{"g"}, @code{"b"}, @code{"m"},
@code{"c"}, or @code{"w"} colors.

@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 legend may be fixed to include the name of the variable
plotted in some future version of Octave.

The colors, line styles, and point styles have the following
meanings for X11 and Postscript terminals under Gnuplot 3.6.

@example
Number ------ Color -------  Line Style      ---- Points Style ----
       x11       postscript  postscript      x11         postscript
=====================================================================
  1    red       green       solid           "o"         "+"
  2    green     blue        long dash       "+"         "x"
  3    blue      red         short dash     square       "*"
  4    magenta   magenta     dotted          "x"        open square
  5    cyan      cyan        dot long dash  triangle    filled square
  6    brown     yellow      dot short dash  "*"         "o"
@end example
@end deftypefn

@seealso{__pltopt1__}
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} {} bar (@var{x}, @var{y})
Given two vectors of x-y data, @code{bar} produces a bar graph.

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

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

@example
bar (x, y);
@end example

@noindent
and

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

@noindent
are equivalent.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
stairs, replot, xlabel, ylabel, and title}
bottom_title
-*- texinfo -*-
@deftypefn {Function File} {} bottom_title (@var{string})
See top_title.
@end deftypefn
close
-*- texinfo -*-
@deftypefn {Command} {} close
@deftypefnx {Command} {} close all
Close the plot window(s).
@end deftypefn
contour
-*- texinfo -*-
@deftypefn {Function File} {} contour (@var{z}, @var{n})
@deftypefnx {Function File} {} contour (@var{x}, @var{y}, @var{z}, @var{n})
Make a contour plot of the three-dimensional surface described by
@var{z}.  Someone needs to improve @code{gnuplot}'s contour routines
before this will be very useful.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, replot, xlabel, ylabel, and title}
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}, ..., @var{fmt} ...)
@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 (See __pltopt__). 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

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

Two 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

xyerrorbar plot of @var{y} versus @var{x} where @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}.

@end deftypefn

@seealso{semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__,
bar, stairs, replot, xlabel, ylabel, and title}
figure
-*- texinfo -*-
@deftypefn {Function File} {} figure (@var{n})
Set the current plot window to plot window @var{n}.  This function
currently requires X11 and a version of gnuplot that supports multiple
frames.  If @var{n} is not specified, the next available window
number is chosen.
@end deftypefn
grid
-*- texinfo -*-
@deftypefn {Function File} {} grid (@var{arg})
For two-dimensional plotting, force the display of a grid on the plot.
The argument may be either @code{"on"} or @code{"off"}.  If it is
omitted, @code{"on"} is assumed.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, replot, xlabel, ylabel, and title}
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.
@end deftypefn

@seealso{bar}
loglog
-*- texinfo -*-
@deftypefn {Function File} {} loglog (@var{args})
Make 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.
@end deftypefn

@seealso{plot, semilogy, loglog, polar, mesh, contour, bar, stairs,
replot, xlabel, ylabel, and title}
loglogerr
-*- texinfo -*-
@deftypefn {Function File} {} loglogerr (@var{args})
This function produces two-dimensional plots on double logarithm axis 
with errorbars. Many different combinations of arguments are possible.  
The most used form is

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

@end deftypefn

@seealso{errorbar, semilogxerr, semilogyerr, polar, mesh, contour, 
__pltopt__, bar, stairs, replot, xlabel, ylabel, and title}
mesh
-*- texinfo -*-
@deftypefn {Function File} {} mesh (@var{x}, @var{y}, @var{z})
Plot a mesh given matrices @var{x}, and @var{y} from @code{meshdom} 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.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, meshgrid, meshdom,
contour, bar, stairs, replot, xlabel, ylabel, and title}
meshdom
-*- texinfo -*-
@deftypefn {Function File} {} meshdom (@var{x}, @var{y})
Given vectors of @var{x} and @var{y} coordinates, return two matrices
corresponding to the @var{x} and @var{y} coordinates of the mesh.

Note: this function is provided for compatibility with older versions
of @sc{Matlab}.  You should use @code{meshgrid} instead.
@end deftypefn
meshgrid
-*- texinfo -*-
@deftypefn {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} coordinates, return two 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}.
@end deftypefn

@seealso{sombrero, plot, semilogx, semilogy, loglog, polar, mesh,
meshdom, contour, bar, stairs, replot, xlabel, ylabel, and title}
mplot
-*- texinfo -*-
@deftypefn {Function File} {} mplot (@var{x}, @var{y})
@deftypefnx {Function File} {} mplot (@var{x}, @var{y}, @var{fmt})
@deftypefnx {Function File} {} mplot (@var{x1}, @var{y1}, @var{x2}, @var{y2})
This is a modified version of the @code{plot} function that works with
the multiplot version of @code{gnuplot} to plot multiple plots per page.
This plot version automatically advances to the next subplot position
after each set of arguments are processed.

See the description of the @var{plot} function for the various options.
@end deftypefn
multiplot
-*- texinfo -*-
@deftypefn {Function File} {} multiplot (@var{xn}, @var{yn})
Sets and resets multiplot mode.

If the arguments are non-zero, @code{multiplot} will set up multiplot
mode with @var{xn}, @var{yn} subplots along the @var{x} and @var{y}
axes.  If both arguments are zero, @code{multiplot} closes multiplot
mode.
@end deftypefn
oneplot
-*- texinfo -*-
@deftypefn {Function File} {} oneplot ()
If in multiplot mode, switches to single plot mode.
@end deftypefn
plot
-*- texinfo -*-
@deftypefn {Function File} {} plot (@var{args})
This function 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.

If more than one argument is given, they are interpreted as

@example
plot (@var{x}, @var{y}, @var{fmt} ...)
@end example

@noindent
where @var{y} and @var{fmt} are optional, and 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 first argument is a vector and the second is a matrix, the
the vector is plotted versus the columns (or rows) of the matrix.
(using whichever combination matches, with columns tried first.)

@item
If the first argument is a matrix and the second is a vector, the
the columns (or rows) of the matrix are plotted versus the vector.
(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

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 points plot style.

@item -@@
Set linespoints 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{"r"}, @code{"g"}, @code{"b"}, @code{"m"},
@code{"c"}, or @code{"w"}, it is interpreted as the plot color (red,
green, blue, magenta, cyan, or white).

@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 color line styles have the following meanings on terminals that
support color.

@example
Number  Gnuplot colors  (lines)points style
  1       red                   *
  2       green                 +
  3       blue                  o
  4       magenta               x
  5       cyan                house
  6       brown            there exists
@end example

The @var{fmt} argument can 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, "*")
@end example

This command will plot the data in the variable @code{b} will be plotted
with points displayed as @samp{*}.

@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.
@end deftypefn

@seealso{semilogx, semilogy, loglog, polar, mesh, contour, __pltopt__
bar, stairs, errorbar, replot, xlabel, ylabel, and title}
plot_border
-*- texinfo -*-
@deftypefn {Function File} {} plot_border (...)
Multiple arguments allowed to specify the sides on which the border
is shown.  Allowed arguments include:

@table @code
@item "blank"
No borders displayed.

@item "all"
All borders displayed

@item "north"
North Border

@item "south"
South Border

@item "east"
East Border

@item "west"
West Border
@end table

@noindent
The arguments may be abbreviated to single characters.  Without any
arguments, @code{plot_border} turns borders off.
@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.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, mesh, contour, bar,
stairs, replot, xlabel, ylabel, and title}
semilogx
-*- texinfo -*-
@deftypefn {Function File} {} semilogx (@var{args})
Make 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.
@end deftypefn

@seealso{plot, semilogy, loglog, polar, mesh, contour, bar, stairs,
replot, xlabel, ylabel, and title}
semilogxerr
-*- texinfo -*-
@deftypefn {Function File} {} semilogxerr (@var{args})
This function produces two-dimensional plots on a semilogarithm axis 
with errorbars. Many different combinations of arguments are possible.  
The most used form is

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

@end deftypefn

@seealso{errorbar, loglogerr semilogyerr, polar, mesh, contour, __pltopt__, 
bar, stairs, replot, xlabel, ylabel, and title}
semilogy
-*- texinfo -*-
@deftypefn {Function File} {} semilogy (@var{args})
Make 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.
@end deftypefn

@seealso{plot, semilogx, loglog, polar, mesh, contour, bar, stairs,
replot, xlabel, ylabel, and title}
semilogyerr
-*- texinfo -*-
@deftypefn {Function File} {} semilogyerr (@var{args})
This function produces two-dimensional plots on a semilogarithm axis 
with errorbars. Many different combinations of arguments are possible.  
The most used form is

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

@end deftypefn

@seealso{errorbar, loglogerr semilogxerr, polar, mesh, contour, __pltopt__, 
bar, stairs, replot, xlabel, ylabel, and title}
shg
-*- texinfo -*-
@deftypefn {Function File} {} shg

Show the graph window.  Currently, this is the same as executing
replot.

@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, replot, xlabel, and ylabel}
sombrero
-*- texinfo -*-
@deftypefn {Function File} {} sombrero (@var{n})

Draw a `sombrero' in three dimensions using @var{n} grid lines.  The
function plotted is

@example
  z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2))
@end example
@end deftypefn
stairs
-*- texinfo -*-
@deftypefn {Function File} {} stairs (@var{x}, @var{y})
Given two vectors of x-y data, bar produces a `stairstep' plot.

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

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

@example
stairs (x, y);
@end example

@noindent
and

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

@noindent
are equivalent.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, replot, xlabel, ylabel, and title}
subplot
-*- texinfo -*-
@deftypefn {Function File} {} subplot (@var{rows}, @var{cols}, @var{index})
@deftypefnx {Function File} {} subplot (@var{rcn})
Sets @code{gnuplot} in multiplot mode and plots in location
given by index (there are @var{cols} by @var{rows} subwindows).

The global variable @var{__multiplot_scale__} should be used when the
command @code{__gnuplot_set__ size xsize, ysize} has been used prior to calling
@code{subplot}.

The value of @var{__multiplot_scale__} should be a vector with two
elements, the first set equal to @var{xsize} and the second to
@var{ysize}.

Input:

@table @var
@item rows
Number of rows in subplot grid.

@item columns
Number of columns in subplot grid.

@item index
Index of subplot where to make the next plot.
@end table

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

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

For example, a plot with 4 by 2 grid will have plot indices running as
follows:
@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
+-----+-----+-----+-----+
|  1  |  2  |  3  |  4  |
+-----+-----+-----+-----+
|  5  |  6  |  7  |  8  |
+-----+-----+-----+-----+
@end group
@end display
@end ifinfo
@end deftypefn
subwindow
-*- texinfo -*-
@deftypefn {Function File} {} subwindow (@var{xn}, @var{yn})
Sets the subwindow position in multiplot mode for the next plot.  The
multiplot mode has to be previously initialized using the
@code{multiplot} function, otherwise this command just becomes an alias
to @code{multiplot}
@end deftypefn
title
-*- texinfo -*-
@deftypefn {Function File} {} title (@var{string})
Specify a title for a plot.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, replot, xlabel, and ylabel}
top_title
-*- texinfo -*-
@deftypefn {Function File} {} top_title (@var{string})
@deftypefnx {Function File} {} bottom_title (@var{string})
Makes a title with text @var{string} at the top (bottom) of the plot.
@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 plot.  If you already have a plot
displayed, use the command @code{replot} to redisplay it with the new
labels.
@end deftypefn

@seealso{plot, semilogx, semilogy, loglog, polar, mesh, contour,
bar, stairs, replot, ylabel, and title}
ylabel
-*- texinfo -*-
@deftypefn {Function File} {} ylabel (@var{string})
See xlabel.
@end deftypefn
zlabel
-*- texinfo -*-
@deftypefn {Function File} {} zlabel (@var{string})
See xlabel.
@end deftypefn
orient
-*- texinfo -*-
@deftypefn {Function File} {} orient (@var{orientation})
Set 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
print
Copyright (C) 1999 Daniel Heiserer
Copyright (C) 2001 Laurent Mazet

This file is part of Octave.

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

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

You should have received a copy of the GNU General Public License
along with Octave; see the file COPYING.  If not, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
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
@ifinfo

@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 ifinfo

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

@seealso{poly, roots, residue, conv, deconv, polyval, polyderiv, and
polyinteg}
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.
@end deftypefn

@seealso{deconv, poly, roots, residue, polyval, polyderiv, and polyinteg}
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.
@end deftypefn

@seealso{conv, poly, roots, residue, polyval, polyderiv, and polyinteg}
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}.  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}.
@end deftypefn
polyder
-*- texinfo -*-
@deftypefn {Function File} {} polyder (@var{c})
See polyderiv.
@end deftypefn
polyderiv
-*- texinfo -*-
@deftypefn {Function File} {} polyderiv (@var{c})
Return the coefficients of the derivative of the polynomial whose
coefficients are given by vector @var{c}.
@end deftypefn

@seealso{poly, polyinteg, polyreduce, roots, conv, deconv, residue,
filter, polyval, and polyvalm}
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
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.
@end deftypefn

@seealso{poly, polyderiv, polyreduce, roots, conv, deconv, residue,
filter, polyval, and polyvalm}
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"}.
@end deftypefn

@seealso{polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, and polyinteg}
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.
@end deftypefn

@seealso{poly, roots, conv, deconv, residue, filter, polyval,
polyvalm, polyderiv, and polyinteg}
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}.
@end deftypefn

@seealso{polyvalm, poly, roots, conv, deconv, residue, filter,
polyderiv, and polyinteg}
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.
@end deftypefn

@seealso{polyval, poly, roots, conv, deconv, residue, filter,
polyderiv, and polyinteg}
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
@end deftypefn

@seealso{poly, roots, conv, deconv, polyval, polyderiv, and polyinteg}
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
@ifinfo

@example
v(1) * z^(N-1) + ... + v(N-1) * z + v(N)
@end example
@end ifinfo
@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
@end deftypefn

@seealso{create_set, union, and intersection}
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
@end deftypefn

@seealso{union, intersection, and complement}
intersection
-*- texinfo -*-
@deftypefn {Function File} {} intersection (@var{x}, @var{y})
Return the set of elements that are in both sets @var{x} and @var{y}.
For example,

@example
@group
intersection ([ 1, 2, 3 ], [ 2, 3, 5 ])
@result{} [ 2, 3 ]
@end group
@end example
@end deftypefn

@seealso{create_set, union, and complement}
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
@end deftypefn

@seealso{create_set, intersection, and complement}
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), ..., @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, ...,
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
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
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
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
erfinv
-*- texinfo -*-
@deftypefn {Mapping Function} {} erfinv (@var{z})
Computes the inverse of the error function.
@end deftypefn

@seealso{erf and erfc}
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
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
@end deftypefn

@seealso{log, log10, logspace, and exp}
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
@end deftypefn

@seealso{nextpow2}
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
@end deftypefn

@seealso{vander, sylvester_matrix, hilb, invhilb, and toeplitz}
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
@end deftypefn

@seealso{hankel, vander, sylvester_matrix, invhilb, and toeplitz}
invhilb
-*- texinfo -*-
@deftypefn {Function File} {} invhilb (@var{n})
Return the inverse of a Hilbert matrix of order @var{n}.  This can be 
computed 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.

@end deftypefn

@seealso{hankel, vander, sylvester_matrix, hilb, and toeplitz}
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
@end deftypefn

@seealso{hankel, vander, hilb, invhilb, and toeplitz}
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
@end deftypefn

@seealso{hankel, vander, sylvester_matrix, hilb, and invhib}
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
@end deftypefn

@seealso{hankel, sylvester_matrix, hilb, invhilb, and toeplitz}
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

@example
- log (- log (@var{x}))
@end example
@end deftypefn
cor
-*- texinfo -*-
@deftypefn {Function File} {} cor (@var{x}, @var{y})
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}.

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})}.
@end deftypefn
corrcoef
-*- texinfo -*-
@deftypefn {Function File} {} corrcoef (@var{x}, @var{y})
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}.
If called with one argument, compute @code{corrcoef (@var{x}, @var{x})}.
@end deftypefn
cov
-*- texinfo -*-
@deftypefn {Function File} {} cov (@var{x}, @var{y})
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}.  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
@code{(2 * (2@var{n}+5)) / (9 * @var{n} * (@var{n}-1))}.
@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
$$
@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 @code{log (@var{p} /
(1-@var{p}))} of @var{p}.
@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})
If @var{x} is a vector, compute the median value of the elements of
@var{x}.
@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.
@end deftypefn

@seealso{std and mean}
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

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

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, ..., @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
$$
@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}) \over N - 1}}
$$
@end tex
@end iftex
@ifinfo

@example
@group
std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
@end group
@end example
@end ifinfo
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 N-1, provides the square root of best unbiased estimator of 
  the variance [default]
@item 1:
  normalizes with 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.
@end deftypefn

@seealso{mean and median}
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.
@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 N-1, provides the square root of best unbiased estimator
  of the variance [default]
@item 1:
  normalizes with 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 
variance is calculated.
@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
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
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{k} 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
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 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
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{n_size}, @var{m}, @var{t}, @var{n})
@deftypefnx {Function File} {} hypergeometric_rnd (@var{m}, @var{t}, @var{n}, @var{r}, @var{c})
@deftypefnx {Function File} {} hypergeometric_rnd (@var{m}, @var{t}, @var{n}, @var{sz})
Generate a row vector containing a random sample of size @var{n_size}
from the hypergeometric distribution with parameters @var{m}, @var{t},
and @var{n}.

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

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
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 is @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 is @var{sz} is a vector, create a matrix of
@var{sz}.
@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
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
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
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
weibull_cdf
-*- texinfo -*-
@deftypefn {Function File} {} weibull_cdf (@var{x}, @var{alpha}, @var{sigma})
Compute the cumulative distribution function (CDF) at @var{x} of the
Weibull distribution with shape parameter @var{alpha} and scale
parameter @var{sigma}, which is

@example
1 - exp(-(x/sigma)^alpha)
@end example

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

@example
   alpha * sigma^(-alpha) * x^(alpha-1) * exp(-(x/sigma)^alpha)
@end example

@noindent
for @var{x} > 0.
@end deftypefn
weibull_rnd
-*- texinfo -*-
@deftypefn {Function File} {} weibull_rnd (@var{alpha}, @var{sigma}, @var{r}, @var{c})
@deftypefnx {Function File} {} weibull_rnd (@var{alpha}, @var{sigma}, @var{sz})
Return an @var{r} by @var{c} matrix of random samples from the
Weibull distribution with parameters @var{alpha} and @var{sigma}
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
logistic_regression
-*- texinfo -*-
@deftypefn {Functio 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.

Stting @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 ollows 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 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 T^2 is returned in @var{tsq}.  Under the null,

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

@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

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 f
follows an F-distribution with df_num and 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 t approximately follows a Student
distribution with 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.

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

@end deftypefn

@seealso{dec2base, dec2bin, bin2dec, hex2dec, dec2hex}
bin2dec
-*- texinfo -*-
@deftypefn {Function File} {} hex2dec (@var{s})
Return the decimal number corresponding to the binary number stored
in the string @var{s}.  For example,

@example
hex2dec ("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.
@end deftypefn

@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}
blanks
-*- texinfo -*-
@deftypefn {Function File} {} blanks (@var{n})
Return a string of @var{n} blanks.
@end deftypefn
deblank
-*- texinfo -*-
@deftypefn {Function File} {} deblank (@var{s})
Removes the trailing blanks and nulls from the string @var{s}.
If @var{s} is a matrix, @var{deblank} trims each row to the 
length of longest string.
@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.
@end deftypefn

@seealso{base2dec, dec2bin, bin2dec, hex2dec, dec2hex}
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.
@end deftypefn

@seealso{bin2dec, dec2base, base2dec, hex2dec, dec2hex}
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.
@end deftypefn

@seealso{hex2dec, dec2base, base2dec, bin2dec, dec2bin}
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})
Returns 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.
@end deftypefn

@seealso{dec2hex, base2dec, dec2base, bin2dec, dec2bin}
index
-*- texinfo -*-
@deftypefn {Function File} {} index (@var{s}, @var{t})
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

@strong{Caution:}  This function does not work for arrays of strings.
@end deftypefn
isletter
-*- texinfo -*-
@deftypefn {Function File} {} isletter (@var{s})
Returns true if @var{s} is a letter false otherwise.
@end deftypefn

@seealso{isalpha}
lower
-*- texinfo -*-
@deftypefn {Function File} {} lower (@var{s})
Transform all letters in the string @var{s} to lower case.
@end deftypefn

@seealso{tolower}
rindex
-*- texinfo -*-
@deftypefn {Function File} {} rindex (@var{s}, @var{t})
Return the position of the last occurrence of the string @var{t} in the
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 strings.
@end deftypefn
split
-*- texinfo -*-
@deftypefn {Function File} {} split (@var{s}, @var{t})
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).  For example,

@example
split ("Test string", "t")
@result{} "Tes "
        " s  "
        "ring"
@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
strcmp
-*- texinfo -*-
@deftypefn {Function File} {} strcmp (@var{s1}, @var{s2})
Compares two character strings, returning true if they are the same,
and false otherwise.

@strong{Caution:}  For compatibility with @sc{Matlab}, Octave's strcmp
function returns true if the character strings are equal, and false
otherwise.  This is just the opposite of the corresponding C library
function.
@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
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
substr
-*- texinfo -*-
@deftypefn {Function File} {} substr (@var{s}, @var{beg}, @var{len})
Return the substring of @var{s} which starts at character number
@var{beg} and is @var{len} characters long.

If OFFSET is negative, extraction starts that far from the end of
the string.  If 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

@quotation
This function is patterned after AWK.  You can get the same result by
@code{@var{s} (@var{beg} : (@var{beg} + @var{len} - 1))}.
@end quotation
@end deftypefn
upper
-*- texinfo -*-
@deftypefn {Function File} {} upper (@var{s})
Transform all letters in the string @var{s} to upper case.
@end deftypefn

@seealso{toupper}
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
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