## [04d129]: doc / functions.texi  Maximize  Restore  History

### 7283 lines (6463 with data), 226.1 kB

@c This file is generated automatically
@c Do not edit

@chapter Examples
@section MDSSystem
@findex MDSSystem

Robust control of a mass-damper-spring system.
Type @code{which MDSSystem} to locate,
@code{edit MDSSystem} to open and simply
@code{MDSSystem} to run the example file.
@section optiPID
@findex optiPID

Numerical optimization of a PID controller using an objective function.
The objective function is located in the file @command{optiPIDfun}.
Type @code{which optiPID} to locate, @code{edit optiPID} to open
and simply @code{optiPID} to run the example file.
In this example called @code{optiPID}, loosely based on [1], it is assumed
that the plant
@iftex
@tex
$$P(s) = {1 \over (s^{2} + s + 1)\ (s + 1)^{4}}$$
@end tex
@end iftex
@ifnottex
@example
1
P(s) = -----------------------
(s^2 + s + 1) (s + 1)^4
@end example
@end ifnottex
is controlled by a PID controller with second-order roll-off
@iftex
@tex
$$C(s) = k_p \ (1 + {1 \over T_i \ s} + T_d \ s) \ {1 \over (\tau \ s + 1)^{2}}$$
@end tex
@end iftex
@ifnottex
@example
1                1
C(s) = Kp (1 + ---- + Td s) -------------
Ti s         (tau s + 1)^2
@end example
@end ifnottex
in the usual negative feedback structure
@iftex
@tex
$$T(s) = {L(s) \over 1 + L(s)} = {P(s) \ C(s) \over 1 + P(s) \ C(s)}$$
@end tex
@end iftex
@ifnottex
@example
L(s)       P(s) C(s)
T(s) = -------- = -------------
1 + L(s)   1 + P(s) C(s)
@end example
@end ifnottex
The plant P(s) is of higher order but benign.  The initial values for the
controller parameters
@iftex
@tex
$k_p$, $T_i$ and $T_d$
@end tex
@end iftex
@ifnottex
Kp, Ti and Td
@end ifnottex
are obtained by applying the
Astroem and Haegglund rules [2].  These values are to be improved using a
numerical optimization as shown below.
As with all numerical methods, this approach can never guarantee that a
proposed solution is a global minimum.  Therefore, good initial guesses for
the parameters to be optimized are very important.
The Octave function @code{fminsearch} minimizes the objective function @var{J},
which is chosen to be
@iftex
@tex
$$J(k_p, T_i, T_d) = \mu_1 \cdot \int_0^{\infty} \! t \ |e(t)| \ dt \ + \ \mu_2 \cdot (|| y(t) ||_{\infty} - 1) \ + \ \mu_3 \cdot ||S(jw)||_{\infty}$$
@end tex
@end iftex
@ifnottex
@example
inf
J(Kp, Ti, Td) = mu1 INT t |e(t)| dt  +  mu2 (||y(t)||   - 1)  +  mu3 ||S(jw)||
0                               inf                      inf
@end example
@end ifnottex
This particular objective function penalizes the integral of time-weighted absolute error
@iftex
@tex
$$ITAE = \int_0^{\infty} \! t \ |e(t)| \ dt$$
@end tex
@end iftex
@ifnottex
@example
inf
ITAE = INT t |e(t)| dt
0
@end example
@end ifnottex
and the maximum overshoot
@iftex
@tex
$$y_{max} - 1 = || y(t) ||_{\infty} - 1$$
@end tex
@end iftex
@ifnottex
@example
y    - 1 = || y(t) ||   - 1
max                 inf
@end example
@end ifnottex
to a unity reference step
@iftex
@tex
$r(t) = \varepsilon (t)$
@end tex
@end iftex
in the time domain. In the frequency domain, the sensitivity
@iftex
@tex
$$M_s = ||S(jw)||_{\infty}$$
@end tex
@end iftex
@ifnottex
@example
Ms = ||S(jw)||
inf
@end example
@end ifnottex
is minimized for good robustness, where S(jw) denotes the @emph{sensitivity} transfer function
@iftex
@tex
$$S(s) = {1 \over 1 + L(s)} = {1 \over 1 + P(s) \ C(s)}$$
@end tex
@end iftex
@ifnottex
@example
1            1
S(s) = -------- = -------------
1 + L(s)   1 + P(s) C(s)
@end example
@end ifnottex
The constants
@iftex
@tex
$\mu_1$, $\mu_2$ and $\mu_3$
@end tex
@end iftex
@ifnottex
mu1, mu2 and mu3
@end ifnottex
are @emph{relative weighting factors} or @guillemetleft{}tuning knobs@guillemetright{}
which reflect the importance of the different design goals. Varying these factors
corresponds to changing the emphasis from, say, high performance to good robustness.
The main advantage of this approach is the possibility to explore the tradeoffs of
the design problem in a systematic way.
In a first approach, all three design objectives are weigthed equally.
In subsequent iterations, the parameters
@iftex
@tex
$\mu_1 = 1$, $\mu_2 = 10$ and $\mu_3 = 20$
@end tex
@end iftex
@ifnottex
mu1 = 1, mu2 = 10 and mu3 = 20
@end ifnottex
are found to yield satisfactory closed-loop performance.  This controller results
in a system with virtually no overshoot and a phase margin of 64 degrees.

@*@strong{References}@*
[1] Guzzella, L.
@cite{Analysis and Design of SISO Control Systems},
VDF Hochschulverlag, ETH Zurich, 2007@*
[2] Astroem, K. and Haegglund, T.
@cite{PID Controllers: Theory, Design and Tuning},
Second Edition,
Instrument Society of America, 1995
@section Anderson
@findex Anderson

Frequency-weighted coprime factorization controller reduction.

Demonstration of frequency-weighted controller reduction.
The system considered in this example has been studied by Madievski and
Anderson [1] and comprises four spinning disks.  The disks are connected by a
flexible rod, a motor applies torque to the third disk, and the angular
displacement of the first disk is the variable of interest. The state-space
model of eighth order is non-minimumphase and unstable.
The continuous-time LQG controller used in [1] is open-loop stable and of
eighth order like the plant.  This eighth-order controller shall be reduced by
frequency-weighted singular perturbation approximation (SPA).
The major aim of this reduction is the preservation of the closed-loop
transfer function.  This means that the error in approximation of the
controller @var{K} by the reduced-order controller @var{Kr} is minimized by
@iftex
@tex
$$\underset{K_r}{\min} \ || W \ (K - K_r) \ V ||_{\infty}$$
@end tex
@end iftex
@ifnottex
@example
min ||W (K-Kr) V||
Kr               inf
@end example
@end ifnottex
where weights @var{W} and @var{V} are dictated by the requirement to preserve
(as far as possible) the closed-loop transfer function.  In minimizing the
error, they cause the approximation process for @var{K} to be more accurate at
certain frequencies.  Suggested by [1] is the use of the following stability
and performance enforcing weights:
@iftex
@tex
$$W = (I - G K)^{-1} G, \qquad V = (I - G K)^{-1}$$
@end tex
@end iftex
@ifnottex
@example
-1                      -1
W = (I - G K)   G,      V = (I - G K)
@end example
@end ifnottex
This example script reduces the eighth-order controller to orders four and two
by the function call
@code{Kr = spaconred (G, K, nr, 'feedback', '-')}
where argument @var{nr} denotes the desired order (4 or 2).  The key-value
pair @code{'feedback', '-'} allows the reduction of negative feedback
controllers while the default setting expects positive feedback controllers.
The frequency responses of the original and reduced-order controllers are
depicted in figure 1, the step responses of the closed loop in figure 2.
There is no visible difference between the step responses of the closed-loop
systems with original (blue) and fourth order (green) controllers.
The second order controller (red) causes ripples in the step response, but
otherwise the behavior of the system is unaltered.  This leads to the
conclusion that function @command{spaconred} is well suited to reduce the
order of controllers considerably, while stability and performance are
retained.
@*@strong{Reference}@*
[1] Madievski, A.G. and Anderson, B.D.O.
@cite{Sampled-Data Controller Reduction Procedure},
IEEE Transactions of Automatic Control,
Vol. 40, No. 11, November 1995
@chapter Linear Time Invariant Models
@section dss
@findex dss

@deftypefn {Function File} {@var{sys} =} dss (@var{sys})
@deftypefnx {Function File} {@var{sys} =} dss (@var{d})
@deftypefnx {Function File} {@var{sys} =} dss (@var{a}, @var{b}, @var{c}, @var{d}, @var{e}, @dots{})
@deftypefnx {Function File} {@var{sys} =} dss (@var{a}, @var{b}, @var{c}, @var{d}, @var{e}, @var{tsam}, @dots{})
Create or convert to descriptor state-space model.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model to be converted to state-space.
@item a
State matrix (n-by-n).
@item b
Input matrix (n-by-m).
@item c
Output matrix (p-by-n).
@item d
Feedthrough matrix (p-by-m).
@item e
Descriptor matrix (n-by-n).
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified,
a continuous-time model is assumed.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item sys
Descriptor state-space model.
@end table

@strong{Option Keys and Values}
@table @var
@item 'a', 'b', 'c', 'd', 'e'
State-space matrices.  See 'Inputs' for details.

@item 'stname'
The name of the states in @var{sys}.
Cell vector containing strings for each state.
Default names are @code{@{'x1', 'x2', ...@}}

@item 'scaled'
Logical.  If set to true, no automatic scaling is used,
e.g. for frequency response plots.

@item 'tsam'
Sampling time.  See 'Inputs' for details.

@item 'inname'
The name of the input channels in @var{sys}.
Cell vector of length m containing strings.
Default names are @code{@{'u1', 'u2', ...@}}

@item 'outname'
The name of the output channels in @var{sys}.
Cell vector of length p containing strings.
Default names are @code{@{'y1', 'y2', ...@}}

@item 'name'
String containing the name of the model.

@item 'notes'
String or cell of string containing comments.

@item 'userdata'
Any data type.
@end table

@strong{Equations}
@example
@group
.
E x = A x + B u
y = C x + D u
@end group
@end example

@seealso{ss, tf}
@end deftypefn
@section filt
@findex filt

@deftypefn {Function File} {@var{sys} =} filt (@var{num}, @var{den}, @dots{})
@deftypefnx {Function File} {@var{sys} =} filt (@var{num}, @var{den}, @var{tsam}, @dots{})
Create discrete-time transfer function model from data in DSP format.

@strong{Inputs}
@table @var
@item num
Numerator or cell of numerators.  Each numerator must be a row vector
containing the coefficients of the polynomial in ascending powers of z^-1.
num@{i,j@} contains the numerator polynomial from input j to output i.
In the SISO case, a single vector is accepted as well.
@item den
Denominator or cell of denominators.  Each denominator must be a row vector
containing the coefficients of the polynomial in ascending powers of z^-1.
den@{i,j@} contains the denominator polynomial from input j to output i.
In the SISO case, a single vector is accepted as well.
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified,
default value -1 (unspecified) is taken.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item sys
Discrete-time transfer function model.
@end table

@strong{Option Keys and Values}
@table @var
@item 'num'
Numerator.  See 'Inputs' for details.

@item 'den'
Denominator.  See 'Inputs' for details.

@item 'tfvar'
String containing the transfer function variable.

@item 'inv'
Logical.  True for negative powers of the transfer function variable.

@item 'tsam'
Sampling time.  See 'Inputs' for details.

@item 'inname'
The name of the input channels in @var{sys}.
Cell vector of length m containing strings.
Default names are @code{@{'u1', 'u2', ...@}}

@item 'outname'
The name of the output channels in @var{sys}.
Cell vector of length p containing strings.
Default names are @code{@{'y1', 'y2', ...@}}

@item 'name'
String containing the name of the model.

@item 'notes'
String or cell of string containing comments.

@item 'userdata'
Any data type.
@end table

@strong{Example}
@example
@group
3 z^-1
H(z^-1) = -------------------
1 + 4 z^-1 + 2 z^-2

octave:1> H = filt ([0, 3], [1, 4, 2])

Transfer function 'H' from input 'u1' to output ...

3 z^-1
y1:  -------------------
1 + 4 z^-1 + 2 z^-2

Sampling time: unspecified
Discrete-time model.
@end group
@end example

@seealso{tf}
@end deftypefn
@section frd
@findex frd

@deftypefn {Function File} {@var{sys} =} frd (@var{sys})
@deftypefnx {Function File} {@var{sys} =} frd (@var{sys}, @var{w})
@deftypefnx {Function File} {@var{sys} =} frd (@var{H}, @var{w}, @dots{})
@deftypefnx {Function File} {@var{sys} =} frd (@var{H}, @var{w}, @var{tsam}, @dots{})
Create or convert to frequency response data.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model to be converted to frequency response data.
If second argument @var{w} is omitted, the interesting
frequency range is calculated by the zeros and poles of @var{sys}.
@item H
Frequency response array (p-by-m-by-lw).  H(i,j,k) contains the
response from input j to output i at frequency k.  In the SISO case,
a vector (lw-by-1) or (1-by-lw) is accepted as well.
@item w
Frequencies must be in ascending order.
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified,
a continuous-time model is assumed.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item sys
Frequency response data object.
@end table

@strong{Option Keys and Values}
@table @var
@item 'H'
Frequency response array.  See 'Inputs' for details.

@item 'w'
Frequency vector.  See 'Inputs' for details.

@item 'tsam'
Sampling time.  See 'Inputs' for details.

@item 'inname'
The name of the input channels in @var{sys}.
Cell vector of length m containing strings.
Default names are @code{@{'u1', 'u2', ...@}}

@item 'outname'
The name of the output channels in @var{sys}.
Cell vector of length p containing strings.
Default names are @code{@{'y1', 'y2', ...@}}

@item 'name'
String containing the name of the model.

@item 'notes'
String or cell of string containing comments.

@item 'userdata'
Any data type.
@end table

@seealso{dss, ss, tf}
@end deftypefn
@section ss
@findex ss

@deftypefn {Function File} {@var{sys} =} ss (@var{sys})
@deftypefnx {Function File} {@var{sys} =} ss (@var{d})
@deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b})
@deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c})
@deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c}, @var{d}, @dots{})
@deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c}, @var{d}, @var{tsam}, @dots{})
Create or convert to state-space model.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model to be converted to state-space.
@item a
State matrix (n-by-n).
@item b
Input matrix (n-by-m).
@item c
Output matrix (p-by-n).
If @var{c} is empty @code{[]} or not specified, an identity matrix is assumed.
@item d
Feedthrough matrix (p-by-m).
If @var{d} is empty @code{[]} or not specified, a zero matrix is assumed.
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified, a continuous-time model is assumed.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item sys
State-space model.
@end table

@strong{Option Keys and Values}
@table @var
@item 'a', 'b', 'c', 'd', 'e'
State-space matrices.  See 'Inputs' for details.

@item 'stname'
The name of the states in @var{sys}.
Cell vector containing strings for each state.
Default names are @code{@{'x1', 'x2', ...@}}

@item 'scaled'
Logical.  If set to true, no automatic scaling is used,
e.g. for frequency response plots.

@item 'tsam'
Sampling time.  See 'Inputs' for details.

@item 'inname'
The name of the input channels in @var{sys}.
Cell vector of length m containing strings.
Default names are @code{@{'u1', 'u2', ...@}}

@item 'outname'
The name of the output channels in @var{sys}.
Cell vector of length p containing strings.
Default names are @code{@{'y1', 'y2', ...@}}

@item 'name'
String containing the name of the model.

@item 'notes'
String or cell of string containing comments.

@item 'userdata'
Any data type.
@end table

@strong{Example}
@example
@group
octave:1> a = [1 2 3; 4 5 6; 7 8 9];
octave:2> b = [10; 11; 12];
octave:3> stname = @{"V", "A", "kJ"@};
octave:4> sys = ss (a, b, [], [], "stname", stname)
@end group
@end example

@example
@group
sys.a =
V   A  kJ
V    1   2   3
A    4   5   6
kJ   7   8   9
@end group
@end example

@example
@group
sys.b =
u1
V   10
A   11
kJ  12
@end group
@end example

@example
@group
sys.c =
V   A  kJ
y1   1   0   0
y2   0   1   0
y3   0   0   1
@end group
@end example

@example
@group
sys.d =
u1
y1   0
y2   0
y3   0

Continuous-time model.
octave:5>
@end group
@end example

@seealso{tf, dss}
@end deftypefn
@section tf
@findex tf

@deftypefn {Function File} {@var{s} =} tf (@var{'s'})
@deftypefnx {Function File} {@var{z} =} tf (@var{'z'}, @var{tsam})
@deftypefnx {Function File} {@var{sys} =} tf (@var{sys})
@deftypefnx {Function File} {@var{sys} =} tf (@var{num}, @var{den}, @dots{})
@deftypefnx {Function File} {@var{sys} =} tf (@var{num}, @var{den}, @var{tsam}, @dots{})
Create or convert to transfer function model.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model to be converted to transfer function.
@item num
Numerator or cell of numerators.  Each numerator must be a row vector
containing the coefficients of the polynomial in descending powers of
the transfer function variable.
num@{i,j@} contains the numerator polynomial from input j to output i.
In the SISO case, a single vector is accepted as well.
@item den
Denominator or cell of denominators.  Each denominator must be a row vector
containing the coefficients of the polynomial in descending powers of
the transfer function variable.
den@{i,j@} contains the denominator polynomial from input j to output i.
In the SISO case, a single vector is accepted as well.
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified, a continuous-time
model is assumed.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item sys
Transfer function model.
@end table

@strong{Option Keys and Values}
@table @var
@item 'num'
Numerator.  See 'Inputs' for details.

@item 'den'
Denominator.  See 'Inputs' for details.

@item 'tfvar'
String containing the transfer function variable.

@item 'inv'
Logical.  True for negative powers of the transfer function variable.

@item 'tsam'
Sampling time.  See 'Inputs' for details.

@item 'inname'
The name of the input channels in @var{sys}.
Cell vector of length m containing strings.
Default names are @code{@{'u1', 'u2', ...@}}

@item 'outname'
The name of the output channels in @var{sys}.
Cell vector of length p containing strings.
Default names are @code{@{'y1', 'y2', ...@}}

@item 'name'
String containing the name of the model.

@item 'notes'
String or cell of string containing comments.

@item 'userdata'
Any data type.
@end table

@strong{Example}
@example
@group
octave:1> s = tf ('s');
octave:2> G = 1/(s+1)

Transfer function 'G' from input 'u1' to output ...

1
y1:  -----
s + 1

Continuous-time model.
@end group
@end example
@example
@group
octave:3> z = tf ('z', 0.2);
octave:4> H = 0.095/(z-0.9)

Transfer function 'H' from input 'u1' to output ...

0.095
y1:  -------
z - 0.9

Sampling time: 0.2 s
Discrete-time model.
@end group
@end example
@example
@group
octave:5> num = @{[1, 5, 7], [1]; [1, 7], [1, 5, 5]@};
octave:6> den = @{[1, 5, 6], [1, 2]; [1, 8, 6], [1, 3, 2]@};
octave:7> sys = tf (num, den)
@end group
@end example

@example
@group
Transfer function 'sys' from input 'u1' to output ...

s^2 + 5 s + 7
y1:  -------------
s^2 + 5 s + 6

s + 7
y2:  -------------
s^2 + 8 s + 6
@end group
@end example

@example
@group
Transfer function 'sys' from input 'u2' to output ...

1
y1:  -----
s + 2

s^2 + 5 s + 5
y2:  -------------
s^2 + 3 s + 2

Continuous-time model.
octave:8>
@end group
@end example

@seealso{filt, ss, dss}
@end deftypefn
@section zpk
@findex zpk

@deftypefn {Function File} {@var{s} =} zpk (@var{"s"})
@deftypefnx {Function File} {@var{z} =} zpk (@var{"z"}, @var{tsam})
@deftypefnx {Function File} {@var{sys} =} zpk (@var{sys})
@deftypefnx {Function File} {@var{sys} =} zpk (@var{k})
@deftypefnx {Function File} {@var{sys} =} zpk (@var{z}, @var{p}, @var{k}, @dots{})
@deftypefnx {Function File} {@var{sys} =} zpk (@var{z}, @var{p}, @var{k}, @var{tsam}, @dots{})
@deftypefnx {Function File} {@var{sys} =} zpk (@var{z}, @var{p}, @var{k}, @var{tsam}, @dots{})
Create transfer function model from zero-pole-gain data.
This is just a stop-gap compatibility wrapper since zpk
models are not yet implemented.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model to be converted to transfer function.
@item z
Cell of vectors containing the zeros for each channel.
z@{i,j@} contains the zeros from input j to output i.
In the SISO case, a single vector is accepted as well.
@item p
Cell of vectors containing the poles for each channel.
p@{i,j@} contains the poles from input j to output i.
In the SISO case, a single vector is accepted as well.
@item k
Matrix containing the gains for each channel.
k(i,j) contains the gain from input j to output i.
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified,
a continuous-time model is assumed.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item sys
Transfer function model.
@end table

@seealso{tf, ss, dss, frd}
@end deftypefn
@chapter Model Data Access
@section @@lti/dssdata
@findex dssdata

@deftypefn {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}, @var{e}, @var{tsam}] =} dssdata (@var{sys})
@deftypefnx {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}, @var{e}, @var{tsam}] =} dssdata (@var{sys}, @var{[]})
Access descriptor state-space model data.
Argument @var{sys} is not limited to descriptor state-space models.
If @var{sys} is not a descriptor state-space model, it is converted automatically.

@strong{Inputs}
@table @var
@item sys
Any type of @acronym{LTI} model.
@item []
In case @var{sys} is not a dss model (descriptor matrix @var{e} empty),
@code{dssdata (sys, [])} returns the empty element @code{e = []} whereas
@code{dssdata (sys)} returns the identity matrix @code{e = eye (size (a))}.
@end table

@strong{Outputs}
@table @var
@item a
State matrix (n-by-n).
@item b
Input matrix (n-by-m).
@item c
Measurement matrix (p-by-n).
@item d
Feedthrough matrix (p-by-m).
@item e
Descriptor matrix (n-by-n).
@item tsam
Sampling time in seconds.  If @var{sys} is a continuous-time model,
a zero is returned.
@end table
@end deftypefn
@section @@lti/filtdata
@findex filtdata

@deftypefn {Function File} {[@var{num}, @var{den}, @var{tsam}] =} filtdata (@var{sys})
@deftypefnx {Function File} {[@var{num}, @var{den}, @var{tsam}] =} filtdata (@var{sys}, @var{"vector"})
Access discrete-time transfer function data in DSP format.
Argument @var{sys} is not limited to transfer function models.
If @var{sys} is not a transfer function, it is converted automatically.

@strong{Inputs}
@table @var
@item sys
Any type of discrete-time @acronym{LTI} model.
@item "v", "vector"
For SISO models, return @var{num} and @var{den} directly as column vectors
instead of cells containing a single column vector.
@end table

@strong{Outputs}
@table @var
@item num
Cell of numerator(s).  Each numerator is a row vector
containing the coefficients of the polynomial in ascending powers of z^-1.
num@{i,j@} contains the numerator polynomial from input j to output i.
In the SISO case, a single vector is possible as well.
@item den
Cell of denominator(s).  Each denominator is a row vector
containing the coefficients of the polynomial in ascending powers of z^-1.
den@{i,j@} contains the denominator polynomial from input j to output i.
In the SISO case, a single vector is possible as well.
@item tsam
Sampling time in seconds.  If @var{tsam} is not specified, -1 is returned.
@end table
@end deftypefn
@section @@lti/frdata
@findex frdata

@deftypefn {Function File} {[@var{H}, @var{w}, @var{tsam}] =} frdata (@var{sys})
@deftypefnx {Function File} {[@var{H}, @var{w}, @var{tsam}] =} frdata (@var{sys}, @var{"vector"})
Access frequency response data.
Argument @var{sys} is not limited to frequency response data objects.
If @var{sys} is not a frd object, it is converted automatically.

@strong{Inputs}
@table @var
@item sys
Any type of @acronym{LTI} model.
@item "v", "vector"
In case @var{sys} is a SISO model, this option returns the frequency response
as a column vector (lw-by-1) instead of an array (p-by-m-by-lw).
@end table

@strong{Outputs}
@table @var
@item H
Frequency response array (p-by-m-by-lw).  H(i,j,k) contains the
response from input j to output i at frequency k.  In the SISO case,
a vector (lw-by-1) is possible as well.
@item w
Frequencies are in ascending order.
@item tsam
Sampling time in seconds.  If @var{sys} is a continuous-time model,
a zero is returned.
@end table
@end deftypefn
@section @@lti/get
@findex get

@deftypefn {Function File} {} get (@var{sys})
@deftypefnx {Function File} {@var{value} =} get (@var{sys}, @var{"property"})
Access property values of @acronym{LTI} objects.
@end deftypefn
@section @@lti/set
@findex set

@deftypefn {Function File} {} set (@var{sys})
@deftypefnx {Function File} {} set (@var{sys}, @var{"property"}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{retsys} =} set (@var{sys}, @var{"property"}, @var{value}, @dots{})
Set or modify properties of @acronym{LTI} objects.
If no return argument @var{retsys} is specified, the modified @acronym{LTI} object is stored
in input argument @var{sys}.  @command{set} can handle multiple properties in one call:
@code{set (sys, 'prop1', val1, 'prop2', val2, 'prop3', val3)}.
@code{set (sys)} prints a list of the object's property names.
@end deftypefn
@section @@lti/ssdata
@findex ssdata

@deftypefn {Function File} {[@var{a}, @var{b}, @var{c}, @var{d}, @var{tsam}] =} ssdata (@var{sys})
Access state-space model data.
Argument @var{sys} is not limited to state-space models.
If @var{sys} is not a state-space model, it is converted automatically.

@strong{Inputs}
@table @var
@item sys
Any type of @acronym{LTI} model.
@end table

@strong{Outputs}
@table @var
@item a
State matrix (n-by-n).
@item b
Input matrix (n-by-m).
@item c
Measurement matrix (p-by-n).
@item d
Feedthrough matrix (p-by-m).
@item tsam
Sampling time in seconds.  If @var{sys} is a continuous-time model,
a zero is returned.
@end table
@end deftypefn
@section @@lti/tfdata
@findex tfdata

@deftypefn {Function File} {[@var{num}, @var{den}, @var{tsam}] =} tfdata (@var{sys})
@deftypefnx {Function File} {[@var{num}, @var{den}, @var{tsam}] =} tfdata (@var{sys}, @var{"vector"})
@deftypefnx {Function File} {[@var{num}, @var{den}, @var{tsam}] =} tfdata (@var{sys}, @var{"tfpoly"})
Access transfer function data.
Argument @var{sys} is not limited to transfer function models.
If @var{sys} is not a transfer function, it is converted automatically.

@strong{Inputs}
@table @var
@item sys
Any type of @acronym{LTI} model.
@item "v", "vector"
For SISO models, return @var{num} and @var{den} directly as column vectors
instead of cells containing a single column vector.
@end table

@strong{Outputs}
@table @var
@item num
Cell of numerator(s).  Each numerator is a row vector
containing the coefficients of the polynomial in descending powers of
the transfer function variable.
num@{i,j@} contains the numerator polynomial from input j to output i.
In the SISO case, a single vector is possible as well.
@item den
Cell of denominator(s).  Each denominator is a row vector
containing the coefficients of the polynomial in descending powers of
the transfer function variable.
den@{i,j@} contains the denominator polynomial from input j to output i.
In the SISO case, a single vector is possible as well.
@item tsam
Sampling time in seconds.  If @var{sys} is a continuous-time model,
a zero is returned.
@end table
@end deftypefn
@section @@lti/zpkdata
@findex zpkdata

@deftypefn {Function File} {[@var{z}, @var{p}, @var{k}, @var{tsam}] =} zpkdata (@var{sys})
@deftypefnx {Function File} {[@var{z}, @var{p}, @var{k}, @var{tsam}] =} zpkdata (@var{sys}, @var{"v"})
Access zero-pole-gain data.

@strong{Inputs}
@table @var
@item sys
Any type of @acronym{LTI} model.
@item "v", "vector"
For SISO models, return @var{z} and @var{p} directly as column vectors
instead of cells containing a single column vector.
@end table

@strong{Outputs}
@table @var
@item z
Cell of column vectors containing the zeros for each channel.
z@{i,j@} contains the zeros from input j to output i.
@item p
Cell of column vectors containing the poles for each channel.
p@{i,j@} contains the poles from input j to output i.
@item k
Matrix containing the gains for each channel.
k(i,j) contains the gain from input j to output i.
@item tsam
Sampling time in seconds.  If @var{sys} is a continuous-time model,
a zero is returned.
@end table
@end deftypefn
@chapter Model Conversions
@section @@lti/c2d
@findex c2d

@deftypefn {Function File} {@var{sys} =} c2d (@var{sys}, @var{tsam})
@deftypefnx {Function File} {@var{sys} =} c2d (@var{sys}, @var{tsam}, @var{method})
@deftypefnx {Function File} {@var{sys} =} c2d (@var{sys}, @var{tsam}, @var{'prewarp'}, @var{w0})
Convert the continuous @acronym{LTI} model into its discrete-time equivalent.

@strong{Inputs}
@table @var
@item sys
Continuous-time @acronym{LTI} model.
@item tsam
Sampling time in seconds.
@item method
Optional conversion method.  If not specified, default method @var{"zoh"}
is taken.
@table @var
@item 'zoh'
Zero-order hold or matrix exponential.
@item 'tustin', 'bilin'
Bilinear transformation or Tustin approximation.
@item 'prewarp'
Bilinear transformation with pre-warping at frequency @var{w0}.
@item 'matched'
Matched pole/zero method.
@end table
@end table

@strong{Outputs}
@table @var
@item sys
Discrete-time @acronym{LTI} model.
@end table
@end deftypefn
@section @@lti/d2c
@findex d2c

@deftypefn {Function File} {@var{sys} =} d2c (@var{sys})
@deftypefnx {Function File} {@var{sys} =} d2c (@var{sys}, @var{method})
@deftypefnx {Function File} {@var{sys} =} d2c (@var{sys}, @var{'prewarp'}, @var{w0})
Convert the discrete @acronym{LTI} model into its continuous-time equivalent.

@strong{Inputs}
@table @var
@item sys
Discrete-time @acronym{LTI} model.
@item method
Optional conversion method.  If not specified, default method @var{"zoh"}
is taken.
@table @var
@item 'zoh'
Zero-order hold or matrix logarithm.
@item 'tustin', 'bilin'
Bilinear transformation or Tustin approximation.
@item 'prewarp'
Bilinear transformation with pre-warping at frequency @var{w0}.
@item 'matched'
Matched pole/zero method.
@end table
@end table

@strong{Outputs}
@table @var
@item sys
Continuous-time @acronym{LTI} model.
@end table
@end deftypefn
@section @@lti/prescale
@findex prescale

@deftypefn {Function File} {[@var{scaledsys}, @var{info}] =} prescale (@var{sys})
Scale state-space model.  The scaled model @var{scaledsys} is equivalent to
@var{sys}, but the state vector is scaled by diagonal transformation matrices
in order to increase the accuracy of subsequent numerical computations.
Frequency response commands perform automatic scaling unless model property
@var{scaled} is set to @var{true}.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@end table

@strong{Outputs}
@table @var
@item scaledsys
Scaled state-space model.
@item info
@item info.SL
Left scaling factors.  @code{Tl = diag (info.SL)}.
@item info.SR
Right scaling factors.  @code{Tr = diag (info.SR)}.
@end table

@strong{Equations}
@example
@group
Es = Tl * E * Tr
As = Tl * A * Tr
Bs = Tl * B
Cs =      C * Tr
Ds =      D
@end group
@end example

For proper state-space models, @var{Tl} and @var{Tr} are inverse of each other.

@strong{Algorithm}@*
Uses SLICOT TB01ID and TG01AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}.
@end deftypefn
@section @@lti/xperm
@findex xperm

@deftypefn {Function File} {@var{sys} =} xperm (@var{sys}, @var{st_idx})
Reorder states in state-space models.
@end deftypefn
@chapter Model Interconnections
@section @@lti/append
@findex append

@deftypefn {Function File} {@var{sys} =} append (@var{sys1}, @var{sys2})
Group @acronym{LTI} models by appending their inputs and outputs.
@end deftypefn
@section @@lti/blkdiag
@findex blkdiag

@deftypefn {Function File} {@var{sys} =} blkdiag (@var{sys1}, @var{sys2})
Block-diagonal concatenation of @acronym{LTI} models.
@end deftypefn
@section @@lti/connect
@findex connect

@deftypefn {Function File} {@var{sys} =} connect (@var{sys}, @var{cm}, @var{inputs}, @var{outputs})
Arbitrary interconnections between the inputs and outputs of an @acronym{LTI} model.
@end deftypefn
@section @@lti/feedback
@findex feedback

@deftypefn {Function File} {@var{sys} =} feedback (@var{sys1})
@deftypefnx {Function File} {@var{sys} =} feedback (@var{sys1}, @var{"+"})
@deftypefnx {Function File} {@var{sys} =} feedback (@var{sys1}, @var{sys2})
@deftypefnx {Function File} {@var{sys} =} feedback (@var{sys1}, @var{sys2}, @var{"+"})
@deftypefnx {Function File} {@var{sys} =} feedback (@var{sys1}, @var{sys2}, @var{feedin}, @var{feedout})
@deftypefnx {Function File} {@var{sys} =} feedback (@var{sys1}, @var{sys2}, @var{feedin}, @var{feedout}, @var{"+"})
Feedback connection of two @acronym{LTI} models.

@strong{Inputs}
@table @var
@item sys1
@acronym{LTI} model of forward transmission.  @code{[p1, m1] = size (sys1)}.
@item sys2
@acronym{LTI} model of backward transmission.
If not specified, an identity matrix of appropriate size is taken.
@item feedin
Vector containing indices of inputs to @var{sys1} which are involved in the feedback loop.
The number of @var{feedin} indices and outputs of @var{sys2} must be equal.
If not specified, @code{1:m1} is taken.
@item feedout
Vector containing indices of outputs from @var{sys1} which are to be connected to @var{sys2}.
The number of @var{feedout} indices and inputs of @var{sys2} must be equal.
If not specified, @code{1:p1} is taken.
@item "+"
Positive feedback sign.  If not specified, @var{"-"} for a negative feedback interconnection
is assumed.  @var{+1} and @var{-1} are possible as well, but only from the third argument
onward due to ambiguity.
@end table

@strong{Outputs}
@table @var
@item sys
Resulting @acronym{LTI} model.
@end table

@strong{Block Diagram}
@example
@group
u    +         +--------+             y
------>(+)----->|  sys1  |-------+------->
^ -     +--------+       |
|                        |
|       +--------+       |
+-------|  sys2  |<------+
+--------+
@end group
@end example
@end deftypefn
@section @@lti/lft
@findex lft

@deftypefn {Function File} {@var{sys} =} lft (@var{sys1}, @var{sys2})
@deftypefnx {Function File} {@var{sys} =} lft (@var{sys1}, @var{sys2}, @var{nu}, @var{ny})
Linear fractional tranformation, also known as Redheffer star product.

@strong{Inputs}
@table @var
@item sys1
Upper @acronym{LTI} model.
@item sys2
Lower @acronym{LTI} model.
@item nu
The last nu inputs of @var{sys1} are connected with the first nu outputs of @var{sys2}.
If not specified, @code{min (m1, p2)} is taken.
@item ny
The last ny outputs of @var{sys1} are connected with the first ny inputs of @var{sys2}.
If not specified, @code{min (p1, m2)} is taken.
@end table

@strong{Outputs}
@table @var
@item sys
Resulting @acronym{LTI} model.
@end table

@strong{Block Diagram}
@example
@group
.............sys..............
:         +--------+         :
w1 ------------>|        |------------> z1
:         |  sys1  |         :
: u +---->|        |-----+ y :
:   |     +--------+     |   :          Lower LFT
:   |                    |   :
:   |     +--------+     |   :          lft (sys1, sys2)
:   +-----|  sys2  |<----+   :
:         +--------+         :
:............................:
@end group
@end example
@example
@group
.............sys..............
:         +--------+         :
: u +---->|  sys1  |-----+ y :
:   |     +--------+     |   :          Upper LFT
:   |                    |   :
:   |     +--------+     |   :          lft (sys1, sys2)
:   +-----|        |<----+   :
:         |  sys2  |         :
z2 <------------|        |<------------ w2
:         +--------+         :
:............................:
@end group
@end example
@example
@group
.............sys..............
:         +--------+         :
w1 ------------>|        |------------> z1
:         |  sys1  |         :
: u +---->|        |-----+ y :
:   |     +--------+     |   :
:   |                    |   :          lft (sys1, sys2, nu, ny)
:   |     +--------+     |   :
:   +-----|        |<----+   :
:         |  sys2  |         :
z2 <------------|        |<------------ w2
:         +--------+         :
:............................:
@end group
@end example
@end deftypefn
@section @@lti/mconnect
@findex mconnect

@deftypefn {Function File} {@var{sys} =} mconnect (@var{sys}, @var{m})
@deftypefnx {Function File} {@var{sys} =} mconnect (@var{sys}, @var{m}, @var{inputs}, @var{outputs})
Arbitrary interconnections between the inputs and outputs of an @acronym{LTI} model.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@item m
Connection matrix.  Each row belongs to an input and each column represents an output.
@item inputs
Vector of indices of those inputs which are retained.  If not specified, all inputs are kept.
@item outputs
Vector of indices of those outputs which are retained.  If not specified, all outputs are kept.
@end table

@strong{Outputs}
@table @var
@item sys
Interconnected system.
@end table

@strong{Example}
@example
@group
Solve the system equations of
y(t) = G e(t)
e(t) = u(t) + M y(t)
in order to build
y(t) = H u(t)
The matrix M for a (p-by-m) system G
has m rows and p columns (m-by-p).

Example for a 3x2 system:
u1 = -1*y1 + 5*y2 + 0*y3
u2 = pi*y1 + 0*y2 - 7*y3

| -1      5      0 |
M = | pi      0      7 |
@end group
@end example
@end deftypefn
@section @@lti/parallel
@findex parallel

@deftypefn{Function File} {@var{sys} =} parallel (@var{sys1}, @var{sys2})
Parallel connection of two @acronym{LTI} systems.

@strong{Block Diagram}
@example
@group
..........................
:      +--------+        :
:  +-->|  sys1  |---+    :
u  :  |   +--------+   | +  :  y
-------+                O--------->
:  |   +--------+   | +  :
:  +-->|  sys2  |---+    :
:      +--------+        :
:.........sys............:

sys = parallel (sys1, sys2)
@end group
@end example
@end deftypefn
@section @@lti/series
@findex series

@deftypefn {Function File} {@var{sys} =} series (@var{sys1}, @var{sys2})
@deftypefnx {Function File} {@var{sys} =} series (@var{sys1}, @var{sys2}, @var{outputs1}, @var{inputs2})
Series connection of two @acronym{LTI} models.

@strong{Block Diagram}
@example
@group
.....................................
u  :  +--------+ y1    u2  +--------+  :  y
------>|  sys1  |---------->|  sys2  |------->
:  +--------+           +--------+  :
:................sys.................

sys = series (sys1, sys2)
@end group
@end example
@example
@group
.....................................
:                   v2  +--------+  :
:            ---------->|        |  :  y
:  +--------+ y1    u2  |  sys2  |------->
u  :  |        |---------->|        |  :
------>|  sys1  |       z1  +--------+  :
:  |        |---------->            :
:  +--------+                       :
:................sys.................

outputs1 = [1]
inputs2 = [2]
sys = series (sys1, sys2, outputs1, inputs2)
@end group
@end example
@end deftypefn
@chapter Model Characteristics
@section ctrb
@findex ctrb

@deftypefn {Function File} {@var{co} =} ctrb (@var{sys})
@deftypefnx {Function File} {@var{co} =} ctrb (@var{a}, @var{b})
Return controllability matrix.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item a
State matrix (n-by-n).
@item b
Input matrix (n-by-m).
@end table

@strong{Outputs}
@table @var
@item co
Controllability matrix.
@end table

@strong{Equation}
@iftex
@tex
$$C_o = [ B \ \ AB \ \ A^2B \ \ldots \ A^{n-1}B ]$$
@end tex
@end iftex
@ifnottex
@example
2       n-1
Co = [ B AB A B ... A   B ]
@end example
@end ifnottex
@end deftypefn
@section ctrbf
@findex ctrbf

@deftypefn{Function File} {[@var{sysbar}, @var{T}, @var{K}] =} ctrbf (@var{sys})
@deftypefnx{Function File} {[@var{sysbar}, @var{T}, @var{K}] =} ctrbf (@var{sys}, @var{tol})
@deftypefnx{Function File} {[@var{Abar}, @var{Bbar}, @var{Cbar}, @var{T}, @var{K}] =} ctrbf (@var{A}, @var{B}, @var{C})
@deftypefnx{Function File} {[@var{Abar}, @var{Bbar}, @var{Cbar}, @var{T}, @var{K}] =} ctrbf (@var{A}, @var{B}, @var{C}, @var{TOL})
If Co=ctrb(A,B) has rank r <= n = SIZE(A,1), then there is a
similarity transformation Tc such that Tc = [t1 t2] where t1
is the controllable subspace and t2 is orthogonal to t1

@example
@group
Abar = Tc \ A * Tc ,  Bbar = Tc \ B ,  Cbar = C * Tc
@end group
@end example

and the transformed system has the form

@example
@group
| Ac    A12|           | Bc |
Abar = |----------|,   Bbar = | ---|,  Cbar = [Cc | Cnc].
| 0     Anc|           |  0 |
@end group
@end example

where (Ac,Bc) is controllable, and Cc(sI-Ac)^(-1)Bc = C(sI-A)^(-1)B.
and the system is stabilizable if Anc has no eigenvalues in
the right half plane. The last output K is a vector of length n
containing the number of controllable states.
@end deftypefn
@section @@lti/dcgain
@findex dcgain

@deftypefn {Function File} {@var{k} =} dcgain (@var{sys})
DC gain of @acronym{LTI} model.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@end table

@strong{Outputs}
@table @var
@item k
DC gain matrice.  For a system with m inputs and p outputs, the array @var{k}
has dimensions [p, m].
@end table

@seealso{freqresp}
@end deftypefn
@section gram
@findex gram

@deftypefn {Function File} {@var{W} =} gram (@var{sys}, @var{mode})
@deftypefnx {Function File} {@var{Wc} =} gram (@var{a}, @var{b})
@code{gram (@var{sys}, "c")} returns the controllability gramian of
the (continuous- or discrete-time) system @var{sys}.
@code{gram (@var{sys}, "o")} returns the observability gramian of the
(continuous- or discrete-time) system @var{sys}.
@code{gram (@var{a}, @var{b})} returns the controllability gramian
@var{Wc} of the continuous-time system @math{dx/dt = a x + b u};
i.e., @var{Wc} satisfies @math{a Wc + m Wc' + b b' = 0}.

@end deftypefn
@section hsvd
@findex hsvd

@deftypefn{Function File} {@var{hsv} =} hsvd (@var{sys})
@deftypefnx{Function File} {@var{hsv} =} hsvd (@var{sys}, @var{"offset"}, @var{offset})
@deftypefnx{Function File} {@var{hsv} =} hsvd (@var{sys}, @var{"alpha"}, @var{alpha})
Hankel singular values of the stable part of an @acronym{LTI} model.  If no output arguments are
given, the Hankel singular values are displayed in a plot.

@strong{Algorithm}@*
Uses SLICOT AB13AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section @@lti/isct
@findex isct

@deftypefn {Function File} {@var{bool} =} isct (@var{sys})
Determine whether @acronym{LTI} model is a continuous-time system.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@end table

@strong{Outputs}
@table @var
@item bool = 0
@var{sys} is a discrete-time system.
@item bool = 1
@var{sys} is a continuous-time system or a static gain.
@end table
@end deftypefn
@section isctrb
@findex isctrb

@deftypefn {Function File} {[@var{bool}, @var{ncon}] =} isctrb (@var{sys})
@deftypefnx {Function File} {[@var{bool}, @var{ncon}] =} isctrb (@var{sys}, @var{tol})
@deftypefnx {Function File} {[@var{bool}, @var{ncon}] =} isctrb (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{bool}, @var{ncon}] =} isctrb (@var{a}, @var{b}, @var{e})
@deftypefnx {Function File} {[@var{bool}, @var{ncon}] =} isctrb (@var{a}, @var{b}, @var{[]}, @var{tol})
@deftypefnx {Function File} {[@var{bool}, @var{ncon}] =} isctrb (@var{a}, @var{b}, @var{e}, @var{tol})
Logical check for system controllability.
For numerical reasons, @code{isctrb (sys)}
should be used instead of @code{rank (ctrb (sys))}.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.  Descriptor state-space models are possible.
If @var{sys} is not a state-space model, it is converted to
a minimal state-space realization, so beware of pole-zero
cancellations which may lead to wrong results!
@item a
State matrix (n-by-n).
@item b
Input matrix (n-by-m).
@item e
Descriptor matrix (n-by-n).
If @var{e} is empty @code{[]} or not specified, an identity matrix is assumed.
@item tol
Optional roundoff parameter.  Default value is 0.
@end table

@strong{Outputs}
@table @var
@item bool = 0
System is not controllable.
@item bool = 1
System is controllable.
@item ncon
Number of controllable states.
@end table

@strong{Algorithm}@*
Uses SLICOT AB01OD and TG01HD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{isobsv}
@end deftypefn
@section isdetectable
@findex isdetectable

@deftypefn {Function File} {@var{bool} =} isdetectable (@var{sys})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{sys}, @var{tol})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{e})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{[]}, @var{tol})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{e}, @var{tol})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{[]}, @var{[]}, @var{dflg})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{e}, @var{[]}, @var{dflg})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{[]}, @var{tol}, @var{dflg})
@deftypefnx {Function File} {@var{bool} =} isdetectable (@var{a}, @var{c}, @var{e}, @var{tol}, @var{dflg})
Logical test for system detectability.
All unstable modes must be observable or all unobservable states must be stable.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@item a
State transition matrix.
@item c
Measurement matrix.
@item e
Descriptor matrix.
If @var{e} is empty @code{[]} or not specified, an identity matrix is assumed.
@item tol
Optional tolerance for stability.  Default value is 0.
@item dflg = 0
Matrices (@var{a}, @var{c}) are part of a continuous-time system.  Default Value.
@item dflg = 1
Matrices (@var{a}, @var{c}) are part of a discrete-time system.
@end table

@strong{Outputs}
@table @var
@item bool = 0
System is not detectable.
@item bool = 1
System is detectable.
@end table

@strong{Algorithm}@*
Uses SLICOT AB01OD and TG01HD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
See @command{isstabilizable} for description of computational method.
@seealso{isstabilizable, isstable, isctrb, isobsv}
@end deftypefn
@section @@lti/isdt
@findex isdt

@deftypefn {Function File} {@var{bool} =} isdt (@var{sys})
Determine whether acronym{LTI} model is a discrete-time system.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@end table

@strong{Outputs}
@table @var
@item bool = 0
@var{sys} is a continuous-time system.
@item bool = 1
@var{sys} is a discrete-time system or a static gain.
@end table
@end deftypefn
@section @@lti/isminimumphase
@findex isminimumphase

@deftypefn {Function File} {@var{bool} =} isminimumphase (@var{sys})
@deftypefnx {Function File} {@var{bool} =} isminimumphase (@var{sys}, @var{tol})
Determine whether @acronym{LTI} system is minimum phase.
The zeros must lie in the left complex half-plane.
The name minimum-phase refers to the fact that such a system has the
minimum possible phase lag for the given magnitude response |sys(jw)|.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@item tol
Optional tolerance.  Default value is 0.
@end table

@strong{Outputs}
@table @var
@item bool = 0
System is not minimum phase.
@item bool = 1
System is minimum phase.
@end table

@example
@group
real (z) < -tol*(1 + abs (z))    continuous-time
abs (z) < 1 - tol                discrete-time
@end group
@end example
@end deftypefn
@section isobsv
@findex isobsv

@deftypefn {Function File} {[@var{bool}, @var{nobs}] =} isobsv (@var{sys})
@deftypefnx {Function File} {[@var{bool}, @var{nobs}] =} isobsv (@var{sys}, @var{tol})
@deftypefnx {Function File} {[@var{bool}, @var{nobs}] =} isobsv (@var{a}, @var{c})
@deftypefnx {Function File} {[@var{bool}, @var{nobs}] =} isobsv (@var{a}, @var{c}, @var{e})
@deftypefnx {Function File} {[@var{bool}, @var{nobs}] =} isobsv (@var{a}, @var{c}, @var{[]}, @var{tol})
@deftypefnx {Function File} {[@var{bool}, @var{nobs}] =} isobsv (@var{a}, @var{c}, @var{e}, @var{tol})
Logical check for system observability.
For numerical reasons, @code{isobsv (sys)}
should be used instead of @code{rank (obsv (sys))}.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.  Descriptor state-space models are possible.
@item a
State matrix (n-by-n).
@item c
Measurement matrix (p-by-n).
@item e
Descriptor matrix (n-by-n).
If @var{e} is empty @code{[]} or not specified, an identity matrix is assumed.
@item tol
Optional roundoff parameter.  Default value is 0.
@end table

@strong{Outputs}
@table @var
@item bool = 0
System is not observable.
@item bool = 1
System is observable.
@item nobs
Number of observable states.
@end table

@strong{Algorithm}@*
Uses SLICOT AB01OD and TG01HD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{isctrb}
@end deftypefn
@section @@lti/issiso
@findex issiso

@deftypefn {Function File} {@var{bool} =} issiso (@var{sys})
Determine whether @acronym{LTI} model is single-input/single-output (SISO).
@end deftypefn
@section isstabilizable
@findex isstabilizable

@deftypefn {Function File} {@var{bool} =} isstabilizable (@var{sys})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{sys}, @var{tol})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{e})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{[]}, @var{tol})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{e}, @var{tol})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{[]}, @var{[]}, @var{dflg})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{e}, @var{[]}, @var{dflg})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{[]}, @var{tol}, @var{dflg})
@deftypefnx {Function File} {@var{bool} =} isstabilizable (@var{a}, @var{b}, @var{e}, @var{tol}, @var{dflg})
Logical check for system stabilizability.
All unstable modes must be controllable or all uncontrollable states must be stable.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.  If @var{sys} is not a state-space system, it is converted to
a minimal state-space realization, so beware of pole-zero cancellations
which may lead to wrong results!
@item a
State transition matrix.
@item b
Input matrix.
@item e
Descriptor matrix.
If @var{e} is empty @code{[]} or not specified, an identity matrix is assumed.
@item tol
Optional tolerance for stability.  Default value is 0.
@item dflg = 0
Matrices (@var{a}, @var{b}) are part of a continuous-time system.  Default Value.
@item dflg = 1
Matrices (@var{a}, @var{b}) are part of a discrete-time system.
@end table

@strong{Outputs}
@table @var
@item bool = 0
System is not stabilizable.
@item bool = 1
System is stabilizable.
@end table

@strong{Algorithm}@*
Uses SLICOT AB01OD and TG01HD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@example
@group
* Calculate staircase form (SLICOT AB01OD)
* Extract unobservable part of state transition matrix
* Calculate eigenvalues of unobservable part
* Check whether
real (ev) < -tol*(1 + abs (ev))   continuous-time
abs (ev) < 1 - tol                discrete-time
@end group
@end example
@seealso{isdetectable, isstable, isctrb, isobsv}
@end deftypefn
@section @@lti/isstable
@findex isstable

@deftypefn {Function File} {@var{bool} =} isstable (@var{sys})
@deftypefnx {Function File} {@var{bool} =} isstable (@var{sys}, @var{tol})
Determine whether @acronym{LTI} system is stable.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@item tol
Optional tolerance for stability.  Default value is 0.
@end table

@strong{Outputs}
@table @var
@item bool = 0
System is not stable.
@item bool = 1
System is stable.
@end table

@example
@group
real (p) < -tol*(1 + abs (p))    continuous-time
abs (p) < 1 - tol                discrete-time
@end group
@end example
@end deftypefn
@section @@lti/norm
@findex norm

@deftypefn {Function File} {@var{gain} =} norm (@var{sys}, @var{2})
@deftypefnx {Function File} {[@var{gain}, @var{wpeak}] =} norm (@var{sys}, @var{inf})
@deftypefnx {Function File} {[@var{gain}, @var{wpeak}] =} norm (@var{sys}, @var{inf}, @var{tol})
Return H-2 or L-inf norm of @acronym{LTI} model.

@strong{Algorithm}@*
Uses SLICOT AB13BD and AB13DD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section obsv
@findex obsv

@deftypefn {Function File} {@var{ob} =} obsv (@var{sys})
@deftypefnx {Function File} {@var{ob} =} obsv (@var{a}, @var{c})
Return observability matrix.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item a
State matrix (n-by-n).
@item c
Measurement matrix (p-by-n).
@end table

@strong{Outputs}
@table @var
@item ob
Observability matrix.
@end table

@strong{Equation}
@iftex
@tex
$$O_b = \left[ \matrix{ C \cr CA \cr CA^2 \cr \vdots \cr CA^{n-1} } \right ]$$
@end tex
@end iftex
@ifnottex
@example
@group
| C        |
| CA       |
Ob = | CA^2     |
| ...      |
| CA^(n-1) |
@end group
@end example
@end ifnottex
@end deftypefn
@section obsvf
@findex obsvf

@deftypefn{Function File} {[@var{sysbar}, @var{T}, @var{K}] =} obsvf (@var{sys})
@deftypefnx{Function File} {[@var{sysbar}, @var{T}, @var{K}] =} obsvf (@var{sys}, @var{tol})
@deftypefnx{Function File} {[@var{Abar}, @var{Bbar}, @var{Cbar}, @var{T}, @var{K}] =} obsvf (@var{A}, @var{B}, @var{C})
@deftypefnx{Function File} {[@var{Abar}, @var{Bbar}, @var{Cbar}, @var{T}, @var{K}] =} obsvf (@var{A}, @var{B}, @var{C}, @var{TOL})
If Ob=obsv(A,C) has rank r <= n = SIZE(A,1), then there is a
similarity transformation Tc such that To = [t1;t2] where t1 is c
and t2 is orthogonal to t1

@example
@group
Abar = To \ A * To ,  Bbar = To \ B ,  Cbar = C * To
@end group
@end example

and the transformed system has the form

@example
@group
| Ao     0 |           | Bo  |
Abar = |----------|,   Bbar = | --- |,  Cbar = [Co | 0 ].
| A21   Ano|           | Bno |
@end group
@end example

where (Ao,Bo) is observable, and Co(sI-Ao)^(-1)Bo = C(sI-A)^(-1)B. And
system is detectable if Ano has no eigenvalues in the right
half plane. The last output K is a vector of length n containing the
number of observable states.
@end deftypefn
@section @@lti/pole
@findex pole

@deftypefn {Function File} {@var{p} =} pole (@var{sys})
Compute poles of @acronym{LTI} system.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@end table

@strong{Outputs}
@table @var
@item p
Poles of @var{sys}.
@end table

@strong{Algorithm}@*
For (descriptor) state-space models, @command{pole}
relies on Octave's @command{eig}.
For @acronym{SISO} transfer functions, @command{pole}
uses Octave's @command{roots}.
@acronym{MIMO} transfer functions are converted to
a @emph{minimal} state-space representation for the
computation of the poles.

@end deftypefn
@section pzmap
@findex pzmap

@deftypefn {Function File} {} pzmap (@var{sys})
@deftypefnx {Function File} {} pzmap (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx {Function File} {} pzmap (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx {Function File} {[@var{p}, @var{z}] =} pzmap (@var{sys})
Plot the poles and zeros of an LTI system in the complex plane.
If no output arguments are given, the result is plotted on the screen.
Otherwise, the poles and zeros are computed and returned.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item p
Poles of @var{sys}.
@item z
Transmission zeros of @var{sys}.
@end table
@end deftypefn
@section @@lti/size
@findex size

@deftypefn {Function File} {@var{nvec} =} size (@var{sys})
@deftypefnx {Function File} {@var{n} =} size (@var{sys}, @var{dim})
@deftypefnx {Function File} {[@var{p}, @var{m}] =} size (@var{sys})
@acronym{LTI} model size, i.e. number of outputs and inputs.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@item dim
If given a second argument, @command{size} will return the size of the
corresponding dimension.
@end table

@strong{Outputs}
@table @var
@item nvec
Row vector.  The first element is the number of outputs (rows) and the second
element the number of inputs (columns).
@item n
Scalar value.  The size of the dimension @var{dim}.
@item p
Number of outputs.
@item m
Number of inputs.
@end table
@end deftypefn
@section @@lti/zero
@findex zero

@deftypefn {Function File} {@var{z} =} zero (@var{sys})
@deftypefnx {Function File} {@var{z} =} zero (@var{sys}, @var{type})
@deftypefnx {Function File} {[@var{z}, @var{k}, @var{info}] =} zero (@var{sys})
Compute zeros and gain of @acronym{LTI} model.
By default, @command{zero} computes the invariant zeros,
also known as Smith zeros.  Alternatively, when called with
a second input argument, @command{zero} can also compute
the system zeros, transmission zeros, input decoupling zeros
and output decoupling zeros.  See paper [1] for an explanation
of the various zero flavors as well as for further details.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item type
String specifying the type of zeros:
@table @var
@item 'system', 's'
Compute the system zeros.
The system zeros include in all cases
(square, non-square, degenerate or non-degenerate system)
all transmission and decoupling zeros.
@item 'invariant', 'inv'
Compute invariant zeros.  Default selection.
@item 'transmission', 't'
Compute transmission zeros.  Transmission zeros
are a subset of the invariant zeros.
The transmission zeros are the zeros of the
Smith-McMillan form of the transfer function matrix.
@item 'input', 'inp', 'id'
Compute input decoupling zeros.  The input decoupling zeros are
also known as the uncontrollable eigenvalues of the pair (A,B).
@item 'output', 'o', 'od'
Compute output decoupling zeros.  The output decoupling zeros are
also known as the unobservable eigenvalues of the pair (A,C).
@end table
@end table

@strong{Outputs}
@table @var
@item z
Depending on argument @var{type}, @var{z} contains the
invariant (default), system, transmission, input decoupling
or output decoupling zeros of @var{sys} as defined in [1].
@item k
Gain of @acronym{SISO} system @var{sys}.  For @acronym{MIMO}
systems, an empty matrix @code{[]} is returned.
@item info
Struct containing additional information.  For details,
see the documentation of @acronym{SLICOT} routines
@acronym{AB08ND} and @acronym{AG08BD}.
@item info.rank
The normal rank of the transfer function matrix (regular state-space models)
or of the system pencil (descriptor state-space models).
@item info.infz
Contains information on the infinite elementary divisors as follows:
the system has info.infz(i) infinite elementary divisors of degree i,
where i=1,2,...,length(info.infz).
@item info.kronr
Right Kronecker (column) indices.
@item info.kronl
Left Kronecker (row) indices.
@end table

@strong{Examples}
@example
@group
[z, k, info] = zero (sys)        # invariant zeros
z = zero (sys, 'system')         # system zeros
z = zero (sys, 'invariant')      # invariant zeros
z = zero (sys, 'transmission')   # transmission zeros
z = zero (sys, 'output')         # output decoupling zeros
z = zero (sys, 'input')          # input decoupling zeros
@end group
@end example

@strong{Algorithm}@*
For (descriptor) state-space models, @command{zero}
relies on SLICOT AB08ND and AG08BD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
For @acronym{SISO} transfer functions, @command{zero}
uses Octave's @command{roots}.
@acronym{MIMO} transfer functions are converted to
a @emph{minimal} state-space representation for the
computation of the zeros.

@strong{References}@*
[1] MacFarlane, A. and Karcanias, N.
@cite{Poles and zeros of linear multivariable systems:
a survey of the algebraic, geometric and complex-variable
theory}.  Int. J. Control, vol. 24, pp. 33-74, 1976.@*
[2] Rosenbrock, H.H.
@cite{Correction to 'The zeros of a system'}.
Int. J. Control, vol. 20, no. 3, pp. 525-527, 1974.@*
[3] Svaricek, F.
@cite{Computation of the structural invariants of linear
multivariable systems with an extended version of the
program ZEROS}.
Systems & Control Letters, vol. 6, pp. 261-266, 1985.@*
[4] Emami-Naeini, A. and Van Dooren, P.
@cite{Computation of zeros of linear multivariable systems}.
Automatica, vol. 26, pp. 415-430, 1982.@*

@end deftypefn
@chapter Model Simplification
@section @@lti/minreal
@findex minreal

@deftypefn {Function File} {@var{sys} =} minreal (@var{sys})
@deftypefnx {Function File} {@var{sys} =} minreal (@var{sys}, @var{tol})
Minimal realization or zero-pole cancellation of @acronym{LTI} models.
@end deftypefn
@section @@lti/sminreal
@findex sminreal

@deftypefn {Function File} {@var{sys} =} sminreal (@var{sys})
@deftypefnx {Function File} {@var{sys} =} sminreal (@var{sys}, @var{tol})
Perform state-space model reduction based on structure.
Remove states which have no influence on the input-output behaviour.
The physical meaning of the states is retained.

@strong{Inputs}
@table @var
@item sys
State-space model.
@item tol
Optional tolerance for controllability and observability.
Entries of the state-space matrices whose moduli are less or equal to @var{tol}
are assumed to be zero.  Default value is 0.
@end table

@strong{Outputs}
@table @var
@item sys
Reduced state-space model.
@end table

@seealso{minreal}
@end deftypefn
@chapter Time Domain Analysis
@section covar
@findex covar

@deftypefn{Function File} {[@var{p}, @var{q}] =} covar (@var{sys}, @var{w})

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item w
Intensity of Gaussian white noise inputs which drive @var{sys}.
@end table

@strong{Outputs}
@table @var
@item p
Output covariance.
@item q
State covariance.
@end table

@seealso{lyap, dlyap}
@end deftypefn
@section gensig
@findex gensig

@deftypefn{Function File} {[@var{u}, @var{t}] =} gensig (@var{sigtype}, @var{tau})
@deftypefnx{Function File} {[@var{u}, @var{t}] =} gensig (@var{sigtype}, @var{tau}, @var{tfinal})
@deftypefnx{Function File} {[@var{u}, @var{t}] =} gensig (@var{sigtype}, @var{tau}, @var{tfinal}, @var{tsam})
Generate periodic signal.  Useful in combination with lsim.

@strong{Inputs}
@table @var
@item sigtype = "sin"
Sine wave.
@item sigtype = "cos"
Cosine wave.
@item sigtype = "square"
Square wave.
@item sigtype = "pulse"
Periodic pulse.
@item tau
Duration of one period in seconds.
@item tfinal
Optional duration of the signal in seconds.  Default duration is 5 periods.
@item tsam
Optional sampling time in seconds.  Default spacing is tau/64.
@end table

@strong{Outputs}
@table @var
@item u
Vector of signal values.
@item t
Time vector of the signal.
@end table

@seealso{lsim}
@end deftypefn
@section impulse
@findex impulse

@deftypefn{Function File} {} impulse (@var{sys})
@deftypefnx{Function File} {} impulse (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx{Function File} {} impulse (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx{Function File} {} impulse (@var{sys1}, @dots{}, @var{t})
@deftypefnx{Function File} {} impulse (@var{sys1}, @dots{}, @var{tfinal})
@deftypefnx{Function File} {} impulse (@var{sys1}, @dots{}, @var{tfinal}, @var{dt})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} impulse (@var{sys})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} impulse (@var{sys}, @var{t})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} impulse (@var{sys}, @var{tfinal})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} impulse (@var{sys}, @var{tfinal}, @var{dt})
Impulse response of @acronym{LTI} system.
If no output arguments are given, the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item t
Time vector.  Should be evenly spaced.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item tfinal
Optional simulation horizon.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item dt
Optional sampling time.  Be sure to choose it small enough to capture transient
phenomena.  If not specified, it is calculated by the poles of the system.
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item y
Output response array.  Has as many rows as time samples (length of t)
and as many columns as outputs.
@item t
Time row vector.
@item x
State trajectories array.  Has @code{length (t)} rows and as many columns as states.
@end table

@seealso{initial, lsim, step}
@end deftypefn
@section initial
@findex initial

@deftypefn{Function File} {} initial (@var{sys}, @var{x0})
@deftypefnx{Function File} {} initial (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{x0})
@deftypefnx{Function File} {} initial (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'}, @var{x0})
@deftypefnx{Function File} {} initial (@var{sys1}, @dots{}, @var{x0}, @var{t})
@deftypefnx{Function File} {} initial (@var{sys1}, @dots{}, @var{x0}, @var{tfinal})
@deftypefnx{Function File} {} initial (@var{sys1}, @dots{}, @var{x0}, @var{tfinal}, @var{dt})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} initial (@var{sys}, @var{x0})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} initial (@var{sys}, @var{x0}, @var{t})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} initial (@var{sys}, @var{x0}, @var{tfinal})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} initial (@var{sys}, @var{x0}, @var{tfinal}, @var{dt})
Initial condition response of state-space model.
If no output arguments are given, the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
State-space model.
@item x0
Vector of initial conditions for each state.
@item t
Optional time vector.  Should be evenly spaced.  If not specified, it is calculated
by the poles of the system to reflect adequately the response transients.
@item tfinal
Optional simulation horizon.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item dt
Optional sampling time.  Be sure to choose it small enough to capture transient
phenomena.  If not specified, it is calculated by the poles of the system.
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item y
Output response array.  Has as many rows as time samples (length of t)
and as many columns as outputs.
@item t
Time row vector.
@item x
State trajectories array.  Has @code{length (t)} rows and as many columns as states.
@end table

@strong{Example}
@example
@group
.
Continuous Time:   x = A x ,   y = C x ,   x(0) = x0

Discrete Time:   x[k+1] = A x[k] ,   y[k] = C x[k] ,   x[0] = x0
@end group
@end example

@seealso{impulse, lsim, step}
@end deftypefn
@section lsim
@findex lsim

@deftypefn{Function File} {} lsim (@var{sys}, @var{u})
@deftypefnx{Function File} {} lsim (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{u})
@deftypefnx{Function File} {} lsim (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'}, @var{u})
@deftypefnx{Function File} {} lsim (@var{sys1}, @dots{}, @var{u}, @var{t})
@deftypefnx{Function File} {} lsim (@var{sys1}, @dots{}, @var{u}, @var{t}, @var{x0})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} lsim (@var{sys}, @var{u})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} lsim (@var{sys}, @var{u}, @var{t})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} lsim (@var{sys}, @var{u}, @var{t}, @var{x0})
Simulate @acronym{LTI} model response to arbitrary inputs.  If no output arguments are given,
the system response is plotted on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.  System must be proper, i.e. it must not have more zeros than poles.
@item u
Vector or array of input signal.  Needs @code{length(t)} rows and as many columns
as there are inputs.  If @var{sys} is a single-input system, row vectors @var{u}
of length @code{length(t)} are accepted as well.
@item t
Time vector.  Should be evenly spaced.  If @var{sys} is a continuous-time system
and @var{t} is a real scalar, @var{sys} is discretized with sampling time
@code{tsam = t/(rows(u)-1)}.  If @var{sys} is a discrete-time system and @var{t}
is not specified, vector @var{t} is assumed to be @code{0 : tsam : tsam*(rows(u)-1)}.
@item x0
Vector of initial conditions for each state.  If not specified, a zero vector is assumed.
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item y
Output response array.  Has as many rows as time samples (length of t)
and as many columns as outputs.
@item t
Time row vector.  It is always evenly spaced.
@item x
State trajectories array.  Has @code{length (t)} rows and as many columns as states.
@end table

@seealso{impulse, initial, step}
@end deftypefn
@section ramp
@findex ramp

@deftypefn{Function File} {} ramp (@var{sys})
@deftypefnx{Function File} {} ramp (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx{Function File} {} ramp (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx{Function File} {} ramp (@var{sys1}, @dots{}, @var{t})
@deftypefnx{Function File} {} ramp (@var{sys1}, @dots{}, @var{tfinal})
@deftypefnx{Function File} {} ramp (@var{sys1}, @dots{}, @var{tfinal}, @var{dt})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} ramp (@var{sys})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} ramp (@var{sys}, @var{t})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} ramp (@var{sys}, @var{tfinal})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} ramp (@var{sys}, @var{tfinal}, @var{dt})
Ramp response of @acronym{LTI} system.
If no output arguments are given, the response is printed on the screen.
@iftex
@tex
$$r(t) = t \, \cdot \, h(t)$$
@end tex
@end iftex
@ifnottex

@example
r(t) = t * h(t)
@end example

@end ifnottex

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item t
Time vector.  Should be evenly spaced.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item tfinal
Optional simulation horizon.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item dt
Optional sampling time.  Be sure to choose it small enough to capture transient
phenomena.  If not specified, it is calculated by the poles of the system.
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item y
Output response array.  Has as many rows as time samples (length of t)
and as many columns as outputs.
@item t
Time row vector.
@item x
State trajectories array.  Has @code{length (t)} rows and as many columns as states.
@end table

@seealso{impulse, initial, lsim, step}
@end deftypefn
@section step
@findex step

@deftypefn{Function File} {} step (@var{sys})
@deftypefnx{Function File} {} step (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx{Function File} {} step (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx{Function File} {} step (@var{sys1}, @dots{}, @var{t})
@deftypefnx{Function File} {} step (@var{sys1}, @dots{}, @var{tfinal})
@deftypefnx{Function File} {} step (@var{sys1}, @dots{}, @var{tfinal}, @var{dt})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} step (@var{sys})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} step (@var{sys}, @var{t})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} step (@var{sys}, @var{tfinal})
@deftypefnx{Function File} {[@var{y}, @var{t}, @var{x}] =} step (@var{sys}, @var{tfinal}, @var{dt})
Step response of @acronym{LTI} system.
If no output arguments are given, the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item t
Time vector.  Should be evenly spaced.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item tfinal
Optional simulation horizon.  If not specified, it is calculated by
the poles of the system to reflect adequately the response transients.
@item dt
Optional sampling time.  Be sure to choose it small enough to capture transient
phenomena.  If not specified, it is calculated by the poles of the system.
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item y
Output response array.  Has as many rows as time samples (length of t)
and as many columns as outputs.
@item t
Time row vector.
@item x
State trajectories array.  Has @code{length (t)} rows and as many columns as states.
@end table

@seealso{impulse, initial, lsim}
@end deftypefn
@chapter Frequency Domain Analysis
@section bode
@findex bode

@deftypefn {Function File} {} bode (@var{sys})
@deftypefnx {Function File} {} bode (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx {Function File} {} bode (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{w})
@deftypefnx {Function File} {} bode (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx {Function File} {[@var{mag}, @var{pha}, @var{w}] =} bode (@var{sys})
@deftypefnx {Function File} {[@var{mag}, @var{pha}, @var{w}] =} bode (@var{sys}, @var{w})
Bode diagram of frequency response.  If no output arguments are given,
the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.  Must be a single-input and single-output (SISO) system.
@item w
Optional vector of frequency values.  If @var{w} is not specified,
it is calculated by the zeros and poles of the system.
Alternatively, the cell @code{@{wmin, wmax@}} specifies a frequency range,
where @var{wmin} and @var{wmax} denote minimum and maximum frequencies
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item mag
Vector of magnitude.  Has length of frequency vector @var{w}.
@item pha
Vector of phase.  Has length of frequency vector @var{w}.
@item w
Vector of frequency values used.
@end table

@seealso{nichols, nyquist, sigma}
@end deftypefn
@section bodemag
@findex bodemag

@deftypefn {Function File} {} bodemag (@var{sys})
@deftypefnx {Function File} {} bodemag (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx {Function File} {} bodemag (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{w})
@deftypefnx {Function File} {} bodemag (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx {Function File} {[@var{mag}, @var{w}] =} bodemag (@var{sys})
@deftypefnx {Function File} {[@var{mag}, @var{w}] =} bodemag (@var{sys}, @var{w})
Bode magnitude diagram of frequency response.  If no output arguments are given,
the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.  Must be a single-input and single-output (SISO) system.
@item w
Optional vector of frequency values.  If @var{w} is not specified,
it is calculated by the zeros and poles of the system.
Alternatively, the cell @code{@{wmin, wmax@}} specifies a frequency range,
where @var{wmin} and @var{wmax} denote minimum and maximum frequencies
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item mag
Vector of magnitude.  Has length of frequency vector @var{w}.
@item w
Vector of frequency values used.
@end table

@seealso{bode, nichols, nyquist, sigma}
@end deftypefn
@section @@lti/freqresp
@findex freqresp

@deftypefn{Function File} {@var{H} =} freqresp (@var{sys}, @var{w})
Evaluate frequency response at given frequencies.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.
@item w
Vector of frequency values.
@end table

@strong{Outputs}
@table @var
@item H
Array of frequency response.  For a system with m inputs and p outputs, the array @var{H}
has dimensions [p, m, length (w)].
The frequency response at the frequency w(k) is given by H(:,:,k).
@end table

@seealso{dcgain}
@end deftypefn
@section margin
@findex margin

@deftypefn{Function File} {[@var{gamma}, @var{phi}, @var{w_gamma}, @var{w_phi}] =} margin (@var{sys})
@deftypefnx{Function File} {[@var{gamma}, @var{phi}, @var{w_gamma}, @var{w_phi}] =} margin (@var{sys}, @var{tol})
Gain and phase margin of a system.
If no output arguments are given, both gain and phase margin are plotted on a bode diagram.
Otherwise, the margins and their corresponding frequencies are computed and returned.
A more robust criterion to assess the stability of a feedback system is the sensitivity Ms
computed by command @command{sensitivity}.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.  Must be a single-input and single-output (SISO) system.
@item tol
Imaginary parts below @var{tol} are assumed to be zero.
If not specified, default value @code{sqrt (eps)} is taken.
@end table

@strong{Outputs}
@table @var
@item gamma
Gain margin (as gain, not dBs).
@item phi
Phase margin (in degrees).
@item w_gamma
Frequency for the gain margin (in rad/s).
@item w_phi
Frequency for the phase margin (in rad/s).
@end table

@strong{Algorithm}@*
Uses command @command{roots} to calculate the frequencies
@var{w_gamma}, @var{w_phi} from special polynomials created
from the transfer function of @var{sys} as listed below
in section @guillemetleft{}Equations@guillemetright{}.

@strong{Equations}
@example
@group
CONTINUOUS-TIME SYSTEMS
Gain Margin
_               _
L(jw) = L(jw)      BTW: L(jw) = L(-jw) = conj (L(jw))

num(jw)   num(-jw)
------- = --------
den(jw)   den(-jw)

num(jw) den(-jw) = num(-jw) den(jw)

imag (num(jw) den(-jw)) = 0
imag (num(-jw) den(jw)) = 0
@end group
@end example
@example
@group
Phase Margin
|num(jw)|
|L(jw)| = |-------| = 1
|den(jw)|
_     2      2
z z = Re z + Im z

num(jw)   num(-jw)
------- * -------- = 1
den(jw)   den(-jw)

num(jw) num(-jw) - den(jw) den(-jw) = 0

real (num(jw) num(-jw) - den(jw) den(-jw)) = 0
@end group
@end example
@example
@group
DISCRETE-TIME SYSTEMS
Gain Margin
jwT         log z
L(z) = L(1/z)      BTW: z = e    --> w = -----
j T
num(z)   num(1/z)
------ = --------
den(z)   den(1/z)

num(z) den(1/z) - num(1/z) den(z) = 0
@end group
@end example
@example
@group
Phase Margin
|num(z)|
|L(z)| = |------| = 1
|den(z)|
@end group
@end example
@example
@group
L(z) L(1/z) = 1

num(z)   num(1/z)
------ * -------- = 1
den(z)   den(1/z)

num(z) num(1/z) - den(z) den(1/z) = 0
@end group
@end example
@example
@group
PS: How to get L(1/z)
4       3       2
p(z) = a z  +  b z  +  c z  +  d z  +  e

-4      -3      -2      -1
p(1/z) = a z  +  b z  +  c z  +  d z  +  e

-4                    2       3       4
= z   ( a  +  b z  +  c z  +  d z  +  e z  )

4       3       2                     4
= ( e z  +  d z  +  c z  +  b z  +  a ) / ( z  )
@end group
@end example

@seealso{sensitivity, roots}
@end deftypefn
@section nichols
@findex nichols

@deftypefn {Function File} {} nichols (@var{sys})
@deftypefnx {Function File} {} nichols (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx {Function File} {} nichols (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{w})
@deftypefnx {Function File} {} nichols (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx {Function File} {[@var{mag}, @var{pha}, @var{w}] =} nichols (@var{sys})
@deftypefnx {Function File} {[@var{mag}, @var{pha}, @var{w}] =} nichols (@var{sys}, @var{w})
Nichols chart of frequency response.  If no output arguments are given,
the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.  Must be a single-input and single-output (SISO) system.
@item w
Optional vector of frequency values.  If @var{w} is not specified,
it is calculated by the zeros and poles of the system.
Alternatively, the cell @code{@{wmin, wmax@}} specifies a frequency range,
where @var{wmin} and @var{wmax} denote minimum and maximum frequencies
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item mag
Vector of magnitude.  Has length of frequency vector @var{w}.
@item pha
Vector of phase.  Has length of frequency vector @var{w}.
@item w
Vector of frequency values used.
@end table

@seealso{bode, nyquist, sigma}
@end deftypefn
@section nyquist
@findex nyquist

@deftypefn {Function File} {} nyquist (@var{sys})
@deftypefnx {Function File} {} nyquist (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx {Function File} {} nyquist (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{w})
@deftypefnx {Function File} {} nyquist (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx {Function File} {[@var{re}, @var{im}, @var{w}] =} nyquist (@var{sys})
@deftypefnx {Function File} {[@var{re}, @var{im}, @var{w}] =} nyquist (@var{sys}, @var{w})
Nyquist diagram of frequency response.  If no output arguments are given,
the response is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.  Must be a single-input and single-output (SISO) system.
@item w
Optional vector of frequency values.  If @var{w} is not specified,
it is calculated by the zeros and poles of the system.
Alternatively, the cell @code{@{wmin, wmax@}} specifies a frequency range,
where @var{wmin} and @var{wmax} denote minimum and maximum frequencies
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item re
Vector of real parts.  Has length of frequency vector @var{w}.
@item im
Vector of imaginary parts.  Has length of frequency vector @var{w}.
@item w
Vector of frequency values used.
@end table

@seealso{bode, nichols, sigma}
@end deftypefn
@section sensitivity
@findex sensitivity

@deftypefn{Function File} {[@var{Ms}, @var{ws}] =} sensitivity (@var{L})
@deftypefnx{Function File} {[@var{Ms}, @var{ws}] =} sensitivity (@var{P}, @var{C})
@deftypefnx{Function File} {[@var{Ms}, @var{ws}] =} sensitivity (@var{P}, @var{C1}, @var{C2}, @dots{})
Return sensitivity margin @var{Ms}.
The quantity @var{Ms} is simply the inverse of the shortest
distance from the Nyquist curve to the critical point -1.
Reasonable values of @var{Ms} are in the range from 1.3 to 2.
@iftex
@tex
$$M_s = ||S(j\omega)||_{\infty}$$
@end tex
@end iftex
@ifnottex

@example
Ms = ||S(jw)||
inf
@end example

@end ifnottex
If no output arguments are given, the critical distance 1/Ms
is plotted on a Nyquist diagram.
In contrast to gain and phase margin as computed by command
@command{margin}, the sensitivity @var{Ms} is a more robust
criterion to assess the stability of a feedback system.

@strong{Inputs}
@table @var
@item L
Open loop transfer function.
@var{L} can be any type of @acronym{LTI} system, but it must be square.
@item P
Plant model.  Any type of @acronym{LTI} system.
@item C
Controller model.  Any type of @acronym{LTI} system.
@item C1, C2, @dots{}
If several controllers are specified, command @command{sensitivity}
computes the sensitivity @var{Ms} for each of them in combination
with plant @var{P}.
@end table

@strong{Outputs}
@table @var
@item Ms
Sensitivity margin @var{Ms} as defined in [1].
Scalar value.
If several controllers are specified, @var{Ms} becomes
a row vector with as many entries as controllers.
@item ws
The frequency [rad/s] corresponding to the sensitivity peak.
Scalar value.
If several controllers are specified, @var{ws} becomes
a row vector with as many entries as controllers.
@end table

@strong{Algorithm}@*
Uses SLICOT AB13DD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
to calculate the infinity norm of the sensitivity function.

@strong{References}@*
[1] Astr@"om, K. and H@"agglund, T. (1995)
PID Controllers:
Theory, Design and Tuning,
Second Edition.
Instrument Society of America.

@end deftypefn
@section sigma
@findex sigma

@deftypefn {Function File} {} sigma (@var{sys})
@deftypefnx {Function File} {} sigma (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
@deftypefnx {Function File} {} sigma (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{w})
@deftypefnx {Function File} {} sigma (@var{sys1}, @var{'style1'}, @dots{}, @var{sysN}, @var{'styleN'})
@deftypefnx{Function File} {[@var{sv}, @var{w}] =} sigma (@var{sys})
@deftypefnx{Function File} {[@var{sv}, @var{w}] =} sigma (@var{sys}, @var{w})
Singular values of frequency response.  If no output arguments are given,
the singular value plot is printed on the screen.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} system.  Multiple inputs and/or outputs (MIMO systems) make practical sense.
@item w
Optional vector of frequency values.  If @var{w} is not specified,
it is calculated by the zeros and poles of the system.
Alternatively, the cell @code{@{wmin, wmax@}} specifies a frequency range,
where @var{wmin} and @var{wmax} denote minimum and maximum frequencies
@item 'style'
Line style and color, e.g. 'r' for a solid red line or '-.k' for a dash-dotted
black line.  See @command{help plot} for details.
@end table

@strong{Outputs}
@table @var
@item sv
Array of singular values.  For a system with m inputs and p outputs, the array sv
has @code{min (m, p)} rows and as many columns as frequency points @code{length (w)}.
The singular values at the frequency @code{w(k)} are given by @code{sv(:,k)}.
@item w
Vector of frequency values used.
@end table

@seealso{bodemag, svd}
@end deftypefn
@chapter Pole Placement
@section place
@findex place

@deftypefn {Function File} {@var{f} =} place (@var{sys}, @var{p})
@deftypefnx {Function File} {@var{f} =} place (@var{a}, @var{b}, @var{p})
@deftypefnx {Function File} {[@var{f}, @var{info}] =} place (@var{sys}, @var{p}, @var{alpha})
@deftypefnx {Function File} {[@var{f}, @var{info}] =} place (@var{a}, @var{b}, @var{p}, @var{alpha})
Pole assignment for a given matrix pair (@var{A},@var{B}) such that @code{p = eig (A-B*F)}.
If parameter @var{alpha} is specified, poles with real parts (continuous-time)
or moduli (discrete-time) below @var{alpha} are left untouched.

@strong{Inputs}
@table @var
@item sys
Continuous- or discrete-time @acronym{LTI} system.
@item a
State matrix (n-by-n) of a continuous-time system.
@item b
Input matrix (n-by-m) of a continuous-time system.
@item p
Desired eigenvalues of the closed-loop system state-matrix @var{A-B*F}.
@code{length (p) <= rows (A)}.
@item alpha
Specifies the maximum admissible value, either for real
parts or for moduli, of the eigenvalues of @var{A} which will
not be modified by the eigenvalue assignment algorithm.
@code{alpha >= 0} for discrete-time systems.
@end table

@strong{Outputs}
@table @var
@item f
State feedback gain matrix.
@item info
@item info.nfp
The number of fixed poles, i.e. eigenvalues of @var{A} having
real parts less than @var{alpha}, or moduli less than @var{alpha}.
These eigenvalues are not modified by @command{place}.
@item info.nap
The number of assigned eigenvalues.  @code{nap = n-nfp-nup}.
@item info.nup
The number of uncontrollable eigenvalues detected by the
eigenvalue assignment algorithm.
@item info.z
The orthogonal matrix @var{z} reduces the closed-loop
system state matrix @code{A + B*F} to upper real Schur form.
@end table

@strong{Note}
@example
Place is also suitable to design estimator gains:
@group
L = place (A.', C.', p).'
L = place (sys.', p).'   # useful for discrete-time systems
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB01BD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section rlocus
@findex rlocus

@deftypefn {Function File} {} rlocus (@var{sys})
@deftypefnx {Function File} {[@var{rldata}, @var{k}] =} rlocus (@var{sys}, @var{increment}, @var{min_k}, @var{max_k})
Display root locus plot of the specified @acronym{SISO} system.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.  Must be a single-input and single-output (SISO) system.
@item increment
The increment used in computing gain values.
@item min_k
Minimum value of @var{k}.
@item max_k
Maximum value of @var{k}.
@end table

@strong{Outputs}
@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

@strong{Block Diagram}
@example
@group
u    +         +---+      +------+             y
------>(+)----->| k |----->| SISO |-------+------->
^ -     +---+      +------+       |
|                                 |
+---------------------------------+
@end group
@end example
@end deftypefn
@chapter Optimal Control
@section dlqe
@findex dlqe

@deftypefn {Function File} {[@var{m}, @var{p}, @var{z}, @var{e}] =} dlqe (@var{a}, @var{g}, @var{c}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{m}, @var{p}, @var{z}, @var{e}] =} dlqe (@var{a}, @var{g}, @var{c}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{m}, @var{p}, @var{z}, @var{e}] =} dlqe (@var{a}, @var{[]}, @var{c}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{m}, @var{p}, @var{z}, @var{e}] =} dlqe (@var{a}, @var{[]}, @var{c}, @var{q}, @var{r}, @var{s})
Kalman filter for discrete-time systems.

@example
@group
x[k] = Ax[k] + Bu[k] + Gw[k]   (State equation)
y[k] = Cx[k] + Du[k] + v[k]    (Measurement Equation)
E(w) = 0, E(v) = 0, cov(w) = Q, cov(v) = R, cov(w,v) = S
@end group
@end example

@strong{Inputs}
@table @var
@item a
State transition matrix of discrete-time system (n-by-n).
@item g
Process noise matrix of discrete-time system (n-by-g).
If @var{g} is empty @code{[]}, an identity matrix is assumed.
@item c
Measurement matrix of discrete-time system (p-by-n).
@item q
Process noise covariance matrix (g-by-g).
@item r
Measurement noise covariance matrix (p-by-p).
@item s
Optional cross term covariance matrix (g-by-p), s = cov(w,v).
If @var{s} is empty @code{[]} or not specified, a zero matrix is assumed.
@end table

@strong{Outputs}
@table @var
@item m
Kalman filter gain matrix (n-by-p).
@item p
Unique stabilizing solution of the discrete-time Riccati equation (n-by-n).
Symmetric matrix.
@item z
Error covariance (n-by-n), cov(x(k|k)-x)
@item e
Closed-loop poles (n-by-1).
@end table

@strong{Equations}
@example
@group
x[k|k] = x[k|k-1] + M(y[k] - Cx[k|k-1] - Du[k])

x[k+1|k] = Ax[k|k] + Bu[k] for S=0

x[k+1|k] = Ax[k|k] + Bu[k] + G*S*(C*P*C' + R)^-1*(y[k] - C*x[k|k-1]) for non-zero S

E = eig(A - A*M*C) for S=0

E = eig(A - A*M*C - G*S*(C*P*C' + Rv)^-1*C) for non-zero S

@end group
@end example
@seealso{dare, care, dlqr, lqr, lqe}
@end deftypefn
@section dlqr
@findex dlqr

@deftypefn {Function File} {[@var{g}, @var{x}, @var{l}] =} dlqr (@var{sys}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} dlqr (@var{sys}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{[]}, @var{e})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{s}, @var{e})

@strong{Inputs}
@table @var
@item sys
Continuous or discrete-time @acronym{LTI} model (p-by-m, n states).
@item a
State transition matrix of discrete-time system (n-by-n).
@item b
Input matrix of discrete-time system (n-by-m).
@item q
State weighting matrix (n-by-n).
@item r
Input weighting matrix (m-by-m).
@item s
Optional cross term matrix (n-by-m).  If @var{s} is not specified, a zero matrix is assumed.
@item e
Optional descriptor matrix (n-by-n).  If @var{e} is not specified, an identity matrix is assumed.
@end table

@strong{Outputs}
@table @var
@item g
State feedback matrix (m-by-n).
@item x
Unique stabilizing solution of the discrete-time Riccati equation (n-by-n).
@item l
Closed-loop poles (n-by-1).
@end table

@strong{Equations}
@example
@group
x[k+1] = A x[k] + B u[k],   x[0] = x0

inf
J(x0) = SUM (x' Q x  +  u' R u  +  2 x' S u)
k=0

L = eig (A - B*G)
@end group
@end example
@seealso{dare, care, lqr}
@end deftypefn
@section estim
@findex estim

@deftypefn {Function File} {@var{est} =} estim (@var{sys}, @var{l})
@deftypefnx {Function File} {@var{est} =} estim (@var{sys}, @var{l}, @var{sensors}, @var{known})
Return state estimator for a given estimator gain.

@strong{Inputs}
@table @var
@item sys
@acronym{LTI} model.
@item l
State feedback matrix.
@item sensors
Indices of measured output signals y from @var{sys}.  If omitted, all outputs are measured.
@item known
Indices of known input signals u (deterministic) to @var{sys}.  All other inputs to @var{sys}
are assumed stochastic.  If argument @var{known} is omitted, no inputs u are known.
@end table

@strong{Outputs}
@table @var
@item est
State-space model of estimator.
@end table
@seealso{kalman, place}
@end deftypefn
@section kalman
@findex kalman

@deftypefn {Function File} {[@var{est}, @var{g}, @var{x}] =} kalman (@var{sys}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{est}, @var{g}, @var{x}] =} kalman (@var{sys}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{est}, @var{g}, @var{x}] =} kalman (@var{sys}, @var{q}, @var{r}, @var{[]}, @var{sensors}, @var{known})
@deftypefnx {Function File} {[@var{est}, @var{g}, @var{x}] =} kalman (@var{sys}, @var{q}, @var{r}, @var{s}, @var{sensors}, @var{known})
Design Kalman estimator for @acronym{LTI} systems.

@strong{Inputs}
@table @var
@item sys
Nominal plant model.
@item q
Covariance of white process noise.
@item r
Covariance of white measurement noise.
@item s
Optional cross term covariance.  Default value is 0.
@item sensors
Indices of measured output signals y from @var{sys}.  If omitted, all outputs are measured.
@item known
Indices of known input signals u (deterministic) to @var{sys}.  All other inputs to @var{sys}
are assumed stochastic.  If argument @var{known} is omitted, no inputs u are known.
@end table

@strong{Outputs}
@table @var
@item est
State-space model of the Kalman estimator.
@item g
Estimator gain.
@item x
Solution of the Riccati equation.
@end table

@strong{Block Diagram}
@example
@group
u  +-------+         ^
+---------------------------->|       |-------> y
|    +-------+     +       y  |  est  |         ^
u ----+--->|       |----->(+)------>|       |-------> x
|  sys  |       ^ +      +-------+
w -------->|       |       |
+-------+       | v

Q = cov (w, w')     R = cov (v, v')     S = cov (w, v')
@end group
@end example

@seealso{care, dare, estim, lqr}
@end deftypefn
@section lqe
@findex lqe

@deftypefn {Function File} {[@var{l}, @var{p}, @var{e}] =} lqe (@var{sys}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{l}, @var{p}, @var{e}] =} lqe (@var{sys}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{l}, @var{p}, @var{e}] =} lqe (@var{a}, @var{g}, @var{c}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{l}, @var{p}, @var{e}] =} lqe (@var{a}, @var{g}, @var{c}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{l}, @var{p}, @var{e}] =} lqe (@var{a}, @var{[]}, @var{c}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{l}, @var{p}, @var{e}] =} lqe (@var{a}, @var{[]}, @var{c}, @var{q}, @var{r}, @var{s})
Kalman filter for continuous-time systems.

@example
@group
.
x = Ax + Bu + Gw   (State equation)
y = Cx + Du + v    (Measurement Equation)
E(w) = 0, E(v) = 0, cov(w) = Q, cov(v) = R, cov(w,v) = S
@end group
@end example

@strong{Inputs}
@table @var
@item sys
Continuous or discrete-time @acronym{LTI} model (p-by-m, n states).
@item a
State matrix of continuous-time system (n-by-n).
@item g
Process noise matrix of continuous-time system (n-by-g).
If @var{g} is empty @code{[]}, an identity matrix is assumed.
@item c
Measurement matrix of continuous-time system (p-by-n).
@item q
Process noise covariance matrix (g-by-g).
@item r
Measurement noise covariance matrix (p-by-p).
@item s
Optional cross term covariance matrix (g-by-p), s = cov(w,v).
If @var{s} is empty @code{[]} or not specified, a zero matrix is assumed.
@end table

@strong{Outputs}
@table @var
@item l
Kalman filter gain matrix (n-by-p).
@item p
Unique stabilizing solution of the continuous-time Riccati equation (n-by-n).
Symmetric matrix.  If @var{sys} is a discrete-time model, the solution of the
corresponding discrete-time Riccati equation is returned.
@item e
Closed-loop poles (n-by-1).
@end table

@strong{Equations}
@example
@group
.
x = Ax + Bu + L(y - Cx -Du)

E = eig(A - L*C)

@end group
@end example
@seealso{dare, care, dlqr, lqr, dlqe}
@end deftypefn
@section lqr
@findex lqr

@deftypefn {Function File} {[@var{g}, @var{x}, @var{l}] =} lqr (@var{sys}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} lqr (@var{sys}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{[]}, @var{e})
@deftypefnx {Function File} {[@var{g}, @var{x}, @var{l}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{s}, @var{e})

@strong{Inputs}
@table @var
@item sys
Continuous or discrete-time @acronym{LTI} model (p-by-m, n states).
@item a
State matrix of continuous-time system (n-by-n).
@item b
Input matrix of continuous-time system (n-by-m).
@item q
State weighting matrix (n-by-n).
@item r
Input weighting matrix (m-by-m).
@item s
Optional cross term matrix (n-by-m).  If @var{s} is not specified, a zero matrix is assumed.
@item e
Optional descriptor matrix (n-by-n).  If @var{e} is not specified, an identity matrix is assumed.
@end table

@strong{Outputs}
@table @var
@item g
State feedback matrix (m-by-n).
@item x
Unique stabilizing solution of the continuous-time Riccati equation (n-by-n).
@item l
Closed-loop poles (n-by-1).
@end table

@strong{Equations}
@example
@group
.
x = A x + B u,   x(0) = x0

inf
J(x0) = INT (x' Q x  +  u' R u  +  2 x' S u)  dt
0

L = eig (A - B*G)
@end group
@end example
@seealso{care, dare, dlqr}
@end deftypefn
@chapter Robust Control
@section augw
@findex augw

@deftypefn{Function File} {@var{P} =} augw (@var{G}, @var{W1}, @var{W2}, @var{W3})
Extend plant for stacked S/KS/T problem.  Subsequently, the robust control problem
can be solved by h2syn or hinfsyn.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of plant.
@item W1
@acronym{LTI} model of performance weight.  Bounds the largest singular values of sensitivity @var{S}.
Model must be empty @code{[]}, SISO or of appropriate size.
@item W2
@acronym{LTI} model to penalize large control inputs.  Bounds the largest singular values of @var{KS}.
Model must be empty @code{[]}, SISO or of appropriate size.
@item W3
@acronym{LTI} model of robustness and noise sensitivity weight.  Bounds the largest singular values of
complementary sensitivity @var{T}.  Model must be empty @code{[]}, SISO or of appropriate size.
@end table

All inputs must be proper/realizable.
Scalars, vectors and matrices are possible instead of @acronym{LTI} models.

@strong{Outputs}
@table @var
@item P
State-space model of augmented plant.
@end table

@strong{Block Diagram}
@example
@group

| W1 | -W1*G |     z1 = W1 r  -  W1 G u
| 0  |  W2   |     z2 =          W2   u
P = | 0  |  W3*G |     z3 =          W3 G u
|----+-------|
| I  |    -G |     e  =    r  -     G u
@end group
@end example
@example
@group
+------+  z1
+---------------------------------------->|  W1  |----->
|                                         +------+
|                                         +------+  z2
|                 +---------------------->|  W2  |----->
|                 |                       +------+
r   +    e |   +--------+  u |   +--------+  y       +------+  z3
----->(+)---+-->|  K(s)  |----+-->|  G(s)  |----+---->|  W3  |----->
^ -      +--------+        +--------+    |     +------+
|                                        |
+----------------------------------------+
@end group
@end example
@example
@group
+--------+
|        |-----> z1 (p1x1)          z1 = W1 e
r (px1) ----->|  P(s)  |-----> z2 (p2x1)          z2 = W2 u
|        |-----> z3 (p3x1)          z3 = W3 y
u (mx1) ----->|        |-----> e (px1)            e = r - y
+--------+
@end group
@end example
@example
@group
+--------+
r ----->|        |-----> z
|  P(s)  |
u +---->|        |-----+ e
|     +--------+     |
|                    |
|     +--------+     |
+-----|  K(s)  |<----+
+--------+
@end group
@end example

@strong{References}@*
[1] Skogestad, S. and Postlethwaite I. (2005)
@cite{Multivariable Feedback Control: Analysis and Design:
Second Edition}.  Wiley.

@seealso{h2syn, hinfsyn, mixsyn}
@end deftypefn
@section fitfrd
@findex fitfrd

@deftypefn{Function File} {[@var{sys}, @var{n}] =} fitfrd (@var{dat}, @var{n})
@deftypefnx{Function File} {[@var{sys}, @var{n}] =} fitfrd (@var{dat}, @var{n}, @var{flag})
Fit frequency response data with a state-space system.
If requested, the returned system is stable and minimum-phase.

@strong{Inputs}
@table @var
@item dat
@acronym{LTI} model containing frequency response data of a SISO system.
@item n
The desired order of the system to be fitted.  @code{n <= length(dat.w)}.
@item flag
The flag controls whether the returned system is stable and minimum-phase.
@table @var
@item 0
The system zeros and poles are not constrained.  Default value.
@item 1
The system zeros and poles will have negative real parts in the
continuous-time case, or moduli less than 1 in the discrete-time case.
@end table
@end table

@strong{Outputs}
@table @var
@item sys
State-space model of order @var{n}, fitted to frequency response data @var{dat}.
@item n
The order of the obtained system.  The value of @var{n}
could only be modified if inputs @code{n > 0} and @code{flag = 1}.
@end table

@strong{Algorithm}@*
Uses SLICOT SB10YD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section h2syn
@findex h2syn

@deftypefn{Function File} {[@var{K}, @var{N}, @var{info}] =} h2syn (@var{P}, @var{nmeas}, @var{ncon})
H-2 control synthesis for @acronym{LTI} plant.

@strong{Inputs}
@table @var
@item P
Generalized plant.  Must be a proper/realizable @acronym{LTI} model.
@item nmeas
Number of measured outputs v.  The last @var{nmeas} outputs of @var{P} are connected to the
inputs of controller @var{K}.  The remaining outputs z (indices 1 to p-nmeas) are used
to calculate the H-2 norm.
@item ncon
Number of controlled inputs u.  The last @var{ncon} inputs of @var{P} are connected to the
outputs of controller @var{K}.  The remaining inputs w (indices 1 to m-ncon) are excited
by a harmonic test signal.
@end table

@strong{Outputs}
@table @var
@item K
State-space model of the H-2 optimal controller.
@item N
State-space model of the lower LFT of @var{P} and @var{K}.
@item info
@item info.gamma
H-2 norm of @var{N}.
@item info.rcond
Vector @var{rcond} contains estimates of the reciprocal condition
numbers of the matrices which are to be inverted and
estimates of the reciprocal condition numbers of the
Riccati equations which have to be solved during the
computation of the controller @var{K}.  For details,
see the description of the corresponding SLICOT routine.
@end table

@strong{Block Diagram}
@example
@group

gamma = min||N(K)||             N = lft (P, K)
K         2

+--------+
w ----->|        |-----> z
|  P(s)  |
u +---->|        |-----+ v
|     +--------+     |
|                    |
|     +--------+     |
+-----|  K(s)  |<----+
+--------+

+--------+
w ----->|  N(s)  |-----> z
+--------+
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB10HD and SB10ED by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{augw, lqr, dlqr, kalman}
@end deftypefn
@section hinfsyn
@findex hinfsyn

@deftypefn{Function File} {[@var{K}, @var{N}, @var{info}] =} hinfsyn (@var{P}, @var{nmeas}, @var{ncon})
@deftypefnx{Function File} {[@var{K}, @var{N}, @var{info}] =} hinfsyn (@var{P}, @var{nmeas}, @var{ncon}, @var{gmax})
H-infinity control synthesis for @acronym{LTI} plant.

@strong{Inputs}
@table @var
@item P
Generalized plant.  Must be a proper/realizable @acronym{LTI} model.
@item nmeas
Number of measured outputs v.  The last @var{nmeas} outputs of @var{P} are connected to the
inputs of controller @var{K}.  The remaining outputs z (indices 1 to p-nmeas) are used
to calculate the H-infinity norm.
@item ncon
Number of controlled inputs u.  The last @var{ncon} inputs of @var{P} are connected to the
outputs of controller @var{K}.  The remaining inputs w (indices 1 to m-ncon) are excited
by a harmonic test signal.
@item gmax
The maximum value of the H-infinity norm of @var{N}.  It is assumed that @var{gmax} is
sufficiently large so that the controller is admissible.
@end table

@strong{Outputs}
@table @var
@item K
State-space model of the H-infinity (sub-)optimal controller.
@item N
State-space model of the lower LFT of @var{P} and @var{K}.
@item info
@item info.gamma
L-infinity norm of @var{N}.
@item info.rcond
Vector @var{rcond} contains estimates of the reciprocal condition
numbers of the matrices which are to be inverted and
estimates of the reciprocal condition numbers of the
Riccati equations which have to be solved during the
computation of the controller @var{K}.  For details,
see the description of the corresponding SLICOT routine.
@end table

@strong{Block Diagram}
@example
@group

gamma = min||N(K)||             N = lft (P, K)
K         inf

+--------+
w ----->|        |-----> z
|  P(s)  |
u +---->|        |-----+ v
|     +--------+     |
|                    |
|     +--------+     |
+-----|  K(s)  |<----+
+--------+

+--------+
w ----->|  N(s)  |-----> z
+--------+
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB10FD and SB10DD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{augw, mixsyn}
@end deftypefn
@section mixsyn
@findex mixsyn

@deftypefn{Function File} {[@var{K}, @var{N}, @var{info}] =} mixsyn (@var{G}, @var{W1}, @var{W2}, @var{W3}, @dots{})
Solve stacked S/KS/T H-infinity problem.
Mixed-sensitivity is the name given to transfer function shaping problems in which
the sensitivity function
@iftex
@tex
$S = (I + G K)^{-1}$
@end tex
@end iftex
@ifnottex
@example
-1
S = (I + G K)
@end example
@end ifnottex
is shaped along with one or more other closed-loop transfer functions such as @var{K S}
or the complementary sensitivity function
@iftex
@tex
$T = I - S = (I + G K)^{-1} G K$
@end tex
@end iftex
@ifnottex
@example
-1
T = I - S = (I + G K)
@end example
@end ifnottex
in a typical one degree-of-freedom configuration, where @var{G} denotes the plant and
@var{K} the (sub-)optimal controller to be found.  The shaping of multivariable
transfer functions is based on the idea that a satisfactory definition of gain
(range of gain) for a matrix transfer function is given by the singular values
@iftex
@tex
$\sigma$
@end tex
@end iftex
@ifnottex

@end ifnottex
of the transfer function. Hence the classical loop-shaping ideas of feedback design
can be generalized to multivariable systems.  In addition to the requirement that
@var{K} stabilizes @var{G}, the closed-loop objectives are as follows [1]:
@enumerate
@item For @emph{disturbance rejection} make
@iftex
@tex
$\overline{\sigma}(S)$
@end tex
@end iftex
@ifnottex

@end ifnottex
small.
@item For @emph{noise attenuation} make
@iftex
@tex
$\overline{\sigma}(T)$
@end tex
@end iftex
@ifnottex

@end ifnottex
small.
@item For @emph{reference tracking} make
@iftex
@tex
$\overline{\sigma}(T) \approx \underline{\sigma}(T) \approx 1$.
@end tex
@end iftex
@ifnottex

@end ifnottex
@item For @emph{input usage (control energy) reduction} make
@iftex
@tex
$\overline{\sigma}(K S)$
@end tex
@end iftex
@ifnottex

@end ifnottex
small.
@item For @emph{robust stability} in the presence of an additive perturbation
@iftex
@tex
$G_p = G + \Delta$,
@end tex
@end iftex
@ifnottex

@end ifnottex
make
@iftex
@tex
$\overline{\sigma}(K S)$
@end tex
@end iftex
@ifnottex

@end ifnottex
small.
@item For @emph{robust stability} in the presence of a multiplicative output perturbation
@iftex
@tex
$G_p = (I + \Delta) G$,
@end tex
@end iftex
@ifnottex

@end ifnottex
make
@iftex
@tex
$\overline{\sigma}(T)$
@end tex
@end iftex
@ifnottex

@end ifnottex
small.
@end enumerate
In order to find a robust controller for the so-called stacked
@iftex
@tex
$S/KS/T \ H_{\infty}$
@end tex
@end iftex
@ifnottex
S/KS/T H-infinity
@end ifnottex
problem, the user function @command{mixsyn} minimizes the following criterion
@iftex
@tex
$$\underset{K}{\min} || N(K) ||_{\infty}, \quad N = | W_1 S; \ W_2 K S; \ W_3 T |$$
@end tex
@end iftex
@ifnottex
@example
| W1 S   |
min || N(K) ||           N = | W2 K S |
K            oo             | W3 T   |
@end example
@end ifnottex
@code{[K, N] = mixsyn (G, W1, W2, W3)}.
The user-defined weighting functions @var{W1}, @var{W2} and @var{W3} bound the largest
singular values of the closed-loop transfer functions @var{S} (for performance),
@var{K S} (to penalize large inputs) and @var{T} (for robustness and to avoid
sensitivity to noise), respectively [1].
A few points are to be considered when choosing the weights.
The weigths @var{Wi} must all be proper and stable.  Therefore if one wishes,
for example, to minimize @var{S} at low frequencies by a weighting @var{W1} including
integral action,
@iftex
@tex
${1 \over s}$
@end tex
@end iftex
@ifnottex
@example
1
-
s
@end example
@end ifnottex
needs to be approximated by
@iftex
@tex
${1 \over s + \epsilon}$, where $\epsilon \ll 1$.
@end tex
@end iftex
@ifnottex
@example
1
-----    where   e << 1.
s + e
@end example
@end ifnottex
Similarly one might be interested in weighting @var{K S} with a non-proper weight
@var{W2} to ensure that @var{K} is small outside the system bandwidth.
The trick here is to replace a non-proper term such as
@iftex
@tex
$1 + \tau_1 s$ by ${1 + \tau_1 s \over 1 + \tau_2 s}$, where
@end tex
@end iftex
@ifnottex
@example
1 + T1 s
1 + T1 s   by   --------,   where   T2 << T1.
1 + T2 s
@end example
@end ifnottex
@iftex
@tex
$\tau_2 \ll \tau_1$
@end tex
@end iftex
[1, 2].

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of plant.
@item W1
@acronym{LTI} model of performance weight.  Bounds the largest singular values of sensitivity @var{S}.
Model must be empty @code{[]}, SISO or of appropriate size.
@item W2
@acronym{LTI} model to penalize large control inputs.  Bounds the largest singular values of @var{KS}.
Model must be empty @code{[]}, SISO or of appropriate size.
@item W3
@acronym{LTI} model of robustness and noise sensitivity weight.  Bounds the largest singular values of
complementary sensitivity @var{T}.  Model must be empty @code{[]}, SISO or of appropriate size.
@item @dots{}
@end table

All inputs must be proper/realizable.
Scalars, vectors and matrices are possible instead of @acronym{LTI} models.

@strong{Outputs}
@table @var
@item K
State-space model of the H-infinity (sub-)optimal controller.
@item N
State-space model of the lower LFT of @var{P} and @var{K}.
@item info
@item info.gamma
L-infinity norm of @var{N}.
@item info.rcond
Vector @var{rcond} contains estimates of the reciprocal condition
numbers of the matrices which are to be inverted and
estimates of the reciprocal condition numbers of the
Riccati equations which have to be solved during the
computation of the controller @var{K}.  For details,
see the description of the corresponding SLICOT routine.
@end table

@strong{Block Diagram}
@example
@group

| W1 S   |
gamma = min||N(K)||             N = | W2 K S | = lft (P, K)
K         inf              | W3 T   |
@end group
@end example
@example
@group
+------+  z1
+---------------------------------------->|  W1  |----->
|                                         +------+
|                                         +------+  z2
|                 +---------------------->|  W2  |----->
|                 |                       +------+
r   +    e |   +--------+  u |   +--------+  y       +------+  z3
----->(+)---+-->|  K(s)  |----+-->|  G(s)  |----+---->|  W3  |----->
^ -      +--------+        +--------+    |     +------+
|                                        |
+----------------------------------------+
@end group
@end example
@example
@group
+--------+
|        |-----> z1 (p1x1)          z1 = W1 e
r (px1) ----->|  P(s)  |-----> z2 (p2x1)          z2 = W2 u
|        |-----> z3 (p3x1)          z3 = W3 y
u (mx1) ----->|        |-----> e (px1)            e = r - y
+--------+
@end group
@end example
@example
@group
+--------+
r ----->|        |-----> z
|  P(s)  |
u +---->|        |-----+ e
|     +--------+     |
|                    |
|     +--------+     |
+-----|  K(s)  |<----+
+--------+
@end group
@end example
@example
@group
+--------+
r ----->|  N(s)  |-----> z
+--------+
@end group
@end example
@example
@group
Extended Plant:  P = augw (G, W1, W2, W3)
Controller:      K = mixsyn (G, W1, W2, W3)
Entire System:   N = lft (P, K)
Open Loop:       L = G * K
Closed Loop:     T = feedback (L)
@end group
@end example

@strong{Algorithm}@*
Relies on commands @command{augw} and @command{hinfsyn},
which use SLICOT SB10FD and SB10DD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@strong{References}@*
[1] Skogestad, S. and Postlethwaite I. (2005)
@cite{Multivariable Feedback Control: Analysis and Design:
Second Edition}.  Wiley, Chichester, England.@*
[2] Meinsma, G. (1995)
@cite{Unstable and nonproper weights in H-infinity control}
Automatica, Vol. 31, No. 11, pp. 1655-1658

@seealso{hinfsyn, augw}
@end deftypefn
@section ncfsyn
@findex ncfsyn

@deftypefn{Function File} {[@var{K}, @var{N}, @var{info}] =} ncfsyn (@var{G}, @var{W1}, @var{W2}, @var{factor})
Loop shaping H-infinity synthesis.  Compute positive feedback controller using
the McFarlane/Glover loop shaping design procedure [1].
Using a precompensator @var{W1} and/or a postcompensator @var{W2}, the singular values
of the nominal plant @var{G} are shaped to give a desired open-loop shape.
The nominal plant @var{G} and shaping functions @var{W1}, @var{W2} are combined to
form the shaped plant, @var{Gs} where @code{Gs = W2 G W1}.
We assume that @var{W1} and @var{W2} are such that @var{Gs} contains no hidden modes.
It is relatively easy to approximate the closed-loop requirements by the following
open-loop objectives [2]:
@enumerate
@item For @emph{disturbance rejection} make
@iftex
@tex
$\underline{\sigma}(W_2 G W_1)$
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
large; valid for frequencies at which
@iftex
@tex
$\underline{\sigma}(G_S) \gg 1$.
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
@item For @emph{noise attenuation} make
@iftex
@tex
$\overline{\sigma}(W_2 G W_1)$
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
small; valid for frequencies at which
@iftex
@tex
$\overline{\sigma}(G_S) \ll 1$.
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
@item For @emph{reference tracking} make
@iftex
@tex
$\underline{\sigma}(W_2 G W_1)$
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
large; valid for frequencies at which
@iftex
@tex
$\underline{\sigma}(G_S) \gg 1$.
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
@item For @emph{robust stability} to a multiplicative output perturbation
@iftex
@tex
$G_p = (I + \Delta) G$, make
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
@iftex
@tex
$\overline{\sigma}(W_2 G W_1)$
@end tex
@end iftex
@ifnottex
@example

@end example
@end ifnottex
small; valid for frequencies at which
@iftex
@tex
$\overline{\sigma}(G_S) \ll 1$.
@end tex
@end iftex
@ifnottex
@example
.
@end example
@end ifnottex
@end enumerate
Then a stabilizing controller @var{Ks} is synthesized for shaped plant @var{Gs}.
The final positive feedback controller @var{K} is then constructed by combining
the
@iftex
@tex
$H_{\infty}$
@end tex
@end iftex
@ifnottex
@example
H-infinity
@end example
@end ifnottex
controller @var{Ks} with the shaping functions @var{W1} and @var{W2}
such that @code{K = W1 Ks W2}.
In [1] is stated further that the given robust stabilization objective can be
interpreted as a
@iftex
@tex
$H_{\infty}$
@end tex
@end iftex
@ifnottex
@example
H-infinity
@end example
@end ifnottex
problem formulation of minimizing the
@iftex
@tex
$H_{\infty}$
@end tex
@end iftex
@ifnottex
@example
H-infinity
@end example
@end ifnottex
norm of the frequency weighted gain from disturbances on the plant input and output
to the controller input and output as follows:
@iftex
@tex
$$\underset{K}{\min} \, || N(K) ||_{\infty},$$
$$N = | W_{1}^{-1}; W_2 G | \ (I - K G)^{-1} \ | W_1, \ G W_{2}^{-1} |$$
@end tex
@end iftex
@ifnottex
@example
-1            -1            -1
min || N(K) ||   ,    N = | W1   | (I - K G)   | W1   G W2   |
K            oo          | W2 G |
@end example
@end ifnottex
@iftex
@tex

@end tex
@end iftex

@code{[K, N] = ncfsyn (G, W1, W2, f)}
The function @command{ncfsyn} - the somewhat cryptic name stands
for @emph{normalized coprime factorization synthesis} - allows the specification of
an additional argument, factor @var{f}.  Default value @code{f = 1} implies that an
optimal controller is required, whereas @code{f > 1} implies that a suboptimal
controller is required, achieving a performance that is @var{f} times less than optimal.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of plant.
@item W1
@acronym{LTI} model of precompensator.  Model must be SISO or of appropriate size.
An identity matrix is taken if @var{W1} is not specified or if an empty model
@code{[]} is passed.
@item W2
@acronym{LTI} model of postcompensator.  Model must be SISO or of appropriate size.
An identity matrix is taken if @var{W2} is not specified or if an empty model
@code{[]} is passed.
@item factor
@code{factor = 1} implies that an optimal controller is required.
@code{factor > 1} implies that a suboptimal controller is required,
achieving a performance that is @var{factor} times less than optimal.
Default value is 1.
@end table

@strong{Outputs}
@table @var
@item K
State-space model of the H-infinity loop-shaping controller.
@item N
State-space model of the closed loop depicted below.
@item info
@item info.gamma
L-infinity norm of @var{N}.  @code{gamma = norm (N, inf)}.
@item info.emax
Nugap robustness.  @code{emax = inv (gamma)}.
@item info.Gs
Shaped plant.  @code{Gs = W2 * G * W1}.
@item info.Ks
Controller for shaped plant.  @code{Ks = ncfsyn (Gs)}.
@item info.rcond
Estimates of the reciprocal condition numbers of the Riccati equations
and a few other things.  For details, see the description of the
corresponding SLICOT routine.
@end table

@strong{Block Diagram of N}
@example
@group

^ z1              ^ z2
|                 |
w1  +      |   +--------+    |            +--------+
----->(+)---+-->|   Ks   |----+--->(+)---->|   Gs   |----+
^ +      +--------+          ^      +--------+    |
|                        w2  |                    |
|                                                 |
+-------------------------------------------------+
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB10ID, SB10KD and SB10ZD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@strong{References}@*
[1] D. McFarlane and K. Glover,
@cite{A Loop Shaping Design Procedure Using H-infinity Synthesis},
IEEE Transactions on Automatic Control, Vol. 37, No. 6, June 1992.@*
[2] S. Skogestad and I. Postlethwaite,
@cite{Multivariable Feedback Control: Analysis and Design:
Second Edition}.  Wiley, Chichester, England, 2005.@*

@end deftypefn
@chapter Matrix Equation Solvers
@section care
@findex care

@deftypefn {Function File} {[@var{x}, @var{l}, @var{g}] =} care (@var{a}, @var{b}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{l}, @var{g}] =} care (@var{a}, @var{b}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{x}, @var{l}, @var{g}] =} care (@var{a}, @var{b}, @var{q}, @var{r}, @var{[]}, @var{e})
@deftypefnx {Function File} {[@var{x}, @var{l}, @var{g}] =} care (@var{a}, @var{b}, @var{q}, @var{r}, @var{s}, @var{e})
Solve continuous-time algebraic Riccati equation (ARE).

@strong{Inputs}
@table @var
@item a
Real matrix (n-by-n).
@item b
Real matrix (n-by-m).
@item q
Real matrix (n-by-n).
@item r
Real matrix (m-by-m).
@item s
Optional real matrix (n-by-m).  If @var{s} is not specified, a zero matrix is assumed.
@item e
Optional descriptor matrix (n-by-n).  If @var{e} is not specified, an identity matrix is assumed.
@end table

@strong{Outputs}
@table @var
@item x
Unique stabilizing solution of the continuous-time Riccati equation (n-by-n).
@item l
Closed-loop poles (n-by-1).
@item g
Corresponding gain matrix (m-by-n).
@end table

@strong{Equations}
@example
@group
-1
A'X + XA - XB R  B'X + Q = 0

-1
A'X + XA - (XB + S) R  (B'X + S') + Q = 0

-1
G = R  B'X

-1
G = R  (B'X + S')

L = eig (A - B*G)
@end group
@end example
@example
@group
-1
A'XE + E'XA - E'XB R   B'XE + Q = 0

-1
A'XE + E'XA - (E'XB + S) R   (B'XE + S') + Q = 0

-1
G = R  B'XE

-1
G = R  (B'XE + S)

L = eig (A - B*G, E)
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB02OD and SG02AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{dare, lqr, dlqr, kalman}
@end deftypefn
@section dare
@findex dare

@deftypefn {Function File} {[@var{x}, @var{l}, @var{g}] =} dare (@var{a}, @var{b}, @var{q}, @var{r})
@deftypefnx {Function File} {[@var{x}, @var{l}, @var{g}] =} dare (@var{a}, @var{b}, @var{q}, @var{r}, @var{s})
@deftypefnx {Function File} {[@var{x}, @var{l}, @var{g}] =} dare (@var{a}, @var{b}, @var{q}, @var{r}, @var{[]}, @var{e})
@deftypefnx {Function File} {[@var{x}, @var{l}, @var{g}] =} dare (@var{a}, @var{b}, @var{q}, @var{r}, @var{s}, @var{e})
Solve discrete-time algebraic Riccati equation (ARE).

@strong{Inputs}
@table @var
@item a
Real matrix (n-by-n).
@item b
Real matrix (n-by-m).
@item q
Real matrix (n-by-n).
@item r
Real matrix (m-by-m).
@item s
Optional real matrix (n-by-m).  If @var{s} is not specified, a zero matrix is assumed.
@item e
Optional descriptor matrix (n-by-n).  If @var{e} is not specified, an identity matrix is assumed.
@end table

@strong{Outputs}
@table @var
@item x
Unique stabilizing solution of the discrete-time Riccati equation (n-by-n).
@item l
Closed-loop poles (n-by-1).
@item g
Corresponding gain matrix (m-by-n).
@end table

@strong{Equations}
@example
@group
-1
A'XA - X - A'XB (B'XB + R)   B'XA + Q = 0

-1
A'XA - X - (A'XB + S) (B'XB + R)   (B'XA + S') + Q = 0

-1
G = (B'XB + R)   B'XA

-1
G = (B'XB + R)   (B'XA + S')

L = eig (A - B*G)
@end group
@end example
@example
@group
-1
A'XA - E'XE - A'XB (B'XB + R)   B'XA + Q = 0

-1
A'XA - E'XE - (A'XB + S) (B'XB + R)   (B'XA + S') + Q = 0

-1
G = (B'XB + R)   B'XA

-1
G = (B'XB + R)   (B'XA + S')

L = eig (A - B*G, E)
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB02OD and SG02AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{care, lqr, dlqr, kalman}
@end deftypefn
@section dlyap
@findex dlyap

@deftypefn{Function File} {@var{x} =} dlyap (@var{a}, @var{b})
@deftypefnx{Function File} {@var{x} =} dlyap (@var{a}, @var{b}, @var{c})
@deftypefnx{Function File} {@var{x} =} dlyap (@var{a}, @var{b}, @var{[]}, @var{e})
Solve discrete-time Lyapunov or Sylvester equations.

@strong{Equations}
@example
@group
AXA' - X + B = 0      (Lyapunov Equation)

AXB' - X + C = 0      (Sylvester Equation)

AXA' - EXE' + B = 0   (Generalized Lyapunov Equation)
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB03MD, SB04QD and SG03AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{dlyapchol, lyap, lyapchol}
@end deftypefn
@section dlyapchol
@findex dlyapchol

@deftypefn{Function File} {@var{u} =} dlyapchol (@var{a}, @var{b})
@deftypefnx{Function File} {@var{u} =} dlyapchol (@var{a}, @var{b}, @var{e})
Compute Cholesky factor of discrete-time Lyapunov equations.

@strong{Equations}
@example
@group
A U' U A'  -  U' U  +  B B'  =  0           (Lyapunov Equation)

A U' U A'  -  E U' U E'  +  B B'  =  0      (Generalized Lyapunov Equation)
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB03OD and SG03BD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{dlyap, lyap, lyapchol}
@end deftypefn
@section lyap
@findex lyap

@deftypefn{Function File} {@var{x} =} lyap (@var{a}, @var{b})
@deftypefnx{Function File} {@var{x} =} lyap (@var{a}, @var{b}, @var{c})
@deftypefnx{Function File} {@var{x} =} lyap (@var{a}, @var{b}, @var{[]}, @var{e})
Solve continuous-time Lyapunov or Sylvester equations.

@strong{Equations}
@example
@group
AX + XA' + B = 0      (Lyapunov Equation)

AX + XB + C = 0       (Sylvester Equation)

AXE' + EXA' + B = 0   (Generalized Lyapunov Equation)
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB03MD, SB04MD and SG03AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{lyapchol, dlyap, dlyapchol}
@end deftypefn
@section lyapchol
@findex lyapchol

@deftypefn{Function File} {@var{u} =} lyapchol (@var{a}, @var{b})
@deftypefnx{Function File} {@var{u} =} lyapchol (@var{a}, @var{b}, @var{e})
Compute Cholesky factor of continuous-time Lyapunov equations.

@strong{Equations}
@example
@group
A U' U  +  U' U A'  +  B B'  =  0           (Lyapunov Equation)

A U' U E'  +  E U' U A'  +  B B'  =  0      (Generalized Lyapunov Equation)
@end group
@end example

@strong{Algorithm}@*
Uses SLICOT SB03OD and SG03BD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@seealso{lyap, dlyap, dlyapchol}
@end deftypefn
@chapter Model Reduction
@section bstmodred
@findex bstmodred

@deftypefn{Function File} {[@var{Gr}, @var{info}] =} bstmodred (@var{G}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} bstmodred (@var{G}, @var{nr}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} bstmodred (@var{G}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} bstmodred (@var{G}, @var{nr}, @var{opt}, @dots{})

Model order reduction by Balanced Stochastic Truncation (BST) method.
The aim of model reduction is to find an @acronym{LTI} system @var{Gr} of order
@var{nr} (nr < n) such that the input-output behaviour of @var{Gr}
approximates the one from original system @var{G}.

BST is a relative error method which tries to minimize
@iftex
@tex
$$|| G^{-1} (G-G_r) ||_{\infty} = min$$
@end tex
@end iftex
@ifnottex
@example
-1
||G  (G-Gr)||    = min
inf
@end example
@end ifnottex

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model to be reduced.
@item nr
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Gr
Reduced order state-space model.
@item info
@table @var
@item info.n
The order of the original system @var{G}.
@item info.ns
The order of the @var{alpha}-stable subsystem of the original system @var{G}.
@item info.hsv
The Hankel singular values of the phase system corresponding
to the @var{alpha}-stable part of the original system @var{G}.
The @var{ns} Hankel singular values are ordered decreasingly.
@item info.nu
The order of the @var{alpha}-unstable subsystem of both the original
system @var{G} and the reduced-order system @var{Gr}.
@item info.nr
The order of the obtained reduced order system @var{Gr}.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'nr'
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is the sum of NU and the number of
Hankel singular values greater than @code{MAX(TOL1,NS*EPS)};
@var{nr} can be further reduced to ensure that
@code{HSV(NR-NU) > HSV(NR+1-NU)}.

@item 'method'
Approximation method for the H-infinity norm.
Valid values corresponding to this key are:
@table @var
@item 'sr-bta', 'b'
Use the square-root Balance & Truncate method.
@item 'bfsr-bta', 'f'
Use the balancing-free square-root Balance & Truncate method.  Default method.
@item 'sr-spa', 's'
Use the square-root Singular Perturbation Approximation method.
@item 'bfsr-spa', 'p'
Use the balancing-free square-root Singular Perturbation Approximation method.
@end table

@item 'alpha'
Specifies the ALPHA-stability boundary for the eigenvalues
of the state dynamics matrix @var{G.A}.  For a continuous-time
system, ALPHA <= 0 is the boundary value for
the real parts of eigenvalues, while for a discrete-time
system, 0 <= ALPHA <= 1 represents the
boundary value for the moduli of eigenvalues.
The ALPHA-stability domain does not include the boundary.
Default value is 0 for continuous-time systems and
1 for discrete-time systems.

@item 'beta'
Use @code{[G, beta*I]} as new system @var{G} to combine
absolute and relative error methods.
BETA > 0 specifies the absolute/relative error weighting
parameter.  A large positive value of BETA favours the
minimization of the absolute approximation error, while a
small value of BETA is appropriate for the minimization
of the relative error.
BETA = 0 means a pure relative error method and can be
used only if rank(G.D) = rows(G.D) which means that
the feedthrough matrice must not be rank-deficient.
Default value is 0.

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of reduced system.
For model reduction, the recommended value of @var{tol1} lies
in the interval [0.00001, 0.001].  @var{tol1} < 1.
If @var{tol1} <= 0 on entry, the used default value is
@var{tol1} = NS*EPS, where NS is the number of
ALPHA-stable eigenvalues of A and EPS is the machine
precision.
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the phase system (see METHOD) corresponding
to the ALPHA-stable part of the given system.
The recommended value is TOL2 = NS*EPS.  TOL2 <= TOL1 < 1.
This value is used by default if @var{'tol2'} is not specified
or if TOL2 <= 0 on entry.

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on system @var{G} prior to order reduction.
Default value is true if @code{G.scaled == false} and
false if @code{G.scaled == true}.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

BST is often suitable to perform model reduction in order to obtain
low order design models for controller synthesis.

Approximation Properties:
@itemize @bullet
@item
Guaranteed stability of reduced models
@item
Approximates simultaneously gain and phase
@item
Preserves non-minimum phase zeros
@item
Guaranteed a priori error bound
@iftex
@tex
$$|| G^{-1} (G-G_r) ||_{\infty} \leq 2 \sum_{j=r+1}^{n} {1+\sigma_j \over 1-\sigma_j} - 1$$
@end tex
@end iftex
@end itemize

@strong{Algorithm}@*
Uses SLICOT AB09HD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section btamodred
@findex btamodred

@deftypefn{Function File} {[@var{Gr}, @var{info}] =} btamodred (@var{G}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} btamodred (@var{G}, @var{nr}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} btamodred (@var{G}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} btamodred (@var{G}, @var{nr}, @var{opt}, @dots{})

Model order reduction by frequency weighted Balanced Truncation Approximation (BTA) method.
The aim of model reduction is to find an @acronym{LTI} system @var{Gr} of order
@var{nr} (nr < n) such that the input-output behaviour of @var{Gr}
approximates the one from original system @var{G}.

BTA is an absolute error method which tries to minimize
@iftex
@tex
$$|| G - G_r ||_{\infty} = min$$
$$|| V \ (G - G_r) \ W ||_{\infty} = min$$
@end tex
@end iftex
@ifnottex
@example
||G-Gr||    = min
inf

||V (G-Gr) W||    = min
inf
@end example
@end ifnottex
where @var{V} and @var{W} denote output and input weightings.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model to be reduced.
@item nr
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Gr
Reduced order state-space model.
@item info
@table @var
@item info.n
The order of the original system @var{G}.
@item info.ns
The order of the @var{alpha}-stable subsystem of the original system @var{G}.
@item info.hsv
The Hankel singular values of the @var{alpha}-stable part of
the original system @var{G}, ordered decreasingly.
@item info.nu
The order of the @var{alpha}-unstable subsystem of both the original
system @var{G} and the reduced-order system @var{Gr}.
@item info.nr
The order of the obtained reduced order system @var{Gr}.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'nr'
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is chosen automatically such that states with
Hankel singular values @var{info.hsv} > @var{tol1} are retained.

@item 'left', 'output'
@acronym{LTI} model of the left/output frequency weighting @var{V}.
Default value is an identity matrix.

@item 'right', 'input'
@acronym{LTI} model of the right/input frequency weighting @var{W}.
Default value is an identity matrix.

@item 'method'
Approximation method for the L-infinity norm to be used as follows:
@table @var
@item 'sr', 'b'
Use the square-root Balance & Truncate method.
@item 'bfsr', 'f'
Use the balancing-free square-root Balance & Truncate method.  Default method.
@end table

@item 'alpha'
Specifies the ALPHA-stability boundary for the eigenvalues
of the state dynamics matrix @var{G.A}.  For a continuous-time
system, ALPHA <= 0 is the boundary value for
the real parts of eigenvalues, while for a discrete-time
system, 0 <= ALPHA <= 1 represents the
boundary value for the moduli of eigenvalues.
The ALPHA-stability domain does not include the boundary.
Default value is 0 for continuous-time systems and
1 for discrete-time systems.

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced model.
For model reduction, the recommended value of @var{tol1} is
c*info.hsv(1), where c lies in the interval [0.00001, 0.001].
Default value is info.ns*eps*info.hsv(1).
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the ALPHA-stable part of the given
model.  TOL2 <= TOL1.
If not specified, ns*eps*info.hsv(1) is chosen.

@item 'gram-ctrb'
Specifies the choice of frequency-weighted controllability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to a combination method [4]
of the approaches of Enns [1] and Lin-Chiu [2,3].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified combination method of [4].
@end table

@item 'gram-obsv'
Specifies the choice of frequency-weighted observability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to a combination method [4]
of the approaches of Enns [1] and Lin-Chiu [2,3].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified combination method of [4].
@end table

@item 'alpha-ctrb'
Combination method parameter for defining the
frequency-weighted controllability Grammian.
abs(alphac) <= 1.
If alphac = 0, the choice of
Grammian corresponds to the method of Enns [1], while if
alphac = 1, the choice of Grammian corresponds
to the method of Lin and Chiu [2,3].
Default value is 0.

@item 'alpha-obsv'
Combination method parameter for defining the
frequency-weighted observability Grammian.
abs(alphao) <= 1.
If alphao = 0, the choice of
Grammian corresponds to the method of Enns [1], while if
alphao = 1, the choice of Grammian corresponds
to the method of Lin and Chiu [2,3].
Default value is 0.

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on system @var{G} prior to order reduction.
This is done by state transformations.
Default value is true if @code{G.scaled == false} and
false if @code{G.scaled == true}.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

Approximation Properties:
@itemize @bullet
@item
Guaranteed stability of reduced models
@item
Lower guaranteed error bound
@item
Guaranteed a priori error bound
@iftex
@tex
$$\sigma_{r+1} \leq || (G-G_r) ||_{\infty} \leq 2 \sum_{j=r+1}^{n} \sigma_j$$
@end tex
@end iftex
@end itemize

@strong{References}@*
[1] Enns, D.
@cite{Model reduction with balanced realizations: An error bound
and a frequency weighted generalization}.
Proc. 23-th CDC, Las Vegas, pp. 127-132, 1984.

[2] Lin, C.-A. and Chiu, T.-Y.
@cite{Model reduction via frequency-weighted balanced realization}.
Control Theory and Advanced Technology, vol. 8,
pp. 341-351, 1992.

[3] Sreeram, V., Anderson, B.D.O and Madievski, A.G.
@cite{New results on frequency weighted balanced reduction
technique}.
Proc. ACC, Seattle, Washington, pp. 4004-4009, 1995.

[4] Varga, A. and Anderson, B.D.O.
@cite{Square-root balancing-free methods for the frequency-weighted
balancing related model reduction}.
(report in preparation)

@strong{Algorithm}@*
Uses SLICOT AB09ID by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section hnamodred
@findex hnamodred

@deftypefn{Function File} {[@var{Gr}, @var{info}] =} hnamodred (@var{G}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} hnamodred (@var{G}, @var{nr}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} hnamodred (@var{G}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} hnamodred (@var{G}, @var{nr}, @var{opt}, @dots{})

Model order reduction by frequency weighted optimal Hankel-norm (HNA) method.
The aim of model reduction is to find an @acronym{LTI} system @var{Gr} of order
@var{nr} (nr < n) such that the input-output behaviour of @var{Gr}
approximates the one from original system @var{G}.

HNA is an absolute error method which tries to minimize
@iftex
@tex
$$|| G - G_r ||_H = min$$
$$|| V \ (G - G_r) \ W ||_H = min$$
@end tex
@end iftex
@ifnottex
@example
||G-Gr||  = min
H

||V (G-Gr) W||  = min
H
@end example
@end ifnottex
where @var{V} and @var{W} denote output and input weightings.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model to be reduced.
@item nr
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is chosen automatically according
to the description of key @var{"order"}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Gr
Reduced order state-space model.
@item info
@table @var
@item info.n
The order of the original system @var{G}.
@item info.ns
The order of the @var{alpha}-stable subsystem of the original system @var{G}.
@item info.hsv
The Hankel singular values corresponding to the projection @code{op(V)*G1*op(W)},
where G1 denotes the @var{alpha}-stable part of the original system @var{G}.
The @var{ns} Hankel singular values are ordered decreasingly.
@item info.nu
The order of the @var{alpha}-unstable subsystem of both the original
system @var{G} and the reduced-order system @var{Gr}.
@item info.nr
The order of the obtained reduced order system @var{Gr}.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'nr'
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is the sum of @var{info.nu} and the number of
Hankel singular values greater than @code{max(tol1, ns*eps*info.hsv(1)};

@item 'method'
Specifies the computational approach to be used.
Valid values corresponding to this key are:
@table @var
@item 'descriptor'
Use the inverse free descriptor system approach.
@item 'standard'
Use the inversion based standard approach.
@item 'auto'
Switch automatically to the inverse free
descriptor approach in case of badly conditioned
feedthrough matrices in V or W.  Default method.
@end table

@item 'left', 'v'
@acronym{LTI} model of the left/output frequency weighting.
The weighting must be antistable.
@iftex
@math{|| V \ (G-G_r) \dots ||_H = min}
@end iftex
@ifnottex
@example
|| V (G-Gr) . ||  = min
H
@end example
@end ifnottex

@item 'right', 'w'
@acronym{LTI} model of the right/input frequency weighting.
The weighting must be antistable.
@iftex
@math{|| \dots (G-G_r) \ W ||_H = min}
@end iftex
@ifnottex
@example
|| . (G-Gr) W ||  = min
H
@end example
@end ifnottex

@item 'left-inv', 'inv-v'
@acronym{LTI} model of the left/output frequency weighting.
The weighting must have only antistable zeros.
@iftex
@math{|| inv(V) \ (G-G_r) \dots ||_H = min}
@end iftex
@ifnottex
@example
|| inv(V) (G-Gr) . ||  = min
H
@end example
@end ifnottex

@item 'right-inv', 'inv-w'
@acronym{LTI} model of the right/input frequency weighting.
The weighting must have only antistable zeros.
@iftex
@math{|| \dots (G-G_r) \ inv(W) ||_H = min}
@end iftex
@ifnottex
@example
|| . (G-Gr) inv(W) ||  = min
H
@end example
@end ifnottex

@item 'left-conj', 'conj-v'
@acronym{LTI} model of the left/output frequency weighting.
The weighting must be stable.
@iftex
@math{|| conj(V) \ (G-G_r) \dots ||_H = min}
@end iftex
@ifnottex
@example
|| V (G-Gr) . ||  = min
H
@end example
@end ifnottex

@item 'right-conj', 'conj-w'
@acronym{LTI} model of the right/input frequency weighting.
The weighting must be stable.
@iftex
@math{|| \dots (G-G_r) \ conj(W) ||_H = min}
@end iftex
@ifnottex
@example
|| . (G-Gr) W ||  = min
H
@end example
@end ifnottex

@item 'left-conj-inv', 'conj-inv-v'
@acronym{LTI} model of the left/output frequency weighting.
The weighting must be minimum-phase.
@iftex
@math{|| conj(inv(V)) \ (G-G_r) \dots ||_H = min}
@end iftex
@ifnottex
@example
|| V (G-Gr) . ||  = min
H
@end example
@end ifnottex

@item 'right-conj-inv', 'conj-inv-w'
@acronym{LTI} model of the right/input frequency weighting.
The weighting must be minimum-phase.
@iftex
@math{|| \dots (G-G_r) \ conj(inv(W)) ||_H = min}
@end iftex
@ifnottex
@example
|| . (G-Gr) W ||  = min
H
@end example
@end ifnottex

@item 'alpha'
Specifies the ALPHA-stability boundary for the eigenvalues
of the state dynamics matrix @var{G.A}.  For a continuous-time
system, ALPHA <= 0 is the boundary value for
the real parts of eigenvalues, while for a discrete-time
system, 0 <= ALPHA <= 1 represents the
boundary value for the moduli of eigenvalues.
The ALPHA-stability domain does not include the boundary.
Default value is 0 for continuous-time systems and
1 for discrete-time systems.

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced model.
For model reduction, the recommended value of @var{tol1} is
c*info.hsv(1), where c lies in the interval [0.00001, 0.001].
@var{tol1} < 1.
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the ALPHA-stable part of the given
model.  @var{tol2} <= @var{tol1} < 1.
If not specified, ns*eps*info.hsv(1) is chosen.

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on system @var{G} prior to order reduction.
Default value is true if @code{G.scaled == false} and
false if @code{G.scaled == true}.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

Approximation Properties:
@itemize @bullet
@item
Guaranteed stability of reduced models
@item
Lower guaranteed error bound
@item
Guaranteed a priori error bound
@iftex
@tex
$$\sigma_{r+1} \leq || (G-G_r) ||_{\infty} \leq 2 \sum_{j=r+1}^{n} \sigma_j$$
@end tex
@end iftex
@end itemize

@strong{Algorithm}@*
Uses SLICOT AB09JD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section spamodred
@findex spamodred

@deftypefn{Function File} {[@var{Gr}, @var{info}] =} spamodred (@var{G}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} spamodred (@var{G}, @var{nr}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} spamodred (@var{G}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Gr}, @var{info}] =} spamodred (@var{G}, @var{nr}, @var{opt}, @dots{})

Model order reduction by frequency weighted Singular Perturbation Approximation (SPA).
The aim of model reduction is to find an @acronym{LTI} system @var{Gr} of order
@var{nr} (nr < n) such that the input-output behaviour of @var{Gr}
approximates the one from original system @var{G}.

SPA is an absolute error method which tries to minimize
@iftex
@tex
$$|| G - G_r ||_{\infty} = min$$
$$|| V \ (G - G_r) \ W ||_{\infty} = min$$
@end tex
@end iftex
@ifnottex
@example
||G-Gr||    = min
inf

||V (G-Gr) W||    = min
inf
@end example
@end ifnottex
where @var{V} and @var{W} denote output and input weightings.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model to be reduced.
@item nr
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Gr
Reduced order state-space model.
@item info
@table @var
@item info.n
The order of the original system @var{G}.
@item info.ns
The order of the @var{alpha}-stable subsystem of the original system @var{G}.
@item info.hsv
The Hankel singular values of the @var{alpha}-stable part of
the original system @var{G}, ordered decreasingly.
@item info.nu
The order of the @var{alpha}-unstable subsystem of both the original
system @var{G} and the reduced-order system @var{Gr}.
@item info.nr
The order of the obtained reduced order system @var{Gr}.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'nr'
The desired order of the resulting reduced order system @var{Gr}.
If not specified, @var{nr} is chosen automatically such that states with
Hankel singular values @var{info.hsv} > @var{tol1} are retained.

@item 'left', 'output'
@acronym{LTI} model of the left/output frequency weighting @var{V}.
Default value is an identity matrix.

@item 'right', 'input'
@acronym{LTI} model of the right/input frequency weighting @var{W}.
Default value is an identity matrix.

@item 'method'
Approximation method for the L-infinity norm to be used as follows:
@table @var
@item 'sr', 's'
Use the square-root Singular Perturbation Approximation method.
@item 'bfsr', 'p'
Use the balancing-free square-root Singular Perturbation Approximation method.  Default method.
@end table

@item 'alpha'
Specifies the ALPHA-stability boundary for the eigenvalues
of the state dynamics matrix @var{G.A}.  For a continuous-time
system, ALPHA <= 0 is the boundary value for
the real parts of eigenvalues, while for a discrete-time
system, 0 <= ALPHA <= 1 represents the
boundary value for the moduli of eigenvalues.
The ALPHA-stability domain does not include the boundary.
Default value is 0 for continuous-time systems and
1 for discrete-time systems.

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced model.
For model reduction, the recommended value of @var{tol1} is
c*info.hsv(1), where c lies in the interval [0.00001, 0.001].
Default value is info.ns*eps*info.hsv(1).
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the ALPHA-stable part of the given
model.  TOL2 <= TOL1.
If not specified, ns*eps*info.hsv(1) is chosen.

@item 'gram-ctrb'
Specifies the choice of frequency-weighted controllability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to a combination method [4]
of the approaches of Enns [1] and Lin-Chiu [2,3].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified combination method of [4].
@end table

@item 'gram-obsv'
Specifies the choice of frequency-weighted observability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to a combination method [4]
of the approaches of Enns [1] and Lin-Chiu [2,3].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified combination method of [4].
@end table

@item 'alpha-ctrb'
Combination method parameter for defining the
frequency-weighted controllability Grammian.
abs(alphac) <= 1.
If alphac = 0, the choice of
Grammian corresponds to the method of Enns [1], while if
alphac = 1, the choice of Grammian corresponds
to the method of Lin and Chiu [2,3].
Default value is 0.

@item 'alpha-obsv'
Combination method parameter for defining the
frequency-weighted observability Grammian.
abs(alphao) <= 1.
If alphao = 0, the choice of
Grammian corresponds to the method of Enns [1], while if
alphao = 1, the choice of Grammian corresponds
to the method of Lin and Chiu [2,3].
Default value is 0.

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on system @var{G} prior to order reduction.
Default value is true if @code{G.scaled == false} and
false if @code{G.scaled == true}.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

@strong{References}@*
[1] Enns, D.
@cite{Model reduction with balanced realizations: An error bound
and a frequency weighted generalization}.
Proc. 23-th CDC, Las Vegas, pp. 127-132, 1984.

[2] Lin, C.-A. and Chiu, T.-Y.
@cite{Model reduction via frequency-weighted balanced realization}.
Control Theory and Advanced Technology, vol. 8,
pp. 341-351, 1992.

[3] Sreeram, V., Anderson, B.D.O and Madievski, A.G.
@cite{New results on frequency weighted balanced reduction
technique}.
Proc. ACC, Seattle, Washington, pp. 4004-4009, 1995.

[4] Varga, A. and Anderson, B.D.O.
@cite{Square-root balancing-free methods for the frequency-weighted
balancing related model reduction}.
(report in preparation)

@strong{Algorithm}@*
Uses SLICOT AB09ID by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@chapter Controller Reduction
@section btaconred
@findex btaconred

@deftypefn{Function File} {[@var{Kr}, @var{info}] =} btaconred (@var{G}, @var{K}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} btaconred (@var{G}, @var{K}, @var{ncr}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} btaconred (@var{G}, @var{K}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} btaconred (@var{G}, @var{K}, @var{ncr}, @var{opt}, @dots{})

Controller reduction by frequency-weighted Balanced Truncation Approximation (BTA).
Given a plant @var{G} and a stabilizing controller @var{K}, determine a reduced
order controller @var{Kr} such that the closed-loop system is stable and closed-loop
performance is retained.

The algorithm tries to minimize the frequency-weighted error
@iftex
@tex
$$|| V \ (K - K_r) \ W ||_{\infty} = min$$
@end tex
@end iftex
@ifnottex
@example
||V (K-Kr) W||    = min
inf
@end example
@end ifnottex
where @var{V} and @var{W} denote output and input weightings.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of the plant.
It has m inputs, p outputs and n states.
@item K
@acronym{LTI} model of the controller.
It has p inputs, m outputs and nc states.
@item ncr
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Kr
State-space model of reduced order controller.
@item info
@table @var
@item info.ncr
The order of the obtained reduced order controller @var{Kr}.
@item info.ncs
The order of the alpha-stable part of original controller @var{K}.
@item info.hsvc
The Hankel singular values of the alpha-stable part of @var{K}.
The @var{ncs} Hankel singular values are ordered decreasingly.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'ncr'
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically such that states with
Hankel singular values @var{info.hsvc} > @var{tol1} are retained.

@item 'method'
Order reduction approach to be used as follows:
@table @var
@item 'sr', 'b'
Use the square-root Balance & Truncate method.
@item 'bfsr', 'f'
Use the balancing-free square-root Balance & Truncate method.  Default method.
@end table

@item 'weight'
Specifies the type of frequency-weighting as follows:
@table @var
@item 'none'
No weightings are used (V = I, W = I).

@item 'left', 'output'
Use stability enforcing left (output) weighting
@iftex
@tex
$$V = (I - G K)^{-1} G, \qquad W = I$$
@end tex
@end iftex
@ifnottex
@example
-1
V = (I-G*K) *G ,  W = I
@end example
@end ifnottex

@item 'right', 'input'
Use stability enforcing right (input) weighting
@iftex
@tex
$$V = I, \qquad W = (I - G K)^{-1} G$$
@end tex
@end iftex
@ifnottex
@example
-1
V = I ,  W = (I-G*K) *G
@end example
@end ifnottex

@item 'both', 'performance'
Use stability and performance enforcing weightings
@iftex
@tex
$$V = (I - G K)^{-1} G, \qquad W = (I - G K)^{-1}$$
@end tex
@end iftex
@ifnottex
@example
-1                -1
V = (I-G*K) *G ,  W = (I-G*K)
@end example
@end ifnottex
Default value.
@end table

@item 'feedback'
Specifies whether @var{K} is a positive or negative feedback controller:
@table @var
@item '+'
Use positive feedback controller.  Default value.
@item '-'
Use negative feedback controller.
@end table

@item 'alpha'
Specifies the ALPHA-stability boundary for the eigenvalues
of the state dynamics matrix @var{K.A}.  For a continuous-time
controller, ALPHA <= 0 is the boundary value for
the real parts of eigenvalues, while for a discrete-time
controller, 0 <= ALPHA <= 1 represents the
boundary value for the moduli of eigenvalues.
The ALPHA-stability domain does not include the boundary.
Default value is 0 for continuous-time controllers and
1 for discrete-time controllers.

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced controller.
For model reduction, the recommended value of @var{tol1} is
c*info.hsvc(1), where c lies in the interval [0.00001, 0.001].
Default value is info.ncs*eps*info.hsvc(1).
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the ALPHA-stable part of the given
controller.  TOL2 <= TOL1.
If not specified, ncs*eps*info.hsvc(1) is chosen.

@item 'gram-ctrb'
Specifies the choice of frequency-weighted controllability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to standard Enns' method [1].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified Enns' method of [2].
@end table

@item 'gram-obsv'
Specifies the choice of frequency-weighted observability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to standard Enns' method [1].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified Enns' method of [2].
@end table

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on @var{G} and @var{K} prior to order reduction.
Default value is false if both @code{G.scaled == true, K.scaled == true}
and true otherwise.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

@strong{Algorithm}@*
Uses SLICOT SB16AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section cfconred
@findex cfconred

@deftypefn{Function File} {[@var{Kr}, @var{info}] =} cfconred (@var{G}, @var{F}, @var{L}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} cfconred (@var{G}, @var{F}, @var{L}, @var{ncr}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} cfconred (@var{G}, @var{F}, @var{L}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} cfconred (@var{G}, @var{F}, @var{L}, @var{ncr}, @var{opt}, @dots{})

Reduction of state-feedback-observer based controller by coprime factorization (CF).
Given a plant @var{G}, state feedback gain @var{F} and full observer gain @var{L},
determine a reduced order controller @var{Kr}.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of the open-loop plant (A,B,C,D).
It has m inputs, p outputs and n states.
@item F
Stabilizing state feedback matrix (m-by-n).
@item L
Stabilizing observer gain matrix (n-by-p).
@item ncr
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Kr
State-space model of reduced order controller.
@item info
@table @var
@item info.hsv
The Hankel singular values of the extended system?!?.
The @var{n} Hankel singular values are ordered decreasingly.
@item info.ncr
The order of the obtained reduced order controller @var{Kr}.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'ncr'
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically such that states with
Hankel singular values @var{info.hsv} > @var{tol1} are retained.

@item 'method'
Order reduction approach to be used as follows:
@table @var
@item 'sr-bta', 'b'
Use the square-root Balance & Truncate method.
@item 'bfsr-bta', 'f'
Use the balancing-free square-root Balance & Truncate method.  Default method.
@item 'sr-spa', 's'
Use the square-root Singular Perturbation Approximation method.
@item 'bfsr-spa', 'p'
Use the balancing-free square-root Singular Perturbation Approximation method.
@end table

@item 'cf'
Specifies whether left or right coprime factorization is
to be used as follows:
@table @var
@item 'left', 'l'
Use left coprime factorization.  Default method.
@item 'right', 'r'
Use right coprime factorization.
@end table

@item 'feedback'
Specifies whether @var{F} and @var{L} are fed back positively or negatively:
@table @var
@item '+'
A+BK and A+LC are both Hurwitz matrices.
@item '-'
A-BK and A-LC are both Hurwitz matrices.  Default value.
@end table

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced system.
For model reduction, the recommended value of @var{tol1} is
c*info.hsv(1), where c lies in the interval [0.00001, 0.001].
Default value is n*eps*info.hsv(1).
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the coprime factorization controller.
TOL2 <= TOL1.
If not specified, n*eps*info.hsv(1) is chosen.

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on system @var{G} prior to order reduction.
Default value is true if @code{G.scaled == false} and
false if @code{G.scaled == true}.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

@strong{Algorithm}@*
Uses SLICOT SB16BD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section fwcfconred
@findex fwcfconred

@deftypefn{Function File} {[@var{Kr}, @var{info}] =} fwcfconred (@var{G}, @var{F}, @var{L}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} fwcfconred (@var{G}, @var{F}, @var{L}, @var{ncr}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} fwcfconred (@var{G}, @var{F}, @var{L}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} fwcfconred (@var{G}, @var{F}, @var{L}, @var{ncr}, @var{opt}, @dots{})

Reduction of state-feedback-observer based controller by frequency-weighted coprime factorization (FW CF).
Given a plant @var{G}, state feedback gain @var{F} and full observer gain @var{L},
determine a reduced order controller @var{Kr} by using stability enforcing frequency weights.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of the open-loop plant (A,B,C,D).
It has m inputs, p outputs and n states.
@item F
Stabilizing state feedback matrix (m-by-n).
@item L
Stabilizing observer gain matrix (n-by-p).
@item ncr
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Kr
State-space model of reduced order controller.
@item info
@table @var
@item info.hsv
The Hankel singular values of the extended system?!?.
The @var{n} Hankel singular values are ordered decreasingly.
@item info.ncr
The order of the obtained reduced order controller @var{Kr}.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'ncr'
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically such that states with
Hankel singular values @var{info.hsv} > @var{tol1} are retained.

@item 'method'
Order reduction approach to be used as follows:
@table @var
@item 'sr', 'b'
Use the square-root Balance & Truncate method.
@item 'bfsr', 'f'
Use the balancing-free square-root Balance & Truncate method.  Default method.
@end table

@item 'cf'
Specifies whether left or right coprime factorization is
to be used as follows:
@table @var
@item 'left', 'l'
Use left coprime factorization.
@item 'right', 'r'
Use right coprime factorization.  Default method.
@end table

@item 'feedback'
Specifies whether @var{F} and @var{L} are fed back positively or negatively:
@table @var
@item '+'
A+BK and A+LC are both Hurwitz matrices.
@item '-'
A-BK and A-LC are both Hurwitz matrices.  Default value.
@end table

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced system.
For model reduction, the recommended value of @var{tol1} is
c*info.hsv(1), where c lies in the interval [0.00001, 0.001].
Default value is n*eps*info.hsv(1).
If @var{'order'} is specified, the value of @var{tol1} is ignored.
@end table

@strong{Algorithm}@*
Uses SLICOT SB16CD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@section spaconred
@findex spaconred

@deftypefn{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @var{ncr}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @var{opt}, @dots{})
@deftypefnx{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @var{ncr}, @var{opt}, @dots{})

Controller reduction by frequency-weighted Singular Perturbation Approximation (SPA).
Given a plant @var{G} and a stabilizing controller @var{K}, determine a reduced
order controller @var{Kr} such that the closed-loop system is stable and closed-loop
performance is retained.

The algorithm tries to minimize the frequency-weighted error
@iftex
@tex
$$|| V \ (K - K_r) \ W ||_{\infty} = min$$
@end tex
@end iftex
@ifnottex
@example
||V (K-Kr) W||    = min
inf
@end example
@end ifnottex
where @var{V} and @var{W} denote output and input weightings.

@strong{Inputs}
@table @var
@item G
@acronym{LTI} model of the plant.
It has m inputs, p outputs and n states.
@item K
@acronym{LTI} model of the controller.
It has p inputs, m outputs and nc states.
@item ncr
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically according
to the description of key @var{'order'}.
@item @dots{}
Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item Kr
State-space model of reduced order controller.
@item info
@table @var
@item info.ncr
The order of the obtained reduced order controller @var{Kr}.
@item info.ncs
The order of the alpha-stable part of original controller @var{K}.
@item info.hsvc
The Hankel singular values of the alpha-stable part of @var{K}.
The @var{ncs} Hankel singular values are ordered decreasingly.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'order', 'ncr'
The desired order of the resulting reduced order controller @var{Kr}.
If not specified, @var{ncr} is chosen automatically such that states with
Hankel singular values @var{info.hsvc} > @var{tol1} are retained.

@item 'method'
Order reduction approach to be used as follows:
@table @var
@item 'sr', 's'
Use the square-root Singular Perturbation Approximation method.
@item 'bfsr', 'p'
Use the balancing-free square-root Singular Perturbation Approximation method.  Default method.
@end table

@item 'weight'
Specifies the type of frequency-weighting as follows:
@table @var
@item 'none'
No weightings are used (V = I, W = I).

@item 'left', 'output'
Use stability enforcing left (output) weighting
@iftex
@tex
$$V = (I - G K)^{-1} G, \qquad W = I$$
@end tex
@end iftex
@ifnottex
@example
-1
V = (I-G*K) *G ,  W = I
@end example
@end ifnottex

@item 'right', 'input'
Use stability enforcing right (input) weighting
@iftex
@tex
$$V = I, \qquad W = (I - G K)^{-1} G$$
@end tex
@end iftex
@ifnottex
@example
-1
V = I ,  W = (I-G*K) *G
@end example
@end ifnottex

@item 'both', 'performance'
Use stability and performance enforcing weightings
@iftex
@tex
$$V = (I - G K)^{-1} G, \qquad W = (I - G K)^{-1}$$
@end tex
@end iftex
@ifnottex
@example
-1                -1
V = (I-G*K) *G ,  W = (I-G*K)
@end example
@end ifnottex
Default value.
@end table

@item 'feedback'
Specifies whether @var{K} is a positive or negative feedback controller:
@table @var
@item '+'
Use positive feedback controller.  Default value.
@item '-'
Use negative feedback controller.
@end table

@item 'alpha'
Specifies the ALPHA-stability boundary for the eigenvalues
of the state dynamics matrix @var{K.A}.  For a continuous-time
controller, ALPHA <= 0 is the boundary value for
the real parts of eigenvalues, while for a discrete-time
controller, 0 <= ALPHA <= 1 represents the
boundary value for the moduli of eigenvalues.
The ALPHA-stability domain does not include the boundary.
Default value is 0 for continuous-time controllers and
1 for discrete-time controllers.

@item 'tol1'
If @var{'order'} is not specified, @var{tol1} contains the tolerance for
determining the order of the reduced controller.
For model reduction, the recommended value of @var{tol1} is
c*info.hsvc(1), where c lies in the interval [0.00001, 0.001].
Default value is info.ncs*eps*info.hsvc(1).
If @var{'order'} is specified, the value of @var{tol1} is ignored.

@item 'tol2'
The tolerance for determining the order of a minimal
realization of the ALPHA-stable part of the given
controller.  TOL2 <= TOL1.
If not specified, ncs*eps*info.hsvc(1) is chosen.

@item 'gram-ctrb'
Specifies the choice of frequency-weighted controllability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to standard Enns' method [1].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified Enns' method of [2].
@end table

@item 'gram-obsv'
Specifies the choice of frequency-weighted observability
Grammian as follows:
@table @var
@item 'standard'
Choice corresponding to standard Enns' method [1].  Default method.
@item 'enhanced'
Choice corresponding to the stability enhanced
modified Enns' method of [2].
@end table

@item 'equil', 'scale'
Boolean indicating whether equilibration (scaling) should be
performed on @var{G} and @var{K} prior to order reduction.
Default value is false if both @code{G.scaled == true, K.scaled == true}
and true otherwise.
Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
is of utmost importance.  The input and output scaling can @strong{not}
be done by the equilibration option or the @command{prescale} command
because these functions perform state transformations only.
Furthermore, signals should not be scaled simply to a certain range.
For all inputs (or outputs), a certain change should be of the same
importance for the model.
@end table

@strong{Algorithm}@*
Uses SLICOT SB16AD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}
@end deftypefn
@chapter Experimental Data Handling
@section iddata
@findex iddata

@deftypefn{Function File} {@var{dat} =} iddata (@var{y})
@deftypefnx{Function File} {@var{dat} =} iddata (@var{y}, @var{u})
@deftypefnx{Function File} {@var{dat} =} iddata (@var{y}, @var{u}, @var{tsam}, @dots{})
@deftypefnx{Function File} {@var{dat} =} iddata (@var{y}, @var{u}, @var{[]}, @dots{})
Create identification dataset of output and input signals.

@strong{Inputs}
@table @var
@item y
Real matrix containing the output signal in time-domain.
For a system with @var{p} outputs and @var{n} samples,
@var{y} is a n-by-p matrix.
For data from multiple experiments, @var{y} becomes a
e-by-1 or 1-by-e cell vector of n(i)-by-p matrices,
where @var{e} denotes the number of experiments
and n(i) the individual number of samples for each experiment.
@item u
Real matrix containing the input signal in time-domain.
For a system with @var{m} inputs and @var{n} samples,
@var{u} is a n-by-m matrix.
For data from multiple experiments, @var{u} becomes a
e-by-1 or 1-by-e cell vector of n(i)-by-m matrices,
where @var{e} denotes the number of experiments
and n(i) the individual number of samples for each experiment.
If @var{u} is not specified or an empty element @code{[]} is passed,
@var{dat} becomes a time series dataset.
@item tsam
Sampling time.  If not specified, default value -1 (unspecified) is taken.
For multi-experiment data, @var{tsam} becomes a
e-by-1 or 1-by-e cell vector containing individual
sampling times for each experiment.  If a scalar @var{tsam}
is provided, then all experiments have the same sampling time.
@item @dots{}
Optional pairs of properties and values.
@end table

@strong{Outputs}
@table @var
@item dat
iddata identification dataset.
@end table

@strong{Option Keys and Values}
@table @var
@item 'expname'
The name of the experiments in @var{dat}.
Cell vector of length e containing strings.
Default names are @code{@{'exp1', 'exp2', ...@}}

@item 'y'
Output signals.  See 'Inputs' for details.

@item 'outname'
The name of the output channels in @var{dat}.
Cell vector of length p containing strings.
Default names are @code{@{'y1', 'y2', ...@}}

@item 'outunit'
The units of the output channels in @var{dat}.
Cell vector of length p containing strings.

@item 'u'
Input signals.  See 'Inputs' for details.

@item 'inname'
The name of the input channels in @var{dat}.
Cell vector of length m containing strings.
Default names are @code{@{'u1', 'u2', ...@}}

@item 'inunit'
The units of the input channels in @var{dat}.
Cell vector of length m containing strings.

@item 'tsam'
Sampling time.  See 'Inputs' for details.

@item 'timeunit'
The units of the sampling times in @var{dat}.
Cell vector of length e containing strings.

@item 'name'
String containing the name of the dataset.

@item 'notes'
String or cell of string containing comments.

@item 'userdata'
Any data type.
@end table
@end deftypefn
@section @@iddata/cat
@findex cat

@deftypefn {Function File} {@var{dat} =} cat (@var{dim}, @var{dat1}, @var{dat2}, @dots{})
Concatenate iddata sets along dimension @var{dim}.

@strong{Inputs}
@table @var
@item dim
Dimension along which the concatenation takes place.
@table @var
@item 1
Concatenate samples.
The samples are concatenated in the following way:
@code{dat.y@{e@} = [dat1.y@{e@}; dat2.y@{e@}; @dots{}]}
@code{dat.u@{e@} = [dat1.u@{e@}; dat2.u@{e@}; @dots{}]}
where @var{e} denotes the experiment.
The number of experiments, outputs and inputs must be equal for all datasets.
Equivalent to @command{vertcat}.

@item 2
Concatenate inputs and outputs.
The outputs and inputs are concatenated in the following way:
@code{dat.y@{e@} = [dat1.y@{e@}, dat2.y@{e@}, @dots{}]}
@code{dat.u@{e@} = [dat1.u@{e@}, dat2.u@{e@}, @dots{}]}
where @var{e} denotes the experiment.
The number of experiments and samples must be equal for all datasets.
Equivalent to @command{horzcat}.

@item 3
Concatenate experiments.
The experiments are concatenated in the following way:
@code{dat.y = [dat1.y; dat2.y; @dots{}]}
@code{dat.u = [dat1.u; dat2.u; @dots{}]}
The number of outputs and inputs must be equal for all datasets.
Equivalent to @command{merge}.
@end table

@item dat1, dat2, @dots{}
iddata sets to be concatenated.
@end table

@strong{Outputs}
@table @var
@item dat
Concatenated iddata set.
@end table

@seealso{horzcat, merge, vertcat}
@end deftypefn
@section @@iddata/detrend
@findex detrend

@deftypefn {Function File} {@var{dat} =} detrend (@var{dat})
@deftypefnx {Function File} {@var{dat} =} detrend (@var{dat}, @var{ord})
Detrend outputs and inputs of dataset @var{dat} by
removing the best fit of a polynomial of order @var{ord}.
If @var{ord} is not specified, default value 0 is taken.
This corresponds to removing a constant.
@end deftypefn
@section @@iddata/diff
@findex diff

@deftypefn {Function File} {@var{dat} =} diff (@var{dat})
@deftypefnx {Function File} {@var{dat} =} diff (@var{dat}, @var{k})
Return @var{k}-th difference of outputs and inputs of dataset @var{dat}.
If @var{k} is not specified, default value 1 is taken.
@end deftypefn
@section @@iddata/fft
@findex fft

@deftypefn {Function File} {@var{dat} =} fft (@var{dat})
@deftypefnx {Function File} {@var{dat} =} fft (@var{dat}, @var{n})
Transform iddata objects from time to frequency domain
using a Fast Fourier Transform (FFT) algorithm.

@strong{Inputs}
@table @var
@item dat
iddata set containing signals in time-domain.
@item n
Length of the FFT transformations.  If @var{n} does not match
the signal length, the signals in @var{dat} are shortened or
padded with zeros.  @var{n} is a vector with as many elements
as there are experiments in @var{dat} or a scalar with a common
length for all experiments.
If not specified, the signal lengths are taken as default values.
@end table

@strong{Outputs}
@table @var
@item dat
iddata identification dataset in frequency-domain.
In order to preserve signal power and noise level,
the FFTs are normalized by dividing each transform
by the square root of the signal length.
The frequency values are distributed equally from 0
to the Nyquist frequency.  The Nyquist frequency is
only included for even signal lengths.
@end table

@end deftypefn
@section @@iddata/filter
@findex filter

@deftypefn {Function File} {@var{dat} =} filter (@var{dat}, @var{sys})
@deftypefnx {Function File} {@var{dat} =} filter (@var{dat}, @var{b}, @var{a})
Filter output and input signals of dataset @var{dat}.
The filter is specified either by @acronym{LTI} system @var{sys}
or by transfer function polynomials @var{b} and @var{a} as described
in the help text of the built-in filter command.  Type @code{help filter}

@strong{Inputs}
@table @var
@item dat
iddata identification dataset containing signals in time-domain.
@item sys
@acronym{LTI} object containing the discrete-time filter.
@item b
Numerator polynomial of the discrete-time filter.
Must be a row vector containing the coefficients
of the polynomial in ascending powers of z^-1.
@item a
Denominator polynomial of the discrete-time filter.
Must be a row vector containing the coefficients
of the polynomial in ascending powers of z^-1.
@end table

@strong{Outputs}
@table @var
@item dat
iddata identification dataset with filtered
output and input signals.
@end table

@end deftypefn
@section @@iddata/get
@findex get

@deftypefn {Function File} {} get (@var{dat})
@deftypefnx {Function File} {@var{value} =} get (@var{dat}, @var{"property"})
@deftypefnx {Function File} {[@var{val1}, @var{val2}, @dots{}] =} get (@var{dat}, @var{"prop1"}, @var{"prop2"}, @dots{})
Access property values of iddata objects.
Type @command{get(dat)} to display a list of available properties.
@end deftypefn
@section @@iddata/ifft
@findex ifft

@deftypefn {Function File} {@var{dat} =} ifft (@var{dat})
Transform iddata objects from frequency to time domain.

@strong{Inputs}
@table @var
@item dat
iddata set containing signals in frequency domain.
The frequency values must be distributed equally from 0
to the Nyquist frequency.  The Nyquist frequency is
only included for even signal lengths.
@end table

@strong{Outputs}
@table @var
@item dat
iddata identification dataset in time domain.
In order to preserve signal power and noise level,
the FFTs are normalized by multiplying each transform
by the square root of the signal length.
@end table

@end deftypefn
@section @@iddata/merge
@findex merge

@deftypefn {Function File} {@var{dat} =} merge (@var{dat1}, @var{dat2}, @dots{})
Concatenate experiments of iddata datasets.
The experiments are concatenated in the following way:
@code{dat.y = [dat1.y; dat2.y; @dots{}]}
@code{dat.u = [dat1.u; dat2.u; @dots{}]}
The number of outputs and inputs must be equal for all datasets.
@end deftypefn
@section @@iddata/nkshift
@findex nkshift

@deftypefn {Function File} {@var{dat} =} nkshift (@var{dat}, @var{nk})
@deftypefnx {Function File} {@var{dat} =} nkshift (@var{dat}, @var{nk}, @var{'append'})
Shift input channels of dataset @var{dat} according to integer @var{nk}.
A positive value of @var{nk} means that the input channels are delayed
@var{nk} samples.  By default, both input and output signals are shortened
by @var{nk} samples.
If a third argument @var{'append'} is passed, the output signals are left
untouched while @var{nk} zeros are appended to the (shortened) input signals
such that the number of samples in @var{dat} remains constant.
@end deftypefn
@section @@iddata/plot
@findex plot

@deftypefn {Function File} {} plot (@var{dat})
@deftypefnx {Function File} {} plot (@var{dat}, @var{exp})
Plot signals of iddata identification datasets on the screen.
The signals are plotted experiment-wise, either in time- or
frequency-domain.  For multi-experiment datasets,
press any key to switch to the next experiment.
If the plot of a single experiment should be saved by the
@command{print} command, use @code{plot(dat,exp)},
where @var{exp} denotes the desired experiment.
@end deftypefn
@section @@iddata/resample
@findex resample

@deftypefn {Function File} {@var{dat} =} resample (@var{dat}, @var{p}, @var{q})
@deftypefnx {Function File} {@var{dat} =} resample (@var{dat}, @var{p}, @var{q}, @var{n})
@deftypefnx {Function File} {@var{dat} =} resample (@var{dat}, @var{p}, @var{q}, @var{h})
Change the sample rate of the output and input signals in dataset @var{dat}
by a factor of @code{p/q}.  This is performed using a polyphase algorithm.
The anti-aliasing @acronym{FIR} filter can be specified as follows:
Either by order @var{n} (scalar) with default value 0.  The band edges
are then chosen automatically.  Or by impulse response @var{h} (vector).
Requires the signal package to be installed.

@strong{Algorithm}@*
Uses commands @command{fir1} and @command{resample}
from the signal package.

@strong{References}@*
[1] J. G. Proakis and D. G. Manolakis,
Digital Signal Processing: Principles, Algorithms, and Applications,
4th ed., Prentice Hall, 2007. Chap. 6

[2] A. V. Oppenheim, R. W. Schafer and J. R. Buck,
Discrete-time signal processing, Signal processing series,
Prentice-Hall, 1999

@end deftypefn
@section @@iddata/set
@findex set

@deftypefn {Function File} {} set (@var{dat})
@deftypefnx {Function File} {} set (@var{dat}, @var{"property"}, @var{value}, @dots{})
@deftypefnx {Function File} {@var{dat} =} set (@var{dat}, @var{"property"}, @var{value}, @dots{})
Set or modify properties of iddata objects.
If no return argument @var{dat} is specified, the modified @acronym{LTI} object is stored
in input argument @var{dat}.  @command{set} can handle multiple properties in one call:
@code{set (dat, 'prop1', val1, 'prop2', val2, 'prop3', val3)}.
@code{set (dat)} prints a list of the object's property names.
@end deftypefn
@section @@iddata/size
@findex size

@deftypefn {Function File} {@var{nvec} =} size (@var{dat})
@deftypefnx {Function File} {@var{ndim} =} size (@var{dat}, @var{dim})
@deftypefnx {Function File} {[@var{n}, @var{p}, @var{m}, @var{e}] =} size (@var{dat})
Return dimensions of iddata set @var{dat}.

@strong{Inputs}
@table @var
@item dat
iddata set.
@item dim
If given a second argument, @command{size} will return the size of the
corresponding dimension.
@end table

@strong{Outputs}
@table @var
@item nvec
Row vector.  The first element is the total number of samples (rows of dat.y and dat.u).
The second element is the number of outputs (columns of dat.y) and the third element
the number of inputs (columns of dat.u).  The fourth element is the number of experiments.
@item ndim
Scalar value.  The size of the dimension @var{dim}.
@item n
Row vector containing the number of samples of each experiment.
@item p
Number of outputs.
@item m
Number of inputs.
@item e
Number of experiments.
@end table
@end deftypefn
@chapter System Identification
@section arx
@findex arx

@deftypefn {Function File} {[@var{sys}, @var{x0}] =} arx (@var{dat}, @var{n}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}] =} arx (@var{dat}, @var{n}, @var{opt}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}] =} arx (@var{dat}, @var{opt}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}] =} arx (@var{dat}, @var{'na'}, @var{na}, @var{'nb'}, @var{nb})
Estimate ARX model using QR factorization.
@iftex
@tex
$$A(q) \, y(t) = B(q) \, u(t) \, + \, e(t)$$
@end tex
@end iftex
@ifnottex

@example
A(q) y(t) = B(q) u(t) + e(t)
@end example

@end ifnottex

@strong{Inputs}
@table @var
@item dat
iddata identification dataset containing the measurements, i.e. time-domain signals.
@item n
The desired order of the resulting model @var{sys}.
@item @dots{}
Optional pairs of keys and values.  @code{'key1', value1, 'key2', value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item sys
Discrete-time transfer function model.
If the second output argument @var{x0} is returned,
@var{sys} becomes a state-space model.
@item x0
Initial state vector.  If @var{dat} is a multi-experiment dataset,
@var{x0} becomes a cell vector containing an initial state vector
for each experiment.
@end table

@strong{Option Keys and Values}
@table @var
@item 'na'
Order of the polynomial A(q) and number of poles.

@item 'nb'
Order of the polynomial B(q)+1 and number of zeros+1.
@var{nb} <= @var{na}.

@item 'nk'
Input-output delay specified as number of sampling instants.
Scalar positive integer.  This corresponds to a call to command
@command{nkshift}, followed by padding the B polynomial with
@end table

@strong{Algorithm}@*
Uses the formulae given in [1] on pages 318-319,
'Solving for the LS Estimate by QR Factorization'.
For the initial conditions, SLICOT IB01CD is used by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@strong{References}@*
[1] Ljung, L. (1999)
@cite{System Identification: Theory for the User: Second Edition}.
Prentice Hall, New Jersey, USA.

@end deftypefn
@section moen4
@findex moen4

@deftypefn {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moen4 (@var{dat}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moen4 (@var{dat}, @var{n}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moen4 (@var{dat}, @var{opt}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moen4 (@var{dat}, @var{n}, @var{opt}, @dots{})
Estimate state-space model using combined subspace method:
@acronym{MOESP} algorithm for finding the matrices A and C,
and @acronym{N4SID} algorithm for finding the matrices B and D.
If no output arguments are given, the singular values are
plotted on the screen in order to estimate the system order.

@strong{Inputs}
@table @var
@item dat
iddata set containing the measurements, i.e. time-domain signals.
@item n
The desired order of the resulting state-space system @var{sys}.
If not specified, @var{n} is chosen automatically according
to the singular values and tolerances.
@item @dots{}
Optional pairs of keys and values.  @code{'key1', value1, 'key2', value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item sys
Discrete-time state-space model.
@item x0
Initial state vector.  If @var{dat} is a multi-experiment dataset,
@var{x0} becomes a cell vector containing an initial state vector
for each experiment.
@item info
@table @var
@item info.K
Kalman gain matrix.
@item info.Q
State covariance matrix.
@item info.Ry
Output covariance matrix.
@item info.S
State-output cross-covariance matrix.
@item info.L
Noise variance matrix factor. LL'=Ry.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'n'
The desired order of the resulting state-space system @var{sys}.
@var{s} > @var{n} > 0.

@item 's'
The number of block rows @var{s} in the input and output
block Hankel matrices to be processed.  @var{s} > 0.
In the MOESP theory, @var{s} should be larger than @var{n},
the estimated dimension of state vector.

@item 'alg', 'algorithm'
Specifies the algorithm for computing the triangular
factor R, as follows:
@table @var
@item 'C'
Cholesky algorithm applied to the correlation
matrix of the input-output data.  Default method.
@item 'F'
Fast QR algorithm.
@item 'Q'
QR algorithm applied to the concatenated block
Hankel matrices.
@end table

@item 'tol'
Absolute tolerance used for determining an estimate of
the system order.  If  @var{tol} >= 0,  the estimate is
indicated by the index of the last singular value greater
than or equal to @var{tol}.  (Singular values less than @var{tol}
are considered as zero.)  When  @var{tol} = 0,  an internally
computed default value,  @var{tol} = @var{s}*@var{eps}*SV(1),  is used,
where  SV(1)  is the maximal singular value, and @var{eps} is
the relative machine precision.
When @var{tol} < 0,  the estimate is indicated by the
index of the singular value that has the largest
logarithmic gap to its successor.  Default value is 0.

@item 'rcond'
The tolerance to be used for estimating the rank of
matrices. If the user sets @var{rcond} > 0,  the given value
of @var{rcond} is used as a lower bound for the reciprocal
condition number;  an m-by-n matrix whose estimated
condition number is less than  1/@var{rcond}  is considered to
be of full rank.  If the user sets @var{rcond} <= 0,  then an
implicitly computed, default tolerance, defined by
@var{rcond} = m*n*@var{eps},  is used instead, where @var{eps} is the
relative machine precision.  Default value is 0.

@item 'confirm'
Specifies whether or not the user's confirmation of the
system order estimate is desired, as follows:
@table @var
@item true
User's confirmation.
@item false
No confirmation.  Default value.
@end table

@item 'noiseinput'
The desired type of noise input channels.
@table @var
@item 'n'
No error inputs.  Default value.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k$$
$$y_k = C x_k + D u_k$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k]
y[k]   = C x[k] + D u[k]
@end example
@end ifnottex

@item 'e'
Return @var{sys} as a (p-by-m+p) state-space model with
both measured input channels u and noise channels e
with covariance matrix @var{Ry}.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k + K e_k$$
$$y_k = C x_k + D u_k + e_k$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k] + K e[k]
y[k]   = C x[k] + D u[k] +   e[k]
@end example
@end ifnottex

@item 'v'
Return @var{sys} as a (p-by-m+p) state-space model with
both measured input channels u and white noise channels v
with identity covariance matrix.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k + K L v_k$$
$$y_k = C x_k + D u_k + L v_k$$
$$e = L v, \ L L^T = R_y$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k] + K L v[k]
y[k]   = C x[k] + D u[k] +   L v[k]
e = L v,  L L' = Ry
@end example
@end ifnottex

@item 'k'
Return @var{sys} as a Kalman predictor for simulation.
@iftex
@tex
$$\widehat{x}_{k+1} = A \widehat{x}_k + B u_k + K (y_k - \widehat{y}_k)$$
$$\widehat{y}_k = C \widehat{x}_k + D u_k$$
@end tex
@end iftex
@ifnottex
@example
^          ^                        ^
x[k+1] = A x[k] + B u[k] + K(y[k] - y[k])
^          ^
y[k]   = C x[k] + D u[k]
@end example
@end ifnottex

@iftex
@tex
$$\widehat{x}_{k+1} = (A-KC) \widehat{x}_k + (B-KD) u_k + K y_k$$
$$\widehat{y}_k = C \widehat{x}_k + D u_k + 0 y_k$$
@end tex
@end iftex
@ifnottex
@example
^               ^
x[k+1] = (A-KC) x[k] + (B-KD) u[k] + K y[k]
^          ^
y[k]   = C x[k] + D u[k] + 0 y[k]
@end example
@end ifnottex
@end table
@end table

@strong{Algorithm}@*
Uses SLICOT IB01AD, IB01BD and IB01CD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@end deftypefn
@section moesp
@findex moesp

@deftypefn {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moesp (@var{dat}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moesp (@var{dat}, @var{n}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moesp (@var{dat}, @var{opt}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} moesp (@var{dat}, @var{n}, @var{opt}, @dots{})
Estimate state-space model using @acronym{MOESP} algorithm.
@acronym{MOESP}: Multivariable Output Error State sPace.
If no output arguments are given, the singular values are
plotted on the screen in order to estimate the system order.

@strong{Inputs}
@table @var
@item dat
iddata set containing the measurements, i.e. time-domain signals.
@item n
The desired order of the resulting state-space system @var{sys}.
If not specified, @var{n} is chosen automatically according
to the singular values and tolerances.
@item @dots{}
Optional pairs of keys and values.  @code{'key1', value1, 'key2', value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item sys
Discrete-time state-space model.
@item x0
Initial state vector.  If @var{dat} is a multi-experiment dataset,
@var{x0} becomes a cell vector containing an initial state vector
for each experiment.
@item info
@table @var
@item info.K
Kalman gain matrix.
@item info.Q
State covariance matrix.
@item info.Ry
Output covariance matrix.
@item info.S
State-output cross-covariance matrix.
@item info.L
Noise variance matrix factor. LL'=Ry.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'n'
The desired order of the resulting state-space system @var{sys}.
@var{s} > @var{n} > 0.

@item 's'
The number of block rows @var{s} in the input and output
block Hankel matrices to be processed.  @var{s} > 0.
In the MOESP theory, @var{s} should be larger than @var{n},
the estimated dimension of state vector.

@item 'alg', 'algorithm'
Specifies the algorithm for computing the triangular
factor R, as follows:
@table @var
@item 'C'
Cholesky algorithm applied to the correlation
matrix of the input-output data.  Default method.
@item 'F'
Fast QR algorithm.
@item 'Q'
QR algorithm applied to the concatenated block
Hankel matrices.
@end table

@item 'tol'
Absolute tolerance used for determining an estimate of
the system order.  If  @var{tol} >= 0,  the estimate is
indicated by the index of the last singular value greater
than or equal to @var{tol}.  (Singular values less than @var{tol}
are considered as zero.)  When  @var{tol} = 0,  an internally
computed default value,  @var{tol} = @var{s}*@var{eps}*SV(1),  is used,
where  SV(1)  is the maximal singular value, and @var{eps} is
the relative machine precision.
When @var{tol} < 0,  the estimate is indicated by the
index of the singular value that has the largest
logarithmic gap to its successor.  Default value is 0.

@item 'rcond'
The tolerance to be used for estimating the rank of
matrices. If the user sets @var{rcond} > 0,  the given value
of @var{rcond} is used as a lower bound for the reciprocal
condition number;  an m-by-n matrix whose estimated
condition number is less than  1/@var{rcond}  is considered to
be of full rank.  If the user sets @var{rcond} <= 0,  then an
implicitly computed, default tolerance, defined by
@var{rcond} = m*n*@var{eps},  is used instead, where @var{eps} is the
relative machine precision.  Default value is 0.

@item 'confirm'
Specifies whether or not the user's confirmation of the
system order estimate is desired, as follows:
@table @var
@item true
User's confirmation.
@item false
No confirmation.  Default value.
@end table

@item 'noiseinput'
The desired type of noise input channels.
@table @var
@item 'n'
No error inputs.  Default value.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k$$
$$y_k = C x_k + D u_k$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k]
y[k]   = C x[k] + D u[k]
@end example
@end ifnottex

@item 'e'
Return @var{sys} as a (p-by-m+p) state-space model with
both measured input channels u and noise channels e
with covariance matrix @var{Ry}.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k + K e_k$$
$$y_k = C x_k + D u_k + e_k$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k] + K e[k]
y[k]   = C x[k] + D u[k] +   e[k]
@end example
@end ifnottex

@item 'v'
Return @var{sys} as a (p-by-m+p) state-space model with
both measured input channels u and white noise channels v
with identity covariance matrix.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k + K L v_k$$
$$y_k = C x_k + D u_k + L v_k$$
$$e = L v, \ L L^T = R_y$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k] + K L v[k]
y[k]   = C x[k] + D u[k] +   L v[k]
e = L v,  L L' = Ry
@end example
@end ifnottex

@item 'k'
Return @var{sys} as a Kalman predictor for simulation.
@iftex
@tex
$$\widehat{x}_{k+1} = A \widehat{x}_k + B u_k + K (y_k - \widehat{y}_k)$$
$$\widehat{y}_k = C \widehat{x}_k + D u_k$$
@end tex
@end iftex
@ifnottex
@example
^          ^                        ^
x[k+1] = A x[k] + B u[k] + K(y[k] - y[k])
^          ^
y[k]   = C x[k] + D u[k]
@end example
@end ifnottex

@iftex
@tex
$$\widehat{x}_{k+1} = (A-KC) \widehat{x}_k + (B-KD) u_k + K y_k$$
$$\widehat{y}_k = C \widehat{x}_k + D u_k + 0 y_k$$
@end tex
@end iftex
@ifnottex
@example
^               ^
x[k+1] = (A-KC) x[k] + (B-KD) u[k] + K y[k]
^          ^
y[k]   = C x[k] + D u[k] + 0 y[k]
@end example
@end ifnottex
@end table
@end table

@strong{Algorithm}@*
Uses SLICOT IB01AD, IB01BD and IB01CD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@end deftypefn
@section n4sid
@findex n4sid

@deftypefn {Function File} {[@var{sys}, @var{x0}, @var{info}] =} n4sid (@var{dat}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} n4sid (@var{dat}, @var{n}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} n4sid (@var{dat}, @var{opt}, @dots{})
@deftypefnx {Function File} {[@var{sys}, @var{x0}, @var{info}] =} n4sid (@var{dat}, @var{n}, @var{opt}, @dots{})
Estimate state-space model using @acronym{N4SID} algorithm.
@acronym{N4SID}: Numerical algorithm for Subspace State Space System IDentification.
If no output arguments are given, the singular values are
plotted on the screen in order to estimate the system order.

@strong{Inputs}
@table @var
@item dat
iddata set containing the measurements, i.e. time-domain signals.
@item n
The desired order of the resulting state-space system @var{sys}.
If not specified, @var{n} is chosen automatically according
to the singular values and tolerances.
@item @dots{}
Optional pairs of keys and values.  @code{'key1', value1, 'key2', value2}.
@item opt
Optional struct with keys as field names.
Struct @var{opt} can be created directly or
by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
@end table

@strong{Outputs}
@table @var
@item sys
Discrete-time state-space model.
@item x0
Initial state vector.  If @var{dat} is a multi-experiment dataset,
@var{x0} becomes a cell vector containing an initial state vector
for each experiment.
@item info
@table @var
@item info.K
Kalman gain matrix.
@item info.Q
State covariance matrix.
@item info.Ry
Output covariance matrix.
@item info.S
State-output cross-covariance matrix.
@item info.L
Noise variance matrix factor. LL'=Ry.
@end table
@end table

@strong{Option Keys and Values}
@table @var
@item 'n'
The desired order of the resulting state-space system @var{sys}.
@var{s} > @var{n} > 0.

@item 's'
The number of block rows @var{s} in the input and output
block Hankel matrices to be processed.  @var{s} > 0.
In the MOESP theory, @var{s} should be larger than @var{n},
the estimated dimension of state vector.

@item 'alg', 'algorithm'
Specifies the algorithm for computing the triangular
factor R, as follows:
@table @var
@item 'C'
Cholesky algorithm applied to the correlation
matrix of the input-output data.  Default method.
@item 'F'
Fast QR algorithm.
@item 'Q'
QR algorithm applied to the concatenated block
Hankel matrices.
@end table

@item 'tol'
Absolute tolerance used for determining an estimate of
the system order.  If  @var{tol} >= 0,  the estimate is
indicated by the index of the last singular value greater
than or equal to @var{tol}.  (Singular values less than @var{tol}
are considered as zero.)  When  @var{tol} = 0,  an internally
computed default value,  @var{tol} = @var{s}*@var{eps}*SV(1),  is used,
where  SV(1)  is the maximal singular value, and @var{eps} is
the relative machine precision.
When @var{tol} < 0,  the estimate is indicated by the
index of the singular value that has the largest
logarithmic gap to its successor.  Default value is 0.

@item 'rcond'
The tolerance to be used for estimating the rank of
matrices. If the user sets @var{rcond} > 0,  the given value
of @var{rcond} is used as a lower bound for the reciprocal
condition number;  an m-by-n matrix whose estimated
condition number is less than  1/@var{rcond}  is considered to
be of full rank.  If the user sets @var{rcond} <= 0,  then an
implicitly computed, default tolerance, defined by
@var{rcond} = m*n*@var{eps},  is used instead, where @var{eps} is the
relative machine precision.  Default value is 0.

@item 'confirm'
Specifies whether or not the user's confirmation of the
system order estimate is desired, as follows:
@table @var
@item true
User's confirmation.
@item false
No confirmation.  Default value.
@end table

@item 'noiseinput'
The desired type of noise input channels.
@table @var
@item 'n'
No error inputs.  Default value.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k$$
$$y_k = C x_k + D u_k$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k]
y[k]   = C x[k] + D u[k]
@end example
@end ifnottex

@item 'e'
Return @var{sys} as a (p-by-m+p) state-space model with
both measured input channels u and noise channels e
with covariance matrix @var{Ry}.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k + K e_k$$
$$y_k = C x_k + D u_k + e_k$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k] + K e[k]
y[k]   = C x[k] + D u[k] +   e[k]
@end example
@end ifnottex

@item 'v'
Return @var{sys} as a (p-by-m+p) state-space model with
both measured input channels u and white noise channels v
with identity covariance matrix.
@iftex
@tex
$$x_{k+1} = A x_k + B u_k + K L v_k$$
$$y_k = C x_k + D u_k + L v_k$$
$$e = L v, \ L L^T = R_y$$
@end tex
@end iftex
@ifnottex
@example
x[k+1] = A x[k] + B u[k] + K L v[k]
y[k]   = C x[k] + D u[k] +   L v[k]
e = L v,  L L' = Ry
@end example
@end ifnottex

@item 'k'
Return @var{sys} as a Kalman predictor for simulation.
@iftex
@tex
$$\widehat{x}_{k+1} = A \widehat{x}_k + B u_k + K (y_k - \widehat{y}_k)$$
$$\widehat{y}_k = C \widehat{x}_k + D u_k$$
@end tex
@end iftex
@ifnottex
@example
^          ^                        ^
x[k+1] = A x[k] + B u[k] + K(y[k] - y[k])
^          ^
y[k]   = C x[k] + D u[k]
@end example
@end ifnottex

@iftex
@tex
$$\widehat{x}_{k+1} = (A-KC) \widehat{x}_k + (B-KD) u_k + K y_k$$
$$\widehat{y}_k = C \widehat{x}_k + D u_k + 0 y_k$$
@end tex
@end iftex
@ifnottex
@example
^               ^
x[k+1] = (A-KC) x[k] + (B-KD) u[k] + K y[k]
^          ^
y[k]   = C x[k] + D u[k] + 0 y[k]
@end example
@end ifnottex
@end table
@end table

@strong{Algorithm}@*
Uses SLICOT IB01AD, IB01BD and IB01CD by courtesy of
@uref{http://www.slicot.org, NICONET e.V.}

@end deftypefn
@section @@lti/ctranspose
@findex ctranspose

Conjugate transpose or pertransposition of @acronym{LTI} objects.
Used by Octave for "sys'".
For a transfer-function matrix G, G' denotes the conjugate
of G given by G.'(-s) for a continuous-time system or G.'(1/z)
for a discrete-time system.
The frequency response of the pertransposition of G is the
Hermitian (conjugate) transpose of G(jw), i.e.
freqresp (G', w) = freqresp (G, w)'.
@strong{WARNING:} Do @strong{NOT} use this for dual problems,
use the transpose "sys.'" (note the dot) instead.
@section @@lti/horzcat
@findex horzcat

Horizontal concatenation of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group.  Used by Octave for "[sys1, sys2]".
@section @@lti/inv
@findex inv

Inversion of @acronym{LTI} objects.
@section @@lti/minus
@findex minus

Binary subtraction of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group.  Used by Octave for "sys1 - sys2".
@section @@lti/mldivide
@findex mldivide

Matrix left division of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group in mtimes.  Used by Octave for "sys1 \ sys2".
@section @@lti/mpower
@findex mpower

Matrix power of @acronym{LTI} objects.  The exponent must be an integer.
Used by Octave for "sys^int".
@section @@lti/mrdivide
@findex mrdivide

Matrix right division of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group in mtimes.  Used by Octave for "sys1 / sys2".
@section @@lti/mtimes
@findex mtimes

Matrix multiplication of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group.  Used by Octave for "sys1 * sys2".
@section @@lti/plus
@findex plus

Binary addition of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group.  Used by Octave for "sys1 + sys2".
Operation is also known as "parallel connection".
@section @@lti/subsasgn
@findex subsasgn

Subscripted assignment for @acronym{LTI} objects.
Used by Octave for "sys.property = value".
@section @@lti/subsref
@findex subsref

Subscripted reference for @acronym{LTI} objects.
Used by Octave for "sys = sys(2:4, :)" or "val = sys.prop".
@section @@lti/transpose
@findex transpose

Transpose of @acronym{LTI} objects.  Used by Octave for "sys.'".
Useful for dual problems, i.e. controllability and observability
or designing estimator gains with @command{lqr} and @command{place}.
@section @@lti/uminus
@findex uminus

Unary minus of @acronym{LTI} object.  Used by Octave for "-sys".
@section @@lti/uplus
@findex uplus

Unary plus of @acronym{LTI} object.  Used by Octave for "+sys".
@section @@lti/vertcat
@findex vertcat

Vertical concatenation of @acronym{LTI} objects.  If necessary, object conversion
is done by sys_group.  Used by Octave for "[sys1; sys2]".
@section @@iddata/horzcat
@findex horzcat

@deftypefn {Function File} {@var{dat} =} horzcat (@var{dat1}, @var{dat2}, @dots{})
Horizontal concatenation of iddata datasets.
The outputs and inputs are concatenated in the following way:
@code{dat.y@{e@} = [dat1.y@{e@}, dat2.y@{e@}, @dots{}]}
@code{dat.u@{e@} = [dat1.u@{e@}, dat2.u@{e@}, @dots{}]}
where @var{e} denotes the experiment.
The number of experiments and samples must be equal for all datasets.
@end deftypefn
@section @@iddata/subsasgn
@findex subsasgn

Subscripted assignment for iddata objects.
Used by Octave for "dat.property = value".
@section @@iddata/subsref
@findex subsref

Subscripted reference for iddata objects.
Used by Octave for "dat = dat(2:4, :)" or "val = dat.prop".
@section @@iddata/vertcat
@findex vertcat

@deftypefn {Function File} {@var{dat} =} vertcat (@var{dat1}, @var{dat2}, @dots{})
Vertical concatenation of iddata datasets.
The samples are concatenated in the following way:
@code{dat.y@{e@} = [dat1.y@{e@}; dat2.y@{e@}; @dots{}]}
@code{dat.u@{e@} = [dat1.u@{e@}; dat2.u@{e@}; @dots{}]}
where @var{e} denotes the experiment.
The number of experiments, outputs and inputs must be equal for all datasets.
@end deftypefn
@chapter Miscellaneous
@section options
@findex options

@deftypefn{Function File} {@var{opt} =} options (@var{"key1"}, @var{value1}, @var{"key2"}, @var{value2}, @dots{})
Create options struct @var{opt} from a number of key and value pairs.
For use with order reduction commands.

@strong{Inputs}
@table @var
@item key, property
The name of the property.
@item value
The value of the property.
@end table

@strong{Outputs}
@table @var
@item opt
Struct with fields for each key.
@end table

@strong{Example}
@example
@group
octave:1> opt = options ("method", "spa", "tol", 1e-6)
opt =

scalar structure containing the fields:

method = spa
tol =  1.0000e-06

@end group
@end example
@example
@group
octave:2> save filename opt
octave:3> # save the struct 'opt' to file 'filename' for later use
octave:5> # load struct 'opt' from file 'filename'
@end group
@end example

@end deftypefn
@section strseq
@findex strseq

@deftypefn {Function File} {@var{strvec} =} strseq (@var{str}, @var{idx})
Return a cell vector of indexed strings by appending the indices @var{idx}
to the string @var{str}.

@example
strseq ("x", 1:3) = @{"x1"; "x2"; "x3"@}
strseq ("u", [1, 2, 5]) = @{"u1"; "u2"; "u5"@}
@end example
@end deftypefn
@section test_control
@findex test_control

@deftypefn {Script File} {} test_control
Execute all available tests at once.
The Octave control package is based on the @uref{http://www.slicot.org, @acronym{SLICOT}} library.
@acronym{SLICOT} needs @acronym{BLAS} and @acronym{LAPACK} libraries which are also prerequisites
for Octave itself.
In case of failing tests, it is highly recommended to use
@uref{http://www.netlib.org/blas/, Netlib's reference @acronym{BLAS}} and
@uref{http://www.netlib.org/lapack/, @acronym{LAPACK}}
for building Octave.  Using @acronym{ATLAS} may lead to sign changes
in some entries of the state-space matrices.
In general, these sign changes are not 'wrong' and can be regarded as
the result of state transformations.  Such state transformations
(but not input/output transformations) have no influence on the
input-output behaviour of the system.  For better numerics,
the control package uses such transformations by default when
calculating the frequency responses and a few other things.
However, arguments like the Hankel singular Values (@acronym{HSV}) must not change.
Differing @acronym{HSV}s and failing algorithms are known for using Framework Accelerate
from Mac OS X 10.7.
@end deftypefn
@section BMWengine
@findex BMWengine

@deftypefn{Function File} {@var{sys} =} BMWengine ()
@deftypefnx{Function File} {@var{sys} =} BMWengine (@var{"scaled"})
@deftypefnx{Function File} {@var{sys} =} BMWengine (@var{"unscaled"})
Model of the BMW 4-cylinder engine at ETH Zurich's control laboratory.
@example
@group
OPERATING POINT
Saugrohrdruck              p_s = 0.48 bar
Motordrehzahl              n = 860 U/min
Lambda-Messwert            lambda = 1.000
Relativer Wandfilminhalt   nu = 1
@end group
@end example
@example
@group
INPUTS
U_2 Relative Einspritzmenge             [-]
M_L Lastdrehmoment                      [Nm]
@end group
@end example
@example
@group
STATES
X_2 Saugrohrdruck              [bar]
X_3 Motordrehzahl              [U/min]
X_4 Messwert Lamba-Sonde       [-]
X_5 Relativer Wandfilminhalt   [-]
@end group
@end example
@example
@group
OUTPUTS
Y_1 Motordrehzahl              [U/min]
Y_2 Messwert Lambda-Sonde      [-]
@end group
@end example
@example
@group
SCALING
U_2N, X_4N, X_5N, Y_2N   0.05
X_2N   0.05 bar
X_3N, Y_1N   200 U/min
@end group
@end example
@end deftypefn
@section Boeing707
@findex Boeing707

@deftypefn {Function File} {@var{sys} =} Boeing707 ()
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
@ifnottex
(@var{M} = 0.26, @var{Ga0} = -3 deg, @var{alpha0} = 4 deg, @var{kappa} = 50 deg).
@end ifnottex

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
@section WestlandLynx
@findex WestlandLynx

@deftypefn{Function File} {@var{sys} =} WestlandLynx ()
Model of the Westland Lynx Helicopter about hover.
@example
@group
INPUTS
main rotor collective
longitudinal cyclic
lateral cyclic
tail rotor collective
@end group
@end example
@example
@group
STATES
forward velocity         v_x         [ft/s]
lateral velocity         v_y         [ft/s]
vertical velocity        v_z         [ft/s]
@end group
@end example
@example
@group
OUTPUTS
heave velocity           H_dot       [ft/s]