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: ord2,  Next: parallel,  Prev: jet707,  Up: blockdiag

 - Function File :  OUTSYS = ord2 (NFREQ, DAMP{[, GAIN})
     Creates a continuous 2nd order system with parameters: *Inputs*
    NFREQ:   NATURAL FREQUENCY [HZ]. (NOT IN RAD/S)
    DAMP:    DAMPING COEFFICIENT
    GAIN:    DC-GAIN
          This is steady state value only for damp > 0.
          gain is assumed to be 1.0 if ommitted.  *Outputs* OUTSYS
     system data structure has representation with `w = 2 * pi *
     nfreq':
              /                                        \
              | / -2w*damp -w \  / w \                 |
          G = | |             |, |   |, [ 0  gain ], 0 |
              | \   w       0 /  \ 0 /                 |
              \                                        /
     *See also* `jet707' (MIMO example, Boeing 707-321 aircraft model)


File: octave,  Node: parallel,  Next: sysadd,  Prev: ord2,  Up: blockdiag

 - Function File :  SYSP = parallel(ASYS, BSYS)
     Forms the parallel connection of two systems.
                   ____________________
                   |      ________    |
          u  ----->|----> | Asys |--->|----> y1
              |    |      --------    |
              |    |      ________    |
              |--->|----> | Bsys |--->|----> y2
                   |      --------    |
                   --------------------
                        Ksys


File: octave,  Node: sysadd,  Next: sysappend,  Prev: parallel,  Up: blockdiag

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


File: octave,  Node: sysappend,  Next: sysconnect,  Prev: sysadd,  Up: blockdiag

 - Function File : RETSYS = sysappend (SYS,B{, C, D, OUTNAME, INNAME,
          YD})
     appends new inputs and/or outputs to a system

     *Inputs*
    SYS
          system data structure

    B
          matrix to be appended to sys "B" matrix (empty if none)

    C
          matrix to be appended to sys "C" matrix (empty if none)

    D
          revised sys d matrix (can be passed as [] if the revised d is
          all zeros)

    OUTNAME
          list of names for new outputs

    INNAME
          list of names for new inputs

    YD
          binary vector; `yd(ii)=0' indicates a continuous output;
          `yd(ii)=1' indicates a discrete output.

     *Outputs* SYS
             sys.b := [sys.b , b]
             sys.c := [sys.c  ]
                      [ c     ]
             sys.d := [sys.d | D12 ]
                      [D21   | D22 ]
     where D12, D21, and D22 are the appropriate dimensioned
     blocks of the input parameter D.
        * The leading block D11 of D is ignored.

        * If INNAME and OUTNAME are not given as arguments,         the
          new inputs and outputs are be assigned default names.

        * YD is a binary vector of length rows(c) that indicates
          continuous/sampled outputs.  Default value for YD is:

        * SYS = continuous or mixed YD = `zeros(1,rows(c))'

        * SYS = discrete YD = `ones(1,rows(c))'



File: octave,  Node: sysconnect,  Next: syscont,  Prev: sysappend,  Up: blockdiag

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



File: octave,  Node: syscont,  Next: syscont_disc,  Prev: sysconnect,  Up: blockdiag

 - 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



File: octave,  Node: syscont_disc,  Next: sysdisc,  Prev: syscont,  Up: blockdiag

 - 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



File: octave,  Node: sysdisc,  Next: sysdup,  Prev: syscont_disc,  Up: blockdiag

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



File: octave,  Node: sysdup,  Next: sysgroup,  Prev: sysdisc,  Up: blockdiag

 - Function File :  RETSYS = sysdup (ASYS, OUT_IDX, IN_IDX)
     Duplicate specified input/output connections of a system

     *Inputs*
    ASYS
          system data structure (*Note ss2sys::)

    OUT_IDX,IN_IDX
          list of connections indices;        duplicates are made of
          Y(OUT_IDX(II)) and U(IN_IDX(II)).

     *Outputs* RETSYS: resulting closed loop system:     duplicated i/o
     names are appended with a `"+"' suffix.

     *Method* `sysdup' creates copies of selected inputs and outputs as
     shown below.  u1/y1 is the set of original inputs/outputs, and
     u2,y2 is the set of duplicated inputs/outputs in the order
     specified  in IN_IDX, OUT_IDX, respectively
                    ____________________
          u1  ----->|                  |----> y1
                    |       Asys       |
          u2 ------>|                  |----->y2
          (in_idx)  -------------------| (out_idx)



File: octave,  Node: sysgroup,  Next: sysgroupn,  Prev: sysdup,  Up: blockdiag

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



File: octave,  Node: sysgroupn,  Next: sysmult,  Prev: sysgroup,  Up: blockdiag

 - Function File :  NAMES = sysgroupn (NAMES)
     Locate and mark duplicate names.  Used internally in sysgroup (and
     elsewhere).


File: octave,  Node: sysmult,  Next: sysprune,  Prev: sysgroupn,  Up: blockdiag

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


File: octave,  Node: sysprune,  Next: sysreorder,  Prev: sysmult,  Up: blockdiag

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



File: octave,  Node: sysreorder,  Next: sysscale,  Prev: sysprune,  Up: blockdiag

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


File: octave,  Node: sysscale,  Next: syssub,  Prev: sysreorder,  Up: blockdiag

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


File: octave,  Node: syssub,  Prev: sysscale,  Up: blockdiag

 - 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 :  OUTSYS = ugain(n)
     Creates a system with unity gain, no states.   This trivial system
     is sometimes needed to create arbitrary  complex systems from
     simple systems with buildssic.   Watch out if you are forming
     sampled systems since "ugain"  does not contain a sampling period.

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


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


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

Numerical Functions
===================

 - Function File:  are (A, B, C, OPT)
     Solve the algebraic Riccati equation
          a' * x + x * a - x * b * x + c = 0

     *Inputs*

     for identically dimensioned square matrices
    A
          NxN matrix.

    B
          NxN matrix or NxM matrix; in the latter case   B is replaced
          by `b:=b*b''.

    C
          NxN matrix or PxM matrix; in the latter case   C is replaced
          by `c:=c'*c'.

    OPT
          (optional argument; default = `"B"'): String option passed to
          `balance' prior to ordered Schur decomposition.

     *Outputs* X: solution of the ARE.

     *Method* Laub's Schur method (IEEE Transactions on Automatic
     Control, 1979) is applied to the appropriate Hamiltonian matrix.


 - Function File:  dare (A, B, C, R, OPT)
     Return the solution, X of the discrete-time algebraic Riccati
     equation
          a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0

     *Inputs*
    A
          N by N.

    B
          N by M.

    C
          N by N, symmetric positive semidefinite, or P by N.  In the
          latter case `c:=c'*c' is used.

    R
          M by M, symmetric positive definite (invertible).

    OPT
          (optional argument; default = `"B"'): String option passed to
          `balance' prior to ordered QZ decomposition.

     *Outputs* X solution of DARE.

     *Method* Generalized eigenvalue approach (Van Dooren; SIAM J.
     Sci. Stat. Comput., Vol 2) applied  to the appropriate symplectic
     pencil.

     See also: Ran and Rodman, "Stable Hermitian Solutions of Discrete
     Algebraic Riccati Equations," Mathematics of Control, Signals and
     Systems, Vol 5, no 2 (1992)  pp 165-194.


 - Function File :  M = dgram ( A, B)
     Return controllability grammian of discrete time system
            x(k+1) = a x(k) + b u(k)

     *Inputs*
    A
          N by N matrix

    B
          N by M matrix

     *Outputs* M (N by N) satisfies
           a m a' - m + b*b' = 0


 - Function File: X =  dlyap (A, B)
     Solve the discrete-time Lyapunov equation

     *Inputs*
    A
          N by N matrix

    B
          Matrix: N by N, N by M, or P by N.       *Outputs*   X:
     matrix satisfying appropriate discrete time Lyapunov equation.
     Options:
        * B is square: solve `a x a' - x + b = 0'

        * B is not square: X satisfies either
                     a x a' - x + b b' = 0
                       or
                a' x a - x + b' b = 0,
                       whichever is appropriate.     *Method*   Uses
     Schur decomposition method as in Kitagawa,     `An Algorithm for
     Solving the Matrix Equation X =     FXF' + S',   International
     Journal of Control, Volume 25, Number 5, pages 745-753   (1977).

     Column-by-column solution method as suggested in   Hammarling,
     `Numerical Solution of the Stable, Non-Negative   Definite
     Lyapunov Equation', IMA Journal of Numerical Analysis, Volume   2,
     pages 303-323 (1982).


 - Function File :  M = gram (A, B)
     Return controllability grammian M of the continuous time system `
     dx/dt = a x + b u'.

     M satisfies ` a m + m a' + b b' = 0 '.

 - Function File:  lyap (A, B, C)
 - Function File:  lyap (A, B)
     Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart
      algorithm (Communications of the ACM, 1972).

     If A, B, and C are specified, then `lyap' returns   the solution
     of the  Sylvester equation    A and B must be real matrices.

     *Note* `qzval' is obsolete; use `qz' instead.

 - Function File :   zgfmul
 - Function File :   zgfslv
 - Function File :   zginit
 - Function File : RETSYS = zgpbal (ASYS)
 - Function File :  zgreduce
 - Function File :  [NONZ, ZER] = zgrownorm (MAT, MEPS)
 - Function File :  x = zgscal (F, Z, N, M, P)
 - Function File :   zgsgiv ( )
 - Function File :  X = zgshsr( Y)
     Used internally by `tzero'.  Minimal argument checking performed.

     Details involving major subroutines:
    `zgpbal'
          Implementation of zero computation generalized eigenvalue
          problem  balancing method.  `zgpbal' computes a
          state/input/output weighting that attempts to  reduced the
          range of the magnitudes of the nonzero elements of [a,b,c,d]
          The weighting uses scalar multiplication by powers of 2, so
          no roundoff  will occur.

          `zgpbal' should be followed by `zgpred'

    `zgreduce'
          Implementation of procedure REDUCE in (Emami-Naeini and Van
          Dooren, Automatica, 1982).

    `zgrownorm'
          Returns NONZ = number of rows of MAT whose two norm exceeds
               MEPS, ZER = number of rows of mat whose two norm
          is less than meps

    `zgscal'
          Generalized conjugate gradient iteration to  solve
          zero-computation generalized eigenvalue problem balancing
          equation  `fx=z';  called by `zgepbal'

    `zgsgiv'
          apply givens rotation c,s to column vector a,b

    `zgshsr'
          Apply Householder vector based on `e^(m)' (all ones) to
          (column vector) Y.  Called by `zgfslv'.

     References:
    *ZGEP*
          Hodel, "Computation of Zeros with Balancing," 1992, Linear
          Algebra  and its Applications

    **Generalized CG**
          Golub and Van Loan, "Matrix Computations, 2nd ed" 1989



File: octave,  Node: sysprop,  Next: systime,  Prev: numerical,  Up: Control Theory

System Analysis-Properties
==========================

 - Function File :   analdemo ( )
     Octave Controls toolbox demo: State Space analysis demo

 - Function File: [N, M, P] = abcddim (A, B, C, D)
     Check for compatibility of the dimensions of the matrices defining
     the linear system [A, B, C, D] corresponding to

          dx/dt = a x + b u
          y = c x + d u

     or a similar discrete-time system.

     If the matrices are compatibly dimensioned, then `abcddim' returns

    N
          The number of system states.

    M
          The number of system inputs.

    P
          The number of system outputs.

     Otherwise `abcddim' returns N = M = P = -1.

     Note: n = 0 (pure gain block) is returned without warning.

     See also: is_abcd

 - Function File : [Y, MY, NY] = abcddims (X)
     Used internally in `abcddim'.  If X is a zero-size matrix, both
     dimensions are set to 0 in Y.  MY and NY are the row and column
     dimensions of the result.

 - Function File : QS = ctrb(SYS {, B})
 - Function File : QS = ctrb(A, B)
     Build controllability matrix
                       2       n-1
          Qs = [ B AB A B ... A   B ]

     of a system data structure or the pair (A, B).

     *Note* `ctrb' forms the controllability matrix.         The
     numerical properties of `is_controllable'        are much better
     for controllability tests.

 - Function File : RETVAL = h2norm(SYS)
     Computes the H2 norm of a system data structure (continuous time
     only)

     Reference:  Doyle, Glover, Khargonekar, Francis, "State Space
     Solutions to Standard  H2 and Hinf Control Problems", IEEE TAC
     August 1989

 - Function File : [G, GMIN, GMAX] = hinfnorm(SYS{, TOL, GMIN, GMAX,
          PTOL})
     Computes the H infinity norm of a system data structure.

     *Inputs*
    SYS
          system data structure

    TOL
          H infinity norm search tolerance (default: 0.001)

    GMIN
          minimum value for norm search (default: 1e-9)

    GMAX
          maximum value for norm search (default: 1e+9)

    PTOL
          pole tolerance:
             * if sys is continuous, poles with |real(pole)| <
               ptol*||H|| (H is appropriate Hamiltonian) are considered
               to be on the imaginary axis.

             * if sys is discrete, poles with |abs(pole)-1| <
               ptol*||[s1,s2]|| (appropriate symplectic pencil) are
               considered to be on the unit circle

             * Default: 1e-9

     *Outputs*
    G
          Computed gain, within TOL of actual gain.  G is returned as
          Inf if the system is unstable.

    GMIN, GMAX
          Actual system gain lies in the interval [GMIN, GMAX]

     References:  Doyle, Glover, Khargonekar, Francis, "State space
     solutions to standard     H2 and Hinf control problems", IEEE TAC
     August 1989  Iglesias and Glover, "State-Space approach to
     discrete-time Hinf control,"     Int. J. Control, vol 54, #5, 1991
     Zhou, Doyle, Glover, "Robust and Optimal Control," Prentice-Hall,
     1996  $Revision: 1.9 $

 - Function File :  QB = obsv (SYS{, C})
     Build observability matrix
               | C        |
               | CA       |
          Qb = | CA^2     |
               | ...      |
               | CA^(n-1) |
     of a system data structure or the pair (A, C).

     Note: `obsv()' forms the observability matrix.

     The numerical properties of is_observable()        are much better
     for observability tests.

 - Function File : [ZER, POL]= pzmap (SYS)
     Plots the zeros and poles of a system in the complex plane.
     *Inputs*  SYS system data structure

     *Outputs* if omitted, the poles and zeros are plotted on the
     screen.            otherwise, pol, zer are returned as the system
     poles and zeros.            (see sys2zp for a preferable function
     call)

 - Function File: outputs =  synKnames (inputs)
     Return controller signal names based in plant signal names and
     dimensions

 - Function File :  RETVAL = is_abcd( A{, B, C, D})
     Returns RETVAL = 1 if the dimensions of A, B, C, D  are
     compatible, otherwise RETVAL = 0 with an appropriate diagnostic
     message printed to the screen.

 - Function File : [RETVAL, U] = is_controllable (SYS{, TOL})
 - Function File : [RETVAL, U] = is_controllable (A{, B ,TOL})
     Logical check for system controllability.

     *Inputs*
    SYS
          system data structure

    A, B
          N by N, N by M matrices, respectively

    TOL
          optional roundoff paramter.  default value: `10*eps'

     *Outputs*
    RETVAL
          Logical flag; returns true (1) if the system SYS or the pair
          (A,B) is controllable, whichever was passed as input
          arguments.

    U
          U is an orthogonal basis of the controllable subspace.

     *Method* Controllability is determined by applying Arnoldi
     iteration with complete re-orthogonalization to obtain an
     orthogonal basis of the Krylov subspace
          span ([b,a*b,...,a^{n-1}*b]).
     The Arnoldi iteration is executed with `krylov' if the system has
     a single input; otherwise a block Arnoldi iteration is performed
     with `krylovb'.

     *See also* `is_observable', `is_stabilizable', `is_detectable',
         `krylov', `krylovb'


 - Function File :  [RETVAL, U] = is_detectable (A, C{, TOL})
 - Function File :  [RETVAL, U] = is_detectable (SYS{, TOL})
     Test for detactability (observability of unstable modes) of (A,C).

     Returns 1 if the system A or the pair (A,C)is  detectable, 0 if
     not.

     *See* `is_stabilizable' for detailed description of arguments and
     computational method.


 - Function File :  [RETVAL, DGKF_STRUCT ] = is_dgkf (ASYS, NU, NY, TOL
          )
     Determine whether a continuous time state space system meets
     assumptions of DGKF algorithm.   Partitions system into:
          [dx/dt] = [A  | Bw  Bu  ][w]
          [ z   ]   [Cz | Dzw Dzu ][u]
          [ y   ]   [Cy | Dyw Dyu ]
     or similar discrete-time system.  If necessary, orthogonal
     transformations QW, QZ and nonsingular  transformations RU, RY are
     applied to respective vectors W, Z, U, Y in order to satisfy DGKF
     assumptions.  Loop shifting is used if DYU block is nonzero.

     *Inputs*
    ASYS
          system data structure

    NU
          number of controlled inputs

    NY
          number of measured outputs

    TOL
          threshhold for 0.  Default: 200EPS *Outputs*
    RETVAL
          true(1) if system passes check, false(0) otherwise

    DGKF_STRUCT
          data structure of `is_dgkf' results.  Entries:
         NW, NZ
               dimensions of W, Z

         A
               system A matrix

         BW
               (N x NW) QW-transformed disturbance input matrix

         BU
               (N x NU) RU-transformed controlled input matrix;

               *Note* `B = [Bw Bu] '

         CZ
               (NZ x N) Qz-transformed error output matrix

         CY
               (NY x N) RY-transformed measured output matrix

               *Note* `C = [Cz; Cy] '

         DZU, DYW
               off-diagonal blocks of transformed D matrix that enter
               Z, Y from U, W respectively

         RU
               controlled input transformation matrix

         RY
               observed output transformation matrix

         DYU_NZ
               nonzero if the DYU block is nonzero.

         DYU
               untransformed DYU block

         DFLG
               nonzero if the system is discrete-time   `is_dgkf' exits
     with an error if the system is mixed discrete/continuous

     *References*
    *[1]*
          Doyle, Glover, Khargonekar, Francis, "State Space Solutions
            to Standard H2 and Hinf Control Problems," IEEE TAC August
          1989

    *[2]*
          Maciejowksi, J.M.: "Multivariable feedback design,"


 - Function File :  RETVAL = is_digital ( SYS)
     Return nonzero if system is digital; Exits with an error of sys is
     a mixed (continuous and discrete) system

 - Function File :  [RETVAL,U] = is_observable (A, C{,TOL})
 - Function File :  [RETVAL,U] = is_observable (SYS{, TOL})
     Logical check for system observability.   Returns 1 if the system
     SYS or the pair (A,C) is  observable, 0 if not.

     *See* `is_controllable' for detailed description of arguments and
     default values.

 - Function File :  RETVAL = is_sample (TS)
     return true if TS is a legal sampling time  (real,scalar, > 0)

 - Function File :  RETVAL = is_siso (SYS)
     return nonzero if the system data structure SYS is single-input,
     single-output.

 - Function File : [RETVAL, U] = is_stabilizable (SYS{, TOL})
 - Function File : [RETVAL, U] = is_stabilizable (A{, B ,TOL})
     Logical check for system stabilizability (i.e., all unstable modes
     are controllable).

     *See* `is_controllable' for description of inputs, outputs.  Test
     for stabilizability is performed via an ordered Schur decomposition
     that reveals the unstable subspace of the system A matrix.


 - Function File : FLG = is_signal_list (MYLIST)
     returns true if mylist is a list of individual strings (legal for
     input to SYSSETSIGNALS).

 - Function File :  RETVAL = is_stable (A{,TOL,DFLG})
 - Function File :  RETVAL = is_stable (SYS{,TOL})
     Returns retval = 1 if the matrix A or the system SYS is stable, or
     0 if not.

     *Inputs*
    TOL
          is a roundoff paramter, set to 200*EPS if omitted.

    DFLG
          Digital system flag (not required for system data structure):
         `DFLG != 0'
               stable if eig(a) in unit circle

         `DFLG == 0'
               stable if eig(a) in open LHP (default)


File: octave,  Node: systime,  Next: sysfreq,  Prev: sysprop,  Up: Control Theory

System Analysis-Time Domain
===========================

 - Function File :  DSYS = c2d (SYS{, OPT, T})
 - Function File :  DSYS = c2d (SYS{, T})
     *Inputs*
    SYS
          system data structure (may have both continuous time and
          discrete time subsystems)

    OPT
          string argument; conversion option (optional argument; may be
          omitted as shown above)
         `"ex"'
               use the matrix exponential (default)

         `"bi"'
               use the bilinear transformation
                   2(z-1)
               s = -----
                   T(z+1)
          FIXME: This option exits with an error if SYS is not purely
          continuous. (The `ex' option can handle mixed systems.)

    T
          sampling time; required if sys is purely continuous.

          *Note* If the 2nd argument is not a string, `c2d' assumes that
          the 2nd argument is T and performs appropriate argument
          checks.

     *Outputs* DSYS discrete time equivalent via zero-order hold,
     sample each T sec.

     converts the system data structure describing
          .
          x = Ac x + Bc u
     into a discrete time equivalent model
          x[n+1] = Ad x[n] + Bd u[n]
     via the matrix exponential or bilinear transform

     *Note* This function adds the suffix  `_d' to the names of the new
     discrete states.

 - Function File : CSYS = d2c (SYS{,TOL})
 - Function File : CSYS = d2c (SYS, OPT)
     Convert discrete (sub)system to a purely continuous system.
     Sampling time used is `sysgettsam(SYS)'

     *Inputs*
    SYS
          system data structure with discrete components

    TOL
          Scalar value.   tolerance for convergence of default `"log"'
          option (see below)

    OPT
          conversion option.  Choose from:
         `"log"'
               (default) Conversion is performed via a matrix logarithm.
               Due to some problems with this computation, it is
               followed by a steepest descent algorithm to identify
               continuous time A, B, to get a better fit to the
               original data.

               If called as `d2c'(SYS,TOL), TOL=positive scalar,
               the `"log"' option is used.  The default value for TOL
               is         `1e-8'.

         `"bi"'
               Conversion is performed via bilinear transform `z = (1 +
               s T / 2)/(1 - s T / 2)' where T is the system sampling
               time (see `sysgettsam').

               FIXME: bilinear option exits with an error if SYS is not
               purely discrete

     *Outputs* CSYS continuous time system (same dimensions and signal
     names as in SYS).

 - Function File : [DSYS, FIDX] = dmr2d (SYS, IDX, SPREFIX, TS2
          {,CUFLG})
     convert a multirate digital system to a single rate digital system
     states specified by IDX, SPREFIX are sampled at TS2, all   others
     are assumed sampled at TS1 = `sysgettsam(SYS)'.

     *Inputs*
    SYS
          discrete time system; `dmr2d' exits with an error if SYS is
          not discrete

    IDX
          list of states with sampling time `sysgettsam(SYS)' (may be
          empty)

    SPREFIX
          list of string prefixes of states with sampling time
          `sysgettsam(SYS)' (may be empty)

    TS2
          sampling time of states not specified by IDX, SPREFIX must be
          an integer multiple of `sysgettsam(SYS)'

    CUFLG
          "constant u flag" if CUFLG is nonzero then the system inputs
          are         assumed to be constant over the revised sampling
          interval TS2.          Otherwise, since the inputs can change
          during the interval         T in `[k Ts2, (k+1) Ts2]', an
          additional set of inputs is         included in the revised B
          matrix so that these intersample inputs         may be
          included in the single-rate system.          default  CUFLG =
          1.

     *Outputs*
    DSYS
          equivalent discrete time system with sampling time TS2.

          The sampling time of sys is updated to TS2.

          if CUFLG=0 then a set of additional inputs is added to
           the system with suffixes _d1, ..., _dn to indicate their
               delay from the starting time k TS2, i.e.           u =
          [u_1; u_1_d1; ..., u_1_dn] where u_1_dk is the input
             k*Ts1 units of time after u_1 is sampled. (Ts1 is
              the original sampling time of discrete time sys and
                 TS2 = (n+1)*Ts1)

    FIDX
          indices of "formerly fast" states specified by IDX and
          SPREFIX; these states are updated to the new (slower)
          sampling interval TS2.

     *WARNING* Not thoroughly tested yet; especially when CUFLG == 0.


 - Function File :  damp(P{, TSAM})
     Displays eigenvalues, natural frequencies and damping ratios
     of the eigenvalues of a matrix P or the A-matrix of a       system
     P, respectively.        If P is a system, TSAM must not be
     specified.        If P is a matrix and TSAM is specified,
     eigenvalues       of P are assumed to be in Z-domain.

     See also: `eig'

 - Function File : GM = dcgain(SYS{, tol})
     Returns dc-gain matrix. If dc-gain is infinite       an empty
     matrix is returned.        The argument TOL is an optional
     tolerance for the condition       number of A-Matrix in SYS
     (default TOL = 1.0e-10)

 - Function File : [Y, T] = impulse (SYS{, INP,TSTOP, N})
     Impulse response for a linear system.         The system can be
     discrete or multivariable (or both).  If no output arguments are
     specified, `impulse'  produces a plot or the step response data
     for system SYS.

     *Inputs*
    SYS
          System data structure.

    INP
          Index of input being excited

    TSTOP
          The argument TSTOP (scalar value) denotes the time when the
          simulation should end.

    N
          the number of data values.

          Both parameters TSTOP and N can be omitted and will be
          computed from the eigenvalues of the A-Matrix.  *Outputs* Y,
     T: impulse response

 - Function File : [Y, T] = step (SYS{, INP,TSTOP, N})
     Step response of a linear system; calling protocol is identical to
     `impulse'.

 - Function File :   stepimp ( )
     Used internally in `impulse', `step'.


File: octave,  Node: sysfreq,  Next: cacsd,  Prev: systime,  Up: Control Theory

System Analysis-Frequency Domain
================================

   *Demonstration/tutorial script*

 - Function File :   frdemo ( )

 - Function File : [MAG, PHASE, W] = bode(SYS{,W, OUT_IDX, IN_IDX})
     If no output arguments are given: produce Bode plots of a system;
     otherwise, compute the frequency response of a system data
     structure

     *Inputs*
    SYS
          a system data structure (must be either purely continuous or
          discrete;          see is_digital)

    W
          frequency values for evaluation.

          if SYS is continuous, then bode evaluates `G(jw)' where
          `G(s)' is the system transfer function.

          if SYS is discrete, then bode evaluates G(`exp'(jwT)), where
             * T=`sysgettsam(SYS)' (the system sampling time) and

             * `G(z)' is the system transfer function.

          * Default* the default frequency range is selected as
          follows: (These         steps are NOT performed if W is
          specified)
            1. via routine bodquist, isolate all poles and zeros away
               from W=0 (JW=0 or ``exp'(jwT)'=1) and select the
               frequency range based on the breakpoint locations of the
               frequencies.

            2. if SYS is discrete time, the frequency range is limited
                           to `jwT' in [0,2 pi /T]

            3. A "smoothing" routine is used to ensure that the plot
               phase does               not change excessively from
               point to point and that singular               points
               (e.g., crossovers from +/- 180) are accurately shown.


    OUT_IDX, IN_IDX
          the indices of the output(s) and input(s) to be used in
          the frequency response; see `sysprune'.  *Outputs*
    MAG, PHASE
          the magnitude and phase of the frequency response
          `G(jw)' or `G(`exp'(jwT))' at the selected frequency values.

    W
          the vector of frequency values used

     *Notes*
       1. If no output arguments are given, e.g.,
               bode(sys);
          bode plots the results to the screen.  Descriptive labels are
          automatically placed.

          Failure to include a concluding semicolon will yield some
          garbage being printed to the screen (`ans = []').

       2. If the requested plot is for an MIMO system, mag is set to
          `||G(jw)||' or `||G(`exp'(jwT))||' and phase information is
          not computed.

 - Function File : [WMIN, WMAX] = bode_bounds (ZER, POL, DFLG{, TSAM })
     Get default range of frequencies based on cutoff frequencies of
     system poles and zeros.  Frequency range is the interval
     [10^wmin,10^wmax]

     Used internally in freqresp (`bode', `nyquist')

 - Function File :  [F, W] = bodquist (SYS, W, OUT_IDX, IN_IDX)
     used internally by bode, nyquist; compute system frequency
     response.

     *Inputs*
    SYS
          input system structure

    W
          range of frequencies; empty if user wants default

    OUT_IDX
          list of outputs; empty if user wants all

    IN_IDX
          list of inputs; empty if user wants all

    RNAME
          name of routine that called bodquist ("bode" or "nyquist")
     *Outputs*
    W
          list of frequencies

    F
          frequency response of sys; `f(ii) = f(omega(ii))' *Note*
     bodquist could easily be incorporated into a Nichols plot
     function; this is in a "to do" list.

 - Function File :  RETVAL = freqchkw ( W )
     Used by `freqresp' to check that input frequency vector W is legal.
     Returns boolean value.

 - Function File :  OUT = freqresp (SYS,USEW{,W});
     Frequency response function - used internally by `bode', `nyquist'.
     minimal argument checking; "do not attempt to do this at home"

     *Inputs*
    SYS
          system data structure

    USEW
          returned by `freqchkw'

    OPTIONAL
          must be present if USEW is true (nonzero) *Outputs*
    OUT
          vector of finite `G(j*w)' entries (or `||G(j*w)||' for MIMO)

    W
          vector of corresponding frequencies

 - Function File : OUT = ltifr (A, B, W)
 - Function File : OUT = ltifr (SYS, W)
     Linear time invariant frequency response of single input systems
     *Inputs*
    A, B
          coefficient matrices of `dx/dt = A x + B u'

    SYS
          system data structure

    W
          vector of frequencies *Outputs* OUT
                                     -1
                      G(s) = (jw I-A) B
     for complex frequencies `s = jw'.

 - Function File : [REALP, IMAGP, W] = nyquist (SYS{, W, OUT_IDX,
          IN_IDX, ATOL})
 - Function File :  nyquist (SYS{, W, OUT_IDX, IN_IDX, ATOL})
     Produce Nyquist plots of a system; if no output arguments are
     given, Nyquist plot is printed to the screen.

     Arguments are identical to `bode' with exceptions as noted below:

     *Inputs* (pass as empty to get default values)
    ATOL
          for interactive nyquist plots: atol is a change-in-slope
          tolerance for the of asymptotes (default = 0; 1e-2 is a good
          choice).  This allows the user to "zoom in" on portions of
          the Nyquist plot too small to be seen with large asymptotes.
     *Outputs*
    REALP, IMAGP
          the real and imaginary parts of the frequency response
          `G(jw)' or `G(exp(jwT))' at the selected frequency values.

    W
          the vector of frequency values used

     If no output arguments are given, nyquist plots the results to the
     screen.   If ATOL != 0 and asymptotes are detected then the user
     is asked     interactively if they wish to zoom in (remove
     asymptotes)  Descriptive labels are automatically placed.

     Note: if the requested plot is for an MIMO system, a warning
     message is  presented; the returned information is of the magnitude
     ||G(jw)|| or ||G(exp(jwT))|| only; phase information is not
     computed.


 - Function File:  tzero (A, B, C, D{, OPT})
 - Function File:  tzero (SYS{,OPT})
     Compute transmission zeros of a continuous
          .
          x = Ax + Bu
          y = Cx + Du
     or discrete
          x(k+1) = A x(k) + B u(k)
          y(k)   = C x(k) + D u(k)
     system.  *Outputs*
    ZER
          transmission zeros of the system

    GAIN
          leading coefficient (pole-zero form) of SISO transfer function
          returns gain=0 if system is multivariable *References*
       1. Emami-Naeini and Van Dooren, Automatica, 1982.

       2. Hodel, "Computation of Zeros with Balancing," 1992 Lin. Alg.
          Appl.

 - Function File :  ZR = tzero2 (A, B, C, D, BAL)
     Compute the transmission zeros of a, b, c, d.

     bal = balancing option (see balance); default is "B".

     Needs to incorporate `mvzero' algorithm to isolate finite zeros;
     use `tzero' instead.

