This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.

START-INFO-DIR-ENTRY
* Octave: (octave).	Interactive language for numerical computations.
END-INFO-DIR-ENTRY

   Copyright (C) 1996, 1997 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


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

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

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

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

 - Loadable Function:  lsode (FCN, X0, T, T_CRIT)
     Return a matrix of X as a function of T, given the initial state
     of the system X0.  Each row in the result matrix corresponds to
     one of the elements in the vector T.  The first element of T
     corresponds to the initial state X0, so that the first row of the
     output is X0.

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

          XDOT = f (X, T)

     where XDOT and X are vectors and T is a scalar.

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

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

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

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

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

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

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

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

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


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

Differential-Algebraic Equations
================================

   The function `dassl' can be used to solve DAEs of the form

     0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0

using Petzold's DAE solver DASSL.

 - Loadable Function: [X, XDOT] = dassl (FCN, X0, XDOT0, T, T_CRIT)
     Return a matrix of states and their first derivatives with respect
     to T.  Each row in the result matrices correspond to one of the
     elements in the vector T.  The first element of T corresponds to
     the initial state X0 and derivative XDOT0, so that the first row
     of the output X is X0 and the first row of the output XDOT is
     XDOT0.

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

          RES = f (X, XDOT, T)

     where X, XDOT, and RES are vectors, and T is a scalar.

     The second and third arguments to `dassl' specify the initial
     condition of the states and their derivatives, and the fourth
     argument specifies a vector of output times at which the solution
     is desired, including the time corresponding to the initial
     condition.

     The set of initial states and derivatives are not strictly
     required to be consistent.  In practice, however, DASSL is not
     very good at determining a consistent set for you, so it is best
     if you ensure that the initial values result in the function
     evaluating to zero.

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

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

   See K. E. Brenan, et al., `Numerical Solution of Initial-Value
Problems in Differential-Algebraic Equations', North-Holland (1989) for
more information about the implementation of DASSL.

   % DO NOT EDIT!  Generated automatically by munge-texi.


File: octave,  Node: Optimization,  Next: Statistics,  Prev: Differential Equations,  Up: Top

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

* Menu:

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


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

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


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

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


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

Linear Least Squares
====================

 - Function File: [BETA, V, R] = gls (Y, X, O)
     Generalized least squares estimation for the multivariate model `Y
     = X * B + E' with `mean (E) =  0' and `cov (vec (E)) = (S^2)*O',
     where Y is a T by P matrix, X is a T by K  matrix, B is a K by P
     matrix, E is a T by P matrix, and O is a TP by TP  matrix.

     Each row of Y and X is an observation and each column a variable.

     The return values BETA, V, and R are defined as  follows.

    BETA
          The GLS estimator for B.

    V
          The GLS estimator for `S^2'.

    R
          The matrix of GLS residuals, `R = Y - X * BETA'.

 - Function File: [BETA, SIGMA, R] = ols (Y, X)
     Ordinary least squares estimation for the multivariate model `Y =
     X*B + E' with `mean (E) = 0' and `cov (vec (E)) = kron (S, I)'.
     where Y is a T by P matrix, X is a T by K  matrix, B is a K by P
     matrix, and E is a T  by P matrix.

     Each row of Y and X is an observation and each column a  variable.

     The return values BETA, SIGMA, and R are defined as  follows.

    BETA
          The OLS estimator for B, `BETA = pinv (X) * Y', where `pinv
          (X)' denotes the pseudoinverse of X.

    SIGMA
          The OLS estimator for the matrix S,

               SIGMA = (Y-X*BETA)'
                  * (Y-X*BETA)
                  / (T-rank(X))

    R
          The matrix of OLS residuals, `R = Y - X * BETA'.

   % DO NOT EDIT!  Generated automatically by munge-texi.


File: octave,  Node: Statistics,  Next: Sets,  Prev: Optimization,  Up: Top

Statistics
**********

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

 - Function File:  mean (X, OPT)
     If X is a vector, compute the mean of the elements of X

           mean (x) = SUM_i x(i) / N
      If X is a matrix, compute the mean for each column and return them
     in a row vector.

     With the optional argument OPT, the kind of mean computed can be
     selected.  The following options are recognized:

    `"a"'
          Compute the (ordinary) arithmetic mean.  This is the default.

    `"g"'
          Computer the geometric mean.

    `"h"'
          Compute the harmonic mean.

 - Function File:  median (X)
     If X is a vector, compute the median value of the elements of X.

                       x(ceil(N/2)),             N odd
           median(x) =
                       (x(N/2) + x((N/2)+1))/2,  N even
      If X is a matrix, compute the median value for each  column
     and return them in a row vector.

 - Function File:  std (X)
     If X is a vector, compute the standard deviation of the elements
     of X.

           std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
      If X is a matrix, compute the standard deviation for  each
     column and return them in a row vector.

 - Function File:  cov (X, Y)
     If each row of X and Y is an observation and each column is  a
     variable, the (I,J)-th entry of `cov (X, Y)' is the covariance
     between the I-th  variable in X and the J-th variable in Y.  If
     called  with one argument, compute `cov (X, X)'.

 - Function File:  corrcoef (X, Y)
     If each row of X and Y is an observation and each column is  a
     variable, the (I,J)-th entry of `corrcoef (X, Y)' is the
     correlation between the I-th variable in X and the J-th variable
     in Y.   If called with one argument, compute `corrcoef (X, X)'.

 - Function File:  kurtosis (X)
     If X is a vector of length N, return the kurtosis

           kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3

     of X.  If X is a matrix, return the row vector containing  the
     kurtosis of each column.

 - Function File:  mahalanobis (X, Y)
     Return the Mahalanobis' D-square distance between the multivariate
     samples X and Y, which must have the same number of  components
     (columns), but may have a different number of observations  (rows).

 - Function File:  skewness (X)
     If X is a vector of length N, return the skewness

           skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)

     of X.  If X is a matrix, return the row vector containing  the
     skewness of each column.

   % DO NOT EDIT!  Generated automatically by munge-texi.


File: octave,  Node: Sets,  Next: Polynomial Manipulations,  Prev: Statistics,  Up: Top

Sets
****

   Octave has a limited set of functions for managing sets of data,
where a set is defined as a collection unique elements.

 - Function File:  create_set (X)
     Return a row vector containing the unique values in X, sorted in
     ascending order.  For example,

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

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

           union ([ 1, 2, 4 ], [ 2, 3, 5 ])
          => [ 1, 2, 3, 4, 5 ]

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

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

 - Function File:  complement (X, Y)
     Return the elements of set Y that are not in set X.  For  example,

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

   % DO NOT EDIT!  Generated automatically by munge-texi.


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

Polynomial Manipulations
************************

   In Octave, a polynomial is represented by its coefficients (arranged
in descending order).  For example, a vector  C of length  N+1
corresponds to the following polynomial of order  N

     p(x) = C(1) x^N + ... + C(N) x + C(N+1).

 - Function File:  compan (C)
     Compute the companion matrix corresponding to polynomial
     coefficient  vector C.

     The companion matrix is

                _                                                        _
               |  -c(2)/c(1)   -c(3)/c(1)  ...  -c(N)/c(1)  -c(N+1)/c(1)  |
               |       1            0      ...       0             0      |
               |       0            1      ...       0             0      |
           A = |       .            .   .            .             .      |
               |       .            .       .        .             .      |
               |       .            .           .    .             .      |
               |_      0            0      ...       1             0     _|

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

 - Function File:  conv (A, B)
     Convolve two vectors.

     `y = conv (a, b)' returns a vector of length equal to `length (a)
     + length (b) - 1'.   If A and B are polynomial coefficient
     vectors, `conv'  returns the coefficients of the product
     polynomial.

 - Function File:  deconv (Y, A)
     Deconvolve two vectors.

     `[b, r] = deconv (y, a)' solves for B and R such that `y = conv
     (a, b) + r'.

     If Y and A are polynomial coefficient vectors, B will  contain the
     coefficients of the polynomial quotient and R will be  a remander
     polynomial of lowest order.

 - Function File:  poly (A)
     If A is a square N-by-N matrix, `poly (A)'  is the row vector of
     the coefficients of `det (z * eye (N) - a)',  the characteristic
     polynomial of A.  If X is a vector, `poly (X)' is a vector of
     coefficients of the polynomial  whose roots are the elements of X.

 - Function File:  polyderiv (C)
     Return the coefficients of the derivative of the polynomial whose
     coefficients are given by vector C.

 - Function File: [P, YF] = polyfit (X, Y, N)
     Return the coefficients of a polynomial P(X) of degree N that
     minimizes `sumsq (p(x(i)) - y(i))',   to best fit the data in the
     least squares sense.

     If two output arguments are requested, the second contains the
     values of  the polynomial for each value of X.

 - Function File:  polyinteg (C)
     Return the coefficients of the integral of the polynomial whose
     coefficients are represented by the vector C.

     The constant of integration is set to zero.

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

 - Function File:  polyval (C, X)
     Evaluate a polynomial.

     `polyval (C, X)' will evaluate the polynomial at the  specified
     value of X.

     If X is a vector or matrix, the polynomial is evaluated at each of
     the elements of X.

 - Function File:  polyvalm (C, X)
     Evaluate a polynomial in the matrix sense.

     `polyvalm (C, X)' will evaluate the polynomial in the  matrix
     sense, i.e. matrix multiplication is used instead of element by
     element multiplication as is used in polyval.

     The argument X must be a square matrix.

 - Function File:  residue (B, A, TOL)
     If B and A are vectors of polynomial coefficients, then  residue
     calculates the partial fraction expansion corresponding to the
     ratio of the two polynomials.

     The function `residue' returns R, P, K, and E, where the vector R
     contains the residue terms, P  contains the pole values, K
     contains the coefficients of a direct  polynomial term (if it
     exists) and E is a vector containing the  powers of the
     denominators in the partial fraction terms.

     Assuming B and A represent polynomials   P (s) and Q(s)   we have:

            P(s)    M       r(m)         N
            ---- = SUM -------------  + SUM k(i)*s^(N-i)
            Q(s)   m=1 (s-p(m))^e(m)    i=1

     where M is the number of poles (the length of the R, P, and E
     vectors) and N is the length of the K  vector.

     The argument TOL is optional, and if not specified, a default
     value of 0.001 is assumed.  The tolerance value is used to
     determine  whether poles with small imaginary components are
     declared real.  It is  also used to determine if two poles are
     distinct.  If the ratio of the  imaginary part of a pole to the
     real part is less than TOL, the  imaginary part is discarded.  If
     two poles are farther apart than TOL they are distinct.  For
     example,

            b = [1, 1, 1];
            a = [1, -5, 8, -4];
            [r, p, k, e] = residue (b, a);
          => r = [-2, 7, 3]
          => p = [2, 2, 1]
          => k = [](0x0)
          => e = [1, 2, 1]

     which implies the following partial fraction expansion

                   s^2 + s + 1       -2        7        3
              ------------------- = ----- + ------- + -----
              s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)

 - Function File:  roots (V)
     For a vector V with N components, return  the roots of the
     polynomial

           v(1) * z^(N-1) + ... + v(N-1) * z + v(N).

   % DO NOT EDIT!  Generated automatically by munge-texi.


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

Control Theory
**************

   The Octave Control Systems Toolbox (OCST) was initially developed by
Dr. A. Scottedward Hodel (a.s.hodel@eng.auburn.edu) with the assistance
of his students
   * R. Bruce Tenison (btenison@dibbs.net),

   * David C. Clem,

   * John E. Ingram (John.Ingram@sea.siemans.com), and

   * Kristi McGowan.  This development was supported in part by NASA's
Marshall Space Flight Center as part of an in-house CACSD environment.
Additional important contributions were made by Dr. Kai Mueller
(mueller@ifr.ing.tu-bs.de) and Jose Daniel Munoz Frias (`place.m').

   An on-line menu-driven tutorial is available via `DEMOcontrol';
beginning OCST users should start with this program.

 - Function File :   DEMOcontrol
     Octave Control Systems Toolbox demo/tutorial program.  The demo
     allows the user to select among several categories of OCST
     function:
           octave:1> DEMOcontrol
            O C T A V E    C O N T R O L   S Y S T E M S   T O O L B O X
           Octave Controls System Toolbox Demo
          
             [ 1] System representation
             [ 2] Block diagram manipulations
             [ 3] Frequency response functions
             [ 4] State space analysis functions
             [ 5] Root locus functions
             [ 6] LQG/H2/Hinfinity functions
             [ 7] End
      Command examples are interactively run for users to observe
     the use  of OCST functions.

* Menu:

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


File: octave,  Node: sysstruct,  Next: sysinterface,  Prev: Control Theory,  Up: Control Theory

System Data Structure
=====================

* Menu:

* sysstructvars::
* sysstructtf::
* sysstructzp::
* sysstructss::

   The OCST stores all dynamic systems in a single data structure
format that can represent continuous systems, discrete-systems, and
mixed (hybrid) systems in state-space form, and can also represent
purely continuous/discrete systems in either transfer function or
pole-zero form. In order to provide more flexibility in treatment of
discrete/hybrid systems, the OCST also keeps a record of which system
outputs are sampled.

   Octave structures are accessed with a syntax much like that used by
the C programming language.  For consistency in use of the data
structure used in the OCST, it is recommended that the system structure
access m-files be used (*Note sysinterface::).  Some elements of the
data structure are absent depending on the internal system
representation(s) used.  More than one system representation can be
used for SISO systems; the OCST m-files ensure that all representations
used are consistent with one another.

 - Function File :  sysrepdemo
     Tutorial for the use of the system data structure functions.


File: octave,  Node: sysstructvars,  Next: sysstructtf,  Prev: sysstruct,  Up: sysstruct

Variables common to all OCST system formats
-------------------------------------------

   The data structure elements (and variable types) common to all
system representations are listed below; examples of the initialization
and use of the system data structures are given in subsequent sections
and in the online demo `DEMOcontrol'.
N,NZ
     The respective number of continuous and discrete states in the
     system (scalar)

INNAME, OUTNAME
     list of name(s) of the system input, output signal(s). (list of
     strings)

SYS
     System status vector.  (vector)

     This vector indicates both what representation was used to
     initialize the system data structure (called the primary system
     type) and which other representations are currently up-to-date
     with the primary system type (*Note structaccess::).

    SYS(0)
          primary system type

          =0 for tf form (initialized with `tf2sys' or `fir2sys')

          =1 for zp form (initialized with `zp2sys')

          =2 for ss form (initialized with `ss2sys')

    SYS(1:3)
          boolean flags to indicate whether tf, zp, or ss, respectively,
                 are "up to date" (whether it is safe to use the
          variables           associated with these representations).
          These flags are changed when calls are made to the
          `sysupdate' command.

TSAM
     Discrete time sampling period  (nonnegative scalar).   TSAM is set
     to 0 for continuous time systems.

YD
     Discrete-time output list (vector)

     indicates which outputs are discrete time (i.e.,     produced by
     D/A converters) and which are continuous time.      yd(ii) = 0 if
     output ii is continuous, = 1 if discrete.

   The remaining variables of the  system data structure are only
present if the corresponding entry of the `sys' vector is true (=1).


File: octave,  Node: sysstructtf,  Next: sysstructzp,  Prev: sysstructvars,  Up: sysstruct

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

NUM
     numerator coefficients   (vector)

DEN
     denominator coefficients   (vector)


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

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

ZER
     system zeros   (vector)

POL
     system poles    (vector)

K
     leading coefficient   (scalar)


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

`ss' format variables
---------------------

A,B,C,D
     The usual state-space matrices. If a system has both
     continuous and discrete states, they are sorted so that
     continuous states come first, then discrete states

     *Note* some functions (e.g., `bode', `hinfsyn') will not accept
     systems with both discrete and continuous states/outputs

STNAME
     names of system states   (list of strings)


File: octave,  Node: sysinterface,  Next: sysdisp,  Prev: sysstruct,  Up: Control Theory

System Construction and Interface Functions
===========================================

   Construction and manipulations of the OCST system data structure
(*Note sysstruct::) requires attention to many details in order to
ensure that data structure contents remain consistent.  Users are
strongly encouraged to use the system interface functions in this
section.  Functions for the formatted display in of system data
structures are given in *Note sysdisp::.

* Menu:

* fir2sys::
* ss2sys::
* tf2sys::
* zp2sys::
* structaccess::
* structintern::


File: octave,  Node: fir2sys,  Next: ss2sys,  Prev: sysinterface,  Up: sysinterface

Finite impulse response system interface functions
--------------------------------------------------

 - Function File :  SYS = fir2sys ( NUM{, TSAM, INNAME, OUTNAME } )
     construct a system data structure from FIR description

     *Inputs:*
    NUM
          vector of coefficients [c_0 c_1 ... c_n]  of the SISO FIR
          transfer function

          C(z) = c0 + c1*z^{-1} + c2*z^{-2} + ... + znz^{-n}

    TSAM
          sampling time (default: 1)

    INNAME
          name of input signal;  may be a string or a list with a
          single entry.

    OUTNAME
          name of output signal; may be a string or a list with a
          single entry.

     *Outputs* SYS (system data structure)

     *Example*
           octave:1> sys = fir2sys([1 -1 2 4],0.342,"A/D input","filter output");
           octave:2> sysout(sys)
           Input(s)
                   1: A/D input
          
           Output(s):
                   1: filter output (discrete)
          
           Sampling interval: 0.342
           transfer function form:
           1*z^3 - 1*z^2 + 2*z^1 + 4
           -------------------------
           1*z^3 + 0*z^2 + 0*z^1 + 0

 - Function File : [C, TSAM, INPUT, OUTPUT] = sys2fir (SYS)
     Extract FIR data from system data structure; see *Note fir2sys::
     for  parameter descriptions.



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

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

 - Function File :  SYS = ss2sys (A,B,C{,D, TSAM, N, NZ, STNAME,
          INNAME, OUTNAME, OUTLIST})
     Create system structure from state-space data.   May be continous,
      discrete, or mixed (sampeled-data)

     *Inputs*
    A, B, C, D
          usual state space matrices.

          default: D = zero matrix

    TSAM
          sampling rate.  Default: tsam = 0 (continuous system)

    N, NZ
          number of continuous, discrete states in the system

          default:
         TSAM = 0
               n = `rows'(A), nz = 0

         TSAM > 0
               n = 0,       nz = `rows'(A)

               see below for system partitioning

    STNAME
          list of strings of state signal names

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

    INNAME
          list of strings of input signal names

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

    OUTNAME
          list of strings of input signal names

          default (OUTNAME = [] on input): `y_n'

    OUTLIST
          list of indices of outputs y that are sampled

          default:
         TSAM = 0
               `outlist = []'

         TSAM > 0
               `outlist = 1:`rows'(C)'

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

          *Note* `sys2ss' returns a vector YD where YD(OUTLIST) = 1;
          all other entries of YD are 0.

     *Outputs* OUTSYS = system data structure

     *System partitioning*

     Suppose for simplicity that outlist specified    that the first
     several outputs were continuous and the remaining outputs    were
     discrete.  Then the system is partitioned as
           x = [ xc ]  (n x 1)
               [ xd ]  (nz x 1 discrete states)
           a = [ acc acd ]  b = [ bc ]
               [ adc add ]      [ bd ]
           c = [ ccc ccd ]  d = [ dc ]
               [ cdc cdd ]      [ dd ]
          
               (cdc = c(outlist,1:n), etc.)
      with dynamic equations:   d/dt xc(t)     = acc*xc(t)      +
     acd*xd(k*tsam) + bc*u(t)

     xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)

     yc(t)      = ccc*xc(t)      + ccd*xd(k*tsam) + dc*u(t)

     yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)

     *Signal partitions*
                   | continuous      | discrete               |
           ----------------------------------------------------
           states  | stname(1:n,:)   | stname((n+1):(n+nz),:) |
           ----------------------------------------------------
           outputs | outname(cout,:) | outname(outlist,:)     |
           ----------------------------------------------------
      where cout is the list of in 1:`rows'(P)  that are not
     contained in outlist. (Discrete/continuous outputs  may be entered
     in any order desired by the user.)

     *Example*
           octave:1> a = [1 2 3; 4 5 6; 7 8 10];
           octave:2> b = [0 0 ; 0 1 ; 1 0];
           octave:3> c = eye(3);
           octave:4> sys = ss2sys(a,b,c,[],0,3,0,list("volts","amps","joules"));
           octave:5> sysout(sys);
           Input(s)
                   1: u_1
                   2: u_2
          
           Output(s):
                   1: y_1
                   2: y_2
                   3: y_3
          
           state-space form:
           3 continuous states, 0 discrete states
           State(s):
                   1: volts
                   2: amps
                   3: joules
          
           A matrix: 3 x 3
              1   2   3
              4   5   6
              7   8  10
           B matrix: 3 x 2
             0  0
             0  1
             1  0
           C matrix: 3 x 3
             1  0  0
             0  1  0
             0  0  1
           D matrix: 3 x 3
             0  0
             0  0
             0  0
      Notice that the D matrix is constructed  by default to the
     correct dimensions.  Default input and output signals names were
     assigned  since none were given.


 - Function File : [A,B,C,D,TSAM,N,NZ,STNAME,INNAME,OUTNAME,YD] =
          sys2ss (SYS)
     Extract state space representation from system data structure.

     *Inputs* SYS system data structure (*Note sysstruct::)

     *Outputs*
    A,B,C,D
          state space matrices for sys

    TSAM
          sampling time of sys (0 if continuous)

    N, NZ
          number of continuous, discrete states (discrete states come
                  last in state vector X)

    STNAME, INNAME, OUTNAME
          signal names (lists of strings);  names of states,
          inputs, and outputs, respectively

    YD
          binary vector; YD(II) is 1 if output Y(II)$   is discrete
          (sampled); otherwise  YD(II) 0.

     A warning massage is printed if the system is a mixed  continuous
     and discrete system

     *Example*
           octave:1> sys=tf2sys([1 2],[3 4 5]);
           octave:2> [a,b,c,d] = sys2ss(sys)
           a =
              0.00000   1.00000
             -1.66667  -1.33333
           b =
             0
             1
           c = 0.66667  0.33333
           d = 0


File: octave,  Node: tf2sys,  Next: zp2sys,  Prev: ss2sys,  Up: sysinterface

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

 - Function File :  SYS =  tf2sys( NUM, DEN {, TSAM, INNAME, OUTNAME })
     build system data structure from transfer function format data

     *Inputs*
    NUM, DEN
          coefficients of numerator/denominator polynomials

    TSAM
          sampling interval. default: 0 (continuous time)

    INNAME, OUTNAME
          input/output signal names; may be a string or list with a
          single string  entry.

     *Outputs* SYS = system data structure

     *Example*
           octave:1> sys=tf2sys([2 1],[1 2 1],0.1);
           octave:2> sysout(sys)
           Input(s)
                   1: u_1
           Output(s):
                   1: y_1 (discrete)
           Sampling interval: 0.1
           transfer function form:
           2*z^1 + 1
           -----------------
           1*z^2 + 2*z^1 + 1


File: octave,  Node: zp2sys,  Next: structaccess,  Prev: tf2sys,  Up: sysinterface

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

 - Function File :  SYS = zp2sys (ZER,POL,K{,TSAM,INNAME,OUTNAME})
     Create system data structure from zero-pole data

     *Inputs*
    ZER
          vector of system zeros

    POL
          vector of system poles

    K
          scalar leading coefficient

    TSAM
          sampling period. default: 0 (continuous system)

    INNAME, OUTNAME
          input/output signal names (lists of strings)

     *Outputs*   sys: system data structure

     *Example*
           octave:1> sys=zp2sys([1 -1],[-2 -2 0],1);
           octave:2> sysout(sys)
           Input(s)
                   1: u_1
           Output(s):
                   1: y_1
           zero-pole form:
           1 (s - 1) (s + 1)
           -----------------
           s (s + 2) (s + 2)

 - Function File : [ZER, POL, K, TSAM, INNAME, OUTNAME] = sys2zp (SYS)
     Extract zero/pole/leading coefficient information from a system
     data  structure

     See *Note zp2sys:: for parameter descriptions.

     *Example*
           octave:1> sys=ss2sys([1 -2; -1.1,-2.1],[0;1],[1 1]);
           octave:2> [zer,pol,k] = sys2zp(sys)
           zer = 3.0000
           pol =
             -2.6953
              1.5953
           k = 1


File: octave,  Node: structaccess,  Next: structintern,  Prev: zp2sys,  Up: sysinterface

Data structure access functions
-------------------------------

 - Function File : RETSYS = syschnames (SYS, OPT, LIST, NAMES)
     Superseded by `syssetsignals'

 - Function File :  retsys = syschtsam ( sys,tsam )
     This function changes the sampling time (tsam) of the system.
     Exits with  an error if sys is purely continuous time.

 - Function File :  [N, NZ, M, P,YD] = sysdimensions (SYS{, OPT})
     return the number of states, inputs, and/or outputs in the system
     SYS.

     *Inputs*
    SYS
          system data structure

    OPT
          String indicating which dimensions are desired.  Values:
         `"all"'
               (default) return all parameters as specified under
               Outputs below.

         `"cst"'
               return N= number of continuous states

         `"dst"'
               return N= number of discrete states

         `"in"'
               return N= number of inputs

         `"out"'
               return N= number of outputs

     *Outputs*
    N
          number of continuous states (or individual requested
          dimension as specified  by OPT).

    NZ
          number of discrete states

    M
          number of system inputs

    P
          number of system outputs

    YD
          binary vector; YD(II) is nonzero if output II is  discrete.
          yd(ii) = 0 if output II is continous


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

     *Inputs* SYS: system data structure

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

     *Note* FIR initialized systems return `systype="tf"'.


 - Function File :  SYS = sysupdate ( SYS, OPT )
     Update the internal representation of a system.

     *Inputs*
    SYS:
          system data structure

    OPT
          string:
         `"tf"'
               update transfer function form

         `"zp"'
               update zero-pole form

         `"ss"'
               update state space form

         `"all"'
               all of the above

     *Outputs* RETSYS: contains union of data in sys and requested data.
     If requested data in sys is already up to date then retsys=sys.

     Conversion to `tf' or `zp' exits with an error if the system is
     mixed continuous/digital.


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

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

 - Function File :   syschnamesl
     used internally in syschnames   item olist: index list
     old_names: original list names   inames: new names   listname:
     name of index list

     combines the two string lists old_names and inames

 - Function File :  IONAME = sysdefioname (N,STR {,M})
     return default input or output names given N, STR, M.  N is the
     final value, STR is the string prefix, and M  is start value

     used internally, minimal argument checking

     *Example* `ioname = sysdefioname(5,"u",3)'  returns the list:
           ioname =
           (
             [1] = u_3
             [2] = u_4
             [3] = u_5
           )

 - Function File :  STNAME = sysdefstname (N, NZ)
     return default state names given N, NZ

     used internally, minimal argument checking


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

System display functions
========================

 - Function File :  Y = polyout ( C{, X})
     write formatted polynomial
              c(x) = c(1) * x^n + ... + c(n) x + c(n+1)
       to string Y or to the screen (if Y is omitted) X defaults to the
     string `"s"'

   See also: polyval, polyvalm, poly, roots, conv, deconv, residue,
filter, polyderiv, polyinteg, polyout

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

 - Function File :   outlist (LMAT{, TABCHAR, YD, ILIST })
     Prints an enumerated list of strings.    internal use only;
     minimal argument checking performed

     *Inputs*
    LMAT
          list of strings

    TABCHAR
          tab character (default: none)

    YD
          indices of strings to append with the string "(discrete)"
                 (used by SYSOUT; minimal checking of this argument)
           yd = []  indicates all outputs are continuous

    ILIST
          index numbers to print with names.

          default: `1:rows(lmat)'

     *Outputs*     prints the list to the screen, numbering each string
     in order.



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

Block Diagram Manipulations
===========================

   *Note systime::

   Unless otherwise noted, all parameters (input,output) are system
data structures.

 - Function File :  outputs = bddemo ( inputs )
     Octave Controls toolbox demo: Block Diagram Manipulations demo

 - Function File : SYS = buildssic(CLST, ULST, OLST, ILST, S1, S2, S3,
          S4, S5, S6, S7, S8)
     Contributed by Kai Mueller.

     Form an arbitrary complex (open or closed loop) system in
     state-space form from several systems. "`buildssic'" can   easily
     (despite it's cryptic syntax) integrate transfer functions   from
     a complex block diagram into a single system with one call.
     This function is especially useful for building open loop
     interconnections for H_infinity and H2 designs or for closing
     loops with these controllers.

     Although this function is general purpose, the use of "`sysgroup'"
      "`sysmult'", "`sysconnect'" and the like is recommended for
     standard   operations since they can handle mixed discrete and
     continuous   systems and also the names of inputs, outputs, and
     states.

     The parameters consist of 4 lists that describe the connections
     outputs and inputs and up to 8 systems s1-s8.    Format of the
     lists:
    CLST
          connection list, describes the input signal of  each system.
          The maximum number of rows of Clst is  equal to the sum of
          all inputs of s1-s8.

          Example: `[1 2 -1; 2 1 0]' ==> new input 1 is old inpout 1  +
          output 2 - output 1, new input 2 is old input 2  + output 1.
          The order of rows is arbitrary.

    ULST
          if not empty the old inputs in vector Ulst will
          be appended to the outputs. You need this if you
          want to "pull out" the input of a system. Elements
          are input numbers of s1-s8.

    OLST
          output list, specifiy the outputs of the resulting
          systems. Elements are output numbers of s1-s8.
          The numbers are alowed to be negative and may
          appear in any order. An empty matrix means             all
          outputs.

    ILST
          input list, specifiy the inputs of the resulting
          systems. Elements are input numbers of s1-s8.
          The numbers are alowed to be negative and may
          appear in any order. An empty matrix means             all
          inputs.

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

     The closed loop system GW can be optained by
           GW = buildssic([1 2; 2 -1], 2, [1 2 3], 2, G, K);

    CLST
          (1. row) connect input 1 (G) with output 2 (K).   (2. row)
          connect input 2 (K) with neg. output 1 (G).

    ULST
          append input of (2) K to the number of outputs.

    OLST
          Outputs are output of 1 (G), 2 (K) and appended output 3
          (from Ulst).

    ILST
          the only input is 2 (K).

     Here is a real example:
                                    +----+
               -------------------->| W1 |---> v1
           z   |                    +----+
           ----|-------------+                   || GW   ||     => min.
               |             |                        vz   infty
               |    +---+    v      +----+
               *--->| G |--->O--*-->| W2 |---> v2
               |    +---+       |   +----+
               |                |
               |                v
              u                  y

     The closed loop system GW from [z; u]' to [v1; v2; y]' can be
     obtained by (all SISO systems):
           GW = buildssic([1, 4; 2, 4; 3, 1], 3, [2, 3, 5],
                          [3, 4], G, W1, W2, One);
      where "One" is a unity gain (auxillary) function with order 0.
     (e.g. `One = ugain(1);')

 - Function File :  OUTSYS  = jet707 ( )
     Creates linearized state space model of a Boeing 707-321 aircraft
     at v=80m/s. (M = 0.26, Ga0 = -3 deg, alpha0 = 4 deg, kappa = 50
     deg)   System inputs:   (1) thrust   and (2) elevator angle
     System outputs:  (1) airspeed and (2) pitch angle   Ref: R.
     Brockhaus: Flugregelung (Flight Control), Springer, 1994

     see also: ord2

     Contributed by Kai Mueller

   See also: jet707 (MIMO example, Boeing 707-321 aircraft model)

 - Function File :  SYS = sysadd ( GSYS,HSYS)
     returns SYS = GSYS + HSYS.
        * Exits with  an error if GSYS and HSYS are not compatibly
          dimensioned.

        * Prints a warning message is system states have identical
          names;    duplicate names are given a suffix to make them
          unique.

        * SYS input/output names are taken from GSYS.
                     ________
                ----|  Gsys  |---
           u   |    ----------  +|
           -----                (_)----> y
               |     ________   +|
                ----|  Hsys  |---
                     --------

 - Function File : RETSYS = sysconnect (SYS, OUT_IDX,IN_IDX{,ORDER,
          TOL})
     Close the loop from specified outputs to respective specified
     inputs

     *Inputs*
    SYS
          system data structure

    OUT_IDX, IN_IDX
          list of connections indices; y(out_idx(ii))  is connected to
          u(in_idx(ii)).

    ORDER
          logical flag (default = 0)
         `0'
               leave inputs and outputs in their original order

         `1'
               permute inputs and outputs to the order shown in the
               diagram below

    TOL
          tolerance for singularities in algebraic loops default: 200EPS

     *Outputs* SYS: resulting closed loop system.

     *Method* `sysconnect' internally permutes selected inputs, outputs
     as shown   below, closes the loop, and then permutes inputs and
     outputs back to their   original order
                            ____________________
            u_1       ----->|                  |----> y_1
                            |        sys       |
                    old u_2 |                  |
           u_2* ---->(+)--->|                  |----->y_2
           (in_idx)   ^     -------------------|    | (out_idx)
                      |                             |
                      -------------------------------
      The input that has the summing junction added to it has an *
     added to the end  of the input name.


 - Function File:  [CSYS, ACD, CCD] =  syscont (SYS)
     Extract the purely continuous subsystem of an input system.

     *Inputs* SYS is a system data structure

     *Outputs*
    CSYS
          is the purely continuous input/output connections of SYS

    ACD, CCD:
          connections from discrete states to continuous states,
                  discrete states to continuous outputs, respectively.

          returns CSYS empty if no continuous/continous path exists


 - Function File :  [N_TOT, ST_C, ST_D, Y_C, Y_D] = syscont_disc(SYS)
     Used internally in syscont and sysdisc.

     *Inputs*  SYS is a system data structure.

     *Outputs*
    N_TOT
          total number of states

    ST_C
          vector of continuous state indices (empty if none)

    ST_D
          vector of discrete state indices (empty if none)

    Y_C
          vector of continuous output indices

    Y_D
          vector of discrete output indices


 - Function File :  [DSYS, ADC, CDC] = sysdisc (SYS)
     *Inputs* SYS = system data structure

     *Outputs*
    DSYS
          purely discrete portion of sys (returned empty if there is
                 no purely discrete path from inputs to outputs)

    ADC, CDC
          connections from continuous states to discrete states and
          discrete      outputs, respectively.


 - Function File :  SYS = sysgroup ( ASYS, BSYS)
     Combines two systems into a single system

     *Inputs* ASYS, BSYS: system data structures

     *Outputs* sys = block diag(Asys,Bsys)
                    __________________
                    |    ________    |
           u1 ----->|--> | Asys |--->|----> y1
                    |    --------    |
                    |    ________    |
           u2 ----->|--> | Bsys |--->|----> y2
                    |    --------    |
                    ------------------
                         Ksys
      The function also rearranges the internal state-space
     realization of SYS  so that the   continuous states come first and
     the discrete states come last.    If there are duplicate names,
     the second name has a unique suffix appended   on to the end of
     the name.


 - Function File :  NAMES = sysgroupn (NAMES)
     names = sysgroupn(names)  Locate and mark duplicate names  inputs:
       names: list of signal names    kind: kind of signal name (used
     for diagnostic message purposes only)  outputs:    returns names
     with unique suffixes added; diagnostic warning       message is
     printed to inform the user of the new signal name

     used internally in sysgroup and elsewhere.


 - Function File :  SYS = sysmult( ASYS, BSYS)
     Compute sys = Asys*Bsys (series connection):
           u   ----------     ----------
           --->|  Bsys  |---->|  Asys  |--->
               ----------     ----------
      A warning occurs if there is direct feed-through  from an
     input of Bsys or a continuous state of Bsys through a discrete
     output of Bsys to a continuous state or output in Asys (system
     data structure  does not recognize discrete inputs).

 - Function File :  RETSYS = sysprune ( ASYS, OUT_IDX, IN_IDX)
     Extract specified inputs/outputs from a system

     *Inputs*
    ASYS
          system data structure

    OUT_IDX,IN_IDX
          list of connections indices; the new         system has
          outputs y(out_idx(ii)) and inputs u(in_idx(ii)).          May
          select as [] (empty matrix) to specify all outputs/inputs.

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


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

     *Outputs* PV: a permutation vector to order elements of `[1:vlen]'
     in `list' to the end of a vector.

     Used internally by `sysconnect' to permute vector elements to their
      desired locations.

 - Function File : SYS = sysscale (SYS, OUTSCALE, INSCALE{, OUTNAME,
          INNAME})
     scale inputs/outputs of a system.

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

     *Outputs* SYS: resulting open loop system:
                 -----------    -------    -----------
           u --->| inscale |--->| sys |--->| outscale |---> y
                 -----------    -------    -----------
       If the input names and output names (each a list of strings)
     are not given and the scaling matrices   are not square, then
     default names will be given to the inputs and/or   outputs.

     A warning message is printed if outscale attempts to add continuous
     system outputs to discrete system outputs; otherwise YD is  set
     appropriately in the returned value of SYS.

 - Function File :  SYS = syssub (GSYS, HSYS)
     returns sys = Gsys - Hsys

     Method: GSYS and HSYS are connected in parallel   The input vector
     is connected to both systems; the outputs are   subtracted.
     Returned system names are those of GSYS.
                     ________
                ----|  Gsys  |---
           u   |    ----------  +|
           -----                (_)----> y
               |     ________   -|
                ----|  Hsys  |---
                     --------

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

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

     vl = Gain @ low frequencies

     vh = Gain @ high frequencies

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

