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


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


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

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


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


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


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 *Note DEMOcontrol::;
beginning OCST users should start with this program.

* Menu:

* OCST demonstration/tutorial:DEMOcontrol.
* System Data Structure:sysstruct.
* System Construction and Interface Functions:sysinterface.
* System display functions:sysdisp.
* Block Diagram Manipulations:blockdiag.
* Numerical Functions:numerical.
* System Analysis-Properties:sysprop.
* System Analysis-Time Domain:systime.
* System Analysis-Frequency Domain:sysfreq.
* Controller Design:cacsd.
* Miscellaneous Functions:misc.


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

OCST demo 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.


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

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

* Menu:

* Demo program:sysrepdemo.
* Variables common to all OCST system formats:sysstructvars.
* tf format variables:sysstructtf.
* zp format variables:sysstructzp.
* ss format variables: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.


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

System representation demo program
==================================

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


File: octave,  Node: sysstructvars,  Next: sysstructtf,  Prev: sysrepdemo,  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 sysupdate::).

    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:

* Finite impulse response system interface functions:fir2sys.
* sys2fir::
* State space system interface functions:ss2sys.
* sys2ss::
* Transfer function system interface functions:tf2sys.
* sys2tf::
* Zero-pole system interface functions:zp2sys.
* sys2zp::
* Data structure access functions:structaccess.
* Data structure internal functions:structintern


File: octave,  Node: fir2sys,  Next: sys2fir,  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


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

 - 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: sys2ss,  Prev: sys2fir,  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 (sampeld-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.



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

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

     *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: sys2tf,  Prev: sys2ss,  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: sys2tf,  Next: zp2sys,  Prev: tf2sys,  Up: sysinterface

 - Function File : [NUM,DEN,TSAM,INNAME,OUTNAME] = sys2tf (SYS)
     Extract transfer function data from a system data structure

     See *Note tf2sys:: for parameter descriptions.

     *Example*
          octave:1> sys=ss2sys([1 -2; -1.1,-2.1],[0;1],[1 1]);
          octave:2> [num,den] = sys2tf(sys)
          num = 1.0000  -3.0000
          den = 1.0000   1.1000  -4.3000


File: octave,  Node: zp2sys,  Next: sys2zp,  Prev: sys2tf,  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)


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

 - 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: sys2zp,  Up: sysinterface

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

* Menu:

* syschnames::
* syschtsam::
* sysdimensions::
* sysgetsignals::
* sysgettsam::
* sysgettype::
* syssetsignals::
* sysupdate::


File: octave,  Node: syschnames,  Next: syschtsam,  Prev: structaccess,  Up: structaccess

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



File: octave,  Node: syschtsam,  Next: sysdimensions,  Prev: syschnames,  Up: structaccess

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


File: octave,  Node: sysdimensions,  Next: sysgetsignals,  Prev: syschtsam,  Up: structaccess

 - 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



File: octave,  Node: sysgetsignals,  Next: sysgettsam,  Prev: sysdimensions,  Up: structaccess

 - Function File : [STNAME, INNAME, OUTNAME, YD] = sysgetsignals (SYS)
 - Function File :  SIGLIST = sysgetsignals (SYS,SIGID)
 - Function File :  SIGNAME = sysgetsignals (SYS,SIGID,SIGNUM{, STRFLG})
     Get signal names from a system

     *Inputs*
    SYS
          system data structure for the state space system

    SIGID
          signal id.  String.  Must be one of
         `"in"'
               input signals

         `"out"'
               output signals

         `"st"'
               stage signals

         `"yd"'
               value of logical vector YD

    SIGNUM
          Index of signal (or indices of signals if signum is a vector)

    STRFLG
          flag to return a string instead of a list;  Values:
         `0'
               (default) return a list (even if signum is a scalar)

         `1'
               return a string.  Exits with an error if signum is not a
               scalar.

     *Outputs*
    *If SIGID is not specified
         STNAME, INNAME, OUTNAME
               signal names (lists of strings);  names of states,
                  inputs, and outputs, respectively

         YD
               binary vector; YD(II) is nonzero if output II is
               discrete.

    *If SIGID is specified but SIGNUM is not specified, then
         `sigid="in"'
               SIGLIST is set to the list of input names

         `sigid="out"'
               SIGLIST is set to the list of output names

         `sigid="st"'
               SIGLIST is set to the list of state names

               stage signals

         `sigid="yd"'
               SIGLIST is set to logical vector indicating discrete
               outputs; SIGLIST(II) = 0 indicates that output II is
               continuous (unsampled), otherwise it is discrete.

    *if the first three input arguments are specified, then SIGNAME is
          a list of the specified signal names (SIGID is `"in"',
          `"out"', or `"st"'), or else the logical flag indicating
          whether output(s) SIGNUM is(are) discrete (SIGVAL=1) or
          continuous (SIGVAL=0).

     *Examples* (From `sysrepdemo')
          octave> sys=ss2sys(rand(4),rand(4,2),rand(3,4));
          octave> [Ast,Ain,Aout,Ayd] = sysgetsignals(sys) i  # get all signal names
          Ast =
          (
            [1] = x_1
            [2] = x_2
            [3] = x_3
            [4] = x_4
          )
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          Aout =
          (
            [1] = y_1
            [2] = y_2
            [3] = y_3
          )
          Ayd =
          
            0  0  0
          octave> Ain = sysgetsignals(sys,"in")   # get only input signal names
          Ain =
          (
            [1] = u_1
            [2] = u_2
          )
          octave> Aout = sysgetsignals(sys,"out",2)   # get name of output 2 (in list)
          Aout =
          (
            [1] = y_2
          )
          octave> Aout = sysgetsignals(sys,"out",2,1)  # get name of output 2 (as string)
          Aout = y_2



File: octave,  Node: sysgettsam,  Next: sysgettype,  Prev: sysgetsignals,  Up: structaccess

 - Function File :  Tsam = sysgettsam ( sys )
     return the sampling time of the system


File: octave,  Node: sysgettype,  Next: syssetsignals,  Prev: sysgettsam,  Up: structaccess

 - 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"'.



File: octave,  Node: syssetsignals,  Next: sysupdate,  Prev: sysgettype,  Up: structaccess

 - Function File : RETSYS = syssetsignals (SYS, OPT, NAMES{, SIG_IDX})
     change the names of selected inputs, outputs and states.  *Inputs*
    SYS
          system data structure

    OPT
          change default name (output)

         `"out"'
               change selected output names

         `"in"'
               change selected input names

         `"st"'
               change selected state names

         `"yd"'
               change selected outputs from discrete to continuous or
                               from continuous to discrete.

    NAMES
         `opt = "out", "in", or "st"'
               string or string array containing desired signal names
               or values.

         `opt = "yd"'
               To desired output continuous/discrete flag.  Set name to
               0 for continuous, or 1 for discrete.

    LIST
          vector of indices of outputs, yd, inputs, or
          states whose respective names should be changed.

          Default: replace entire list of names/entire yd vector.
     *Outputs*     RETSYS=SYS with appropriate signal names changed
            (or yd values, where appropriate)

     *Example*
          octave:1> sys=ss2sys([1 2; 3 4],[5;6],[7 8]);
          octave:2> sys = syssetsignals(sys,"st",str2mat("Posx","Velx"));
          octave:3> sysout(sys)
          Input(s)
                  1: u_1
          Output(s):
                  1: y_1
          state-space form:
          2 continuous states, 0 discrete states
          State(s):
                  1: Posx
                  2: Velx
          A matrix: 2 x 2
            1  2
            3  4
          B matrix: 2 x 1
            5
            6
          C matrix: 1 x 2
            7  8
          D matrix: 1 x 1
          0



File: octave,  Node: sysupdate,  Prev: syssetsignals,  Up: structaccess

 - 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

 - 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

 - Function File :  VEC =  tf2sysl (VEC)
     used internally in *Note tf2sys::.   strip leading zero
     coefficients to get the true polynomial length


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

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

 - Function File :   sysout ( SYS{, OPT})
     print out a system data structure in desired format
    SYS
          system data structure

    OPT
          Display option
         `[]'
               primary system form (default); see *Note sysgettype::.

         `"ss"'
               state space form

         `"tf"'
               transfer function form

         `"zp"'
               zero-pole form

         `"all"'
               all of the above

 - 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"'

 - Function File :   tfout (NUM, DENOM{, X})
     print formatted transfer function `n(s)/d(s) ' to the screen  X
     defaults to the string `"s"'

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

* Menu:

* buildssic::
* jet707::
* ord2::
* parallel::
* sysadd::
* sysappend::
* sysconnect::
* syscont::
* syscont_disc::
* sysdisc::
* sysdup::
* sysgroup::
* sysgroupn::
* sysmult::
* sysprune::
* sysreorder::
* sysscale::
* syssub::

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


File: octave,  Node: buildssic,  Next: jet707,  Prev: blockdiag,  Up: blockdiag

 - 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);')


File: octave,  Node: jet707,  Next: ord2,  Prev: buildssic,  Up: blockdiag

 - 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

