@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.
@section Madievski
@findex Madievski

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

 @deftypefn{Function File} {} VLFamp
 @deftypefnx{Function File} {@var{result} =} VLFamp (@var{verbose})
 Calculations on a two stage preamp for a multi-turn,
 air-core solenoid loop antenna for the reception of
 signals below 30kHz.

 The Octave Control Package functions are used extensively to
 approximate the behavior of operational amplifiers and passive
 electrical circuit elements.

 This example presents several 'screen' pages of documentation of the
 calculations and some reasoning about why.  Plots of the results are
 presented in most cases.

 The process is to display a 'screen' page of text followed by the
 calculation and a 'Press return to continue' message.  To proceed in
 the example, press return.  ^C to exit.

 At one point in the calculations, the process may seem to hang, but,
 this is because of extensive calculations.

 The returned transfer function is more than 100 characters long so
 will wrap in screens that are narrow and appear jumbled.
 @end deftypefn
@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}, @dots{})
 @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.
 Type @command{set (dss)} for more information.
 @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 'ingroup'
 Struct with input group names as field names and
 vectors of input indices as field values.
 Default is an empty struct.

 @item 'outgroup'
 Struct with output group names as field names and
 vectors of output indices as field values.
 Default is an empty struct.

 @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.
 Type @command{set (filt)} for more information.
 @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 'ingroup'
 Struct with input group names as field names and
 vectors of input indices as field values.
 Default is an empty struct.

 @item 'outgroup'
 Struct with output group names as field names and
 vectors of output indices as field values.
 Default is an empty struct.

 @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
 Frequency vector (lw-by-1) in radian per second [rad/s].
 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.
 Type @command{set (frd)} for more information.
 @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 'ingroup'
 Struct with input group names as field names and
 vectors of input indices as field values.
 Default is an empty struct.

 @item 'outgroup'
 Struct with output group names as field names and
 vectors of output indices as field values.
 Default is an empty struct.

 @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}, @dots{})
 @deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @dots{})
 @deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c}, @dots{})
 @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.
 Type @command{set (ss)} for more information.
 @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 'ingroup'
 Struct with input group names as field names and
 vectors of input indices as field values.
 Default is an empty struct.

 @item 'outgroup'
 Struct with output group names as field names and
 vectors of output indices as field values.
 Default is an empty struct.

 @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
 .
 x = A x + B u
 y = C x + D u
 @end group
 @end example

 @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{mat}, @dots{})
 @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 mat
 Gain matrix to be converted to static 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.
 Type @command{set (tf)} for more information.
 @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 'ingroup'
 Struct with input group names as field names and
 vectors of input indices as field values.
 Default is an empty struct.

 @item 'outgroup'
 Struct with output group names as field names and
 vectors of output indices as field values.
 Default is an empty struct.

 @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}, @dots{})
 @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.
 Type @command{set (tf)} for more information.
 @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
 Frequency vector (lw-by-1) in radian per second [rad/s].
 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{"key"})
 @deftypefnx {Function File} {[@var{val1}, @var{val2}, @dots{}] =} get (@var{sys}, @var{"key1"}, @var{"key2"}, @dots{})
 Access key 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{"key"}, @var{value}, @dots{})
 @deftypefnx {Function File} {@var{retsys} =} set (@var{sys}, @var{"key"}, @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, 'key1', val1, 'key2', val2, 'key3', val3)}.
 @code{set (sys)} prints a list of the object's key 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/d2d
@findex d2d

 @deftypefn {Function File} {@var{sys} =} d2d (@var{sys}, @var{tsam})
 @deftypefnx {Function File} {@var{sys} =} d2d (@var{sys}, @var{tsam}, @var{method})
 @deftypefnx {Function File} {@var{sys} =} d2d (@var{sys}, @var{tsam}, @var{'prewarp'}, @var{w0})
 Resample discrete-time @acronym{LTI} model to sampling time @var{tsam}.

 @strong{Inputs}
 @table @var
 @item sys
 Discrete-time @acronym{LTI} model.
 @item tsam
 Desired 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 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
 Resampled discrete-time @acronym{LTI} model with sampling time @var{tsam}.
 @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
 Structure containing additional information.
 @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{retsys} =} xperm (@var{sys}, @var{idx})
 Reorder states in state-space models.

 @strong{Inputs}
 @table @var
 @item sys
 State-space model.
 @item idx
 Vector containing the state indices in the desired order.
 Alternatively, a cell vector containing the state names
 is possible as well.  See @code{sys.stname}.  State names
 only work if they were assigned explicitly before, i.e.
 @code{sys.stname} contains no empty strings.
 Note that if certain state indices of @var{sys} are
 missing or appear multiple times in @var{idx}, these
 states will be pruned or duplicated accordingly in the
 resulting state-space model @var{retsys}.
 @end table

 @strong{Outputs}
 @table @var
 @item retsys
 Resulting state-space model with states reordered according to @var{idx}.
 @end table

 @end deftypefn
@chapter Model Interconnections
@section append
@findex append

 @deftypefn {Function File} {@var{sys} =} append (@var{sys1}, @var{sys2}, @dots{}, @var{sysN})
 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}, @dots{}, @var{sysN})
 Block-diagonal concatenation of @acronym{LTI} models.
 @end deftypefn
@section @@lti/connect
@findex connect

 @deftypefn {Function File} {@var{sys} =} connect (@var{sys1}, @var{sys2}, @dots{}, @var{sysN}, @var{inputs}, @var{outputs})
 @deftypefnx {Function File} {@var{sys} =} connect (@var{sys}, @var{cm}, @var{inputs}, @var{outputs})
 Name-based or index-based interconnections between the inputs and outputs of @acronym{LTI} models.
 
 @strong{Inputs}
 @table @var
 @item sys1, @dots{}, sysN
 @acronym{LTI} models to be connected.  The properties 'inname' and 'outname'
 of each model should be set according to the desired input-output connections.
 @item inputs
 For name-based interconnections, string or cell of strings containing the names
 of the inputs to be kept.  The names must be part of the properties 'ingroup' or
 'inname'.  For index-based interconnections, vector containing the indices of the
 inputs to be kept.
 @item outputs
 For name-based interconnections, string or cell of strings containing the names
 of the outputs to be kept.  The names must be part of the properties 'outgroup' 
 or 'outname'.  For index-based interconnections, vector containing the indices of
 the outputs to be kept.
 @item cm
 Connection matrix (not name-based).  Each row of the matrix represents a summing
 junction.  The first column holds the indices of the inputs to be summed with
 outputs of the subsequent columns.  The output indices can be negative, if the output
 is to be substracted, or zero.  For example, the row
 @example
 [2 0 3 -4 0]
 @end example
 or
 @example
 [2 -4 3]
 @end example
 will sum input u(2) with outputs y(3) and y(4) as
 @example
 u(2) + y(3) - y(4).
 @end example
 @end table

 @strong{Outputs}
 @table @var
 @item sys
 Resulting interconnected system with outputs @var{outputs} and
 inputs @var{inputs}.
 @end table

 @seealso{sumblk}
 @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
@section sumblk
@findex sumblk

 @deftypefn{Function File} {@var{S} =} sumblk (@var{formula})
 @deftypefnx{Function File} {@var{S} =} sumblk (@var{formula}, @var{n})
 Create summing junction @var{S} from string @var{formula}
 for name-based interconnections.

 @strong{Inputs}
 @table @var
 @item formula
 String containing the formula of the summing junction,
 e.g. @code{e = r - y + d} 
 @item n
 Signal size.  Default value is 1.
 @end table

 @strong{Outputs}
 @table @var
 @item S
 State-space model of the summing junction.
 @end table

 @strong{Example}
 @example
 @group
 octave:1> S = sumblk ('e = r - y + d')
 
 S.d =
        r   y   d
    e   1  -1   1
 
 Static gain.
 octave:2> S = sumblk ('e = r - y + d', 2)
 
 S.d =
        r1  r2  y1  y2  d1  d2
    e1   1   0  -1   0   1   0
    e2   0   1   0  -1   0   1
 
 Static gain.
 @end group
 @end example
 @seealso{connect}
 @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 has asymptotically stable zero dynamics.
 According to the definition of Byrnes/Isidori [1], the zeros
 of a minimum-phase system must be strictly
 inside the left complex half-plane (continuous-time case)
 or inside the unit circle (discrete-time case).
 Note that the poles are not tested.

 M. Zeitz [2] discusses the inconsistent definitions of the minimum-phase property
 in a German paper.  The abstract in English states the following [2]:
 
 Originally, the minimum phase property has been defined by H. W. Bode [3]
 in order to characterize the unique relationship between gain and phase of
 the frequency response.
 With regard to the design of digital filters, another definition of minimum
 phase is used and a filter is said to be minimum phase if both the filter
 and its inverse are asymptotically stable.
 Finally, systems with asymptotically stable zero dynamics are named as
 minimum phase by C. I. Byrnes and A. Isidori [1].
 Due to the inconsistent definitions, avoiding the minimum phase property
 for control purposes is advocated and the well-established criteria of
 Hurwitz or Ljapunow to describe the stability of filters and zero dynamics
 are recommended.
 
 @strong{Inputs}
 @table @var
 @item sys
 @acronym{LTI} system.
 @item tol
 Optional tolerance.
 @var{tol} must be a real-valued, non-negative scalar.
 Default value is 0.
 @end table

 @strong{Outputs}
 @table @var
 @item bool
 True if the system is minimum-phase and false otherwise.
 @end table

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

 @strong{References}@*
 [1] Byrnes, C.I. and Isidori, A.
 @cite{A Frequency Domain Philosophy for Nonlinear Systems}.
 IEEE Conf. Dec. Contr. 23, pp. 1569–1573, 1984.

 [2] Zeitz, M.
 @cite{Minimum phase – no relevant property of automatic control!}.
 at – Automatisierungstechnik. Volume 62, Issue 1, pp. 3–10, 2014.

 [3] Bode, H.W.
 @cite{Network Analysis and Feedback Amplifier Design}.
 D. Van Nostrand Company, pp. 312-318, 1945.
 pp. 341-351, 1992.
 @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.
 @var{tol} must be a real-valued, non-negative scalar.
 Default value is 0.
 @end table

 @strong{Outputs}
 @table @var
 @item bool
 True if the system is stable and false otherwise.
 @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
 Invariant 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})
 Return the steady-state covariance.

 @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
 in rad/s.
 @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
 in rad/s.
 @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 function @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 function @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
 in rad/s.
 @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
 in rad/s.
 @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 function
 @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, function @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
 in rad/s.
 @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
 Structure containing additional information.
 @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.
 Note the positive sign in @code{A + B*F}.
 @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 augstate
@findex augstate

 @deftypefn {Function File} {@var{augsys} =} augstate (@var{sys})
 Append state vector x of system @var{sys} to output vector y.

 @example
 @group
 .                  .
 x = A x + B u      x = A x + B u
 y = C x + D u  =>  y = C x + D u
                    x = I x + O u
 @end group
 @end example

 @end deftypefn
@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})
 Linear-quadratic regulator for discrete-time systems.

 @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 (w).  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

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

 @seealso{kalman, lqe, 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})
 Linear-quadratic regulator.

 @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{gamma}, @var{info}] =} h2syn (@var{P}, @var{nmeas}, @var{ncon})
 @deftypefnx{Function File} {[@var{K}, @var{N}, @var{gamma}, @var{info}] =} h2syn (@var{P})
 H-2 control synthesis for @acronym{LTI} plant.

 @strong{Inputs}
 @table @var
 @item P
 Generalized plant.  Must be a proper/realizable @acronym{LTI} model.
 If @var{P} is constructed with @command{mktito} or @command{augw},
 arguments @var{nmeas} and @var{ncon} can be omitted.
 @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
 Structure containing additional information.
 @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{gamma}, @var{info}] =} hinfsyn (@var{P}, @var{nmeas}, @var{ncon})
 @deftypefnx{Function File} {[@var{K}, @var{N}, @var{gamma}, @var{info}] =} hinfsyn (@var{P}, @var{nmeas}, @var{ncon}, @dots{})
 @deftypefnx{Function File} {[@var{K}, @var{N}, @var{gamma}, @var{info}] =} hinfsyn (@var{P}, @var{nmeas}, @var{ncon}, @var{opt}, @dots{})
 @deftypefnx{Function File} {[@var{K}, @var{N}, @var{gamma}, @var{info}] =} hinfsyn (@var{P}, @dots{})
 @deftypefnx{Function File} {[@var{K}, @var{N}, @var{gamma}, @var{info}] =} hinfsyn (@var{P}, @var{opt}, @dots{})
 H-infinity control synthesis for @acronym{LTI} plant.

 @strong{Inputs}
 @table @var
 @item P
 Generalized plant.  Must be a proper/realizable @acronym{LTI} model.
 If @var{P} is constructed with @command{mktito} or @command{augw},
 arguments @var{nmeas} and @var{ncon} can be omitted.
 @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 @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 function @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
 @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
 Structure containing additional information.
 @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{Option Keys and Values}
 @table @var
 @item 'method'
 String specifying the desired kind of controller:
 @table @var
 @item 'optimal', 'opt', 'o'
 Compute optimal controller using gamma iteration.
 Default selection for compatibility reasons.
 @item 'suboptimal', 'sub', 's'
 Compute (sub-)optimal controller.  For stability reasons,
 suboptimal controllers are to be preferred over optimal ones.
 @end table
 @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.  Default value is 1e15.
 @item 'gmin'
 Initial lower bound for gamma iteration.  Default value is 0.
 @var{gmin} is only meaningful for optimal discrete-time controllers.
 @item 'tolgam'
 Tolerance used for controlling the accuracy of @var{gamma}
 and its distance to the estimated minimal possible
 value of @var{gamma}.  Default value is 0.01.
 If @var{tolgam} = 0, then a default value equal to @code{sqrt(eps)}
 is used, where @var{eps} is the relative machine precision.
 For suboptimal controllers, @var{tolgam} is ignored.
 @item 'actol'
 Upper bound for the poles of the closed-loop system @var{N}
 used for determining if it is stable.
 @var{actol} >= 0 for stable systems.
 For suboptimal controllers, @var{actol} is ignored.
 @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, SB10DD and SB10AD 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{gamma}, @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{}
 Optional arguments of @command{hinfsyn}.  Type @command{help hinfsyn} for more information.
 @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
 Structure containing additional information.
 @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 functions @command{augw} and @command{hinfsyn},
 which use SLICOT SB10FD, SB10DD and SB10AD 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 mktito
@findex mktito

 @deftypefn{Function File} {@var{P} =} mktito (@var{P}, @var{nmeas}, @var{ncon})
 Partition @acronym{LTI} plant @var{P} for robust controller synthesis.
 If a plant is partitioned this way, one can omit the inputs @var{nmeas}
 and @var{ncon} when calling the functions @command{hinfsyn} and @command{h2syn}.

 @strong{Inputs}
 @table @var
 @item P
 Generalized plant.
 @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/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.
 @end table

 @strong{Outputs}
 @table @var
 @item P
 Partitioned plant.  The input/output groups and names are overwritten with designations
 according to [1].
 @end table

 @strong{Block Diagram}
 @example
 @group

 min||N(K)||             N = lft (P, K)
  K         norm

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

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

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

 @end deftypefn
@section ncfsyn
@findex ncfsyn

 @deftypefn{Function File} {[@var{K}, @var{N}, @var{gamma}, @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.
 Note that @var{K} is a @emph{positive} feedback controller.
 @item N
 State-space model of the closed loop depicted below.
 @item info
 Structure containing additional information.
 @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 function @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
 @end table

 @strong{Outputs}
 @table @var
 @item Gr
 Reduced order state-space model.
 @item info
 Struct containing additional information.
 @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} function
 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 function @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
 @end table

 @strong{Outputs}
 @table @var
 @item Gr
 Reduced order state-space model.
 @item info
 Struct containing additional information.
 @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} function
 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 function @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
 @end table

 @strong{Outputs}
 @table @var
 @item Gr
 Reduced order state-space model.
 @item info
 Struct containing additional information.
 @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} function
 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 function @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
 @end table

 @strong{Outputs}
 @table @var
 @item Gr
 Reduced order state-space model.
 @item info
 Struct containing additional information.
 @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} function
 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 function @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
 Struct containing additional information.
 @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} function
 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 function @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
 Struct containing additional information.
 @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} function
 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 function @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
 Struct containing additional information.
 @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 function @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
 Struct containing additional information.
 @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} function
 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 Octave's built-in filter function.  Type @code{help filter}
 for more information.

 @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{'key'})
 @deftypefnx {Function File} {[@var{val1}, @var{val2}, @dots{}] =} get (@var{dat}, @var{'key1'}, @var{'key2'}, @dots{})
 Access key values of iddata objects.
 Type @command{get(dat)} to display a list of available keys.
 @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 functions @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{'key'}, @var{value}, @dots{})
 @deftypefnx {Function File} {@var{dat} =} set (@var{dat}, @var{'key'}, @var{value}, @dots{})
 Set or modify keys of iddata objects.
 If no return argument @var{dat} is specified, the modified @acronym{IDDATA} object is stored
 in input argument @var{dat}.  @command{set} can handle multiple keys in one call:
 @code{set (dat, 'key1', val1, 'key2', val2, 'key3', val3)}.
 @code{set (dat)} prints a list of the object's key 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 function @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 function
 @command{nkshift}, followed by padding the B polynomial with
 @var{nk} leading zeros.
 @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 function @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
 Struct containing additional information.
 @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 function @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
 Struct containing additional information.
 @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 function @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
 Struct containing additional information.
 @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
@chapter Overloaded LTI Operators
@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/end
@findex end

 End indexing for @acronym{LTI} objects.
 Used by Octave for "sys(1:end, end-1)".
@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/repmat
@findex repmat

 @deftypefn {Function File} {@var{rsys} =} repmat (@var{sys}, @var{m}, @var{n})
 @deftypefnx {Function File} {@var{rsys} =} repmat (@var{sys}, [@var{m}, @var{n}])
 @deftypefnx {Function File} {@var{rsys} =} repmat (@var{sys}, @var{m})
 Form a block transfer matrix of @var{sys} with @var{m} copies vertically
 and @var{n} copies horizontally.  If @var{n} is not specified, it is set to @var{m}.
 @code{repmat (sys, 2, 3)} is equivalent to @code{[sys, sys, sys; sys, sys, sys]}.
 @end deftypefn
@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/times
@findex times

 Hadamard/Schur product of transfer function matrices.
 Also known as element-wise multiplication.
 Used by Octave for "sys1 .* sys2".@*
 @strong{Example}
 @example
 @group
 # Compute Relative-Gain Array
 G = tf (Boeing707)
 RGA = G .* inv (G).'
 # Gain at 0 rad/s
 RGA(0)
 @end group
 @end example
@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]".
@chapter Overloaded IDDATA Operators
@section @@iddata/end
@findex end

 End indexing for @acronym{IDDATA} objects.
 Used by Octave for "dat(1:end)".
@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 db2mag
@findex db2mag

 @deftypefn {Function File} {@var{mag} =} db2mag (@var{db})
 Convert Decibels (dB) to Magnitude.

 @strong{Inputs}
 @table @var
 @item db
 Decibel (dB) value(s).  Both real-valued scalars and matrices are accepted.
 @end table

 @strong{Outputs}
 @table @var
 @item mag
 Magnitude value(s).
 @end table

 @seealso{mag2db}
 @end deftypefn
@section mag2db
@findex mag2db

 @deftypefn {Function File} {@var{db} =} mag2db (@var{mag})
 Convert Magnitude to Decibels (dB).

 @strong{Inputs}
 @table @var
 @item mag
 Magnitude value(s).  Both real-valued scalars and matrices are accepted.
 @end table

 @strong{Outputs}
 @table @var
 @item db
 Decibel (dB) value(s).
 @end table

 @seealso{db2mag}
 @end deftypefn
@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 and system identification functions.
 Option structs are a way to avoid typing the same key and value pairs
 over and over again.

 @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:4> load filename
 octave:5> # load struct 'opt' from file 'filename'
 @end group
 @end example

 @end deftypefn
@section pid
@findex pid

 @deftypefn{Function File} {@var{C} =} pid (@var{Kp})
 @deftypefnx{Function File} {@var{C} =} pid (@var{Kp}, @var{Ki})
 @deftypefnx{Function File} {@var{C} =} pid (@var{Kp}, @var{Ki}, @var{Kd})
 @deftypefnx{Function File} {@var{C} =} pid (@var{Kp}, @var{Ki}, @var{Kd}, @var{Tf})
 Return the transfer function @var{C} of the @acronym{PID} controller
 in parallel form with first-order roll-off.

 @example
 @group
              Ki      Kd s
 C(s) = Kp + ---- + --------
              s     Tf s + 1
 @end group
 @end example
 @end deftypefn
@section pidstd
@findex pidstd

 @deftypefn{Function File} {@var{C} =} pidstd (@var{Kp})
 @deftypefnx{Function File} {@var{C} =} pidstd (@var{Kp}, @var{Ti})
 @deftypefnx{Function File} {@var{C} =} pidstd (@var{Kp}, @var{Ti}, @var{Td})
 @deftypefnx{Function File} {@var{C} =} pidstd (@var{Kp}, @var{Ti}, @var{Td}, @var{N})
 Return the transfer function @var{C} of the @acronym{PID} controller
 in standard form with first-order roll-off.

 @example
 @group
                 1        Td s
 C(s) = Kp (1 + ---- + ----------)
                Ti s   Td/N s + 1
 @end group
 @end example
 @end deftypefn
@section repsys
@findex repsys

 @deftypefn {Function File} {@var{rsys} =} repsys (@var{sys}, @var{m}, @var{n})
 @deftypefnx {Function File} {@var{rsys} =} repsys (@var{sys}, [@var{m}, @var{n}])
 @deftypefnx {Function File} {@var{rsys} =} repsys (@var{sys}, @var{m})
 Form a block transfer matrix of @var{sys} with @var{m} copies vertically
 and @var{n} copies horizontally.  If @var{n} is not specified, it is set to @var{m}.
 @code{repsys (sys, 2, 3)} is equivalent to @code{[sys, sys, sys; sys, sys, sys]}.
 @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 thiran
@findex thiran

 @deftypefn {Function File} {@var{sys} =} thiran (@var{tau}, @var{tsam})
 Approximation of continuous-time delay using a discrete-time
 allpass Thiran filter. 

 Thiran filters can approximate continuous-time delays that are
 non-integer multiples of the sampling time (fractional delays).
 This approximation gives a better matching of the phase shift
 between the continuous- and the discrete-time system.
 If there is no fractional part in the delay, then the standard
 discrete-time delay representation is used. 

 @strong{Inputs}
 @table @var
 @item tau
 A continuous-time delay, given in time units (seconds).
 @item tsam
 The sampling time of the resulting Thiran filter.
 @end table

 @strong{Outputs}
 @table @var
 @item sys
 Transfer function model of the resulting filter.
 The order of the filter is determined automatically.
 @end table

 @strong{Example}
 @example
 @group
 octave:1> sys = thiran (1.33, 0.5)

 Transfer function 'sys' from input 'u1' to output ...
 
       0.003859 z^3 - 0.03947 z^2 + 0.2787 z + 1
  y1:  -----------------------------------------
        z^3 + 0.2787 z^2 - 0.03947 z + 0.003859 
 
 Sampling time: 0.5 s
 Discrete-time model.
 @end group
 @end example
 @example
 @group
 octave:2> sys = thiran (1, 0.5)

 Transfer function 'sys' from input 'u1' to output ...
 
        1
  y1:  ---
       z^2 
 
 Sampling time: 0.5 s
 Discrete-time model.
 @end group
 @end example

 @seealso{absorbdelay, pade}
 @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
 Drosselklappenstellung     alpha_DK = 10.3 Grad
 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_1 Sollsignal Drosselklappenstellung   [Grad]
 U_2 Relative Einspritzmenge             [-]
 U_3 Zuendzeitpunkt                      [Grad KW]
 M_L Lastdrehmoment                      [Nm]
 @end group
 @end example
 @example
 @group
 STATES
 X_1 Drosselklappenstellung     [Grad]
 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_1N, X_1N   1 Grad
 U_2N, X_4N, X_5N, Y_2N   0.05
 U_3N   1.6 Grad KW
 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
 pitch attitude           theta       [rad]
 roll attitude            phi         [rad]
 roll rate (body-axis)    p           [rad/s]
 pitch rate (body-axis)   q           [rad/s]
 yaw rate                 xi          [rad/s]
 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]
 pitch attitude           theta       [rad]
 roll attitude            phi         [rad]
 heading rate             psi_dot     [rad/s]
 roll rate                p           [rad/s]
 pitch rate               q           [rad/s]
 @end group
 @end example

 @strong{References}@*
 [1] Skogestad, S. and Postlethwaite I. (2005)
 @cite{Multivariable Feedback Control: Analysis and Design:
 Second Edition}.  Wiley.
 @url{http://www.nt.ntnu.no/users/skoge/book/2nd_edition/matlab_m/matfiles.html}

 @end deftypefn
