@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Control Theory, Signal Processing, Polynomial Manipulations, Top
@chapter Control Theory

The Octave Control Systems Toolbox (OCST) was initially developed
by Dr.@: A. Scottedward Hodel 
@email{a.s.hodel@@eng.auburn.edu} with the assistance
of his students
@itemize @bullet
@item R. Bruce Tenison @email{btenison@@dibbs.net}, 
@item David C. Clem,
@item John E. Ingram @email{John.Ingram@@sea.siemans.com}, and 
@item Kristi McGowan.  
@end itemize
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 @email{mueller@@ifr.ing.tu-bs.de}
and Jose Daniel Munoz Frias (@code{place.m}).

An on-line menu-driven tutorial is available via @ref{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.
@end menu

@node DEMOcontrol, sysstruct, Control Theory, Control Theory
@unnumberedsec OCST demo program
@DOCSTRING(DEMOcontrol)

@node sysstruct, sysinterface, DEMOcontrol, Control Theory
@section 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.
@end menu
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 (@xref{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.

@node sysrepdemo, sysstructvars, sysstruct, sysstruct
@unnumberedsec System representation demo program
@DOCSTRING(sysrepdemo)

@node sysstructvars, sysstructtf, sysrepdemo, sysstruct
@subsection 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 @code{DEMOcontrol}.
@table @var
@item n,nz
The respective number of continuous and discrete states
in the system (scalar)

@item inname, outname
list of name(s) of the system input, output signal(s). (list of strings)

@item 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 (@xref{sysupdate}).

@table @var

@item sys(0)
primary system type

           =0 for tf form (initialized with @code{tf2sys} or @code{fir2sys})

           =1 for zp form (initialized with @code{zp2sys})

           =2 for ss form (initialized with @code{ss2sys})

@item 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 @code{sysupdate} command.
@end table

@item tsam
 Discrete time sampling period  (nonnegative scalar).
 @var{tsam} is set to 0 for continuous time systems.

@item 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.
@end table

The remaining variables of the  system data structure are only present
if the corresponding entry of the @code{sys} vector is true (=1).

@node sysstructtf, sysstructzp, sysstructvars, sysstruct
@subsection @code{tf} format variables

@table @var

@item num
 numerator coefficients   (vector)

@item den
 denominator coefficients   (vector)

@end table

@node sysstructzp, sysstructss, sysstructtf, sysstruct
@subsection @code{zp} format variables
@table @var
@item zer
 system zeros   (vector)

@item pol
 system poles    (vector)

@item k
 leading coefficient   (scalar)

@end table

@node sysstructss,  , sysstructzp, sysstruct
@subsection @code{ss} format variables
@table @var
@item 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

@strong{Note} some functions (e.g., @code{bode}, @code{hinfsyn}) 
will not accept systems with both discrete and continuous states/outputs

@item stname
names of system states   (list of strings)

@end table

@node sysinterface, sysdisp, sysstruct,  Control Theory
@section System Construction and Interface Functions

Construction and manipulations of the OCST system data structure
(@xref{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 @ref{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
@end menu

@node fir2sys,sys2fir,sysinterface,sysinterface
@subsection Finite impulse response system interface functions

@DOCSTRING(fir2sys)

@node sys2fir,ss2sys,fir2sys, sysinterface
@DOCSTRING(sys2fir)

@node ss2sys, sys2ss, sys2fir, sysinterface
@subsection State space system interface functions

@DOCSTRING(ss2sys)

@node sys2ss,tf2sys,ss2sys,sysinterface
@DOCSTRING(sys2ss)

@node tf2sys,sys2tf,sys2ss,sysinterface
@subsection Transfer function system interface functions
@DOCSTRING(tf2sys)

@node sys2tf,zp2sys,tf2sys,sysinterface
@DOCSTRING(sys2tf)

@node zp2sys,sys2zp,sys2tf,sysinterface
@subsection Zero-pole system interface functions
@DOCSTRING(zp2sys)

@node sys2zp, structaccess, zp2sys, sysinterface
@DOCSTRING(sys2zp)

@node structaccess, structintern, sys2zp, sysinterface
@subsection Data structure access functions

@menu
* syschnames::
* syschtsam::
* sysdimensions::
* sysgetsignals::
* sysgettsam::
* sysgettype::
* syssetsignals::
* sysupdate::
@end menu

@node syschnames, syschtsam, structaccess, structaccess
@DOCSTRING(syschnames)

@node syschtsam, sysdimensions, syschnames, structaccess
@DOCSTRING(syschtsam)

@node sysdimensions, sysgetsignals, syschtsam, structaccess
@DOCSTRING(sysdimensions)

@node sysgetsignals, sysgettsam, sysdimensions, structaccess
@DOCSTRING(sysgetsignals)

@node sysgettype, syssetsignals, sysgettsam, structaccess
@DOCSTRING(sysgettype)

@node syssetsignals, sysupdate, sysgettype, structaccess
@DOCSTRING(syssetsignals)

@node sysupdate, , syssetsignals, structaccess
@DOCSTRING(sysupdate)

@node structintern, , structaccess, sysinterface
@subsection Data structure internal functions
@DOCSTRING(syschnamesl)

@DOCSTRING(sysdefioname)

@DOCSTRING(sysdefstname)

@DOCSTRING(tf2sysl)

@node sysdisp, blockdiag, sysinterface, Control Theory
@section System display functions

@DOCSTRING(sysout)

@DOCSTRING(polyout)

@DOCSTRING(tfout)

@DOCSTRING(zpout)

@DOCSTRING(outlist)

@node blockdiag, numerical,  sysdisp, Control Theory
@section Block Diagram Manipulations

@xref{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::
@end menu

@DOCSTRING(bddemo)

@node buildssic, jet707, blockdiag, blockdiag
@DOCSTRING(buildssic)

@node jet707, ord2,  buildssic, blockdiag
@DOCSTRING(jet707)

@node ord2, parallel, jet707, blockdiag
@DOCSTRING(ord2)

@node sysadd, sysappend,  parallel, blockdiag
@DOCSTRING(sysadd)

@node sysappend, sysconnect, sysadd,  blockdiag
@DOCSTRING(sysappend)

@node sysconnect, syscont, sysappend,  blockdiag
@DOCSTRING(sysconnect)

@node syscont, syscont_disc,  sysconnect, blockdiag

@DOCSTRING(syscont)

@node syscont_disc, sysdisc,  syscont, blockdiag
@DOCSTRING(syscont_disc)

@node sysdisc, sysdup,  syscont_disc, blockdiag
@DOCSTRING(sysdisc)

@node sysdup, sysgroup,  sysdisc, blockdiag
@DOCSTRING(sysdup) 

@node sysgroup, sysgroupn,  sysdup, blockdiag
@DOCSTRING(sysgroup)

@node sysgroupn, sysmult,  sysgroup, blockdiag
@DOCSTRING(sysgroupn)

@node sysmult, sysprune,  sysgroupn, blockdiag
@DOCSTRING(sysmult)

@node sysprune, sysreorder, sysmult, blockdiag
@DOCSTRING(sysprune)

@node sysreorder, sysscale,  sysprune, blockdiag
@DOCSTRING(sysreorder)

@node sysscale, syssub,  sysreorder, blockdiag
@DOCSTRING(sysscale)

@node syssub, ,  sysscale, blockdiag
@DOCSTRING(syssub)

@DOCSTRING(ugain)

@DOCSTRING(wgt1o)

@node numerical,  sysprop, blockdiag, Control Theory
@section Numerical Functions
@DOCSTRING(are)

@DOCSTRING(dare)

@DOCSTRING(dgram)

@DOCSTRING(dlyap)

@DOCSTRING(gram)

@DOCSTRING(lyap)

@DOCSTRING(pinv)

@DOCSTRING(qzval)

@DOCSTRING(zgfmul)
@DOCSTRING(zgfslv)
@DOCSTRING(zginit)
@DOCSTRING(zgpbal)
@DOCSTRING(zgreduce)
@DOCSTRING(zgrownorm)
@DOCSTRING(zgscal)
@DOCSTRING(zgsgiv)
@DOCSTRING(zgshsr)

References:
@table @strong
@item  ZGEP
 Hodel, "Computation of Zeros with Balancing," 1992, Linear Algebra
 and its Applications
@item @strong{Generalized CG}
 Golub and Van Loan, "Matrix Computations, 2nd ed" 1989
@end table

@node sysprop, systime, numerical,  Control Theory
@section System Analysis-Properties

@DOCSTRING(analdemo)

@DOCSTRING(abcddim)

@DOCSTRING(abcddims)

@DOCSTRING(ctrb)

@DOCSTRING(h2norm)

@DOCSTRING(hinfnorm)

@DOCSTRING(obsv)

@DOCSTRING(pzmap)

@deftypefn{Function File} {outputs = } synKnames (inputs)
Return controller signal names based in plant signal names and dimensions
@end deftypefn

@DOCSTRING(is_abcd)

@DOCSTRING(is_controllable)

@DOCSTRING(is_detectable)

@DOCSTRING(is_dgkf)

@DOCSTRING(is_digital)

@DOCSTRING(is_observable)

@DOCSTRING(is_sample)

@DOCSTRING(is_siso)

@DOCSTRING(is_stabilizable)

@DOCSTRING(is_signal_list)

@DOCSTRING(is_stable)

@node systime, sysfreq, sysprop, Control Theory
@section System Analysis-Time Domain

@DOCSTRING(c2d)

@DOCSTRING(d2c)

@DOCSTRING(dmr2d)

@DOCSTRING(damp)

@DOCSTRING(dcgain)

@DOCSTRING(impulse)

@DOCSTRING(step)

@DOCSTRING(stepimp)

@node sysfreq, cacsd, systime,  Control Theory
@section System Analysis-Frequency Domain

@strong{Demonstration/tutorial script}
@DOCSTRING(frdemo)

@DOCSTRING(bode)

@DOCSTRING(bode_bounds)

@DOCSTRING(bodquist)

@DOCSTRING(freqchkw)

@DOCSTRING(freqresp)

@DOCSTRING(ltifr)

@DOCSTRING(nyquist)

@DOCSTRING(tzero)

@DOCSTRING(tzero2)

@node cacsd, misc, sysfreq, Control Theory
@section Controller Design

@DOCSTRING(dgkfdemo)

@DOCSTRING(hinfdemo)

@DOCSTRING(dlqe)

@DOCSTRING(dlqr)

@DOCSTRING(h2syn)

@DOCSTRING(hinf_ctr)

@DOCSTRING(hinfsyn)

@DOCSTRING(hinfsyn_c)
@deftypefn {Function File } {[@var{xx}, @var{err}] =} hinfsyn_c (@var{nn}, @var{ptol}, @var{s1}@{, @var{s2}@})
used internally in hinfsyn to evaluate hamiltonian/symplectic
 eigenvalue problems.

@strong{WARNING} Argument checking not performed.

@strong{Inputs}
@table @var
@item  s1 @r{(alone)}
hamiltonian matrix
@item (s1,s2) @r{ as a pair}
symplectic matrix pencil
@end table
@strong{Outputs}
@table @var
@item   xx: positive (semi-)definite solution of DARE (set to 0 if err <=2)
@item   code:  error:
@table @strong
@item 0
no error 
@item 1
   (s1): eigenvalues on imaginary axis

          (s1,s2): gen. eigenvalues on unit circle
@item 2
   unequal number of stable/antistable (generalized) eigenvalues
@item 3
(s1): infinite entries in solution x 

(s1,s2): infinite entires in solution x or (I + R X) singular
@item 4
x is not symmetric
@item 5
x has negative eigenvalues
@end table
@end table

Solution method: Either Laub's schur method or Symplectic GEP approach; 
uses Van Dooren's code to re-order qz decompostion 
(www.netlib.com - toms/590)

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.

@end deftypefn

@DOCSTRING(hinfsyn_chk)

@DOCSTRING(lqe)

@DOCSTRING(lqg)

@DOCSTRING(lqr)

@DOCSTRING(lsim)

@DOCSTRING(place)

@node misc, , cacsd, Control Theory
@section Miscellaneous Functions (Not yet properly filed/documented)

@DOCSTRING(axis2dlim)

@deftypefn {Function File } { outputs =} mb ( inputs ) 
@format
 $Revision: 1.9 $


@end format
@end deftypefn

@DOCSTRING(moddemo)

@DOCSTRING(prompt)

@DOCSTRING(rldemo)

@DOCSTRING(rlocus)

@DOCSTRING(sortcom)

@DOCSTRING(ss2tf)

@DOCSTRING(ss2zp)

@DOCSTRING(starp)

@DOCSTRING(susball)

@DOCSTRING(tf2ss)

@DOCSTRING(tf2zp)

@DOCSTRING(zp2ss)

@DOCSTRING(zp2ssg2)

@DOCSTRING(zp2tf)