Mercurial > hg > octave-lyh
changeset 3346:8dd4718801fd
[project @ 1999-11-09 18:18:12 by jwe]
line wrap: on
line diff
--- a/doc/interpreter/control.txi +++ b/doc/interpreter/control.txi @@ -39,27 +39,7 @@ @node DEMOcontrol, sysstruct, Control Theory, Control Theory @unnumberedsec OCST demo program -@deftypefn {Function File } { } DEMOcontrol -Octave Control Systems Toolbox demo/tutorial program. The demo -allows the user to select among several categories of OCST function: -@example -@group -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 -@end group -@end example -Command examples are interactively run for users to observe the use -of OCST functions. -@end deftypefn +@DOCSTRING(DEMOcontrol) @node sysstruct, sysinterface, DEMOcontrol, Control Theory @section System Data Structure @@ -89,9 +69,7 @@ @node sysrepdemo, sysstructvars, sysstruct, sysstruct @unnumberedsec System representation demo program -@deftypefn {Function File } {} sysrepdemo -Tutorial for the use of the system data structure functions. -@end deftypefn +@DOCSTRING(sysrepdemo) @node sysstructvars, sysstructtf, sysrepdemo, sysstruct @subsection Variables common to all OCST system formats @@ -218,387 +196,32 @@ @node fir2sys,sys2fir,sysinterface,sysinterface @subsection Finite impulse response system interface functions -@deftypefn {Function File } { @var{sys} =} fir2sys ( @var{num}@{, @var{tsam}, @var{inname}, @var{outname} @} ) - construct a system data structure from FIR description - -@strong{Inputs:} -@table @var -@item num - vector of coefficients @math{[c_0 c_1 ... c_n]} -of the SISO FIR transfer function -@ifinfo - -C(z) = c0 + c1*z^@{-1@} + c2*z^@{-2@} + ... + znz^@{-n@} - -@end ifinfo -@iftex -@tex -$$C(z) = c0 + c1*z^{-1} + c2*z^{-2} + ... + znz^{-n}$$ -@end tex -@end iftex - -@item tsam - sampling time (default: 1) - -@item inname -name of input signal; may be a string or a list with a single entry. - -@item outname - name of output signal; may be a string or a list with a single entry. -@end table - -@strong{Outputs} - @var{sys} (system data structure) - -@strong{Example} -@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 -@end example -@end deftypefn +@DOCSTRING(fir2sys) @node sys2fir,ss2sys,fir2sys, sysinterface -@deftypefn {Function File } {[@var{c}, @var{tsam}, @var{input}, @var{output}] =} sys2fir (@var{sys}) - -Extract FIR data from system data structure; see @ref{fir2sys} for -parameter descriptions. - -@end deftypefn - +@DOCSTRING(sys2fir) @node ss2sys, sys2ss, sys2fir, sysinterface @subsection State space system interface functions -@deftypefn {Function File } { @var{sys} =} ss2sys (@var{a},@var{b},@var{c}@{,@var{d}, @var{tsam}, @var{n}, @var{nz}, @var{stname}, @var{inname}, @var{outname}, @var{outlist}@}) - Create system structure from state-space data. May be continous, - discrete, or mixed (sampeld-data) -@strong{Inputs} -@table @var -@item a, b, c, d - usual state space matrices. - - default: @var{d} = zero matrix - -@item tsam - sampling rate. Default: @math{tsam = 0} (continuous system) - -@item n, nz - number of continuous, discrete states in the system - - default: -@table @var -@item tsam = 0 -@math{n = @code{rows}(@var{a})}, @math{nz = 0} - -@item tsam > 0 -@math{ n = 0}, @math{nz = @code{rows}(@var{a})} - - see below for system partitioning - -@end table - -@item stname - list of strings of state signal names - - default (@var{stname}=[] on input): @code{x_n} for continuous states, - @code{xd_n} for discrete states - -@item inname - list of strings of input signal names - - default (@var{inname} = [] on input): @code{u_n} - -@item outname - list of strings of input signal names - - default (@var{outname} = [] on input): @code{y_n} - -@item outlist - - list of indices of outputs y that are sampled - - default: -@table @var -@item tsam = 0 -@math{outlist = []} -@item tsam > 0 -@math{outlist = 1:@code{rows}(@var{c})} -@end table - -Unlike states, discrete/continous outputs may appear in any order. - -@strong{Note} @code{sys2ss} returns a vector @var{yd} where -@var{yd}(@var{outlist}) = 1; all other entries of @var{yd} are 0. - -@end table - -@strong{Outputs} -@var{outsys} = system data structure - -@strong{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 -@example -@group -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.) -@end group -@end example -with dynamic equations: -@ifinfo -@math{ d/dt xc(t) = acc*xc(t) + acd*xd(k*tsam) + bc*u(t)} - -@math{ xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)} - -@math{ yc(t) = ccc*xc(t) + ccd*xd(k*tsam) + dc*u(t)} - -@math{ yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)} -@end ifinfo -@iftex -@tex -$$\eqalign{ -{d \over dt} x_c(t) - & = a_{cc} x_c(t) + a_{cd} x_d(k*t_{sam}) + bc*u(t) \cr -x_d((k+1)*t_{sam}) - & = a_{dc} x_c(k t_{sam}) + a_{dd} x_d(k t_{sam}) + b_d u(k t_{sam}) \cr -y_c(t) - & = c_{cc} x_c(t) + c_{cd} x_d(k t_{sam}) + d_c u(t) \cr -y_d(k t_{sam}) - & = c_{dc} x_c(k t_{sam}) + c_{dd} x_d(k t_{sam}) + d_d u(k t_{sam}) -}$$ -@end tex -@end iftex - -@strong{Signal partitions} -@example -@group - | continuous | discrete | ----------------------------------------------------- -states | stname(1:n,:) | stname((n+1):(n+nz),:) | ----------------------------------------------------- -outputs | outname(cout,:) | outname(outlist,:) | ----------------------------------------------------- -@end group -@end example -where @math{cout} is the list of in 1:@code{rows}(@var{p}) -that are not contained in outlist. (Discrete/continuous outputs -may be entered in any order desired by the user.) - -@strong{Example} -@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 -@end example -Notice that the @var{D} matrix is constructed by default to the -correct dimensions. Default input and output signals names were assigned -since none were given. - -@end deftypefn +@DOCSTRING(ss2sys) @node sys2ss,tf2sys,ss2sys,sysinterface -@deftypefn {Function File } {[@var{a},@var{b},@var{c},@var{d},@var{tsam},@var{n},@var{nz},@var{stname},@var{inname},@var{outname},@var{yd}] =} sys2ss (@var{sys}) -Extract state space representation from system data structure. - -@strong{Inputs} -@var{sys} system data structure (@xref{sysstruct}) - -@strong{Outputs} -@table @var -@item a,b,c,d - state space matrices for sys - -@item tsam - sampling time of sys (0 if continuous) - -@item n, nz - number of continuous, discrete states (discrete states come - last in state vector @var{x}) - -@item stname, inname, outname - signal names (lists of strings); names of states, - inputs, and outputs, respectively - -@item yd - binary vector; @var{yd}(@var{ii}) is 1 if output @var{y}(@var{ii})$ - is discrete (sampled); otherwise @var{yd}(@var{ii}) 0. - -@end table - -@strong{Example} -@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 -@end example -@end deftypefn +@DOCSTRING(sys2ss) @node tf2sys,sys2tf,sys2ss,sysinterface @subsection Transfer function system interface functions -@deftypefn {Function File } { @var{sys} = } tf2sys( @var{num}, @var{den} @{, @var{tsam}, @var{inname}, @var{outname} @}) - build system data structure from transfer function format data - -@strong{Inputs} -@table @var -@item num, den - coefficients of numerator/denominator polynomials -@item tsam - sampling interval. default: 0 (continuous time) -@item inname, outname - input/output signal names; may be a string or list with a single string -entry. -@end table - -@strong{Outputs} - @var{sys} = system data structure - -@strong{Example} -@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 -@end example -@end deftypefn +@DOCSTRING(tf2sys) @node sys2tf,zp2sys,tf2sys,sysinterface -@deftypefn {Function File } {[@var{num},@var{den},@var{tsam},@var{inname},@var{outname}] =} sys2tf (@var{sys}) -Extract transfer function data from a system data structure - -See @ref{tf2sys} for parameter descriptions. - -@strong{Example} -@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 -@end example -@end deftypefn +@DOCSTRING(sys2tf) @node zp2sys,sys2zp,sys2tf,sysinterface @subsection Zero-pole system interface functions - -@deftypefn {Function File } { @var{sys} =} zp2sys (@var{zer},@var{pol},@var{k}@{,@var{tsam},@var{inname},@var{outname}@}) - Create system data structure from zero-pole data - -@strong{Inputs} -@table @var -@item zer - vector of system zeros -@item pol - vector of system poles -@item k - scalar leading coefficient -@item tsam - sampling period. default: 0 (continuous system) -@item inname, outname - input/output signal names (lists of strings) -@end table - -@strong{Outputs} - sys: system data structure - -@strong{Example} -@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) -@end example -@end deftypefn +@DOCSTRING(zp2sys) @node sys2zp, structaccess, zp2sys, sysinterface -@deftypefn {Function File } {[@var{zer}, @var{pol}, @var{k}, @var{tsam}, @var{inname}, @var{outname}] =} sys2zp (@var{sys}) -Extract zero/pole/leading coefficient information from a system data -structure - -See @ref{zp2sys} for parameter descriptions. - -@strong{Example} -@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 -@end example -@end deftypefn +@DOCSTRING(sys2zp) @node structaccess, structintern, sys2zp, sysinterface @subsection Data structure access functions @@ -615,410 +238,48 @@ @end menu @node syschnames, syschtsam, structaccess, structaccess -@deftypefn {Function File } {@var{retsys} =} syschnames (@var{sys}, @var{opt}, @var{list}, @var{names}) -Superseded by @code{syssetsignals} - -@end deftypefn +@DOCSTRING(syschnames) @node syschtsam, sysdimensions, syschnames, structaccess -@deftypefn {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. -@end deftypefn +@DOCSTRING(syschtsam) @node sysdimensions, sysgetsignals, syschtsam, structaccess -@deftypefn {Function File } { [@var{n}, @var{nz}, @var{m}, @var{p},@var{yd}] =} sysdimensions (@var{sys}@{, @var{opt}@}) - return the number of states, inputs, and/or outputs in the system @var{sys}. - -@strong{Inputs} -@table @var -@item sys - system data structure - -@item opt -String indicating which dimensions are desired. Values: -@table @code -@item "all" -(default) return all parameters as specified under Outputs below. - -@item "cst" -return @var{n}= number of continuous states - -@item "dst" -return @var{n}= number of discrete states - -@item "in" -return @var{n}= number of inputs - -@item "out" -return @var{n}= number of outputs -@end table -@end table - -@strong{Outputs} -@table @var -@item n - number of continuous states (or individual requested dimension as specified -by @var{opt}). -@item nz - number of discrete states -@item m - number of system inputs -@item p - number of system outputs -@item yd - binary vector; @var{yd}(@var{ii}) is nonzero if output @var{ii} is -discrete. -@math{yd(ii) = 0} if output @var{ii} is continous -@end table - -@end deftypefn +@DOCSTRING(sysdimensions) @node sysgetsignals, sysgettsam, sysdimensions, structaccess -@deftypefn {Function File } {[@var{stname}, @var{inname}, @var{outname}, @var{yd}] =} sysgetsignals (@var{sys}) -@deftypefnx{Function File } { @var{siglist} =} sysgetsignals (@var{sys},@var{sigid}) -@deftypefnx{Function File } { @var{signame} =} sysgetsignals (@var{sys},@var{sigid},@var{signum}@{, @var{strflg}@}) - Get signal names from a system - -@strong{Inputs} -@table @var -@item sys - system data structure for the state space system - -@item sigid -signal id. String. Must be one of -@table @code -@item "in" -input signals -@item "out" -output signals -@item "st" -stage signals -@item "yd" -value of logical vector @var{yd} -@end table - -@item signum -Index of signal (or indices of signals if signum is a vector) - -@item strflg -flag to return a string instead of a list; Values: -@table @code -@item 0 -(default) return a list (even if signum is a scalar) - -@item 1 -return a string. Exits with an error if signum is not a scalar. -@end table - -@end table - -@strong{Outputs} -@table @bullet -@item If @var{sigid} is not specified -@table @var -@item stname, inname, outname - signal names (lists of strings); names of states, - inputs, and outputs, respectively -@item yd - binary vector; @var{yd}(@var{ii}) is nonzero if output @var{ii} is -discrete. -@end table - -@item If @var{sigid} is specified but @var{signum} is not specified, then -@table @code -@item sigid="in" -@var{siglist} is set to the list of input names - -@item sigid="out" -@var{siglist} is set to the list of output names - -@item sigid="st" -@var{siglist} is set to the list of state names - -stage signals -@item sigid="yd" -@var{siglist} is set to logical vector indicating discrete outputs; -@var{siglist(ii) = 0} indicates that output @var{ii} is continuous -(unsampled), otherwise it is discrete. - -@end table - -@item if the first three input arguments are specified, then @var{signame} is -a list of the specified signal names (@var{sigid} is @code{"in"}, -@code{"out"}, or @code{"st"}), or else the logical flag -indicating whether output(s) @var{signum} is(are) discrete (@var{sigval}=1) -or continuous (@var{sigval}=0). -@end table - -@strong{Examples} (From @code{sysrepdemo}) -@example -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 -@end example - -@end deftypefn - -@node sysgettsam, sysgettype, sysgetsignals, structaccess -@deftypefn {Function File } { Tsam =} sysgettsam ( sys ) - return the sampling time of the system -@end deftypefn +@DOCSTRING(sysgetsignals) @node sysgettype, syssetsignals, sysgettsam, structaccess -@deftypefn {Function File } { @var{systype} =} sysgettype ( @var{sys} ) - return the initial system type of the system - -@strong{Inputs} - @var{sys}: system data structure - -@strong{Outputs} - @var{systype}: string indicating how the structure was initially - constructed: - values: @code{"ss"}, @code{"zp"}, or @code{"tf"} - -@strong{Note} FIR initialized systems return @code{systype="tf"}. - - -@end deftypefn +@DOCSTRING(sysgettype) @node syssetsignals, sysupdate, sysgettype, structaccess -@deftypefn {Function File } {@var{retsys} =} syssetsignals (@var{sys}, @var{opt}, @var{names}@{, @var{sig_idx}@}) - change the names of selected inputs, outputs and states. -@strong{Inputs} -@table @var -@item sys - system data structure - -@item opt -change default name (output) - -@table @code -@item "out" - change selected output names -@item "in" - change selected input names -@item "st" - change selected state names -@item "yd" - change selected outputs from discrete to continuous or - from continuous to discrete. -@end table - -@item names -@table @code -@item opt = "out", "in", or "st" - string or string array containing desired signal names or values. -@item opt = "yd" -To desired output continuous/discrete flag. -Set name to 0 for continuous, or 1 for discrete. -@end table -@item 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. -@end table -@strong{Outputs} - @var{retsys=sys} with appropriate signal names changed - (or yd values, where appropriate) - - -@strong{Example} -@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 -@end example - -@end deftypefn +@DOCSTRING(syssetsignals) @node sysupdate, , syssetsignals, structaccess -@deftypefn {Function File } { @var{sys} =} sysupdate ( @var{sys}, @var{opt} ) - Update the internal representation of a system. - -@strong{Inputs} -@table @var -@item sys: -system data structure -@item opt - string: -@table @code -@item "tf" -update transfer function form -@item "zp" -update zero-pole form -@item "ss" -update state space form -@item "all" -all of the above -@end table -@end table - -@strong{Outputs} -@var{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 @code{tf} or @code{zp} exits with an error if the system is - mixed continuous/digital. -@end deftypefn +@DOCSTRING(sysupdate) @node structintern, , structaccess, sysinterface @subsection Data structure internal functions -@deftypefn {Function File } { } syschnamesl - used internally in syschnames -@end deftypefn +@DOCSTRING(syschnamesl) -@deftypefn {Function File } { @var{ioname} =} sysdefioname (@var{n},@var{str} @{,@var{m}@}) -return default input or output names given @var{n}, @var{str}, @var{m}. - @var{n} is the final value, @var{str} is the string prefix, and @var{m} -is start value - - used internally, minimal argument checking +@DOCSTRING(sysdefioname) -@strong{Example} @code{ioname = sysdefioname(5,"u",3)} -returns the list: -@example -ioname = -( - [1] = u_3 - [2] = u_4 - [3] = u_5 -) -@end example -@end deftypefn +@DOCSTRING(sysdefstname) -@deftypefn {Function File } { @var{stname} =} sysdefstname (@var{n}, @var{nz}) - return default state names given @var{n}, @var{nz} - - used internally, minimal argument checking -@end deftypefn - -@deftypefn {Function File } { @var{vec} = } tf2sysl (@var{vec}) - used internally in @ref{tf2sys}. - strip leading zero coefficients to get the true polynomial length -@end deftypefn +@DOCSTRING(tf2sysl) @node sysdisp, blockdiag, sysinterface, Control Theory @section System display functions -@deftypefn {Function File } { } sysout ( @var{sys}@{, @var{opt}@}) - print out a system data structure in desired format -@table @var -@item sys - system data structure -@item opt -Display option -@table @code -@item [] - primary system form (default); see @ref{sysgettype}. -@item "ss" - state space form -@item "tf" - transfer function form -@item "zp" - zero-pole form -@item "all" - all of the above -@end table -@end table -@end deftypefn +@DOCSTRING(sysout) -@deftypefn {Function File } { @var{y} =} polyout ( @var{c}@{, @var{x}@}) -write formatted polynomial -@example - c(x) = c(1) * x^n + ... + c(n) x + c(n+1) -@end example - to string @var{y} or to the screen (if @var{y} is omitted) - @var{x} defaults to the string @code{"s"} -@end deftypefn +@DOCSTRING(polyout) -@deftypefn {Function File } { } tfout (@var{num}, @var{denom}@{, @var{x}@}) - print formatted transfer function @math{n(s)/d(s) } to the screen - @var{x} defaults to the string @code{"s"} -@end deftypefn - -@deftypefn {Function File } { } zpout (@var{zer}, @var{pol}, @var{k}@{, @var{x}@}) - print formatted zero-pole form to the screen. -@var{x} defaults to the string @code{"s"} -@end deftypefn - -@deftypefn {Function File } { } outlist (@var{lmat}@{, @var{tabchar}, @var{yd}, @var{ilist} @}) - Prints an enumerated list of strings. - internal use only; minimal argument checking performed +@DOCSTRING(tfout) -@strong{Inputs} -@table @var -@item lmat - list of strings -@item tabchar - tab character (default: none) -@item yd - indices of strings to append with the string "(discrete)" - (used by @var{sysout}; minimal checking of this argument) - @math{yd = [] } indicates all outputs are continuous -@item ilist -index numbers to print with names. +@DOCSTRING(zpout) -default: @code{1:rows(lmat)} -@end table - -@strong{Outputs} - prints the list to the screen, numbering each string in order. - -@end deftypefn +@DOCSTRING(outlist) @node blockdiag, numerical, sysdisp, Control Theory @section Block Diagram Manipulations @@ -1048,853 +309,92 @@ * syssub:: @end menu -@deftypefn {Function File } { outputs =} bddemo ( inputs ) - Octave Controls toolbox demo: Block Diagram Manipulations demo -@end deftypefn +@DOCSTRING(bddemo) @node buildssic, jet707, blockdiag, blockdiag -@deftypefn {Function File } {[@var{sys}] =} buildssic(@var{Clst}, @var{Ulst}, @var{Olst}, @var{Ilst}, @var{s1}, @var{s2}, @var{s3}, @var{s4}, @var{s5}, @var{s6}, @var{s7}, @var{s8}) - -Contributed by Kai Mueller. - - Form an arbitrary complex (open or closed loop) system in - state-space form from several systems. "@code{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 "@code{sysgroup}" - "@code{sysmult}", "@code{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: -@table @var -@item 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: -@code{[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. - -@item 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. - -@item 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. - -@item 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. -@end table - - Example: Very simple closed loop system. -@example -@group -w e +-----+ u +-----+ - --->o--*-->| K |--*-->| G |--*---> y - ^ | +-----+ | +-----+ | - - | | | | - | | +----------------> u - | | | - | +-------------------------|---> e - | | - +----------------------------+ -@end group -@end example - -The closed loop system GW can be optained by -@example -GW = buildssic([1 2; 2 -1], [2], [1 2 3], [2], G, K); -@end example -@table @var -@item Clst -(1. row) connect input 1 (G) with output 2 (K). -(2. row) connect input 2 (K) with neg. output 1 (G). -@item Ulst -append input of (2) K to the number of outputs. -@item Olst -Outputs are output of 1 (G), 2 (K) and appended output 3 (from Ulst). -@item Ilst -the only input is 2 (K). -@end table - -Here is a real example: -@example -@group - +----+ - -------------------->| W1 |---> v1 -z | +----+ -----|-------------+ || GW || => min. - | | vz infty - | +---+ v +----+ - *--->| G |--->O--*-->| W2 |---> v2 - | +---+ | +----+ - | | - | v - u y -@end group -@end example - -The closed loop system GW from [z; u]' to [v1; v2; y]' can be -obtained by (all SISO systems): -@example -GW = buildssic([1 4;2 4;3 1],[3],[2 3 5],[3 4],G,W1,W2,One); -@end example -where "One" is a unity gain (auxillary) function with order 0. -(e.g. @code{One = ugain(1);}) -@end deftypefn +@DOCSTRING(buildssic) @node jet707, ord2, buildssic, blockdiag -@deftypefn {Function File } { @var{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 -@end deftypefn +@DOCSTRING(jet707) @node ord2, parallel, jet707, blockdiag -@deftypefn {Function File } { @var{outsys} =} ord2 (@var{nfreq}, @var{damp}@{[, @var{gain}@}) - Creates a continuous 2nd order system with parameters: -@strong{Inputs} -@table @var -@item nfreq: natural frequency [Hz]. (not in rad/s) -@item damp: damping coefficient -@item gain: dc-gain - This is steady state value only for damp > 0. - gain is assumed to be 1.0 if ommitted. -@end table -@strong{Outputs} -@var{outsys} - system data structure has representation with @math{w = 2 * pi * nfreq}: -@example - / \ - | / -2w*damp -w \ / w \ | -G = | | |, | |, [ 0 gain ], 0 | - | \ w 0 / \ 0 / | - \ / -@end example -@strong{See also} @code{jet707} (MIMO example, Boeing 707-321 aircraft model) -@end deftypefn - -@node parallel, sysadd, ord2, blockdiag -@deftypefn {Function File } { @var{sysp} =} parallel(@var{Asys}, @var{Bsys}) -Forms the parallel connection of two systems. -@example - ____________________ - | ________ | -u ----->|----> | Asys |--->|----> y1 - | | -------- | - | | ________ | - |--->|----> | Bsys |--->|----> y2 - | -------- | - -------------------- - Ksys -@end example -@end deftypefn +@DOCSTRING(ord2) @node sysadd, sysappend, parallel, blockdiag -@deftypefn {Function File } { @var{sys} =} sysadd ( @var{Gsys},@var{Hsys}) -returns @var{sys} = @var{Gsys} + @var{Hsys}. -@itemize @bullet -@item Exits with -an error if @var{Gsys} and @var{Hsys} are not compatibly dimensioned. -@item Prints a warning message is system states have identical names; - duplicate names are given a suffix to make them unique. -@item @var{sys} input/output names are taken from @var{Gsys}. -@end itemize -@example -@group - ________ - ----| Gsys |--- -u | ---------- +| ------ (_)----> y - | ________ +| - ----| Hsys |--- - -------- -@end group -@end example -@end deftypefn +@DOCSTRING(sysadd) @node sysappend, sysconnect, sysadd, blockdiag -@deftypefn {Function File } {@var{retsys} =} sysappend (@var{sys},@var{b}@{, @var{c}, @var{d}, @var{outname}, @var{inname}, @var{yd}@}) -appends new inputs and/or outputs to a system - -@strong{Inputs} -@table @var -@item sys -system data structure - -@item b -matrix to be appended to sys "B" matrix (empty if none) - -@item c -matrix to be appended to sys "C" matrix (empty if none) - -@item d -revised sys d matrix (can be passed as [] if the revised d is all zeros) - -@item outname -list of names for new outputs - -@item inname -list of names for new inputs - -@item yd -binary vector; @math{yd(ii)=0} indicates a continuous output; -@math{yd(ii)=1} indicates a discrete output. -@end table - -@strong{Outputs} @var{sys} -@example -@group - sys.b := [sys.b , b] - sys.c := [sys.c ] - [ c ] - sys.d := [sys.d | D12 ] - [D21 | D22 ] -@end group -@end example -where @var{D12}, @var{D21}, and @var{D22} are the appropriate dimensioned -blocks of the input parameter @var{d}. -@itemize @bullet -@item The leading block @var{D11} of @var{d} is ignored. -@item If @var{inname} and @var{outname} are not given as arguments, - the new inputs and outputs are be assigned default names. -@item @var{yd} is a binary vector of length rows(c) that indicates - continuous/sampled outputs. Default value for @var{yd} is: - -@item @var{sys} = continuous or mixed -@var{yd} = @code{zeros(1,rows(c))} - -@item @var{sys} = discrete -@var{yd} = @code{ones(1,rows(c))} - -@end itemize - -@end deftypefn +@DOCSTRING(sysappend) @node sysconnect, syscont, sysappend, blockdiag -@deftypefn {Function File } {@var{retsys} =} sysconnect (@var{sys}, @var{out_idx},@var{in_idx}@{,@var{order}, @var{tol}@}) -Close the loop from specified outputs to respective specified inputs - -@strong{Inputs} -@table @var -@item sys -system data structure -@item out_idx, in_idx -list of connections indices; @math{y(out_idx(ii))} -is connected to @math{u(in_idx(ii))}. -@item order -logical flag (default = 0) -@table @code -@item 0 -leave inputs and outputs in their original order -@item 1 -permute inputs and outputs to the order shown in the diagram below -@end table -@item tol -tolerance for singularities in algebraic loops default: 200@var{eps} -@end table - -@strong{Outputs} - @var{sys}: resulting closed loop system. - -@strong{Method} -@code{sysconnect} internally permutes selected inputs, outputs as shown - below, closes the loop, and then permutes inputs and outputs back to their - original order -@example -@group - ____________________ - u_1 ----->| |----> y_1 - | sys | - old u_2 | | -u_2* ---->(+)--->| |----->y_2 -(in_idx) ^ -------------------| | (out_idx) - | | - ------------------------------- -@end group -@end example -The input that has the summing junction added to it has an * added to the end -of the input name. - -@end deftypefn +@DOCSTRING(sysconnect) @node syscont, syscont_disc, sysconnect, blockdiag -@deftypefn {Function File} { [@var{csys}, @var{Acd}, @var{Ccd}] = } syscont (@var{sys}) -Extract the purely continuous subsystem of an input system. - -@strong{Inputs} -@var{sys} is a system data structure - -@strong{Outputs} -@table @var -@item csys - is the purely continuous input/output connections of @var{sys} -@item Acd, Ccd: - connections from discrete states to continuous states, - discrete states to continuous outputs, respectively. - - returns @var{csys} empty if no continuous/continous path exists -@end table - -@end deftypefn +@DOCSTRING(syscont) @node syscont_disc, sysdisc, syscont, blockdiag -@deftypefn {Function File } { [@var{n_tot}, @var{st_c}, @var{st_d}, @var{y_c}, @var{y_d}] =} syscont_disc(@var{sys}) -Used internally in syscont and sysdisc. - -@strong{Inputs} -@var{ sys} is a system data structure. - -@strong{Outputs} -@table @var -@item n_tot -total number of states -@item st_c -vector of continuous state indices (empty if none) -@item st_d -vector of discrete state indices (empty if none) -@item y_c -vector of continuous output indices -@item y_d -vector of discrete output indices -@end table - -@end deftypefn +@DOCSTRING(syscont_disc) @node sysdisc, sysdup, syscont_disc, blockdiag -@deftypefn {Function File } { [@var{dsys}, @var{Adc}, @var{Cdc}] =} sysdisc (@var{sys}) - -@strong{Inputs} -@var{sys} = system data structure - -@strong{Outputs} -@table @var -@item dsys - purely discrete portion of sys (returned empty if there is - no purely discrete path from inputs to outputs) -@item Adc, Cdc - connections from continuous states to discrete states and discrete - outputs, respectively. -@end table - -@end deftypefn +@DOCSTRING(sysdisc) @node sysdup, sysgroup, sysdisc, blockdiag -@deftypefn {Function File } { @var{retsys} =} sysdup (@var{Asys}, @var{out_idx}, @var{in_idx}) - Duplicate specified input/output connections of a system - -@strong{Inputs} -@table @var -@item Asys - system data structure (@xref{ss2sys}) -@item out_idx,in_idx - list of connections indices; - duplicates are made of @var{y(out_idx(ii))} and @var{u(in_idx(ii))}. -@end table - -@strong{Outputs} -@var{retsys}: resulting closed loop system: - duplicated i/o names are appended with a @code{"+"} suffix. - - -@strong{Method} -@code{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 @var{in_idx}, @var{out_idx}, respectively -@example -@group - ____________________ -u1 ----->| |----> y1 - | Asys | -u2 ------>| |----->y2 -(in_idx) -------------------| (out_idx) -@end group -@end example - -@end deftypefn +@DOCSTRING(sysdup) @node sysgroup, sysgroupn, sysdup, blockdiag -@deftypefn {Function File } { @var{sys} =} sysgroup ( @var{Asys}, @var{Bsys}) -Combines two systems into a single system - -@strong{Inputs} -@var{Asys}, @var{Bsys}: system data structures - -@strong{Outputs} - @math{sys = @r{block diag}(Asys,Bsys)} -@example -@group - __________________ - | ________ | -u1 ----->|--> | Asys |--->|----> y1 - | -------- | - | ________ | -u2 ----->|--> | Bsys |--->|----> y2 - | -------- | - ------------------ - Ksys -@end group -@end example -The function also rearranges the internal state-space realization of @var{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. - -@end deftypefn +@DOCSTRING(sysgroup) @node sysgroupn, sysmult, sysgroup, blockdiag -@deftypefn {Function File } { @var{names} =} sysgroupn (@var{names}) -Locate and mark duplicate names. Used internally in sysgroup (and elsewhere). -@end deftypefn +@DOCSTRING(sysgroupn) @node sysmult, sysprune, sysgroupn, blockdiag -@deftypefn {Function File } { @var{sys} =} sysmult( @var{Asys}, @var{Bsys}) -Compute @math{sys = Asys*Bsys} (series connection): -@example -@group -u ---------- ---------- ---->| Bsys |---->| Asys |---> - ---------- ---------- -@end group -@end example -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). -@end deftypefn +@DOCSTRING(sysmult) @node sysprune, sysreorder, sysmult, blockdiag -@deftypefn {Function File } { @var{retsys} =} sysprune ( @var{Asys}, @var{out_idx}, @var{in_idx}) -Extract specified inputs/outputs from a system - -@strong{Inputs} -@table @var -@item Asys -system data structure -@item 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. -@end table - -@strong{Outputs} -@var{retsys}: resulting system -@example -@group - ____________________ -u1 ------->| |----> y1 - (in_idx) | Asys | (out_idx) -u2 ------->| |----| y2 - (deleted)-------------------- (deleted) -@end group -@end example - -@end deftypefn +@DOCSTRING(sysprune) @node sysreorder, sysscale, sysprune, blockdiag -@deftypefn {Function File } { @var{pv} =} sysreorder( @var{vlen}, @{var{list}) - -@strong{Inputs} -@var{vlen}=vector length, @var{list}= a subset of @code{[1:vlen]}, - -@strong{Outputs} - @var{pv}: a permutation vector to order elements of @code{[1:vlen]} in -@code{list} to the end of a vector. - - Used internally by @code{sysconnect} to permute vector elements to their - desired locations. -@end deftypefn +@DOCSTRING(sysreorder) @node sysscale, syssub, sysreorder, blockdiag -@deftypefn {Function File } {@var{sys} =} sysscale (@var{sys}, @var{outscale}, @var{inscale}@{, @var{outname}, @var{inname}@}) -scale inputs/outputs of a system. - -@strong{Inputs} - sys: structured system - outscale, inscale: constant matrices of appropriate dimension - -@strong{Outputs} -@var{sys}: resulting open loop system: -@example - ----------- ------- ----------- -u --->| inscale |--->| sys |--->| outscale |---> y - ----------- ------- ----------- -@end example - 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 @var{yd} is -set appropriately in the returned value of @var{sys}. -@end deftypefn +@DOCSTRING(sysscale) @node syssub, , sysscale, blockdiag -@deftypefn {Function File } { @var{sys} =} syssub (@var{Gsys}, @var{Hsys}) - returns @math{sys = Gsys - Hsys} - - Method: @var{Gsys} and @var{Hsys} are connected in parallel - The input vector is connected to both systems; the outputs are - subtracted. Returned system names are those of @var{Gsys}. -@example -@group - ________ - ----| Gsys |--- -u | ---------- +| ------ (_)----> y - | ________ -| - ----| Hsys |--- - -------- -@end group -@end example -@end deftypefn +@DOCSTRING(syssub) -@deftypefn {Function File } { @var{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) - -@end deftypefn +@DOCSTRING(ugain) -@deftypefn {Function File } { @var{wsys} =} wgt1o (@var{vl}, @var{vh}, @var{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) -@end deftypefn +@DOCSTRING(wgt1o) @node numerical, sysprop, blockdiag, Control Theory @section Numerical Functions -@deftypefn {Function File} {} are (@var{a}, @var{b}, @var{c}, @var{opt}) -Solve the algebraic Riccati equation -@iftex -@tex -$$ -A^TX + XA - XBX + C = 0 -$$ -@end tex -@end iftex -@ifinfo -@example -a' * x + x * a - x * b * x + c = 0 -@end example -@end ifinfo +@DOCSTRING(are) -@strong{Inputs} -@noindent -for identically dimensioned square matrices -@table @var -@item a -@var{n}x@var{n} matrix. -@item b - @var{n}x@var{n} matrix or @var{n}x@var{m} matrix; in the latter case - @var{b} is replaced by @math{b:=b*b'}. -@item c - @var{n}x@var{n} matrix or @var{p}x@var{m} matrix; in the latter case - @var{c} is replaced by @math{c:=c'*c}. -@item opt -(optional argument; default = @code{"B"}): -String option passed to @code{balance} prior to ordered Schur decomposition. -@end table - -@strong{Outputs} -@var{x}: solution of the ARE. +@DOCSTRING(dare) -@strong{Method} -Laub's Schur method (IEEE Transactions on -Automatic Control, 1979) is applied to the appropriate Hamiltonian -matrix. - -@end deftypefn - -@deftypefn {Function File} {} dare (@var{a}, @var{b}, @var{c}, @var{r}, @var{opt}) - -Return the solution, @var{x} of the discrete-time algebraic Riccati -equation -@iftex -@tex -$$ -A^TXA - X + A^TXB (R + B^TXB)^{-1} B^TXA + C = 0 -$$ -@end tex -@end iftex -@ifinfo -@example -a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0 -@end example -@end ifinfo -@noindent +@DOCSTRING(dgram) -@strong{Inputs} -@table @var -@item a -@var{n} by @var{n}. - -@item b -@var{n} by @var{m}. - -@item c -@var{n} by @var{n}, symmetric positive semidefinite, or @var{p} by @var{n}. -In the latter case @math{c:=c'*c} is used. - -@item r -@var{m} by @var{m}, symmetric positive definite (invertible). - -@item opt -(optional argument; default = @code{"B"}): -String option passed to @code{balance} prior to ordered @var{QZ} decomposition. -@end table - -@strong{Outputs} -@var{x} solution of DARE. - -@strong{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. - -@end deftypefn +@DOCSTRING(dlyap) -@deftypefn {Function File } { @var{m} =} dgram ( @var{a}, @var{b}) - Return controllability grammian of discrete time system -@example - x(k+1) = a x(k) + b u(k) -@end example - -@strong{Inputs} -@table @var -@item a -@var{n} by @var{n} matrix -@item b -@var{n} by @var{m} matrix -@end table +@DOCSTRING(gram) -@strong{Outputs} -@var{m} (@var{n} by @var{n}) satisfies -@example - a m a' - m + b*b' = 0 -@end example - -@end deftypefn - -@deftypefn {Function File} {@var{x} = } dlyap (@var{a}, @var{b}) -Solve the discrete-time Lyapunov equation - - @strong{Inputs} - @table @var - @item a - @var{n} by @var{n} matrix - @item b - Matrix: @var{n} by @var{n}, @var{n} by @var{m}, or @var{p} by @var{n}. - @end table +@DOCSTRING(lyap) - @strong{Outputs} - @var{x}: matrix satisfying appropriate discrete time Lyapunov equation. - Options: - @itemize @bullet - @item @var{b} is square: solve @code{a x a' - x + b = 0} - @item @var{b} is not square: @var{x} satisfies either - @example - a x a' - x + b b' = 0 - @end example - @noindent - or - @example - a' x a - x + b' b = 0, - @end example - @noindent - whichever is appropriate. - @end itemize - -@strong{Method} - Uses Schur decomposition method as in Kitagawa, - @cite{An Algorithm for Solving the Matrix Equation @var{X} = - @var{F}@var{X}@var{F}' + @var{S}}, - International Journal of Control, Volume 25, Number 5, pages 745--753 - (1977). +@DOCSTRING(pinv) -Column-by-column solution method as suggested in - Hammarling, @cite{Numerical Solution of the Stable, Non-Negative - Definite Lyapunov Equation}, IMA Journal of Numerical Analysis, Volume - 2, pages 303--323 (1982). - -@end deftypefn - -@deftypefn {Function File } { @var{m} =} gram (@var{a}, @var{b}) - Return controllability grammian @var{m} of the continuous time system -@math{ dx/dt = a x + b u}. - -@var{m} satisfies @math{ a m + m a' + b b' = 0 }. -@end deftypefn - - -@deftypefn {Function File} {} lyap (@var{a}, @var{b}, @var{c}) -@deftypefnx {Function File} {} lyap (@var{a}, @var{b}) - Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart - algorithm (Communications of the ACM, 1972). +@DOCSTRING(qzval) - If @var{a}, @var{b}, and @var{c} are specified, then @code{lyap} returns - the solution of the Sylvester equation - @iftex - @tex - $$ A X + X B + C = 0 $$ - @end tex - @end iftex - @ifinfo - @example - a x + x b + c = 0 - @end example - @end ifinfo - If only @code{(a, b)} are specified, then @code{lyap} returns the - solution of the Lyapunov equation - @iftex - @tex - $$ A^T X + X A + B = 0 $$ - @end tex - @end iftex - @ifinfo - @example - a' x + x a + b = 0 - @end example - @end ifinfo - If @var{b} is not square, then @code{lyap} returns the solution of either - @iftex - @tex - $$ A^T X + X A + B^T B = 0 $$ - @end tex - @end iftex - @ifinfo - @example - a' x + x a + b' b = 0 - @end example - @end ifinfo - @noindent - or - @iftex - @tex - $$ A X + X A^T + B B^T = 0 $$ - @end tex - @end iftex - @ifinfo - @example - a x + x a' + b b' = 0 - @end example - @end ifinfo - @noindent - whichever is appropriate. -@end deftypefn - -@deftypefn {Function File } { } pinv ( @var{X}@{,@var{tol}@} ) -Returns the pseudoinverse of X; singular values less than tol are ignored. -@end deftypefn +@DOCSTRING(zgfmul) +@DOCSTRING(zgfslv) +@DOCSTRING(zginit) +@DOCSTRING(zgpbal) +@DOCSTRING(zgreduce) +@DOCSTRING(zgrownorm) +@DOCSTRING(zgscal) +@DOCSTRING(zgsgiv) +@DOCSTRING(zgshsr) -@deftypefn {Function File } { @var{x} =} qzval (@var{A}, @var{B}) -Compute generalized eigenvalues of the matrix pencil -@ifinfo -@example -(A - lambda B). -@end example -@end ifinfo -@iftex -@tex -$(A - \lambda B)$. -@end tex -@end iftex - -@var{A} and @var{B} must be real matrices. - -@strong{Note} @code{qzval} is obsolete; use @code{qz} instead. -@end deftypefn - -@deftypefn {Function File } { } zgfmul -@deftypefnx {Function File } { } zgfslv -@deftypefnx {Function File } { } zginit -@deftypefnx {Function File } {@var{retsys} =} zgpbal (@var{Asys}) -@deftypefnx {Function File } {} zgreduce -@deftypefnx {Function File } { [@var{nonz}, @var{zer}] =} zgrownorm (@var{mat}, @var{meps}) -@deftypefnx {Function File } { x =} zgscal (@var{f}, @var{z}, @var{n}, @var{m}, @var{p}) -@deftypefnx {Function File } { } zgsgiv ( ) -@deftypefnx {Function File } { @var{x} =} zgshsr( @var{y}) -Used internally by @code{tzero}. -Minimal argument checking performed. - -Details involving major subroutines: -@table @code -@item zgpbal -Implementation of zero computation generalized eigenvalue problem - balancing method. @code{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. - - @code{zgpbal} should be followed by @code{zgpred} - -@item zgreduce -Implementation of procedure REDUCE in (Emami-Naeini and Van Dooren, -Automatica, 1982). - -@item zgrownorm - Returns @var{nonz} = number of rows of @var{mat} whose two norm exceeds - @var{meps}, @var{zer} = number of rows of mat whose two norm - is less than meps - -@item zgscal -Generalized conjugate gradient iteration to - solve zero-computation generalized eigenvalue problem balancing equation - @math{fx=z}; - called by @code{zgepbal} - -@item zgsgiv -apply givens rotation c,s to column vector a,b -@item zgshsr -Apply Householder vector based on @code{e^(m)} (all ones) to -(column vector) @var{y}. Called by @code{zgfslv}. - -@end table References: @table @strong @item ZGEP @@ -1904,1121 +404,112 @@ Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 @end table -@end deftypefn - @node sysprop, systime, numerical, Control Theory @section System Analysis-Properties -@deftypefn {Function File } { } analdemo ( ) - Octave Controls toolbox demo: State Space analysis demo -@end deftypefn - +@DOCSTRING(analdemo) -@deftypefn {Function File} {[@var{n}, @var{m}, @var{p}] =} abcddim (@var{a}, @var{b}, @var{c}, @var{d}) -Check for compatibility of the dimensions of the matrices defining -the linear system -@iftex -@tex -$[A, B, C, D]$ corresponding to -$$ -\eqalign{ - {dx\over dt} &= A x + B u\cr - y &= C x + D u} -$$ -@end tex -@end iftex -@ifinfo -[A, B, C, D] corresponding to - -@example -dx/dt = a x + b u -y = c x + d u -@end example - -@end ifinfo -or a similar discrete-time system. - -If the matrices are compatibly dimensioned, then @code{abcddim} returns - -@table @var -@item n -The number of system states. +@DOCSTRING(abcddim) -@item m -The number of system inputs. - -@item p -The number of system outputs. -@end table - -Otherwise @code{abcddim} returns @var{n} = @var{m} = @var{p} = @minus{}1. - -Note: n = 0 (pure gain block) is returned without warning. - -See also: is_abcd -@end deftypefn - -@deftypefn {Function File } {[@var{y}, @var{my}, @var{ny}] =} abcddims (@var{x}) +@DOCSTRING(abcddims) -Used internally in @code{abcddim}. If @var{x} is a zero-size matrix, -both dimensions are set to 0 in @var{y}. -@var{my} and @var{ny} are the row and column dimensions of the result. -@end deftypefn - -@deftypefn {Function File } {@var{Qs} =} ctrb(@var{sys} @{, @var{b}@}) -@deftypefnx {Function File } {@var{Qs} =} ctrb(@var{A}, @var{B}) -Build controllability matrix -@example - 2 n-1 -Qs = [ B AB A B ... A B ] -@end example - - of a system data structure or the pair (@var{A}, @var{B}). - -@strong{Note} @code{ctrb} forms the controllability matrix. - The numerical properties of @code{is_controllable} - are much better for controllability tests. -@end deftypefn - -@deftypefn {Function File } {@var{retval} =} h2norm(@var{sys}) -Computes the H2 norm of a system data structure (continuous time only) +@DOCSTRING(ctrb) -Reference: - Doyle, Glover, Khargonekar, Francis, ``State Space Solutions to Standard - H2 and Hinf Control Problems", IEEE TAC August 1989 -@end deftypefn - -@deftypefn {Function File } {[@var{g}, @var{gmin}, @var{gmax}] =} hinfnorm(@var{sys}@{, @var{tol}, @var{gmin}, @var{gmax}, @var{ptol}@}) - Computes the H infinity norm of a system data structure. +@DOCSTRING(h2norm) -@strong{Inputs} -@table @var -@item sys -system data structure -@item tol -H infinity norm search tolerance (default: 0.001) -@item gmin -minimum value for norm search (default: 1e-9) -@item gmax -maximum value for norm search (default: 1e+9) -@item ptol - pole tolerance: -@itemize @bullet -@item if sys is continuous, poles with -|real(pole)| < ptol*||H|| (H is appropriate Hamiltonian) -are considered to be on the imaginary axis. - -@item if sys is discrete, poles with -|abs(pole)-1| < ptol*||[s1,s2]|| (appropriate symplectic pencil) -are considered to be on the unit circle - -@item Default: 1e-9 -@end itemize -@end table +@DOCSTRING(hinfnorm) -@strong{Outputs} -@table @var -@item g -Computed gain, within @var{tol} of actual gain. @var{g} is returned as Inf -if the system is unstable. -@item gmin, gmax -Actual system gain lies in the interval [@var{gmin}, @var{gmax}] -@end table - - 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 $ -@end deftypefn +@DOCSTRING(obsv) -@deftypefn {Function File } { @var{Qb} =} obsv (@var{sys}@{, @var{c}@}) -Build observability matrix -@example -@group - | C | - | CA | -Qb = | CA^2 | - | ... | - | CA^(n-1) | -@end group -@end example -of a system data structure or the pair (A, C). - -Note: @code{obsv()} forms the observability matrix. - - The numerical properties of is_observable() - are much better for observability tests. -@end deftypefn - -@deftypefn {Function File } {[@var{zer}, @var{pol}]=} pzmap (@var{sys}) - Plots the zeros and poles of a system in the complex plane. -@strong{Inputs} - @var{sys} system data structure - -@strong{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) -@end deftypefn +@DOCSTRING(pzmap) @deftypefn{Function File} {outputs = } synKnames (inputs) Return controller signal names based in plant signal names and dimensions @end deftypefn -@deftypefn {Function File } { @var{retval} =} is_abcd( @var{a}@{, @var{b}, @var{c}, @var{d}@}) - Returns @var{retval} = 1 if the dimensions of @var{a}, @var{b}, @var{c}, @var{d} - are compatible, otherwise @var{retval} = 0 with an appropriate diagnostic -message printed to the screen. -@end deftypefn - -@deftypefn {Function File } {[@var{retval}, @var{U}] =} is_controllable (@var{sys}@{, @var{tol}@}) -@deftypefnx {Function File } {[@var{retval}, @var{U}] =} is_controllable (@var{a}@{, @var{b} ,@var{tol}@}) -Logical check for system controllability. +@DOCSTRING(is_abcd) -@strong{Inputs} -@table @var -@item sys -system data structure -@item a, b -@var{n} by @var{n}, @var{n} by @var{m} matrices, respectively -@item tol -optional roundoff paramter. default value: @code{10*eps} -@end table - -@strong{Outputs} -@table @var -@item retval -Logical flag; returns true (1) if the system @var{sys} or the -pair (@var{a},@var{b}) is controllable, whichever was passed as input arguments. -@item U - U is an orthogonal basis of the controllable subspace. -@end table +@DOCSTRING(is_controllable) -@strong{Method} -Controllability is determined by applying Arnoldi iteration with -complete re-orthogonalization to obtain an orthogonal basis of the -Krylov subspace -@example -span ([b,a*b,...,a^@{n-1@}*b]). -@end example -The Arnoldi iteration is executed with @code{krylov} if the system has a single input; otherwise a block Arnoldi iteration is performed with @code{krylovb}. - -@strong{See also} -@code{is_observable}, @code{is_stabilizable}, @code{is_detectable}, - @code{krylov}, @code{krylovb} - -@end deftypefn - -@deftypefn {Function File } { [@var{retval}, @var{U}] =} is_detectable (@var{a}, @var{c}@{, @var{tol}@}) -@deftypefnx {Function File } { [@var{retval}, @var{U}] =} is_detectable (@var{sys}@{, @var{tol}@}) -Test for detactability (observability of unstable modes) of (@var{a},@var{c}). +@DOCSTRING(is_detectable) - Returns 1 if the system @var{a} or the pair (@var{a},@var{c})is - detectable, 0 if not. - -@strong{See} @code{is_stabilizable} for detailed description of arguments and -computational method. - -@end deftypefn +@DOCSTRING(is_dgkf) -@deftypefn {Function File } { [@var{retval}, @var{dgkf_struct} ] =} is_dgkf (@var{Asys}, @var{nu}, @var{ny}, @var{tol} ) - Determine whether a continuous time state space system meets - assumptions of DGKF algorithm. - Partitions system into: -@example -[dx/dt] = [A | Bw Bu ][w] -[ z ] [Cz | Dzw Dzu ][u] -[ y ] [Cy | Dyw Dyu ] -@end example -or similar discrete-time system. -If necessary, orthogonal transformations @var{Qw}, @var{Qz} and nonsingular - transformations @var{Ru}, @var{Ry} are applied to respective vectors -@var{w}, @var{z}, @var{u}, @var{y} in order to satisfy DGKF assumptions. -Loop shifting is used if @var{Dyu} block is nonzero. +@DOCSTRING(is_digital) -@strong{Inputs} -@table @var -@item Asys -system data structure -@item nu -number of controlled inputs -@item ny - number of measured outputs -@item tol - threshhold for 0. Default: 200@var{eps} -@end table -@strong{Outputs} -@table @var -@item retval - true(1) if system passes check, false(0) otherwise -@item dgkf_struct - data structure of @code{is_dgkf} results. Entries: -@table @var -@item nw, nz - dimensions of @var{w}, @var{z} -@item A - system @var{A} matrix -@item Bw - (@var{n} x @var{nw}) @var{Qw}-transformed disturbance input matrix -@item Bu - (@var{n} x @var{nu}) @var{Ru}-transformed controlled input matrix; +@DOCSTRING(is_observable) - @strong{Note} @math{B = [Bw Bu] } -@item Cz - (@var{nz} x @var{n}) Qz-transformed error output matrix -@item Cy - (@var{ny} x @var{n}) @var{Ry}-transformed measured output matrix +@DOCSTRING(is_sample) - @strong{Note} @math{C = [Cz; Cy] } -@item Dzu, Dyw - off-diagonal blocks of transformed @var{D} matrix that enter -@var{z}, @var{y} from @var{u}, @var{w} respectively -@item Ru - controlled input transformation matrix -@item Ry - observed output transformation matrix -@item Dyu_nz - nonzero if the @var{Dyu} block is nonzero. -@item Dyu - untransformed @var{Dyu} block -@item dflg - nonzero if the system is discrete-time - @end table -@end table -@code{is_dgkf} exits with an error if the system is mixed discrete/continuous - -@strong{References} -@table @strong -@item [1] - Doyle, Glover, Khargonekar, Francis, "State Space Solutions - to Standard H2 and Hinf Control Problems," IEEE TAC August 1989 -@item [2] - Maciejowksi, J.M.: "Multivariable feedback design," -@end table +@DOCSTRING(is_siso) -@end deftypefn - -@deftypefn {Function File } { @var{retval} =} is_digital ( @var{sys}) -Return nonzero if system is digital; -Exits with an error of sys is a mixed (continuous and discrete) system -@end deftypefn - -@deftypefn {Function File } { [@var{retval},@var{U}] =} is_observable (@var{a}, @var{c}@{,@var{tol}@}) -@deftypefnx {Function File } { [@var{retval},@var{U}] =} is_observable (@var{sys}@{, @var{tol}@}) -Logical check for system observability. - Returns 1 if the system @var{sys} or the pair (@var{a},@var{c}) is - observable, 0 if not. - -@strong{See} @code{is_controllable} for detailed description of arguments -and default values. -@end deftypefn - -@deftypefn {Function File } { @var{retval} =} is_sample (@var{Ts}) - return true if @var{Ts} is a legal sampling time - (real,scalar, > 0) -@end deftypefn - -@deftypefn {Function File } { @var{retval} =} is_siso (@var{sys}) -return nonzero if the system data structure -@var{sys} is single-input, single-output. -@end deftypefn - -@deftypefn {Function File } {[@var{retval}, @var{U}] =} is_stabilizable (@var{sys}@{, @var{tol}@}) -@deftypefnx {Function File } {[@var{retval}, @var{U}] =} is_stabilizable (@var{a}@{, @var{b} ,@var{tol}@}) -Logical check for system stabilizability (i.e., all unstable modes are controllable). +@DOCSTRING(is_stabilizable) -@strong{See} @code{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 @var{A} matrix. - -@end deftypefn - -@deftypefn {Function File } {@var{flg} =} is_signal_list (@var{mylist}) -returns true if mylist is a list of individual strings (legal for input -to @var{syssetsignals}). -@end deftypefn - -@deftypefn {Function File } { @var{retval} =} is_stable (@var{a}@{,@var{tol},@var{dflg}@}) -@deftypefnx {Function File } { @var{retval} =} is_stable (@var{sys}@{,@var{tol}@}) - Returns retval = 1 if the matrix @var{a} or the system @var{sys} -is stable, or 0 if not. +@DOCSTRING(is_signal_list) -@strong{Inputs} -@table @var -@item tol -is a roundoff paramter, set to 200*@var{eps} if omitted. -@item dflg -Digital system flag (not required for system data structure): -@table @code -@item @var{dflg} != 0 -stable if eig(a) in unit circle - -@item @var{dflg} == 0 -stable if eig(a) in open LHP (default) -@end table -@end table -@end deftypefn +@DOCSTRING(is_stable) @node systime, sysfreq, sysprop, Control Theory @section System Analysis-Time Domain -@deftypefn {Function File } { @var{dsys} =} c2d (@var{sys}@{, @var{opt}, @var{T}@}) -@deftypefnx {Function File } { @var{dsys} =} c2d (@var{sys}@{, @var{T}@}) +@DOCSTRING(c2d) -@strong{Inputs} -@table @var -@item sys - system data structure (may have both continuous time and discrete time subsystems) -@item opt -string argument; conversion option (optional argument; -may be omitted as shown above) -@table @code -@item "ex" -use the matrix exponential (default) -@item "bi" -use the bilinear transformation -@end table -@example - 2(z-1) -s = ----- - T(z+1) -@end example -FIXME: This option exits with an error if @var{sys} is not purely -continuous. (The @code{ex} option can handle mixed systems.) -@item @var{T} -sampling time; required if sys is purely continuous. - -@strong{Note} If the 2nd argument is not a string, @code{c2d} assumes that -the 2nd argument is @var{T} and performs appropriate argument checks. -@end table - -@strong{Outputs} -@var{dsys} discrete time equivalent via zero-order hold, -sample each @var{T} sec. - -converts the system data structure describing -@example -. -x = Ac x + Bc u -@end example -into a discrete time equivalent model -@example -x[n+1] = Ad x[n] + Bd u[n] -@end example -via the matrix exponential or bilinear transform +@DOCSTRING(d2c) -@strong{Note} This function adds the suffix @code{_d} -to the names of the new discrete states. -@end deftypefn - -@deftypefn {Function File } {@var{csys} =} d2c (@var{sys}@{,@var{tol}@}) -@deftypefnx {Function File } {@var{csys} =} d2c (@var{sys}, @var{opt}) -Convert discrete (sub)system to a purely continuous system. Sampling -time used is @code{sysgettsam(@var{sys})} +@DOCSTRING(dmr2d) -@strong{Inputs} -@table @var -@item sys - system data structure with discrete components -@item tol -Scalar value. - tolerance for convergence of default @code{"log"} option (see below) -@item opt - conversion option. Choose from: -@table @code -@item "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 -@var{A}, @var{B}, to get a better fit to the original data. - -If called as @code{d2c}(@var{sys},@var{tol}), @var{tol=}positive scalar, - the @code{"log"} option is used. The default value for @var{tol} is - @code{1e-8}. -@item "bi" - Conversion is performed via bilinear transform -@math{z = (1 + s T / 2)/(1 - s T / 2)} where @var{T} is the -system sampling time (see @code{sysgettsam}). - -FIXME: bilinear option exits with an error if @var{sys} is not purely discrete - -@end table -@end table -@strong{Outputs} @var{csys} continuous time system (same dimensions and -signal names as in @var{sys}). -@end deftypefn - -@deftypefn {Function File } {[@var{dsys}, @var{fidx}] =} dmr2d (@var{sys}, @var{idx}, @var{sprefix}, @var{Ts2} @{,@var{cuflg}@}) - convert a multirate digital system to a single rate digital system - states specified by @var{idx}, @var{sprefix} are sampled at @var{Ts2}, all - others are assumed sampled at @var{Ts1} = @code{sysgettsam(@var{sys})}. +@DOCSTRING(damp) -@strong{Inputs} -@table @var -@item sys -discrete time system; -@code{dmr2d} exits with an error if @var{sys} is not discrete -@item idx -list of states with sampling time @code{sysgettsam(@var{sys})} (may be empty) -@item sprefix -list of string prefixes of states with sampling time @code{sysgettsam(@var{sys})} -(may be empty) -@item Ts2 -sampling time of states not specified by @var{idx}, @var{sprefix} -must be an integer multiple of @code{sysgettsam(@var{sys})} -@item cuflg -"constant u flag" if @var{cuflg} is nonzero then the system inputs are - assumed to be constant over the revised sampling interval @var{Ts2}. - Otherwise, since the inputs can change during the interval - @var{t} in @math{[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 - @var{cuflg} = 1. -@end table +@DOCSTRING(dcgain) -@strong{Outputs} -@table @var -@item dsys - equivalent discrete time system with sampling time @var{Ts2}. - - The sampling time of sys is updated to @var{Ts2}. - - if @var{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 @var{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 - @var{Ts2} = (n+1)*Ts1) - -@item fidx -indices of "formerly fast" states specified by @var{idx} and @var{sprefix}; -these states are updated to the new (slower) sampling interval @var{Ts2}. -@end table - -@strong{WARNING} Not thoroughly tested yet; especially when @var{cuflg} == 0. - -@end deftypefn +@DOCSTRING(impulse) -@deftypefn {Function File } {} damp(@var{p}@{, @var{tsam}@}) - Displays eigenvalues, natural frequencies and damping ratios - of the eigenvalues of a matrix @var{p} or the @var{A}-matrix of a - system @var{p}, respectively. - If @var{p} is a system, @var{tsam} must not be specified. - If @var{p} is a matrix and @var{tsam} is specified, eigenvalues - of @var{p} are assumed to be in @var{z}-domain. - -See also: @code{eig} -@end deftypefn - -@deftypefn {Function File } {@var{gm} =} dcgain(@var{sys}@{, tol@}) - Returns dc-gain matrix. If dc-gain is infinite - an empty matrix is returned. - The argument @var{tol} is an optional tolerance for the condition - number of @var{A}-Matrix in @var{sys} (default @var{tol} = 1.0e-10) -@end deftypefn - -@deftypefn {Function File } {[@var{y}, @var{t}] =} impulse (@var{sys}@{, @var{inp},@var{tstop}, @var{n}@}) -Impulse response for a linear system. - The system can be discrete or multivariable (or both). -If no output arguments are specified, @code{impulse} - produces a plot or the step response data for system @var{sys}. +@DOCSTRING(step) -@strong{Inputs} -@table @var -@item sys -System data structure. -@item inp -Index of input being excited -@item tstop - The argument @var{tstop} (scalar value) denotes the time when the - simulation should end. -@item n -the number of data values. - - Both parameters @var{tstop} and @var{n} can be omitted and will be - computed from the eigenvalues of the A-Matrix. -@end table -@strong{Outputs} -@var{y}, @var{t}: impulse response -@end deftypefn - -@deftypefn {Function File } {[@var{y}, @var{t}] =} step (@var{sys}@{, @var{inp},@var{tstop}, @var{n}@}) -Step response of a linear system; calling protocol is identical to -@code{impulse}. -@end deftypefn - -@deftypefn {Function File } { } stepimp ( ) -Used internally in @code{impulse}, @code{step}. -@end deftypefn +@DOCSTRING(stepimp) @node sysfreq, cacsd, systime, Control Theory @section System Analysis-Frequency Domain @strong{Demonstration/tutorial script} -@deftypefn {Function File } { } frdemo ( ) -@end deftypefn - - -@deftypefn {Function File } {[@var{mag}, @var{phase}, @var{w}] =} bode(@var{sys}@{,@var{w}, @var{out_idx}, @var{in_idx}@}) -If no output arguments are given: produce Bode plots of a system; otherwise, -compute the frequency response of a system data structure - -@strong{Inputs} -@table @var -@item sys - a system data structure (must be either purely continuous or discrete; - see is_digital) -@item w - frequency values for evaluation. - -if @var{sys} is continuous, then bode evaluates @math{G(jw)} where -@math{G(s)} is the system transfer function. +@DOCSTRING(frdemo) -if @var{sys} is discrete, then bode evaluates G(@code{exp}(jwT)), where -@itemize @bullet -@item @var{T}=@code{sysgettsam(@var{sys})} (the system sampling time) and -@item @math{G(z)} is the system transfer function. -@end itemize - -@strong{ Default} the default frequency range is selected as follows: (These - steps are NOT performed if @var{w} is specified) -@enumerate -@item via routine bodquist, isolate all poles and zeros away from -@var{w}=0 (@var{jw}=0 or @math{@code{exp}(jwT)}=1) and select the frequency -range based on the breakpoint locations of the frequencies. -@item if @var{sys} is discrete time, the frequency range is limited - to @math{jwT} in -@ifinfo -[0,2 pi /T] -@end ifinfo -@iftex -@tex -$[0,2\pi/T]$ -@end tex -@end iftex -@item 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. +@DOCSTRING(bode) -@end enumerate -@item out_idx, in_idx - the indices of the output(s) and input(s) to be used in - the frequency response; see @code{sysprune}. -@end table -@strong{Outputs} -@table @var -@item mag, phase - the magnitude and phase of the frequency response - @math{G(jw)} or @math{G(@code{exp}(jwT))} at the selected frequency values. -@item w -the vector of frequency values used -@end table - -@strong{Notes} -@enumerate -@item If no output arguments are given, e.g., -@example -bode(sys); -@end example -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 (@code{ans = []}). - -@item If the requested plot is for an MIMO system, mag is set to - @math{||G(jw)||} or @math{||G(@code{exp}(jwT))||} -and phase information is not computed. -@end enumerate -@end deftypefn +@DOCSTRING(bode_bounds) -@deftypefn {Function File } {[@var{wmin}, @var{wmax}] =} bode_bounds (@var{zer}, @var{pol}, @var{dflg}@{, @var{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 (@code{bode}, @code{nyquist}) -@end deftypefn - -@deftypefn {Function File } { [@var{f}, @var{w}] =} bodquist (@var{sys}, @var{w}, @var{out_idx}, @var{in_idx}) - used internally by bode, nyquist; compute system frequency response. +@DOCSTRING(bodquist) -@strong{Inputs} -@table @var -@item sys -input system structure -@item w -range of frequencies; empty if user wants default -@item out_idx -list of outputs; empty if user wants all -@item in_idx -list of inputs; empty if user wants all -@item rname -name of routine that called bodquist ("bode" or "nyquist") -@end table -@strong{Outputs} -@table @var -@item w - list of frequencies -@item f - frequency response of sys; @math{f(ii) = f(omega(ii))} -@end table -@strong{Note} bodquist could easily be incorporated into a Nichols -plot function; this is in a "to do" list. -@end deftypefn +@DOCSTRING(freqchkw) -@deftypefn {Function File } { @var{retval} =} freqchkw ( @var{w} ) -Used by @code{freqresp} to check that input frequency vector @var{w} is legal. -Returns boolean value. -@end deftypefn - -@deftypefn {Function File } { @var{out} =} freqresp (@var{sys},@var{USEW}@{,@var{w}@}); - Frequency response function - used internally by @code{bode}, @code{nyquist}. - minimal argument checking; "do not attempt to do this at home" - -@strong{Inputs} -@table @var -@item sys -system data structure -@item USEW -returned by @code{freqchkw} -@item optional - must be present if @var{USEW} is true (nonzero) -@end table -@strong{Outputs} -@table @var -@item @var{out} -vector of finite @math{G(j*w)} entries (or @math{||G(j*w)||} for MIMO) -@item w -vector of corresponding frequencies -@end table -@end deftypefn +@DOCSTRING(freqresp) -@deftypefn {Function File } {@var{out} =} ltifr (@var{A}, @var{B}, @var{w}) -@deftypefnx {Function File } {@var{out} =} ltifr (@var{sys}, @var{w}) -Linear time invariant frequency response of single input systems -@strong{Inputs} -@table @var -@item A, B -coefficient matrices of @math{dx/dt = A x + B u} -@item sys - system data structure -@item w - vector of frequencies -@end table -@strong{Outputs} -@var{out} -@example - -1 - G(s) = (jw I-A) B -@end example -for complex frequencies @math{s = jw}. -@end deftypefn - -@deftypefn {Function File } {[@var{realp}, @var{imagp}, @var{w}] =} nyquist (@var{sys}@{, @var{w}, @var{out_idx}, @var{in_idx}, @var{atol}@}) -@deftypefnx {Function File } {} nyquist (@var{sys}@{, @var{w}, @var{out_idx}, @var{in_idx}, @var{atol}@}) -Produce Nyquist plots of a system; if no output arguments are given, Nyquist -plot is printed to the screen. - -Arguments are identical to @code{bode} with exceptions as noted below: +@DOCSTRING(ltifr) -@strong{Inputs} (pass as empty to get default values) -@table @var -@item 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. -@end table -@strong{Outputs} -@table @var -@item realp, imagp -the real and imaginary parts of the frequency response - @math{G(jw)} or @math{G(exp(jwT))} at the selected frequency values. -@item w - the vector of frequency values used -@end table - - If no output arguments are given, nyquist plots the results to the screen. - If @var{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. - -@end deftypefn +@DOCSTRING(nyquist) -@deftypefn {Function File} {} tzero (@var{a}, @var{b}, @var{c}, @var{d}@{, @var{opt}@}) -@deftypefnx {Function File} {} tzero (@var{sys}@{,@var{opt}@}) - Compute transmission zeros of a continuous -@example -. -x = Ax + Bu -y = Cx + Du -@end example -or discrete -@example -x(k+1) = A x(k) + B u(k) -y(k) = C x(k) + D u(k) -@end example -system. -@strong{Outputs} -@table @var -@item zer - transmission zeros of the system -@item gain -leading coefficient (pole-zero form) of SISO transfer function -returns gain=0 if system is multivariable -@end table -@strong{References} -@enumerate -@item Emami-Naeini and Van Dooren, Automatica, 1982. -@item Hodel, "Computation of Zeros with Balancing," 1992 Lin. Alg. Appl. -@end enumerate -@end deftypefn +@DOCSTRING(tzero) -@deftypefn {Function File } { @var{zr} =} tzero2 (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal}) -Compute the transmission zeros of a, b, c, d. - -bal = balancing option (see balance); default is "B". - -Needs to incorporate @code{mvzero} algorithm to isolate finite zeros; use -@code{tzero} instead. -@end deftypefn +@DOCSTRING(tzero2) @node cacsd, misc, sysfreq, Control Theory @section Controller Design -@deftypefn {Function File } { } dgkfdemo ( ) - Octave Controls toolbox demo: H2/Hinfinity options demos -@end deftypefn -@deftypefn {Function File } { } hinfdemo ( ) -Non-trivial H_infinity design demo. - -H_infinity optimal controller for the jet707 plant; -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) -inputs: (1) thrust and (2) elevator angle -outputs: (1) airspeed and (2) pitch angle - -The optimal controller minimizes the H_infinity norm of the -augmented plant P (mixed-sensitivity problem): -@example -@group - w - 1 -----------+ - | +----+ - +---------------------->| W1 |----> z1 - w | | +----+ - 2 ------------------------+ - | | | - | v +----+ v +----+ - +--*-->o-->| G |-->o--*-->| W2 |---> z2 - | +----+ | +----+ - | | - ^ v - u (from y (to K) - controller - K) +@DOCSTRING(dgkfdemo) -+ + + + -| z | | w | -| 1 | | 1 | -| z | = [ P ] * | w | -| 2 | | 2 | -| y | | u | -+ + + + -@end group -@end example -@end deftypefn - -@deftypefn {Function File} {[@var{l}, @var{m}, @var{p}, @var{e}] =} dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) -Construct the linear quadratic estimator (Kalman filter) for the -discrete time system -@iftex -@tex -$$ - x_{k+1} = A x_k + B u_k + G w_k -$$ -$$ - y_k = C x_k + D u_k + w_k -$$ -@end tex -@end iftex -@ifinfo - -@example -x[k+1] = A x[k] + B u[k] + G w[k] - y[k] = C x[k] + D u[k] + w[k] -@end example - -@end ifinfo -where @var{w}, @var{v} are zero-mean gaussian noise processes with -respective intensities @code{@var{sigw} = cov (@var{w}, @var{w})} and -@code{@var{sigv} = cov (@var{v}, @var{v})}. - -If specified, @var{z} is @code{cov (@var{w}, @var{v})}. Otherwise -@code{cov (@var{w}, @var{v}) = 0}. +@DOCSTRING(hinfdemo) -The observer structure is -@iftex -@tex -$$ - z_{k+1} = A z_k + B u_k + k (y_k - C z_k - D u_k) -$$ -@end tex -@end iftex -@ifinfo - -@example -z[k+1] = A z[k] + B u[k] + k (y[k] - C z[k] - D u[k]) -@end example -@end ifinfo - -@noindent -The following values are returned: - -@table @var -@item l -The observer gain, -@iftex -@tex -$(A - ALC)$. -@end tex -@end iftex -@ifinfo -(@var{a} - @var{a}@var{l}@var{c}). -@end ifinfo -is stable. - -@item m -The Riccati equation solution. - -@item p -The estimate error covariance after the measurement update. +@DOCSTRING(dlqe) -@item e -The closed loop poles of -@iftex -@tex -$(A - ALC)$. -@end tex -@end iftex -@ifinfo -(@var{a} - @var{a}@var{l}@var{c}). -@end ifinfo -@end table -@end deftypefn - -@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) -Construct the linear quadratic regulator for the discrete time system -@iftex -@tex -$$ - x_{k+1} = A x_k + B u_k -$$ -@end tex -@end iftex -@ifinfo - -@example -x[k+1] = A x[k] + B u[k] -@end example - -@end ifinfo -to minimize the cost functional -@iftex -@tex -$$ - J = \sum x^T Q x + u^T R u -$$ -@end tex -@end iftex -@ifinfo - -@example -J = Sum (x' Q x + u' R u) -@end example -@end ifinfo +@DOCSTRING(dlqr) -@noindent -@var{z} omitted or -@iftex -@tex -$$ - J = \sum x^T Q x + u^T R u + 2 x^T Z u -$$ -@end tex -@end iftex -@ifinfo - -@example -J = Sum (x' Q x + u' R u + 2 x' Z u) -@end example - -@end ifinfo -@var{z} included. - -The following values are returned: +@DOCSTRING(h2syn) -@table @var -@item k -The state feedback gain, -@iftex -@tex -$(A - B K)$ -@end tex -@end iftex -@ifinfo -(@var{a} - @var{b}@var{k}) -@end ifinfo -is stable. - -@item p -The solution of algebraic Riccati equation. - -@item e -The closed loop poles of -@iftex -@tex -$(A - B K)$. -@end tex -@end iftex -@ifinfo -(@var{a} - @var{b}@var{k}). -@end ifinfo -@end table -@strong{References} -@enumerate -@item Anderson and Moore, Optimal Control: Linear Quadratic Methods, - Prentice-Hall, 1990, pp. 56-58 -@item Kuo, Digital Control Systems, Harcourt Brace Jovanovich, 1992, - section 11-5-2. -@end enumerate -@end deftypefn - -@deftypefn {Function File } {[K}, @var{gain}, @var{Kc}, @var{Kf}, @var{Pc}, @var{Pf}] = h2syn(@var{Asys}, @var{nu}, @var{ny}, @var{tol}) - Design H2 optimal controller per procedure in - Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard - H2 and Hinf Control Problems", IEEE TAC August 1989 +@DOCSTRING(hinf_ctr) -@strong{Inputs} input system is passed as either -@table @var -@item Asys -system data structure (see ss2sys, sys2ss) -@itemize @bullet -@item controller is implemented for continuous time systems -@item controller is NOT implemented for discrete time systems -@end itemize -@item nu -number of controlled inputs -@item ny -number of measured outputs -@item tol -threshhold for 0. Default: 200*eps -@end table - -@strong{Outputs} -@table @var -@item K -system controller -@item gain -optimal closed loop gain -@item Kc -full information control (packed) -@item Kf -state estimator (packed) -@item Pc -ARE solution matrix for regulator subproblem -@item Pf -ARE solution matrix for filter subproblem -@end table -@end deftypefn - -@deftypefn {Function File } {@var{K} =} hinf_ctr(@var{dgs}, @var{F}, @var{H}, @var{Z}, @var{g}) -Called by @code{hinfsyn} to compute the H_inf optimal controller. - -@strong{Inputs} -@table @var -@item dgs -data structure returned by @code{is_dgkf} -@item F, H -feedback and filter gain (not partitioned) -@item g -final gamma value -@end table -@strong{Outputs} -controller K (system data structure) - -Do not attempt to use this at home; no argument checking performed. -@end deftypefn - -@deftypefn {Function File } {[@var{K}, @var{g}, @var{GW}, @var{Xinf}, @var{Yinf}] =} hinfsyn(@var{Asys}, @var{nu}, @var{ny}, @var{gmin}, @var{gmax}, @var{gtol}@{, @var{ptol}, @var{tol}@}) +@DOCSTRING(hinfsyn) -@strong{Inputs} input system is passed as either -@table @var -@item Asys -system data structure (see ss2sys, sys2ss) -@itemize @bullet -@item controller is implemented for continuous time systems -@item controller is NOT implemented for discrete time systems (see -bilinear transforms in @code{c2d}, @code{d2c}) -@end itemize -@item nu -number of controlled inputs -@item ny -number of measured outputs -@item gmin -initial lower bound on H-infinity optimal gain -@item gmax -initial upper bound on H-infinity optimal gain -@item gtol -gain threshhold. Routine quits when gmax/gmin < 1+tol -@item ptol -poles with abs(real(pole)) < ptol*||H|| (H is appropriate -Hamiltonian) are considered to be on the imaginary axis. -Default: 1e-9 -@item tol -threshhold for 0. Default: 200*eps - -@var{gmax}, @var{min}, @var{tol}, and @var{tol} must all be postive scalars. -@end table -@strong{Outputs} -@table @var -@item K -system controller -@item g -designed gain value -@item GW -closed loop system -@item Xinf -ARE solution matrix for regulator subproblem -@item Yinf -ARE solution matrix for filter subproblem -@end table - -@enumerate -@item Doyle, Glover, Khargonekar, Francis, "State Space Solutions - to Standard H2 and Hinf Control Problems," IEEE TAC August 1989 - -@item Maciejowksi, J.M., "Multivariable feedback design," - Addison-Wesley, 1989, ISBN 0-201-18243-2 - -@item Keith Glover and John C. Doyle, "State-space formulae for all - stabilizing controllers that satisfy and h-infinity-norm bound - and relations to risk sensitivity," - Systems & Control Letters 11, Oct. 1988, pp 167-172. -@end enumerate -@end deftypefn - +@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. @@ -3066,273 +557,22 @@ @end deftypefn -@deftypefn {Function File} {[@var{retval}, @var{Pc}, @var{Pf}] =} hinfsyn_chk(@var{A}, @var{B1}, @var{B2}, @var{C1}, @var{C2}, @var{D12}, @var{D21}, @var{g}, @var{ptol}) - Called by @code{hinfsyn} to see if gain @var{g} satisfies conditions in -Theorem 3 of - Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard - H2 and Hinf Control Problems", IEEE TAC August 1989 - -@strong{Warning} Do not attempt to use this at home; no argument checking performed. - -@strong{Inputs} as returned by @code{is_dgkf}, except for: -@table @var -@item g -candidate gain level -@item ptol - as in @code{hinfsyn} -@end table - - Outputs: - retval: = 1 if g exceeds optimal Hinf closed loop gain, else 0 - Pc: solution of "regulator" H-inf ARE - Pf: solution of "filter" H-inf ARE - -@end deftypefn - -@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) -Construct the linear quadratic estimator (Kalman filter) for the -continuous time system -@iftex -@tex -$$ - {dx\over dt} = A x + B u -$$ -$$ - y = C x + D u -$$ -@end tex -@end iftex -@ifinfo - -@example -dx --- = a x + b u -dt - -y = c x + d u -@end example - -@end ifinfo -where @var{w} and @var{v} are zero-mean gaussian noise processes with -respective intensities - -@example -sigw = cov (w, w) -sigv = cov (v, v) -@end example +@DOCSTRING(hinfsyn_chk) -The optional argument @var{z} is the cross-covariance -@code{cov (@var{w}, @var{v})}. If it is omitted, -@code{cov (@var{w}, @var{v}) = 0} is assumed. - -Observer structure is @code{dz/dt = A z + B u + k (y - C z - D u)} - -The following values are returned: - -@table @var -@item k -The observer gain, -@iftex -@tex -$(A - K C)$ -@end tex -@end iftex -@ifinfo -(@var{a} - @var{k}@var{c}) -@end ifinfo -is stable. - -@item p -The solution of algebraic Riccati equation. +@DOCSTRING(lqe) -@item e -The vector of closed loop poles of -@iftex -@tex -$(A - K C)$. -@end tex -@end iftex -@ifinfo -(@var{a} - @var{k}@var{c}). -@end ifinfo -@end table -@end deftypefn - -@deftypefn {Function File } {[@var{K}, @var{Q}, @var{P}, @var{Ee}, @var{Er}] =} lqg(@var{sys}, @var{Sigw}, @var{Sigv}, @var{Q}, @var{R}, @var{in_idx}) -Design a linear-quadratic-gaussian optimal controller for the system -@example -dx/dt = A x + B u + G w [w]=N(0,[Sigw 0 ]) - y = C x + v [v] ( 0 Sigv ]) -@end example -or -@example -x(k+1) = A x(k) + B u(k) + G w(k) [w]=N(0,[Sigw 0 ]) - y(k) = C x(k) + v(k) [v] ( 0 Sigv ]) -@end example - -@strong{Inputs} -@table @var -@item sys -system data structure -@item Sigw, Sigv -intensities of independent Gaussian noise processes (as above) -@item Q, R -state, control weighting respectively. Control ARE is -@item in_idx -indices of controlled inputs +@DOCSTRING(lqg) - default: last dim(R) inputs are assumed to be controlled inputs, all - others are assumed to be noise inputs. -@end table -@strong{Outputs} -@table @var -@item K -system data structure format LQG optimal controller -(Obtain A,B,C matrices with @code{sys2ss}, @code{sys2tf}, or @code{sys2zp} as appropriate) -@item P -Solution of control (state feedback) algebraic Riccati equation -@item Q -Solution of estimation algebraic Riccati equation -@item Ee -estimator poles -@item Es -controller poles -@end table -@end deftypefn - -@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) -construct the linear quadratic regulator for the continuous time system -@iftex -@tex -$$ - {dx\over dt} = A x + B u -$$ -@end tex -@end iftex -@ifinfo - -@example -dx --- = A x + B u -dt -@end example - -@end ifinfo -to minimize the cost functional -@iftex -@tex -$$ - J = \int_0^\infty x^T Q x + u^T R u -$$ -@end tex -@end iftex -@ifinfo - -@example - infinity - / - J = | x' Q x + u' R u - / - t=0 -@end example -@end ifinfo - -@noindent -@var{z} omitted or -@iftex -@tex -$$ - J = \int_0^\infty x^T Q x + u^T R u + 2 x^T Z u -$$ -@end tex -@end iftex -@ifinfo +@DOCSTRING(lqr) -@example - infinity - / - J = | x' Q x + u' R u + 2 x' Z u - / - t=0 -@end example - -@end ifinfo -@var{z} included. - -The following values are returned: - -@table @var -@item k -The state feedback gain, -@iftex -@tex -$(A - B K)$ -@end tex -@end iftex -@ifinfo -(@var{a} - @var{b}@var{k}) -@end ifinfo -is stable. - -@item p -The stabilizing solution of appropriate algebraic Riccati equation. +@DOCSTRING(lsim) -@item e -The vector of the closed loop poles of -@iftex -@tex -$(A - B K)$. -@end tex -@end iftex -@ifinfo -(@var{a} - @var{b}@var{k}). -@end ifinfo -@end table -@end deftypefn - -@deftypefn {Function File } { } lsim (@var{sys}, @var{u}, @var{t}@{,@var{x0}@}) -Produce output for a linear simulation of a system - -Produces a plot for the output of the system, sys. - -U is an array that contains the system's inputs. Each column in u -corresponds to a different time step. Each row in u corresponds to a -different input. T is an array that contains the time index of the -system. T should be regularly spaced. If initial conditions are required -on the system, the x0 vector should be added to the argument list. - -When the lsim function is invoked with output parameters: -[y,x] = lsim(sys,u,t,[x0]) -a plot is not displayed, however, the data is returned in y = system output -and x = system states. -@end deftypefn - -@deftypefn {Function File } { @var{K} =} place (@var{sys}, @var{P}) -Computes the matrix K such that if the state -is feedback with gain K, then the eigenvalues of the closed loop -system (i.e. A-BK) are those specified in the vector P. - -Version: Beta (May-1997): If you have any comments, please let me know. - (see the file place.m for my address) - -Written by: Jose Daniel Munoz Frias. -@end deftypefn +@DOCSTRING(place) @node misc, , cacsd, Control Theory @section Miscellaneous Functions (Not yet properly filed/documented) - -@deftypefn{Function File } { @var{axvec} =} axis2dlim (@var{axdata}) - determine axis limits for 2-d data(column vectors); leaves a 10% margin - around the plots. - puts in margins of +/- 0.1 if data is one dimensional (or a single point) - -@strong{Inputs} - @var{axdata} nx2 matrix of data [x,y] - -@strong{Outputs} - @var{axvec} vector of axis limits appropriate for call to axis() function -@end deftypefn +@DOCSTRING(axis2dlim) @deftypefn {Function File } { outputs =} mb ( inputs ) @format @@ -3342,230 +582,31 @@ @end format @end deftypefn -@deftypefn {Function File } { outputs =} moddemo ( inputs ) -@format - Octave Controls toolbox demo: Model Manipulations demo - Written by David Clem August 15, 1994 - - -@end format -@end deftypefn - -@deftypefn {Function File } { outputs =} prompt ( inputs ) -@format - function prompt([str]) - Prompt user to continue - str: input string. Default value: "\n ---- Press a key to continue ---" - Written by David Clem August 15, 1994 - Modified A. S. Hodel June 1995 - - -@end format -@end deftypefn +@DOCSTRING(moddemo) -@deftypefn {Function File } { outputs =} rldemo ( inputs ) -@end deftypefn +@DOCSTRING(prompt) -@deftypefn {Function File } { outputs =} rlocus ( inputs ) -@format - [rldata, k] = rlocus(sys[,increment,min_k,max_k]) - Displays root locus plot of the specified SISO system. - - ----- --- -------- - --->| + |---|k|---->| SISO |-----------> - ----- --- -------- | - - ^ | - |_____________________________| - -inputs: sys = system data structure - min_k, max_k,increment: minimum, maximum values of k and - the increment used in computing gain values - Outputs: plots the root locus to the screen. - rldata: Data points plotted column 1: real values, column 2: imaginary - values) - k: gains for real axis break points. - - -@end format -@end deftypefn +@DOCSTRING(rldemo) -@deftypefn {Function File } { outputs =} sortcom ( inputs ) -@format - [yy,idx] = sortcom(xx[,opt]): sort a complex vector - xx: complex vector - opt: sorting option: - "re": real part (default) - "mag": by magnitude - "im": by imaginary part - - if opt != "im" then complex conjugate pairs are grouped together, - a - jb followed by a + jb. - yy: sorted values - idx: permutation vector: yy = xx(idx) +@DOCSTRING(rlocus) - -@end format -@end deftypefn - -@deftypefn {Function File } { outputs =} ss2tf ( inputs ) -@format - [num,den] = ss2tf(a,b,c,d) - Conversion from tranfer function to state-space. - The state space system - . - x = Ax + Bu - y = Cx + Du - - is converted to a transfer function +@DOCSTRING(sortcom) - num(s) - G(s)=------- - den(s) - - used internally in system data structure format manipulations - - -@end format -@end deftypefn - -@deftypefn {Function File } { outputs =} ss2zp ( inputs ) -@format - Converts a state space representation to a set of poles and zeros. +@DOCSTRING(ss2tf) - [pol,zer,k] = ss2zp(a,b,c,d) returns the poles and zeros of the state space - system (a,b,c,d). K is a gain associated with the zeros. - - used internally in system data structure format manipulations - - -@end format -@end deftypefn - -@deftypefn {Function File } { outputs =} starp ( inputs ) -@format - - [sys] = starp(P, K, ny, nu) - - Redheffer star product or upper/lower LFT, respectively. - +@DOCSTRING(ss2zp) - +-------+ - --------->| |---------> - | P | - +--->| |---+ ny - | +-------+ | - +-------------------+ - | | - +----------------+ | - | | - | +-------+ | - +--->| |------+ nu - | K | - --------->| |---------> - +-------+ - - If ny and nu "consume" all inputs and outputs of K then the result - is a lower fractional transformation. If ny and nu "consume" all - inputs and outputs of P then the result is an upper fractional - transformation. - - ny and/or nu may be negative (= negative feedback) -@end format -@end deftypefn -@deftypefn {Function File } { outputs =} susball ( inputs ) -@format +@DOCSTRING(starp) -@end format -@end deftypefn -@deftypefn {Function File } { outputs =} swap ( inputs ) -@format - [a1,b1] = swap(a,b) - interchange a and b - +@DOCSTRING(susball) -@end format -@end deftypefn -@deftypefn {Function File } { outputs =} swapcols ( inputs ) -@format - function B = swapcols(A) - permute columns of A into reverse order - - -@end format -@end deftypefn -@deftypefn {Function File } { outputs =} swaprows ( inputs ) -@format - function B = swaprows(A) - permute rows of A into reverse order - - -@end format -@end deftypefn +@DOCSTRING(tf2ss) -@deftypefn {Function File } { outputs =} tf2ss ( inputs ) -@format - Conversion from tranfer function to state-space. - The state space system - . - x = Ax + Bu - y = Cx + Du - - is obtained from a transfer function - - num(s) - G(s)=------- - den(s) +@DOCSTRING(tf2zp) - via the function call [a,b,c,d] = tf2ss(num,den). - The vector 'den' must contain only one row, whereas the vector 'num' - may contain as many rows as there are outputs of the system 'y'. - The state space system matrices obtained from this function will be - in controllable canonical form as described in "Modern Control Theory", - [Brogan, 1991]. - - -@end format -@end deftypefn - - -@deftypefn {Function File } { outputs =} tf2zp ( inputs ) -@format - Converts transfer functions to poles / zeros. - - [zer,pol,k] = tf2zp(num,den) returns the zeros and poles of the SISO system - defined by num/den. K is a gain associated with the system zeros. - +@DOCSTRING(zp2ss) -@end format -@end deftypefn +@DOCSTRING(zp2ssg2) -@deftypefn {Function File } { } zp2ss -Conversion from zero / pole to state space. -The state space system -@example -. -x = Ax + Bu -y = Cx + Du -@end example -is obtained from a vector of zeros and a vector of poles via the -function call @code{[a,b,c,d] = zp2ss(zer,pol,k)}. -The vectors @samp{zer} and -@samp{pol} may either be row or column vectors. Each zero and pole that -has an imaginary part must have a conjugate in the list. -The number of zeros must not exceed the number of poles. -@samp{k} is @code{zp}-form leading coefficient. -@end deftypefn +@DOCSTRING(zp2tf) -@deftypefn {Function File } { [@var{poly}, @var{rvals}] =} zp2ssg2 (@var{rvals}) -Used internally in @code{zp2ss} -Extract 2 values from @var{rvals} (if possible) and construct - a polynomial with those roots. -@end deftypefn - -@deftypefn {Function File } { } zp2tf - Converts zeros / poles to a transfer function. - -@code{[num,den] = zp2tf(zer,pol,k)} forms the transfer function -@code{num/den} from the vectors of poles and zeros. -@end deftypefn -
--- a/scripts/control/DEMOcontrol.m +++ b/scripts/control/DEMOcontrol.m @@ -16,11 +16,33 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { } DEMOcontrol +## Octave Control Systems Toolbox demo/tutorial program. The demo +## allows the user to select among several categories of OCST function: +## @example +## @group +## 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 +## @end group +## @end example +## Command examples are interactively run for users to observe the use +## of OCST functions. +## @end deftypefn + +## Demo programs: bddemo.m, frdemo.m, analdemo.m, moddmeo.m, rldemo.m +## Written by David Clem August 15, 1994 + function DEMOcontrol() -# Controls toolbox demo. -# Demo programs: bddemo.m, frdemo.m, analdemo.m, moddmeo.m, rldemo.m -# -# Written by David Clem August 15, 1994 disp(' 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')
--- a/scripts/control/abcddim.m +++ b/scripts/control/abcddim.m @@ -16,23 +16,52 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [n, m, p] = abcddim (a, b, c, d) +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{n}, @var{m}, @var{p}] =} abcddim (@var{a}, @var{b}, @var{c}, @var{d}) +## Check for compatibility of the dimensions of the matrices defining +## the linear system +## @iftex +## @tex +## $[A, B, C, D]$ corresponding to +## $$ +## \eqalign{ +## {dx\over dt} &= A x + B u\cr +## y &= C x + D u} +## $$ +## @end tex +## @end iftex +## @ifinfo +## [A, B, C, D] corresponding to +## +## @example +## dx/dt = a x + b u +## y = c x + d u +## @end example +## +## @end ifinfo +## or a similar discrete-time system. +## +## If the matrices are compatibly dimensioned, then @code{abcddim} returns +## +## @table @var +## @item n +## The number of system states. +## +## @item m +## The number of system inputs. +## +## @item p +## The number of system outputs. +## @end table +## +## Otherwise @code{abcddim} returns @var{n} = @var{m} = @var{p} = @minus{}1. +## +## Note: n = 0 (pure gain block) is returned without warning. +## +## See also: is_abcd +## @end deftypefn -# Usage: [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). -# -# Returns n = number of system states, -# m = number of system inputs, -# p = number of system outputs. -# -# Note: n = 0 (pure gain block) is returned without warning. -# -# Returns n = m = p = -1 if the system is not compatible. -# -# See also: is_abcd - +function [n, m, p] = abcddim (a, b, c, d) # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. # a s hodel: modified to accept pure-gain systems aug 1996
--- a/scripts/control/abcddims.m +++ b/scripts/control/abcddims.m @@ -16,13 +16,15 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [y,my,ny] = abcddims (x) +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{y}, @var{my}, @var{ny}] =} abcddims (@var{x}) +## +## Used internally in @code{abcddim}. If @var{x} is a zero-size matrix, +## both dimensions are set to 0 in @var{y}. +## @var{my} and @var{ny} are the row and column dimensions of the result. +## @end deftypefn -# Usage: [y,my,ny] = abcddims (x) -# -# Used internally in abcddim. If x is a zero-size matrix, both dimensions -# get set to 0. my and ny are the row and column dimensions of the result. - +function [y,my,ny] = abcddims (x) # Written by A. S. Hodel (scotte@eng.auburn.edu) Feb 1997 y = x;
--- a/scripts/control/analdemo.m +++ b/scripts/control/analdemo.m @@ -16,8 +16,12 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { } analdemo ( ) +## Octave Controls toolbox demo: State Space analysis demo +## @end deftypefn + function analdemo() -# Octave Controls toolbox demo: State Space analysis demo # Written by David Clem August 15, 1994 # Updated by John Ingram December 1996
--- a/scripts/control/are.m +++ b/scripts/control/are.m @@ -16,24 +16,52 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function x = are (a, b, c, opt) +## -*- texinfo -*- +## @deftypefn {Function File} {} are (@var{a}, @var{b}, @var{c}, @var{opt}) +## Solve the algebraic Riccati equation +## @iftex +## @tex +## $$ +## A^TX + XA - XBX + C = 0 +## $$ +## @end tex +## @end iftex +## @ifinfo +## @example +## a' * x + x * a - x * b * x + c = 0 +## @end example +## @end ifinfo +## +## @strong{Inputs} +## @noindent +## for identically dimensioned square matrices +## @table @var +## @item a +## @var{n}x@var{n} matrix. +## @item b +## @var{n}x@var{n} matrix or @var{n}x@var{m} matrix; in the latter case +## @var{b} is replaced by @math{b:=b*b'}. +## @item c +## @var{n}x@var{n} matrix or @var{p}x@var{m} matrix; in the latter case +## @var{c} is replaced by @math{c:=c'*c}. +## @item opt +## (optional argument; default = @code{"B"}): +## String option passed to @code{balance} prior to ordered Schur decomposition. +## @end table +## +## @strong{Outputs} +## @var{x}: solution of the ARE. +## +## @strong{Method} +## Laub's Schur method (IEEE Transactions on +## Automatic Control, 1979) is applied to the appropriate Hamiltonian +## matrix. +## +## @end deftypefn -# Usage: x = are (a, b, c {,opt}) -# -# Solves algebraic riccati equation -# -# a' x + x a - x b x + c = 0 -# -# for identically dimensioned square matrices a, b, c. If b (c) is not -# square, then the function attempts to use b * b' (c' * c) instead. -# -# Solution method: apply Laub's Schur method (IEEE Trans. Auto. Contr, -# 1979) to the appropriate Hamiltonian matrix. -# -# opt is an option passed to the eigenvalue balancing routine default is "B". -# -# See also: balance +## See also: balance, dare +function x = are (a, b, c, opt) # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. if (nargin == 3 || nargin == 4)
--- a/scripts/control/axis2dlim.m +++ b/scripts/control/axis2dlim.m @@ -16,15 +16,21 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn{Function File } { @var{axvec} =} axis2dlim (@var{axdata}) +## determine axis limits for 2-d data(column vectors); leaves a 10% margin +## around the plots. +## puts in margins of +/- 0.1 if data is one dimensional (or a single point) +## +## @strong{Inputs} +## @var{axdata} nx2 matrix of data [x,y] +## +## @strong{Outputs} +## @var{axvec} vector of axis limits appropriate for call to axis() function +## @end deftypefn + function axvec = axis2dlim(axdata) -# function axvec = axis2dlim(axdata) -# determine axis limits for 2-d data; leaves a 10% margin around the plots. -# puts in margins of +/- 0.1 if data is one dimensional (or a single point) -# inputs: -# axdata: nx2 matrix of data [x,y] -# outputs: -# vector of axis limits appropriate for call to axis() function - + if(isempty(axdata)) axdata = 0; endif
--- a/scripts/control/bddemo.m +++ b/scripts/control/bddemo.m @@ -15,9 +15,13 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} bddemo ( inputs ) +## Octave Controls toolbox demo: Block Diagram Manipulations demo +## @end deftypefn function bddemo() -# Octave Controls toolbox demo: Block Diagram Manipulations demo # Written by David Clem August 15, 1994 # Modified by A S Hodel Summer-Fall 1996
--- a/scripts/control/bode.m +++ b/scripts/control/bode.m @@ -15,46 +15,82 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{mag}, @var{phase}, @var{w}] =} bode(@var{sys}@{,@var{w}, @var{out_idx}, @var{in_idx}@}) +## If no output arguments are given: produce Bode plots of a system; otherwise, +## compute the frequency response of a system data structure +## +## @strong{Inputs} +## @table @var +## @item sys +## a system data structure (must be either purely continuous or discrete; +## see is_digital) +## @item w +## frequency values for evaluation. +## +## if @var{sys} is continuous, then bode evaluates @math{G(jw)} where +## @math{G(s)} is the system transfer function. +## +## if @var{sys} is discrete, then bode evaluates G(@code{exp}(jwT)), where +## @itemize @bullet +## @item @var{T}=@code{sysgettsam(@var{sys})} (the system sampling time) and +## @item @math{G(z)} is the system transfer function. +## @end itemize +## +## @strong{ Default} the default frequency range is selected as follows: (These +## steps are NOT performed if @var{w} is specified) +## @enumerate +## @item via routine bodquist, isolate all poles and zeros away from +## @var{w}=0 (@var{jw}=0 or @math{@code{exp}(jwT)}=1) and select the frequency +## range based on the breakpoint locations of the frequencies. +## @item if @var{sys} is discrete time, the frequency range is limited +## to @math{jwT} in +## @ifinfo +## [0,2 pi /T] +## @end ifinfo +## @iftex +## @tex +## $[0,2\pi/T]$ +## @end tex +## @end iftex +## @item 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. +## +## @end enumerate +## @item out_idx, in_idx +## the indices of the output(s) and input(s) to be used in +## the frequency response; see @code{sysprune}. +## @end table +## @strong{Outputs} +## @table @var +## @item mag, phase +## the magnitude and phase of the frequency response +## @math{G(jw)} or @math{G(@code{exp}(jwT))} at the selected frequency values. +## @item w +## the vector of frequency values used +## @end table +## +## @strong{Notes} +## @enumerate +## @item If no output arguments are given, e.g., +## @example +## bode(sys); +## @end example +## 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 (@code{ans = []}). +## +## @item If the requested plot is for an MIMO system, mag is set to +## @math{||G(jw)||} or @math{||G(@code{exp}(jwT))||} +## and phase information is not computed. +## @end enumerate +## @end deftypefn + function [mag_r,phase_r,w_r] = bode(sys,w,outputs,inputs,plot_style) -# [mag,phase,w] = bode(sys[,w,outputs,inputs,plot_style]) -# Produce Bode plots of a system -# -# Compute the frequency response of a system. -# inputs: -# sys: 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) -# if sys is discrete, then bode evaluates G(exp(jwT)), where T=sys.tsam -# (the system sampling time) -# 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,2p*pi] -# (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. -# outputs, inputs: the indices of the output(s) and input(s) to be used in -# the frequency response; see sysprune. -# plot_style: An optional argument specifying the type of plot to -# produce (if plotting is being done). Valid values are -# "dB" or "mag". If omitted, "dB" is assumed. -# -# 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 -# If no output arguments are given, bode plots the results to the screen. -# Descriptive labels are automatically placed. See xlabel, ylable, title, -# and replot. -# -# Note: 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. - # Written by John Ingram July 10th, 1996 # Based on previous code # By R. Bruce Tenison, July 13, 1994
--- a/scripts/control/bode_bounds.m +++ b/scripts/control/bode_bounds.m @@ -15,15 +15,17 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{wmin}, @var{wmax}] =} bode_bounds (@var{zer}, @var{pol}, @var{dflg}@{, @var{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 (@code{bode}, @code{nyquist}) +## @end deftypefn function [wmin,wmax] = bode_bounds(zer,pol,DIGITAL,tsam) -# function [wmin,wmax] = bode_bounds(zer,pol,DIGITAL{,tsam}) -# get default range of frequencies for system zeros and poles -# -# frequency range is the interval [10^wmin,10^wmax] -# -# used internally in freqresp - # make sure zer,pol are row vectors if(!isempty(pol)) pol = reshape(pol,1,length(pol)); endif if(!isempty(zer)) zer = reshape(zer,1,length(zer)); endif
--- a/scripts/control/bodquist.m +++ b/scripts/control/bodquist.m @@ -15,26 +15,42 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{f}, @var{w}] =} bodquist (@var{sys}, @var{w}, @var{out_idx}, @var{in_idx}) +## used internally by bode, nyquist; compute system frequency response. +## +## @strong{Inputs} +## @table @var +## @item sys +## input system structure +## @item w +## range of frequencies; empty if user wants default +## @item out_idx +## list of outputs; empty if user wants all +## @item in_idx +## list of inputs; empty if user wants all +## @item rname +## name of routine that called bodquist ("bode" or "nyquist") +## @end table +## @strong{Outputs} +## @table @var +## @item w +## list of frequencies +## @item f +## frequency response of sys; @math{f(ii) = f(omega(ii))} +## @end table +## @strong{Note} bodquist could easily be incorporated into a Nichols +## plot function; this is in a "to do" list. +## +## Both bode and nyquist share the same introduction, so the common parts are +## in bodquist. It contains the part that finds the number of arguments, +## determines whether or not the system is SISO, and computes the frequency +## response. Only the way the response is plotted is different between the +## two functions. +## @end deftypefn function [f,w] = bodquist(sys,w,outputs,inputs,rname) -# [f,w] = bodquist(sys,w,outputs,inputs) -# used by bode, nyquist -# inputs: -# sys: input system structure -# w: range of frequencies; empty if user wants default -# outputs:list of outputs; empty if user wants all -# inputs: 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)) -# -# Both bode and nyquist share the same introduction, so the common parts are -# in this file bodquist.m. It contains the part that finds the -# number of arguments, determines whether or not the system is SISO, and -# computes the frequency response. Only the way the response is plotted is -# different between the two functions. - # check number of input arguments given if (nargin != 5) usage("[f,w] = bodquist(sys,w,outputs,inputs,rname)");
--- a/scripts/control/buildssic.m +++ b/scripts/control/buildssic.m @@ -15,98 +15,118 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{sys}] =} buildssic(@var{Clst}, @var{Ulst}, @var{Olst}, @var{Ilst}, @var{s1}, @var{s2}, @var{s3}, @var{s4}, @var{s5}, @var{s6}, @var{s7}, @var{s8}) +## +## Contributed by Kai Mueller. +## +## Form an arbitrary complex (open or closed loop) system in +## state-space form from several systems. "@code{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 "@code{sysgroup}" +## "@code{sysmult}", "@code{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: +## @table @var +## @item 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: +## @code{[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. +## +## @item 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. +## +## @item 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. +## +## @item 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. +## @end table +## +## Example: Very simple closed loop system. +## @example +## @group +## w e +-----+ u +-----+ +## --->o--*-->| K |--*-->| G |--*---> y +## ^ | +-----+ | +-----+ | +## - | | | | +## | | +----------------> u +## | | | +## | +-------------------------|---> e +## | | +## +----------------------------+ +## @end group +## @end example +## +## The closed loop system GW can be optained by +## @example +## GW = buildssic([1 2; 2 -1], [2], [1 2 3], [2], G, K); +## @end example +## @table @var +## @item Clst +## (1. row) connect input 1 (G) with output 2 (K). +## (2. row) connect input 2 (K) with neg. output 1 (G). +## @item Ulst +## append input of (2) K to the number of outputs. +## @item Olst +## Outputs are output of 1 (G), 2 (K) and appended output 3 (from Ulst). +## @item Ilst +## the only input is 2 (K). +## @end table +## +## Here is a real example: +## @example +## @group +## +----+ +## -------------------->| W1 |---> v1 +## z | +----+ +## ----|-------------+ || GW || => min. +## | | vz infty +## | +---+ v +----+ +## *--->| G |--->O--*-->| W2 |---> v2 +## | +---+ | +----+ +## | | +## | v +## u y +## @end group +## @end example +## +## The closed loop system GW from [z; u]' to [v1; v2; y]' can be +## obtained by (all SISO systems): +## @example +## GW = buildssic([1 4;2 4;3 1],[3],[2 3 5],[3 4],G,W1,W2,One); +## @end example +## where "One" is a unity gain (auxillary) function with order 0. +## (e.g. @code{One = ugain(1);}) +## @end deftypefn function [sys] = buildssic(Clst,Ulst,Olst,Ilst,s1,s2,s3,s4,s5,s6,s7,s8) -# -# [sys] = buildssic(Clst,Ulst,Olst,Ilst,s1,s2,s3,s4,s5,s6,s7,s8) -# -# 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 ist 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 which 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);) -# - # Written by Kai Mueller April 1998 if((nargin < 5) || (nargin > 12))
--- a/scripts/control/c2d.m +++ b/scripts/control/c2d.m @@ -16,36 +16,57 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function dsys = c2d (sys, opt, T) +## -*- texinfo -*- +## @deftypefn {Function File } { @var{dsys} =} c2d (@var{sys}@{, @var{opt}, @var{T}@}) +## @deftypefnx {Function File } { @var{dsys} =} c2d (@var{sys}@{, @var{T}@}) +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure (may have both continuous time and discrete time subsystems) +## @item opt +## string argument; conversion option (optional argument; +## may be omitted as shown above) +## @table @code +## @item "ex" +## use the matrix exponential (default) +## @item "bi" +## use the bilinear transformation +## @end table +## @example +## 2(z-1) +## s = ----- +## T(z+1) +## @end example +## FIXME: This option exits with an error if @var{sys} is not purely +## continuous. (The @code{ex} option can handle mixed systems.) +## @item @var{T} +## sampling time; required if sys is purely continuous. +## +## @strong{Note} If the 2nd argument is not a string, @code{c2d} assumes that +## the 2nd argument is @var{T} and performs appropriate argument checks. +## @end table +## +## @strong{Outputs} +## @var{dsys} discrete time equivalent via zero-order hold, +## sample each @var{T} sec. +## +## converts the system data structure describing +## @example +## . +## x = Ac x + Bc u +## @end example +## into a discrete time equivalent model +## @example +## x[n+1] = Ad x[n] + Bd u[n] +## @end example +## via the matrix exponential or bilinear transform +## +## @strong{Note} This function adds the suffix @code{_d} +## to the names of the new discrete states. +## @end deftypefn -# Usage: dsys = c2d (sys[, T]) -# Usage: dsys = c2d (sys[, opt[, T]]) -# inputs: -# sys: system data structure (may be mixed discrete/continiuous time) -# optional arguments: -# opt: conversion option: -# "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 can handle mixed systems.) -# -# T: sampling time; required if sys is purely continuous. -# outputs: -# dsys: discrete time equivalent via zero-order hold, sample each T sec. -# -# converts the system described by: -# . -# x = Ac x + Bc u -# -# into a discrete time equivalent model via the matrix exponential -# -# x[n+1] = Ad x[n] + Bd u[n] -# -# Note: This function adds _d to the names of the new discrete states. - +function dsys = c2d (sys, opt, T) # Written by R.B. Tenison (btenison@eng.auburn.edu) # October 1993 # Updated by John Ingram for system data structure August 1996
--- a/scripts/control/ctrb.m +++ b/scripts/control/ctrb.m @@ -16,22 +16,23 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {@var{Qs} =} ctrb(@var{sys} @{, @var{b}@}) +## @deftypefnx {Function File } {@var{Qs} =} ctrb(@var{A}, @var{B}) +## Build controllability matrix +## @example +## 2 n-1 +## Qs = [ B AB A B ... A B ] +## @end example +## +## of a system data structure or the pair (@var{A}, @var{B}). +## +## @strong{Note} @code{ctrb} forms the controllability matrix. +## The numerical properties of @code{is_controllable} +## are much better for controllability tests. +## @end deftypefn + function Qs = ctrb(sys, b) - # ------------------------------------------------------ - # Qs = ctrb(sys [, 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. - # See also: obsv, is_observable, is_controllable - # ------------------------------------------------------ - # Written by Kai P. Mueller November 4, 1997 # based on is_controllable.m of Scottedward Hodel # modified by
--- a/scripts/control/d2c.m +++ b/scripts/control/d2c.m @@ -15,41 +15,48 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {@var{csys} =} d2c (@var{sys}@{,@var{tol}@}) +## @deftypefnx {Function File } {@var{csys} =} d2c (@var{sys}, @var{opt}) +## Convert discrete (sub)system to a purely continuous system. Sampling +## time used is @code{sysgettsam(@var{sys})} +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure with discrete components +## @item tol +## Scalar value. +## tolerance for convergence of default @code{"log"} option (see below) +## @item opt +## conversion option. Choose from: +## @table @code +## @item "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 +## @var{A}, @var{B}, to get a better fit to the original data. +## +## If called as @code{d2c}(@var{sys},@var{tol}), @var{tol=}positive scalar, +## the @code{"log"} option is used. The default value for @var{tol} is +## @code{1e-8}. +## @item "bi" +## Conversion is performed via bilinear transform +## @math{z = (1 + s T / 2)/(1 - s T / 2)} where @var{T} is the +## system sampling time (see @code{sysgettsam}). +## +## FIXME: bilinear option exits with an error if @var{sys} is not purely discrete +## +## @end table +## @end table +## @strong{Outputs} @var{csys} continuous time system (same dimensions and +## signal names as in @var{sys}). +## @end deftypefn +## + function csys = d2c(sys,opt) -# csys = d2c(sys[,tol]) -# csys = d2c(sys,opt) -# -# inputs: -# sys: system data structure with discrete components -# tol: 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 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 -# 1 + s T/2 -# z = --------- -# 1 - s T/2 -# where T is the system sampling time (see syschtsam). -# -# FIXME: exits with an error if sys is not purely discrete -# -# D2C converts the real-coefficient discrete time state space system -# -# x(k+1) = A x(k) + B u(k) -# -# to a continuous time state space system -# . -# x = A1 x + B1 u -# -# The sample time used is that of the system. (see syschtsam). - # Written by R. Bruce Tenison August 23, 1994 # Updated by John Ingram for system data structure August 1996 # SYS_INTERNAL accesses members of system data structure
--- a/scripts/control/damp.m +++ b/scripts/control/damp.m @@ -16,17 +16,19 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {} damp(@var{p}@{, @var{tsam}@}) +## Displays eigenvalues, natural frequencies and damping ratios +## of the eigenvalues of a matrix @var{p} or the @var{A}-matrix of a +## system @var{p}, respectively. +## If @var{p} is a system, @var{tsam} must not be specified. +## If @var{p} is a matrix and @var{tsam} is specified, eigenvalues +## of @var{p} are assumed to be in @var{z}-domain. +## +## See also: @code{eig} +## @end deftypefn + function damp(p, tsam) -# Usage: 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 - # Written by Kai P. Mueller September 29, 1997. # Update
--- a/scripts/control/dare.m +++ b/scripts/control/dare.m @@ -17,31 +17,58 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Usage: x = dare (a, b, c, r {,opt}) -## -## Solves discrete-time algebraic riccati equation -## -## a' x a - x + a' x b (r + b' x b)^{-1} b' x a + c = 0 -## -## for -## -## a: nxn -## b: nxm -## c: nxn, symmetric positive semidefinite -## r: mxm, invertible -## -## If c is not square, then the function attempts to use c'*c instead. -## -## Solution 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. -## -## opt is an option passed to the eigenvalue balancing routine default -## is "B". -## +## -*- texinfo -*- +## @deftypefn {Function File} {} dare (@var{a}, @var{b}, @var{c}, @var{r}, @var{opt}) +## +## Return the solution, @var{x} of the discrete-time algebraic Riccati +## equation +## @iftex +## @tex +## $$ +## A^TXA - X + A^TXB (R + B^TXB)^{-1} B^TXA + C = 0 +## $$ +## @end tex +## @end iftex +## @ifinfo +## @example +## a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0 +## @end example +## @end ifinfo +## @noindent +## +## @strong{Inputs} +## @table @var +## @item a +## @var{n} by @var{n}. +## +## @item b +## @var{n} by @var{m}. +## +## @item c +## @var{n} by @var{n}, symmetric positive semidefinite, or @var{p} by @var{n}. +## In the latter case @math{c:=c'*c} is used. +## +## @item r +## @var{m} by @var{m}, symmetric positive definite (invertible). +## +## @item opt +## (optional argument; default = @code{"B"}): +## String option passed to @code{balance} prior to ordered @var{QZ} decomposition. +## @end table +## +## @strong{Outputs} +## @var{x} solution of DARE. +## +## @strong{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. +## +## @end deftypefn + ## See also: balance, are ## Author: A. S. Hodel <scotte@eng.auburn.edu>
--- a/scripts/control/dcgain.m +++ b/scripts/control/dcgain.m @@ -16,15 +16,15 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {@var{gm} =} dcgain(@var{sys}@{, tol@}) +## Returns dc-gain matrix. If dc-gain is infinite +## an empty matrix is returned. +## The argument @var{tol} is an optional tolerance for the condition +## number of @var{A}-Matrix in @var{sys} (default @var{tol} = 1.0e-10) +## @end deftypefn + function gm = dcgain(sys, tol) -# Usage: gm = dcgain(sys[, tol]) -# Returns dc-gain matrix. If dc-gain is infinity -# 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) -# Prints a warning message of the system is unstable. -# - # Written by Kai P Mueller (mueller@ifr.ing.tu-bs.de) October 1, 1997 if((nargin < 1) || (nargin > 2) || (nargout > 1))
--- a/scripts/control/dgkfdemo.m +++ b/scripts/control/dgkfdemo.m @@ -15,9 +15,13 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +##@deftypefn {Function File } { } dgkfdemo ( ) +## Octave Controls toolbox demo: H2/Hinfinity options demos +##@end deftypefn function dgkfdemo() -# Octave Controls toolbox demo: H2/Hinfinity options demos # Written by A. S. Hodel June 1995 save_val = page_screen_output;
--- a/scripts/control/dgram.m +++ b/scripts/control/dgram.m @@ -16,14 +16,30 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{m} =} dgram ( @var{a}, @var{b}) +## Return controllability grammian of discrete time system +## @example +## x(k+1) = a x(k) + b u(k) +## @end example +## +## @strong{Inputs} +## @table @var +## @item a +## @var{n} by @var{n} matrix +## @item b +## @var{n} by @var{m} matrix +## @end table +## +## @strong{Outputs} +## @var{m} (@var{n} by @var{n}) satisfies +## @example +## a m a' - m + b*b' = 0 +## @end example +## +## @end deftypefn + function m = dgram(a,b) - # m = dgram(a,b) - # Return controllability grammian of discrete time system - # - # x(k+1) = a x(k) + b u(k) - # - # a m a' - m + b*b' = 0 - # Written by A. S. Hodel July 1995 # let dlyap do the error checking...
--- a/scripts/control/dlqe.m +++ b/scripts/control/dlqe.m @@ -16,31 +16,86 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [l, m, p, e] = dlqe (a, g, c, sigw, sigv, s) +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{l}, @var{m}, @var{p}, @var{e}] =} dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) +## Construct the linear quadratic estimator (Kalman filter) for the +## discrete time system +## @iftex +## @tex +## $$ +## x_{k+1} = A x_k + B u_k + G w_k +## $$ +## $$ +## y_k = C x_k + D u_k + w_k +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## x[k+1] = A x[k] + B u[k] + G w[k] +## y[k] = C x[k] + D u[k] + w[k] +## @end example +## +## @end ifinfo +## where @var{w}, @var{v} are zero-mean gaussian noise processes with +## respective intensities @code{@var{sigw} = cov (@var{w}, @var{w})} and +## @code{@var{sigv} = cov (@var{v}, @var{v})}. +## +## If specified, @var{z} is @code{cov (@var{w}, @var{v})}. Otherwise +## @code{cov (@var{w}, @var{v}) = 0}. +## +## The observer structure is +## @iftex +## @tex +## $$ +## z_{k+1} = A z_k + B u_k + k (y_k - C z_k - D u_k) +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## z[k+1] = A z[k] + B u[k] + k (y[k] - C z[k] - D u[k]) +## @end example +## @end ifinfo +## +## @noindent +## The following values are returned: +## +## @table @var +## @item l +## The observer gain, +## @iftex +## @tex +## $(A - ALC)$. +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{a}@var{l}@var{c}). +## @end ifinfo +## is stable. +## +## @item m +## The Riccati equation solution. +## +## @item p +## The estimate error covariance after the measurement update. +## +## @item e +## The closed loop poles of +## @iftex +## @tex +## $(A - ALC)$. +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{a}@var{l}@var{c}). +## @end ifinfo +## @end table +## @end deftypefn -# Usage: [l, m, p, e] = dlqe (A, G, C, SigW, SigV {,S}) -# -# Linear quadratic estimator (Kalman filter) design for the -# discrete time system -# -# x[k+1] = A x[k] + B u[k] + G w[k] -# y[k] = C x[k] + D u[k] + w[k] -# -# where w, v are zero-mean gaussian noise processes with respective -# intensities SigW = cov (w, w) and SigV = cov (v, v). -# -# S (if specified) is cov(w,v); otherwise cov(w,v) = 0. -# -# Observer structure is -# z[k+1] = A z[k] + B u[k] + k(y[k] - C z[k] - D u[k]). -# -# Returns: -# -# l = observer gain, (A - L C) is stable -# m = Ricatti equation solution -# p = the estimate error covariance after the measurement update -# e = closed loop poles of (A - L C) - +function [l, m, p, e] = dlqe (a, g, c, sigw, sigv, s) # Written by A. S. Hodel (scotte@eng.auburn.edu) August, 1993. # Modified for discrete time by R. Bruce Tenison (btenison@eng.auburn.edu) # October, 1993
--- a/scripts/control/dlqr.m +++ b/scripts/control/dlqr.m @@ -16,33 +16,95 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [k, p, e] = dlqr (a, b, q, r, s) +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +## Construct the linear quadratic regulator for the discrete time system +## @iftex +## @tex +## $$ +## x_{k+1} = A x_k + B u_k +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## x[k+1] = A x[k] + B u[k] +## @end example +## +## @end ifinfo +## to minimize the cost functional +## @iftex +## @tex +## $$ +## J = \sum x^T Q x + u^T R u +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## J = Sum (x' Q x + u' R u) +## @end example +## @end ifinfo +## +## @noindent +## @var{z} omitted or +## @iftex +## @tex +## $$ +## J = \sum x^T Q x + u^T R u + 2 x^T Z u +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## J = Sum (x' Q x + u' R u + 2 x' Z u) +## @end example +## +## @end ifinfo +## @var{z} included. +## +## The following values are returned: +## +## @table @var +## @item k +## The state feedback gain, +## @iftex +## @tex +## $(A - B K)$ +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{b}@var{k}) +## @end ifinfo +## is stable. +## +## @item p +## The solution of algebraic Riccati equation. +## +## @item e +## The closed loop poles of +## @iftex +## @tex +## $(A - B K)$. +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{b}@var{k}). +## @end ifinfo +## @end table +## @strong{References} +## @enumerate +## @item Anderson and Moore, Optimal Control: Linear Quadratic Methods, +## Prentice-Hall, 1990, pp. 56-58 +## @item Kuo, Digital Control Systems, Harcourt Brace Jovanovich, 1992, +## section 11-5-2. +## @end enumerate +## @end deftypefn -# Usage: [k, p, e] = dlqr (A, B, Q, R {,S}) -# -# Linear quadratic regulator design for the discrete time system -# -# x[k+1] = A x[k] + B u[k] -# -# to minimize the cost functional -# -# J = Sum { x' Q x + u' R u } S omitted -# -# or -# -# J = Sum { x' Q x + u' R u +2 x' S u} S included -# -# Returns: -# -# k = state feedback gain, (A - B K) is stable -# p = solution of algebraic Riccati equation -# e = closed loop poles of (A - B K) -# -# References: -# Anderson and Moore, Optimal Control: Linear Quadratic Methods, -# Prentice-Hall, 1990, pp. 56-58 -# Kuo, Digital Control Systems, Harcourt Brace Jovanovich, 1992, -# section 11-5-2. +function [k, p, e] = dlqr (a, b, q, r, s) # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. # Converted to discrete time by R. B. Tenison # (btenison@eng.auburn.edu) October 1993
--- a/scripts/control/dlyap.m +++ b/scripts/control/dlyap.m @@ -16,23 +16,51 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File} {@var{x} = } dlyap (@var{a}, @var{b}) +## Solve the discrete-time Lyapunov equation +## +## @strong{Inputs} +## @table @var +## @item a +## @var{n} by @var{n} matrix +## @item b +## Matrix: @var{n} by @var{n}, @var{n} by @var{m}, or @var{p} by @var{n}. +## @end table +## +## @strong{Outputs} +## @var{x}: matrix satisfying appropriate discrete time Lyapunov equation. +## Options: +## @itemize @bullet +## @item @var{b} is square: solve @code{a x a' - x + b = 0} +## @item @var{b} is not square: @var{x} satisfies either +## @example +## a x a' - x + b b' = 0 +## @end example +## @noindent +## or +## @example +## a' x a - x + b' b = 0, +## @end example +## @noindent +## whichever is appropriate. +## @end itemize +## +## @strong{Method} +## Uses Schur decomposition method as in Kitagawa, +## @cite{An Algorithm for Solving the Matrix Equation @var{X} = +## @var{F}@var{X}@var{F}' + @var{S}}, +## International Journal of Control, Volume 25, Number 5, pages 745--753 +## (1977). +## +## Column-by-column solution method as suggested in +## Hammarling, @cite{Numerical Solution of the Stable, Non-Negative +## Definite Lyapunov Equation}, IMA Journal of Numerical Analysis, Volume +## 2, pages 303--323 (1982). +## +## @end deftypefn + function x = dlyap (a, b) - -# Usage: x = dlyap (a, b) -# -# Solve a x a' - x + b = 0 (discrete Lyapunov equation) for square -# matrices a and b. If b is not square, then the function attempts -# to solve either -# -# a x a' - x + b b' = 0 -# -# or -# -# a' x a - x + b' b = 0 -# -# whichever is appropriate. Uses Schur decomposition as in Kitagawa -# (1977). - # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. if ((n = is_square (a)) == 0)
--- a/scripts/control/dmr2d.m +++ b/scripts/control/dmr2d.m @@ -16,47 +16,61 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [dsys,fidx] = dmr2d (sys, idx, sprefix, Ts2,cuflg) +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{dsys}, @var{fidx}] =} dmr2d (@var{sys}, @var{idx}, @var{sprefix}, @var{Ts2} @{,@var{cuflg}@}) +## convert a multirate digital system to a single rate digital system +## states specified by @var{idx}, @var{sprefix} are sampled at @var{Ts2}, all +## others are assumed sampled at @var{Ts1} = @code{sysgettsam(@var{sys})}. +## +## @strong{Inputs} +## @table @var +## @item sys +## discrete time system; +## @code{dmr2d} exits with an error if @var{sys} is not discrete +## @item idx +## list of states with sampling time @code{sysgettsam(@var{sys})} (may be empty) +## @item sprefix +## list of string prefixes of states with sampling time @code{sysgettsam(@var{sys})} +## (may be empty) +## @item Ts2 +## sampling time of states not specified by @var{idx}, @var{sprefix} +## must be an integer multiple of @code{sysgettsam(@var{sys})} +## @item cuflg +## "constant u flag" if @var{cuflg} is nonzero then the system inputs are +## assumed to be constant over the revised sampling interval @var{Ts2}. +## Otherwise, since the inputs can change during the interval +## @var{t} in @math{[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 +## @var{cuflg} = 1. +## @end table +## +## @strong{Outputs} +## @table @var +## @item dsys +## equivalent discrete time system with sampling time @var{Ts2}. +## +## The sampling time of sys is updated to @var{Ts2}. +## +## if @var{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 @var{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 +## @var{Ts2} = (n+1)*Ts1) +## +## @item fidx +## indices of "formerly fast" states specified by @var{idx} and @var{sprefix}; +## these states are updated to the new (slower) sampling interval @var{Ts2}. +## @end table +## +## @strong{WARNING} Not thoroughly tested yet; especially when @var{cuflg} == 0. +## +## @end deftypefn -# Usage: [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 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 sys.tsam (may be empty) -# sprefix: list of string prefixes of states with sampling time -# sys.tsam (may be empty) -# Ts2: sampling time of states not specified by idx, sprefix -# must be an integer multiple of sys.tsam -# 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 -# -# -# WARNING: Not thoroughly tested yet; especially when cuflg == 0. - +function [dsys,fidx] = dmr2d (sys, idx, sprefix, Ts2,cuflg) # Adapted from c2d by a.s.hodel@eng.auburn.edu save_val = implicit_str_to_num_ok; # save for later
--- a/scripts/control/fir2sys.m +++ b/scripts/control/fir2sys.m @@ -15,6 +15,57 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} fir2sys ( @var{num}@{, @var{tsam}, @var{inname}, @var{outname} @} ) +## construct a system data structure from FIR description +## +## @strong{Inputs:} +## @table @var +## @item num +## vector of coefficients @math{[c_0 c_1 ... c_n]} +## of the SISO FIR transfer function +## @ifinfo +## +## C(z) = c0 + c1*z^@{-1@} + c2*z^@{-2@} + ... + znz^@{-n@} +## +## @end ifinfo +## @iftex +## @tex +## $$C(z) = c0 + c1*z^{-1} + c2*z^{-2} + ... + znz^{-n}$$ +## @end tex +## @end iftex +## +## @item tsam +## sampling time (default: 1) +## +## @item inname +## name of input signal; may be a string or a list with a single entry. +## +## @item outname +## name of output signal; may be a string or a list with a single entry. +## @end table +## +## @strong{Outputs} +## @var{sys} (system data structure) +## +## @strong{Example} +## @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 +## @end example +## @end deftypefn function sys = fir2sys (num,tsam,inname,outname) #
--- a/scripts/control/frdemo.m +++ b/scripts/control/frdemo.m @@ -15,9 +15,13 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { } frdemo ( ) +## Octave Controls toolbox demo: Frequency Response demo +## @end deftypefn + function frdemo() -# Octave Controls toolbox demo: Frequency Response demo # Written by David Clem August 15, 1994 # a s hodel: updated to match new order of ss2zp outputs
--- a/scripts/control/freqchkw.m +++ b/scripts/control/freqchkw.m @@ -16,10 +16,13 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retval} =} freqchkw ( @var{w} ) +## Used by @code{freqresp} to check that input frequency vector @var{w} is legal. +## Returns boolean value. +## @end deftypefn + function USEW = freqchkw(w) - # function USEW = freqchkw(w) - # used by freqresp to check that input frequency vector is legal - # A S Hodel July 1996 if(isempty(w))
--- a/scripts/control/freqresp.m +++ b/scripts/control/freqresp.m @@ -16,17 +16,30 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{out} =} freqresp (@var{sys},@var{USEW}@{,@var{w}@}); +## Frequency response function - used internally by @code{bode}, @code{nyquist}. +## minimal argument checking; "do not attempt to do this at home" +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## @item USEW +## returned by @code{freqchkw} +## @item optional +## must be present if @var{USEW} is true (nonzero) +## @end table +## @strong{Outputs} +## @table @var +## @item @var{out} +## vector of finite @math{G(j*w)} entries (or @math{||G(j*w)||} for MIMO) +## @item w +## vector of corresponding frequencies +## @end table +## @end deftypefn + function [ff,w] = freqresp(sys,USEW,w); - # function [ff,w] = freqresp(sys,USEW{,w}); - # Frequency response function - used internally by bode, nyquist. - # minimal argument checking; "do not attempt to do this at home" - # USEW returned by freqchkw - # w: optional, must be present if USEW is given - # - # returns: ff = vector of finite G(j*w) entries (or || G(j*w) || for MIMO) - # w = vector of frequencies used - # ff and w are both returned as row vectors - # Written by: R. Bruce Tenison July 11, 1994 # SYS_INTERNAL accesses members of system data structure
--- a/scripts/control/gram.m +++ b/scripts/control/gram.m @@ -16,14 +16,15 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{m} =} gram (@var{a}, @var{b}) +## Return controllability grammian @var{m} of the continuous time system +## @math{ dx/dt = a x + b u}. +## +## @var{m} satisfies @math{ a m + m a' + b b' = 0 }. +## @end deftypefn + function m = gram(a,b) - # m = gram(a,b) - # Return controllability grammian of continuous time system - # - # dx/dt = a x + b u - # - # a m + a' + b*b' = 0 - # Written by A. S. Hodel # let lyap do the error checking...
--- a/scripts/control/h2norm.m +++ b/scripts/control/h2norm.m @@ -15,19 +15,18 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {@var{retval} =} h2norm(@var{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 +## @end deftypefn + + function h2gain = h2norm(sys) - # Usage: h2gain = h2norm(sys) - # - # Computes the H2 norm system data structure (continuous time only) - # sys = system data structure [see ss2sys()] - # returns h2gain = Inf if system is unstable - # - # Reference: - # Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard - # H2 and Hinf Control Problems", IEEE TAC August 1989 - # - # A. S. Hodel Aug 1995 # updated for system data structure by John Ingram November 1996
--- a/scripts/control/h2syn.m +++ b/scripts/control/h2syn.m @@ -15,32 +15,50 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[K}, @var{gain}, @var{Kc}, @var{Kf}, @var{Pc}, @var{Pf}] = h2syn(@var{Asys}, @var{nu}, @var{ny}, @var{tol}) +## Design H2 optimal controller per procedure in +## Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard +## H2 and Hinf Control Problems", IEEE TAC August 1989 +## +## Discrete time control per Zhou, Doyle, and Glover, ROBUST AND OPTIMAL +## CONTROL, Prentice-Hall, 1996 +## +## @strong{Inputs} input system is passed as either +## @table @var +## @item Asys +## system data structure (see ss2sys, sys2ss) +## @itemize @bullet +## @item controller is implemented for continuous time systems +## @item controller is NOT implemented for discrete time systems +## @end itemize +## @item nu +## number of controlled inputs +## @item ny +## number of measured outputs +## @item tol +## threshhold for 0. Default: 200*eps +## @end table +## +## @strong{Outputs} +## @table @var +## @item K +## system controller +## @item gain +## optimal closed loop gain +## @item Kc +## full information control (packed) +## @item Kf +## state estimator (packed) +## @item Pc +## ARE solution matrix for regulator subproblem +## @item Pf +## ARE solution matrix for filter subproblem +## @end table +## @end deftypefn function [K,gain, Kc, Kf, Pc, Pf] = h2syn(Asys,nu,ny,tol) - # [K,gain, Kc, Kf, Pc, Pf] = h2syn(Asys,nu,ny,tol) - # - # Design H2 optimal controller per procedure in - # Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard - # H2 and Hinf Control Problems", IEEE TAC August 1989 - # - # Discrete time control per Zhou, Doyle, and Glover, ROBUST AND OPTIMAL - # CONTROL, Prentice-Hall, 1996 - # - # inputs: - # Asys: system data structure. - # nu: number of controlled inputs - # ny: number of measured outputs - # tol: threshhold for 0. Default: 200*eps - # outputs: - # K: system controller (system data structure) - # gain: optimal closed loop gain (see Kc, Kf warning below) - # Kc: full information control (system data structure) - # Kf: state estimator (system data structure) - # WARNING: incorporation of the is_dgkf nonsingular transformations - # Ru and Ry into Kc and Kf has not been tested. - # Pc: ARE solution matrix for regulator subproblem - # Pf: ARE solution matrix for filter subproblem - # Updated for System structure December 1996 by John Ingram if ((nargin < 3) | (nargin > 4))
--- a/scripts/control/hinf_ctr.m +++ b/scripts/control/hinf_ctr.m @@ -15,21 +15,27 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {@var{K} =} hinf_ctr(@var{dgs}, @var{F}, @var{H}, @var{Z}, @var{g}) +## Called by @code{hinfsyn} to compute the H_inf optimal controller. +## +## @strong{Inputs} +## @table @var +## @item dgs +## data structure returned by @code{is_dgkf} +## @item F, H +## feedback and filter gain (not partitioned) +## @item g +## final gamma value +## @end table +## @strong{Outputs} +## controller K (system data structure) +## +## Do not attempt to use this at home; no argument checking performed. +## @end deftypefn + function K = hinf_ctr(dgs,F,H,Z,g) - # K = hinf_ctr(dgs,F,H,Z,g) - # - # Called by hinfsyn to compute the H_inf optimal controller. - # - # inputs: - # dgs: data structure returned by is_dgkf - # F, H: feedback and filter gain (not partitioned) - # g: final gamma value - # outputs: - # controller K (system data structure) - # - # Do not attempt to use this at home; no argument checking performed. - # A. S. Hodel August 1995 # Revised by Kai P Mueller April 1998 to solve the general H_infinity # problem using unitary transformations Q (on w and z)
--- a/scripts/control/hinfdemo.m +++ b/scripts/control/hinfdemo.m @@ -16,105 +16,114 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -# hinfdemo H_infinity design demos for continuous SISO and MIMO -# systems and a discrete system. -# The SISO system is difficult to control because -# it is non minimum phase and unstable. The second -# design example controls the "jet707" plant, the -# 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). -# inputs: (1) thrust and (2) elevator angle -# outputs: (1) airspeed and (2) pitch angle. -# The discrete system is a stable and second order. -# -# This is a script file for Octave. -# -# SISO plant: -# -# s - 2 -# G(s) = -------------- -# (s + 2)(s - 1) -# -# +----+ -# -------------------->| W1 |---> v1 -# z | +----+ -# ----|-------------+ || T || => min. -# | | vz infty -# | +---+ v y +----+ -# u *--->| G |--->O--*-->| W2 |---> v2 -# | +---+ | +----+ -# | | -# | +---+ | -# -----| K |<------- -# +---+ -# -# W1 und W2 are the robustness and performance weighting -# functions -# -# MIMO plant: -# The optimal controller minimizes the H_infinity norm of the -# augmented plant P (mixed-sensitivity problem): -# -# w -# 1 -----------+ -# | +----+ -# +---------------------->| W1 |----> z1 -# w | | +----+ -# 2 ------------------------+ -# | | | -# | v +----+ v +----+ -# +--*-->o-->| G |-->o--*-->| W2 |---> z2 -# | +----+ | +----+ -# | | -# ^ v -# u (from y (to K) -# controller -# K) -# -# -# + + + + -# | z | | w | -# | 1 | | 1 | -# | z | = [ P ] * | w | -# | 2 | | 2 | -# | y | | u | -# + + + + -# -# DISCRETE SYSTEM: -# This is not a true discrete design. The design is carried out -# in continuous time while the effect of sampling is described by -# a bilinear transformation of the sampled system. -# This method works quite well if the sampling period is "small" -# compared to the plant time constants. -# -# The continuous plant: -# 1 -# G (s) = -------------- -# k (s + 2)(s + 1) -# -# is discretised with a ZOH (Sampling period = Ts = 1 second): -# -# 0.199788z + 0.073498 -# G(s) = -------------------------- -# (z - 0.36788)(z - 0.13534) -# -# +----+ -# -------------------->| W1 |---> v1 -# z | +----+ -# ----|-------------+ || T || => min. -# | | vz infty -# | +---+ v +----+ -# *--->| G |--->O--*-->| W2 |---> v2 -# | +---+ | +----+ -# | | -# | +---+ | -# -----| K |<------- -# +---+ -# -# W1 and W2 are the robustness and performancs weighting -# functions - +## -*- texinfo -*- +## hinfdemo H_infinity design demos for continuous SISO and MIMO +## systems and a discrete system. +## The SISO system is difficult to control because +## it is non minimum phase and unstable. The second +## design example controls the "jet707" plant, the +## 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). +## inputs: (1) thrust and (2) elevator angle +## outputs: (1) airspeed and (2) pitch angle. +## The discrete system is a stable and second order. +## +## +## @table +## @item SISO plant +## @example +## @group +## s - 2 +## G(s) = -------------- +## (s + 2)(s - 1) +## +## +----+ +## -------------------->| W1 |---> v1 +## z | +----+ +## ----|-------------+ || T || => min. +## | | vz infty +## | +---+ v y +----+ +## u *--->| G |--->O--*-->| W2 |---> v2 +## | +---+ | +----+ +## | | +## | +---+ | +## -----| K |<------- +## +---+ +## @end group +## @end example +## W1 und W2 are the robustness and performance weighting +## functions +## +## @item MIMO plant +## The optimal controller minimizes the H_infinity norm of the +## augmented plant P (mixed-sensitivity problem): +## @example +## @group +## w +## 1 -----------+ +## | +----+ +## +---------------------->| W1 |----> z1 +## w | | +----+ +## 2 ------------------------+ +## | | | +## | v +----+ v +----+ +## +--*-->o-->| G |-->o--*-->| W2 |---> z2 +## | +----+ | +----+ +## | | +## ^ v +## u (from y (to K) +## controller +## K) +## +## +## + + + + +## | z | | w | +## | 1 | | 1 | +## | z | = [ P ] * | w | +## | 2 | | 2 | +## | y | | u | +## + + + + +## @end group +## @end example +## +## @item DISCRETE SYSTEM +## This is not a true discrete design. The design is carried out +## in continuous time while the effect of sampling is described by +## a bilinear transformation of the sampled system. +## This method works quite well if the sampling period is "small" +## compared to the plant time constants. +## +## @item The continuous plant +## @group +## 1 +## G (s) = -------------- +## k (s + 2)(s + 1) +## +## @end group +## is discretised with a ZOH (Sampling period = Ts = 1 second): +## @group +## +## 0.199788z + 0.073498 +## G(s) = -------------------------- +## (z - 0.36788)(z - 0.13534) +## +## +----+ +## -------------------->| W1 |---> v1 +## z | +----+ +## ----|-------------+ || T || => min. +## | | vz infty +## | +---+ v +----+ +## *--->| G |--->O--*-->| W2 |---> v2 +## | +---+ | +----+ +## | | +## | +---+ | +## -----| K |<------- +## +---+ +## @end group +## W1 and W2 are the robustness and performancs weighting +## functions +## @end deftypefn # Kai P. Mueller 30-APR-1998 <mueller@ifr.ing.tu-bs.de
--- a/scripts/control/hinfnorm.m +++ b/scripts/control/hinfnorm.m @@ -15,30 +15,55 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{g}, @var{gmin}, @var{gmax}] =} hinfnorm(@var{sys}@{, @var{tol}, @var{gmin}, @var{gmax}, @var{ptol}@}) +## Computes the H infinity norm of a system data structure. +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## @item tol +## H infinity norm search tolerance (default: 0.001) +## @item gmin +## minimum value for norm search (default: 1e-9) +## @item gmax +## maximum value for norm search (default: 1e+9) +## @item ptol +## pole tolerance: +## @itemize @bullet +## @item if sys is continuous, poles with +## |real(pole)| < ptol*||H|| (H is appropriate Hamiltonian) +## are considered to be on the imaginary axis. +## +## @item if sys is discrete, poles with +## |abs(pole)-1| < ptol*||[s1,s2]|| (appropriate symplectic pencil) +## are considered to be on the unit circle +## +## @item Default: 1e-9 +## @end itemize +## @end table +## +## @strong{Outputs} +## @table @var +## @item g +## Computed gain, within @var{tol} of actual gain. @var{g} is returned as Inf +## if the system is unstable. +## @item gmin, gmax +## Actual system gain lies in the interval [@var{gmin}, @var{gmax}] +## @end table +## +## 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 $ +## @end deftypefn function [g, gmin, gmax] = hinfnorm(sys,tol,gmin,gmax,ptol) - # Usage: [g gmin gmax] = hinfnorm(sys[,tol,gmin,gmax,ptol]) - # - # Computes the H infinity norm of a system data structure - # 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 - # - # 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 if((nargin == 0) || (nargin > 4)) usage("[g gmin gmax] = hinfnorm(sys[,tol,gmin,gmax,ptol])");
--- a/scripts/control/hinfsyn.m +++ b/scripts/control/hinfsyn.m @@ -15,45 +15,67 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{K}, @var{g}, @var{GW}, @var{Xinf}, @var{Yinf}] =} hinfsyn(@var{Asys}, @var{nu}, @var{ny}, @var{gmin}, @var{gmax}, @var{gtol}@{, @var{ptol}, @var{tol}@}) +## +## @strong{Inputs} input system is passed as either +## @table @var +## @item Asys +## system data structure (see ss2sys, sys2ss) +## @itemize @bullet +## @item controller is implemented for continuous time systems +## @item controller is NOT implemented for discrete time systems (see +## bilinear transforms in @code{c2d}, @code{d2c}) +## @end itemize +## @item nu +## number of controlled inputs +## @item ny +## number of measured outputs +## @item gmin +## initial lower bound on H-infinity optimal gain +## @item gmax +## initial upper bound on H-infinity optimal gain +## @item gtol +## gain threshhold. Routine quits when gmax/gmin < 1+tol +## @item ptol +## poles with abs(real(pole)) < ptol*||H|| (H is appropriate +## Hamiltonian) are considered to be on the imaginary axis. +## Default: 1e-9 +## @item tol +## threshhold for 0. Default: 200*eps +## +## @var{gmax}, @var{min}, @var{tol}, and @var{tol} must all be postive scalars. +## @end table +## @strong{Outputs} +## @table @var +## @item K +## system controller +## @item g +## designed gain value +## @item GW +## closed loop system +## @item Xinf +## ARE solution matrix for regulator subproblem +## @item Yinf +## ARE solution matrix for filter subproblem +## @end table +## +## @enumerate +## @item Doyle, Glover, Khargonekar, Francis, "State Space Solutions +## to Standard H2 and Hinf Control Problems," IEEE TAC August 1989 +## +## @item Maciejowksi, J.M., "Multivariable feedback design," +## Addison-Wesley, 1989, ISBN 0-201-18243-2 +## +## @item Keith Glover and John C. Doyle, "State-space formulae for all +## stabilizing controllers that satisfy and h-infinity-norm bound +## and relations to risk sensitivity," +## Systems & Control Letters 11, Oct. 1988, pp 167-172. +## @end enumerate +## @end deftypefn function [K,g,GW,Xinf,Yinf] = hinfsyn(Asys,nu,ny,gmin,gmax,gtol,ptol,tol) - # [K,g,GW,Xinf,Yinf] = hinfsyn(Asys,nu,ny,gmin,gmax,gtol[,ptol,tol]) - # - # [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," - # Addison-Wesley, 1989, ISBN 0-201-18243-2 - # - # [3] Keith Glover and John C. Doyle: "State-space formulae for all - # stabilizing controllers that satisfy and h-infinity-norm bound - # and relations to risk sensitivity," - # Systems & Control Letters 11, Oct. 1988, pp 167-172. - # - # inputs: input system is passed as either - # Asys: system data structure (see ss2sys, sys2ss) - # - controller is implemented for continuous time systems - # - controller is NOT implemented for discrete time systems - # nu: number of controlled inputs - # ny: number of measured outputs - # gmin: initial lower bound on H-infinity optimal gain - # gmax: initial upper bound on H-infinity optimal gain - # gtol: gain threshhold. Routine quits when gmax/gmin < 1+tol - # ptol: poles with abs(real(pole)) < ptol*||H|| (H is appropriate - # Hamiltonian) are considered to be on the imaginary axis. - # Default: 1e-9 - # tol: threshhold for 0. Default: 200*eps - # - # gmax, gmin, gtol, and tol must all be postive scalars. - # - # outputs: - # K: system controller - # g: designed gain value - # GW: closed loop system - # Xinf: ARE solution matrix for regulator subproblem - # Yinf: ARE solution matrix for filter subproblem - - # A. S. Hodel August 1995 # Updated for Packed system structures December 1996 by John Ingram #
--- a/scripts/control/hinfsyn_chk.m +++ b/scripts/control/hinfsyn_chk.m @@ -15,25 +15,37 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{retval}, @var{Pc}, @var{Pf}] =} hinfsyn_chk(@var{A}, @var{B1}, @var{B2}, @var{C1}, @var{C2}, @var{D12}, @var{D21}, @var{g}, @var{ptol}) +## Called by @code{hinfsyn} to see if gain @var{g} satisfies conditions in +## Theorem 3 of +## Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard +## H2 and Hinf Control Problems", IEEE TAC August 1989 +## +## @strong{Warning} Do not attempt to use this at home; no argument checking performed. +## +## @strong{Inputs} as returned by @code{is_dgkf}, except for: +## @table @var +## @item g +## candidate gain level +## @item ptol +## as in @code{hinfsyn} +## @end table +## +## @strong{Outputs} +## @table @var +## @item retval +## 1 if g exceeds optimal Hinf closed loop gain, else 0 +## @item Pc +## solution of "regulator" H-inf ARE +## @item Pf +## solution of "filter" H-inf ARE +## @end table +## Do not attempt to use this at home; no argument checking performed. +## @end deftypefn + function [retval,Pc,Pf] = hinfsyn_chk(A,B1,B2,C1,C2,D12,D21,g,ptol) - # [retval,Pc,Pf] = hinfsyn_chk(A,B1,B2,C1,C2,D12,D21,g,ptol) - # - # Called by hinfsyn to see if gain g satisfies conditions in Theorem 3 of - # Doyle, Glover, Khargonekar, Francis, "State Space Solutions to Standard - # H2 and Hinf Control Problems", IEEE TAC August 1989 - # - # inputs: - # g = candidate gain level - # ptol: as in hinfsyn - # remaining parameters as returned by is_dgkf - # outputs: - # retval: = 1 if g exceeds optimal Hinf closed loop gain, else 0 - # Pc: solution of "regulator" H-inf ARE - # Pf: solution of "filter" H-inf ARE - # - # Do not attempt to use this at home; no argument checking performed. - # A. S. Hodel August 1995 Pc = Pf = [];
--- a/scripts/control/impulse.m +++ b/scripts/control/impulse.m @@ -15,23 +15,36 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{y}, @var{t}] =} impulse (@var{sys}@{, @var{inp},@var{tstop}, @var{n}@}) +## Impulse response for a linear system. +## The system can be discrete or multivariable (or both). +## If no output arguments are specified, @code{impulse} +## produces a plot or the impulse response data for system @var{sys}. +## +## @strong{Inputs} +## @table @var +## @item sys +## System data structure. +## @item inp +## Index of input being excited +## @item tstop +## The argument @var{tstop} (scalar value) denotes the time when the +## simulation should end. +## @item n +## the number of data values. +## +## Both parameters @var{tstop} and @var{n} can be omitted and will be +## computed from the eigenvalues of the A-Matrix. +## @end table +## @strong{Outputs} +## @var{y}, @var{t}: impulse response +## @end deftypefn +## See also: step, stepimp + function [y, t] = impulse(sys, inp, tstop, n) -# step: Impulse response for a linear system. -# The system can be discrete or multivariable (or both). -# -# [y, t] = impulse(sys[, inp, tstop, n]) -# Produces a plot or the step response data for system sys. -# -# The argument tstop (scalar value) denotes the time when the -# simulation should end. The Parameter n is the number of data values. -# Both parameters tstop and n can be ommitted and will be -# computed from the eigenvalues of the A-Matrix. -# -# When the step function is invoked with the output parameter y -# a plot is not displayed. -# -# See also: step, stepimp # Written by Kai P. Mueller October 2, 1997 # based on lsim.m of Scottedward Hodel
--- a/scripts/control/is_abcd.m +++ b/scripts/control/is_abcd.m @@ -16,16 +16,16 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retval} =} is_abcd( @var{a}@{, @var{b}, @var{c}, @var{d}@}) +## Returns @var{retval} = 1 if the dimensions of @var{a}, @var{b}, @var{c}, @var{d} +## are compatible, otherwise @var{retval} = 0 with an appropriate diagnostic +## message printed to the screen. The matrices b, c, or d may be omitted. +## @end deftypefn + +## See also: abcddim + function retval = is_abcd(a, b, c, d) - # ------------------------------------------------------ - # retval = is_abcd(a [, b, c, d]) - # Returns retval = 1 if the dimensions of a, b, c, d - # are compatible, otherwise retval = 0. - # The matrices b, c, or d may be omitted. - # ------------------------------------------------------ - # - # see also: abcddim - # Written by Kai P. Mueller November 4, 1997 # based on is_controllable.m of Scottedward Hodel # modified by
--- a/scripts/control/is_controllable.m +++ b/scripts/control/is_controllable.m @@ -16,24 +16,49 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [retval,U] = is_controllable (a, b, tol) -# [retval, U] = is_controllable (a, b {,tol}) -# = is_controllable (sys{, tol}) -# Returns retval=1 if the system sys or the pair (a, b) is controllable -# 0 if not. -# U is an orthogonal basis of the controllable subspace. -# -# 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^ b]). -# -# tol is a roundoff paramter, set to 10*eps if omitted. -# +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{retval}, @var{U}] =} is_controllable (@var{sys}@{, @var{tol}@}) +## @deftypefnx {Function File } {[@var{retval}, @var{U}] =} is_controllable (@var{a}@{, @var{b} ,@var{tol}@}) +## Logical check for system controllability. +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## @item a, b +## @var{n} by @var{n}, @var{n} by @var{m} matrices, respectively +## @item tol +## optional roundoff paramter. default value: @code{10*eps} +## @end table +## +## @strong{Outputs} +## @table @var +## @item retval +## Logical flag; returns true (1) if the system @var{sys} or the +## pair (@var{a},@var{b}) is controllable, whichever was passed as input arguments. +## @item U +## U is an orthogonal basis of the controllable subspace. +## @end table +## +## @strong{Method} +## Controllability is determined by applying Arnoldi iteration with +## complete re-orthogonalization to obtain an orthogonal basis of the +## Krylov subspace +## @example +## span ([b,a*b,...,a^@{n-1@}*b]). +## @end example +## The Arnoldi iteration is executed with @code{krylov} if the system has a single input; otherwise a block Arnoldi iteration is performed with @code{krylovb}. +## +## @strong{See also} +## @code{is_observable}, @code{is_stabilizable}, @code{is_detectable}, +## @code{krylov}, @code{krylovb} +## +## @end deftypefn + # See also: size, rows, columns, length, is_matrix, is_scalar, is_vector # is_observable, is_stabilizable, is_detectable, krylov, krylovb +function [retval,U] = is_controllable (a, b, tol) # Written by A. S. Hodel (scotte@eng.auburn.edu) August, 1993. # Updated by A. S. Hodel (scotte@eng.auburn.edu) Aubust, 1995 to use krylovb # Updated by John Ingram (ingraje@eng.auburn.edu) July, 1996 for packed systems
--- a/scripts/control/is_detectable.m +++ b/scripts/control/is_detectable.m @@ -16,19 +16,24 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [retval,U] = is_detectable (a,c,tol) +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{retval}, @var{U}] =} is_detectable (@var{a}, @var{c}@{, @var{tol}@}) +## @deftypefnx {Function File } { [@var{retval}, @var{U}] =} is_detectable (@var{sys}@{, @var{tol}@}) +## Test for detactability (observability of unstable modes) of (@var{a},@var{c}). +## +## Returns 1 if the system @var{a} or the pair (@var{a},@var{c})is +## detectable, 0 if not. +## +## @strong{See} @code{is_stabilizable} for detailed description of arguments and +## computational method. +## +## Default: tol = 10*norm(a,'fro')*eps +## +## @end deftypefn -# [retval,U] = is_detectable (a,c,tol) -# usage: is_detectable (a , c {,tol}) -# or is_detectable (sys {,tol}) -# -# Default: tol = 10*norm(a,'fro')*eps -# -# Returns 1 if the system, a, is detectable, 1 if the pair (a, c) is -# detectable, or 0 if not. -# -# See also: size, rows, columns, length, is_matrix, is_scalar, is_vector. +## See also: size, rows, columns, length, is_matrix, is_scalar, is_vector. +function [retval,U] = is_detectable (a,c,tol) # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. # Updated by John Ingram (ingraje@eng.auburn.edu) July 1996.
--- a/scripts/control/is_dgkf.m +++ b/scripts/control/is_dgkf.m @@ -15,59 +15,86 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{retval}, @var{dgkf_struct} ] =} is_dgkf (@var{Asys}, @var{nu}, @var{ny}, @var{tol} ) +## Determine whether a continuous time state space system meets +## assumptions of DGKF algorithm. +## Partitions system into: +## @example +## [dx/dt] = [A | Bw Bu ][w] +## [ z ] [Cz | Dzw Dzu ][u] +## [ y ] [Cy | Dyw Dyu ] +## @end example +## or similar discrete-time system. +## If necessary, orthogonal transformations @var{Qw}, @var{Qz} and nonsingular +## transformations @var{Ru}, @var{Ry} are applied to respective vectors +## @var{w}, @var{z}, @var{u}, @var{y} in order to satisfy DGKF assumptions. +## Loop shifting is used if @var{Dyu} block is nonzero. +## +## @strong{Inputs} +## @table @var +## @item Asys +## system data structure +## @item nu +## number of controlled inputs +## @item ny +## number of measured outputs +## @item tol +## threshhold for 0. Default: 200@var{eps} +## @end table +## @strong{Outputs} +## @table @var +## @item retval +## true(1) if system passes check, false(0) otherwise +## @item dgkf_struct +## data structure of @code{is_dgkf} results. Entries: +## @table @var +## @item nw, nz +## dimensions of @var{w}, @var{z} +## @item A +## system @var{A} matrix +## @item Bw +## (@var{n} x @var{nw}) @var{Qw}-transformed disturbance input matrix +## @item Bu +## (@var{n} x @var{nu}) @var{Ru}-transformed controlled input matrix; +## +## @strong{Note} @math{B = [Bw Bu] } +## @item Cz +## (@var{nz} x @var{n}) Qz-transformed error output matrix +## @item Cy +## (@var{ny} x @var{n}) @var{Ry}-transformed measured output matrix +## +## @strong{Note} @math{C = [Cz; Cy] } +## @item Dzu, Dyw +## off-diagonal blocks of transformed @var{D} matrix that enter +## @var{z}, @var{y} from @var{u}, @var{w} respectively +## @item Ru +## controlled input transformation matrix +## @item Ry +## observed output transformation matrix +## @item Dyu_nz +## nonzero if the @var{Dyu} block is nonzero. +## @item Dyu +## untransformed @var{Dyu} block +## @item dflg +## nonzero if the system is discrete-time +## @end table +## @end table +## @code{is_dgkf} exits with an error if the system is mixed discrete/continuous +## +## @strong{References} +## @table @strong +## @item [1] +## Doyle, Glover, Khargonekar, Francis, "State Space Solutions +## to Standard H2 and Hinf Control Problems," IEEE TAC August 1989 +## @item [2] +## Maciejowksi, J.M.: "Multivariable feedback design," +## @end table +## +## @end deftypefn function [retval,dgkf_struct] = is_dgkf(Asys,nu,ny,tol) - # function [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: [z] = [A | Bw Bu ][w] - # [y] [Cz | Dzw Dzu ][u] - # [Cy | Dyw Dyu ] - #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: structured system - # nu: number of controlled inputs - # ny: number of measured outputs - # tol: threshhold for 0. Default: 200*eps - # 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 - # - # [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," - # Addison-Wesley, 1989, ISBN 0-201-18243-2 - # - # [3] Keith Glover and John C. Doyle: "State-space formulae for all - # stabilizing controllers that satisfy and h-infinity-norm bound - # and relations to risk sensitivity," - # Systems & Control Letters 11, Oct. 1988, pp 167-172. - # [4] P. A. Iglesias and K. Glover, "State-space approach to discrete-time - # H-infinity control." Int. J. Control, 1991, V. 54, #5, 1031-1073. - # - # Written by A. S. Hodel # Updated by John Ingram July 1996 to accept structured systems #
--- a/scripts/control/is_digital.m +++ b/scripts/control/is_digital.m @@ -16,21 +16,23 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retval} =} is_digital ( @var{sys}) +## Return nonzero if system is digital; +## inputs: +## sys: system data structure +## eflg: 0 [default] exit with an error if system is mixed (continuous and +## discrete components) +## : 1 print a warning if system is mixed (continuous and discrete) +## : 2 silent operation +## outputs: +## DIGITAL: 0: system is purely continuous +## : 1: system is purely discrete +## : -1: system is mixed continuous and discrete +## Exits with an error of sys is a mixed (continuous and discrete) system +## @end deftypefn + function DIGITAL = is_digital(sys,eflg) -# function DIGITAL = is_digital(sys{,eflg}) -# return nonzero if system is digital -# inputs: -# sys: system data structure -# eflg: 0 [default] exit with an error if system is mixed (continuous and -# discrete components) -# : 1 print a warning if system is mixed (continuous and discrete) -# : 2 silent operation -# outputs: -# DIGITAL: 0: system is purely continuous -# : 1: system is purely discrete -# : -1: system is mixed continuous and discrete -# exits with an error of sys is a mixed (continuous and discrete) system - # a s hodel July 1996 switch(nargin)
--- a/scripts/control/is_observable.m +++ b/scripts/control/is_observable.m @@ -16,18 +16,33 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{retval},@var{U}] =} is_observable (@var{a}, @var{c}@{,@var{tol}@}) +## @deftypefnx {Function File } { [@var{retval},@var{U}] =} is_observable (@var{sys}@{, @var{tol}@}) +## Logical check for system observability. +## +## Default: tol = 10*norm(a,'fro')*eps +## +## Returns 1 if the system @var{sys} or the pair (@var{a},@var{c}) is +## observable, 0 if not. +## +## @strong{See} @code{is_controllable} for detailed description of arguments +## and default values. +## @end deftypefn + +## See also: size, rows, columns, length, is_matrix, is_scalar, is_vector. + function [retval,U] = is_observable (a,c,tol) # [retval,U] = is_observable (a,c,tol) # usage: is_observable (a , c {,tol}) # or is_observable (sys {,tol}) # -# Default: tol = 10*norm(a,'fro')*eps # # Returns 1 if the system, a, is observable, 1 if the pair (a, c) is # observable, or 0 if not. # -# See also: size, rows, columns, length, is_matrix, is_scalar, is_vector. + # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. # Updated by John Ingram (ingraje@eng.auburn.edu) July 1996.
--- a/scripts/control/is_sample.m +++ b/scripts/control/is_sample.m @@ -15,12 +15,14 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retval} =} is_sample (@var{Ts}) +## return true if @var{Ts} is a legal sampling time +## (real,scalar, > 0) +## @end deftypefn function out = is_sample(Ts) -# -# out = is_sample(Ts): return true if Ts is a legal sampling time -# (real,scalar, > 0) - # A. S. Hodel July 1995 out = (is_scalar(Ts) && (Ts == abs(Ts)) && (Ts != 0) );
--- a/scripts/control/is_signal_list.m +++ b/scripts/control/is_signal_list.m @@ -16,11 +16,13 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {@var{flg} =} is_signal_list (@var{mylist}) +## Returns true if mylist is a list of individual strings (legal for input +## to @var{syssetsignals}). +## @end deftypefn + function flg = is_signal_list(mylist) -# function flg = is_signal_list(mylist) -# returns true if mylist is a list of individual strings. -# - flg = is_list(mylist); if(flg) for ii=1:length(mylist)
--- a/scripts/control/is_siso.m +++ b/scripts/control/is_siso.m @@ -15,6 +15,12 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retval} =} is_siso (@var{sys}) +## return nonzero if the system data structure +## @var{sys} is single-input, single-output. +## @end deftypefn function SISO = is_siso(sys) # function SISO = is_siso(sys)
--- a/scripts/control/is_stabilizable.m +++ b/scripts/control/is_stabilizable.m @@ -16,25 +16,32 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [retval,U] = is_stabilizable (a, b, tol) +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{retval}, @var{U}] =} is_stabilizable (@var{sys}@{, @var{tol}@}) +## @deftypefnx {Function File } {[@var{retval}, @var{U}] =} is_stabilizable (@var{a}@{, @var{b} ,@var{tol}@}) +## Logical check for system stabilizability (i.e., all unstable modes are controllable). +## +## +## Test for stabilizability is performed via an ordered Schur decomposition +## that reveals the unstable subspace of the system @var{A} matrix. +## +## Returns @code{retval} = 1 if the system, @code{a}, is stabilizable, if the pair +## (@code{a}, @code{b}) is stabilizable, or 0 if not. +## @code{U} = orthogonal basis of controllable subspace. +## +## Controllable subspace is determined by applying Arnoldi iteration with +## complete re-orthogonalization to obtain an orthogonal basis of the +## Krylov subspace. +## @example +## span ([b,a*b,...,a^ b]). +## @end example +## tol is a roundoff paramter, set to 200*eps if omitted. +## @end deftypefn -# Usage: [retval,U] = is_stabilizable (a {, b, tol}) -# -# Returns retval = 1 if the system, a, is stabilizable, if the pair (a, b) is -# stabilizable, or 0 if not. -# U = orthogonal basis of controllable subspace. -# -# Controllable subspace is determined by applying Arnoldi iteration with -# complete re-orthogonalization to obtain an orthogonal basis of the -# Krylov subspace. -# -# span ([b,a*b,...,a^ b]). -# -# tol is a roundoff paramter, set to 200*eps if omitted. -# -# See also: size, rows, columns, length, is_matrix, is_scalar, is_vector -# is_observable, is_stabilizable, is_detectable +## See also: size, rows, columns, length, is_matrix, is_scalar, is_vector +## is_observable, is_stabilizable, is_detectable +function [retval,U] = is_stabilizable (a, b, tol) # Written by A. S. Hodel (scotte@eng.auburn.edu) August, 1993. # Updated by A. S. Hodel (scotte@eng.auburn.edu) Aubust, 1995 to use krylovb # Updated by John Ingram (ingraje@eng.auburn.edu) July, 1996 to accept systems
--- a/scripts/control/is_stable.m +++ b/scripts/control/is_stable.m @@ -16,20 +16,32 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function retval = is_stable (a, tol, disc) +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retval} =} is_stable (@var{a}@{,@var{tol},@var{dflg}@}) +## @deftypefnx {Function File } { @var{retval} =} is_stable (@var{sys}@{,@var{tol}@}) +## Returns retval = 1 if the matrix @var{a} or the system @var{sys} +## is stable, or 0 if not. +## +## @strong{Inputs} +## @table @var +## @item tol +## is a roundoff paramter, set to 200*@var{eps} if omitted. +## @item dflg +## Digital system flag (not required for system data structure): +## @table @code +## @item @var{dflg} != 0 +## stable if eig(a) in unit circle +## +## @item @var{dflg} == 0 +## stable if eig(a) in open LHP (default) +## @end table +## @end table +## @end deftypefn -# Usage: retval = is_stable (a {,tol,disc}) -# or retval = is_stable (sys{,tol}) -# -# Returns retval = 1 if the matrix a or the system a is stable, or 0 if not. -# -# tol is a roundoff paramter, set to 200*eps if omitted. -# disc != 0: stable if eig(a) in unit circle -# 0: stable if eig(a) in open LHP (default) -# -# See also: size, rows, columns, length, is_matrix, is_scalar, is_vector -# is_observable, is_stabilizable, is_detectable, krylov, krylovb +## See also: size, rows, columns, length, is_matrix, is_scalar, is_vector +## is_observable, is_stabilizable, is_detectable, krylov, krylovb +function retval = is_stable (a, tol, disc) # Written by A. S. Hodel (scotte@eng.auburn.edu) August, 1993. # Updated by John Ingram (ingraje@eng.auburn.edu) July, 1996 for systems # Updated to simpler form by a.s.hodel 1998
--- a/scripts/control/jet707.m +++ b/scripts/control/jet707.m @@ -15,17 +15,22 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{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 +## @end deftypefn + function outsys = jet707() - # function 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 - # Written by Kai P. Mueller September 28, 1997 # Updates
--- a/scripts/control/lqe.m +++ b/scripts/control/lqe.m @@ -16,29 +16,77 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [k, p, e] = lqe (a, g, c, sigw, sigv, zz) +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) +## Construct the linear quadratic estimator (Kalman filter) for the +## continuous time system +## @iftex +## @tex +## $$ +## {dx\over dt} = A x + B u +## $$ +## $$ +## y = C x + D u +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## dx +## -- = a x + b u +## dt +## +## y = c x + d u +## @end example +## +## @end ifinfo +## where @var{w} and @var{v} are zero-mean gaussian noise processes with +## respective intensities +## +## @example +## sigw = cov (w, w) +## sigv = cov (v, v) +## @end example +## +## The optional argument @var{z} is the cross-covariance +## @code{cov (@var{w}, @var{v})}. If it is omitted, +## @code{cov (@var{w}, @var{v}) = 0} is assumed. +## +## Observer structure is @code{dz/dt = A z + B u + k (y - C z - D u)} +## +## The following values are returned: +## +## @table @var +## @item k +## The observer gain, +## @iftex +## @tex +## $(A - K C)$ +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{k}@var{c}) +## @end ifinfo +## is stable. +## +## @item p +## The solution of algebraic Riccati equation. +## +## @item e +## The vector of closed loop poles of +## @iftex +## @tex +## $(A - K C)$. +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{k}@var{c}). +## @end ifinfo +## @end table +## @end deftypefn -# Usage: [k, p, e] = lqe (A, G, C, SigW, SigV {,Z}) -# -# Linear quadratic estimator (Kalman filter) design for the -# continuous time system -# -# dx/dt = A x + B u + G w -# y = C x + D u + v -# -# where w, v are zero-mean gaussian noise processes with respective -# intensities SigW = cov (w, w) and SigV = cov (v, v). -# -# Z (if specified) is cov(w,v); otherwise cov(w,v) = 0. -# -# Observer structure is dz/dt = A z + B u + k( y - C z - D u). -# -# Returns: -# -# k = observer gain, (A - K C) is stable -# p = solution of algebraic Riccati equation -# e = closed loop poles of (A - K C) - +function [k, p, e] = lqe (a, g, c, sigw, sigv, zz) # Written by A. S. Hodel (scotte@eng.auburn.edu) August, 1993. if ( (nargin != 5) && (nargin != 6))
--- a/scripts/control/lqg.m +++ b/scripts/control/lqg.m @@ -16,36 +16,52 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{K}, @var{Q}, @var{P}, @var{Ee}, @var{Er}] =} lqg(@var{sys}, @var{Sigw}, @var{Sigv}, @var{Q}, @var{R}, @var{in_idx}) +## Design a linear-quadratic-gaussian optimal controller for the system +## @example +## dx/dt = A x + B u + G w [w]=N(0,[Sigw 0 ]) +## y = C x + v [v] ( 0 Sigv ]) +## @end example +## or +## @example +## x(k+1) = A x(k) + B u(k) + G w(k) [w]=N(0,[Sigw 0 ]) +## y(k) = C x(k) + v(k) [v] ( 0 Sigv ]) +## @end example +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## @item Sigw, Sigv +## intensities of independent Gaussian noise processes (as above) +## @item Q, R +## state, control weighting respectively. Control ARE is +## @item in_idx +## indices of controlled inputs +## +## default: last dim(R) inputs are assumed to be controlled inputs, all +## others are assumed to be noise inputs. +## @end table +## @strong{Outputs} +## @table @var +## @item K +## system data structure format LQG optimal controller +## (Obtain A,B,C matrices with @code{sys2ss}, @code{sys2tf}, or @code{sys2zp} as appropriate) +## @item P +## Solution of control (state feedback) algebraic Riccati equation +## @item Q +## Solution of estimation algebraic Riccati equation +## @item Ee +## estimator poles +## @item Es +## controller poles +## @end table +## @end deftypefn + +## See also: h2syn, lqe, lqr + function [K,Q1,P1,Ee,Er] = lqg(sys,Sigw,Sigv,Q,R,input_list) -# -# function [K,Q,P,Ee,Er] = lqg(sys,Sigw,Sigv,Q,R,input_list) -# design a linear-quadratic-gaussian optimal controller for the system -# -# dx/dt = A x + B u + G w [w]=N(0,[Sigw 0 ]) -# y = C x + v [v] ( 0 Sigv ]) -# -# or -# -# x(k+1) = A x(k) + B u(k) + G w(k) [w]=N(0,[Sigw 0 ]) -# y(k) = C x(k) + v(k) [v] ( 0 Sigv ]) -# -# inputs: -# sys: system data structure -# Sigw, Sigv: intensities of independent Gaussian noise processes (as above) -# Q, R: state, control weighting respectively. Control ARE is -# input_list: indices of controlled inputs -# default: last dim(R) inputs are assumed to be controlled inputs, all -# others are assumed to be noise inputs. -# Outputs: -# K: system data structure LQG optimal controller -# (Obtain A,B,C matrices with sys2ss, sys2tf, or sys2zp as appropriate) -# P: Solution of control (state feedback) algebraic Riccati equation -# Q: Solution of estimation algebraic Riccati equation -# Ee: estimator poles -# Es: controller poles -# -# See also: h2syn, lqe, lqr - # Written by A. S. Hodel August 1995; revised for new system format # August 1996
--- a/scripts/control/lqr.m +++ b/scripts/control/lqr.m @@ -16,38 +16,102 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function [k, p, e] = lqr (a, b, q, r, s) +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +## construct the linear quadratic regulator for the continuous time system +## @iftex +## @tex +## $$ +## {dx\over dt} = A x + B u +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## dx +## -- = A x + B u +## dt +## @end example +## +## @end ifinfo +## to minimize the cost functional +## @iftex +## @tex +## $$ +## J = \int_0^\infty x^T Q x + u^T R u +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## infinity +## / +## J = | x' Q x + u' R u +## / +## t=0 +## @end example +## @end ifinfo +## +## @noindent +## @var{z} omitted or +## @iftex +## @tex +## $$ +## J = \int_0^\infty x^T Q x + u^T R u + 2 x^T Z u +## $$ +## @end tex +## @end iftex +## @ifinfo +## +## @example +## infinity +## / +## J = | x' Q x + u' R u + 2 x' Z u +## / +## t=0 +## @end example +## +## @end ifinfo +## @var{z} included. +## +## The following values are returned: +## +## @table @var +## @item k +## The state feedback gain, +## @iftex +## @tex +## $(A - B K)$ +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{b}@var{k}) +## @end ifinfo +## is stable and minimizes the cost functional +## +## @item p +## The stabilizing solution of appropriate algebraic Riccati equation. +## +## @item e +## The vector of the closed loop poles of +## @iftex +## @tex +## $(A - B K)$. +## @end tex +## @end iftex +## @ifinfo +## (@var{a} - @var{b}@var{k}). +## @end ifinfo +## @end table +## +## @strong{Reference} +## Anderson and Moore, OPTIMAL CONTROL: LINEAR QUADRATIC METHODS, +## Prentice-Hall, 1990, pp. 56-58 +## @end deftypefn -# Usage: [k, p, e] = lqr (A, B, Q, R {,S}) -# -# Linear quadratic regulator design for the continuous time system -# dx/dt = A x + B u -# to minimize the cost functional -# -# J = int_0^\infty{ [x' u'] [Q S'; S R] [x ; u] dt} -# -# inputs: -# A, B: coefficient matrices for continuous time system -# Q, R, S: cost functional coefficient matrices. -# Q: must be nonnegative definite. -# R: must be positive definite -# S: defaults to 0 -# -# if S is omitted, the optimization simplifies to the usual -# -# J = int_0^\infty{ x' Q x + u' R u } -# -# Returns: -# -# k = state feedback gain, (A - B K) is stable and minimizes the -# cost functional -# p = solution of algebraic Riccati equation -# e = closed loop poles of (A - B K) -# -# reference: Anderson and Moore, OPTIMAL CONTROL: LINEAR QUADRATIC METHODS, -# Prentice-Hall, 1990, pp. 56-58 - - +function [k, p, e] = lqr (a, b, q, r, s) # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. # disp("lqr: entry");
--- a/scripts/control/lsim.m +++ b/scripts/control/lsim.m @@ -15,24 +15,26 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { } lsim (@var{sys}, @var{u}, @var{t}@{,@var{x0}@}) +## Produce output for a linear simulation of a system +## +## Produces a plot for the output of the system, sys. +## +## U is an array that contains the system's inputs. Each column in u +## corresponds to a different time step. Each row in u corresponds to a +## different input. T is an array that contains the time index of the +## system. T should be regularly spaced. If initial conditions are required +## on the system, the x0 vector should be added to the argument list. +## +## When the lsim function is invoked with output parameters: +## [y,x] = lsim(sys,u,t,[x0]) +## a plot is not displayed, however, the data is returned in y = system output +## and x = system states. +## @end deftypefn function [y,x] = lsim(sys,u,t,x0) -# lsim: Produce output for a linear simulation of a system -# -# lsim(sys,u,t,[x0]) -# Produces a plot for the output of the system, sys. -# -# U is an array that contains the system's inputs. Each column in u -# corresponds to a different time step. Each row in u corresponds to a -# different input. T is an array that contains the time index of the -# system. T should be regularly spaced. If initial conditions are required -# on the system, the x0 vector should be added to the argument list. -# -# When the lsim function is invoked with output parameters: -# [y,x] = lsim(sys,u,t,[x0]) -# a plot is not displayed, however, the data is returned in y = system output -# and x = system states. - # Written by David Clem, A. S. Hodel July 1995 # modified by John Ingram for system format August 1996
--- a/scripts/control/ltifr.m +++ b/scripts/control/ltifr.m @@ -16,20 +16,29 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {@var{out} =} ltifr (@var{A}, @var{B}, @var{w}) +## @deftypefnx {Function File } {@var{out} =} ltifr (@var{sys}, @var{w}) +## Linear time invariant frequency response of single input systems +## @strong{Inputs} +## @table @var +## @item A, B +## coefficient matrices of @math{dx/dt = A x + B u} +## @item sys +## system data structure +## @item w +## vector of frequencies +## @end table +## @strong{Outputs} +## @var{out} +## @example +## -1 +## G(s) = (jw I-A) B +## @end example +## for complex frequencies @math{s = jw}. +## @end deftypefn + function out = ltifr(a,b,w) - #ltifr: Linear time invarient frequency response of SISO systems - # out = ltifr(A,B,w) - # user enters the A and B matrices - # - # out = ltifr(sys,w) - # user enters the system, SYS - # - # this function takes the system matrices, A and B and - # returns: -1 - # G(s) = (jw I-A) B - # - # for complex frequencies s = jw. - # R. B. Tenison, D. Clem, A. S. Hodel, July 1995 # updated by John Ingram August 1996 for system format
--- a/scripts/control/lyap.m +++ b/scripts/control/lyap.m @@ -17,29 +17,64 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## Usage: x = lyap (a, b {,c}) -## -## If (a, b, c) are specified, then lyap returns the solution of the -## Sylvester equation -## -## a x + x b + c = 0 -## -## If only (a, b) are specified, then lyap returns the solution of the -## Lyapunov equation -## -## a' x + x a + b = 0 -## -## If b is not square, then lyap returns the solution of either -## -## a' x + x a + b' b = 0 -## -## or -## -## a x + x a' + b b' = 0 -## -## whichever is appropriate. +## -*- texinfo -*- +## @deftypefn {Function File} {} lyap (@var{a}, @var{b}, @var{c}) +## @deftypefnx {Function File} {} lyap (@var{a}, @var{b}) +## Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart +## algorithm (Communications of the ACM, 1972). +## +## If @var{a}, @var{b}, and @var{c} are specified, then @code{lyap} returns +## the solution of the Sylvester equation +## @iftex +## @tex +## $$ A X + X B + C = 0 $$ +## @end tex +## @end iftex +## @ifinfo +## @example +## a x + x b + c = 0 +## @end example +## @end ifinfo +## If only @code{(a, b)} are specified, then @code{lyap} returns the +## solution of the Lyapunov equation +## @iftex +## @tex +## $$ A^T X + X A + B = 0 $$ +## @end tex +## @end iftex +## @ifinfo +## @example +## a' x + x a + b = 0 +## @end example +## @end ifinfo +## If @var{b} is not square, then @code{lyap} returns the solution of either +## @iftex +## @tex +## $$ A^T X + X A + B^T B = 0 $$ +## @end tex +## @end iftex +## @ifinfo +## @example +## a' x + x a + b' b = 0 +## @end example +## @end ifinfo +## @noindent +## or +## @iftex +## @tex +## $$ A X + X A^T + B B^T = 0 $$ +## @end tex +## @end iftex +## @ifinfo +## @example +## a x + x a' + b b' = 0 +## @end example +## @end ifinfo +## @noindent +## whichever is appropriate. ## ## Solves by using the Bartels-Stewart algorithm (1972). +## @end deftypefn ## Author: A. S. Hodel <scotte@eng.auburn.edu> ## Created: August 1993
--- a/scripts/control/moddemo.m +++ b/scripts/control/moddemo.m @@ -15,11 +15,18 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} moddemo ( inputs ) +## @format +## Octave Controls toolbox demo: Model Manipulations demo +## Written by David Clem August 15, 1994 +## +## @end format +## @end deftypefn function moddemo() -# Octave Controls toolbox demo: Model Manipulations demo # Written by David Clem August 15, 1994 - # a s hodel: updated to reflect updated output order in ss2zp while (1)
--- a/scripts/control/nyquist.m +++ b/scripts/control/nyquist.m @@ -15,6 +15,74 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +##@deftypefn {Function File } {[@var{realp}, @var{imagp}, @var{w}] =} nyquist (@var{sys}@{, @var{w}, @var{out_idx}, @var{in_idx}, @var{atol}@}) +##@deftypefnx {Function File } {} nyquist (@var{sys}@{, @var{w}, @var{out_idx}, @var{in_idx}, @var{atol}@}) +##Produce Nyquist plots of a system; if no output arguments are given, Nyquist +##plot is printed to the screen. +## +##Compute the frequency response of a system. +##@strong{Inputs} (pass as empty to get default values) +##@table +##@item sys +## system data structure (must be either purely continuous or discrete; +## see is_digital) +##@item w +## frequency values for evaluation. +## if sys is continuous, then bode evaluates @math{G(jw)} +## if sys is discrete, then bode evaluates @math{G(exp(jwT))}, where +## @math{@var{T}=sysgettsam(@var{sys})} (the system sampling time) +##@item default +## the default frequency range is selected as follows: (These +## steps are NOT performed if @var{w} is specified) +##@end table +##@enumerate +##@item via routine bodquist, isolate all poles and zeros away from +##@var{w}=0 (@var{jw}=0 or @math{exp(@var{jwT})=1}) and select the frequency +##range based on the breakpoint locations of the frequencies. +##@item if @var{sys} is discrete time, the frequency range is limited +##to @var{jwT} in +##@ifinfo +##[0,2p*pi] +##@end ifinfo +##@iftex +##$[0,2p*\pi]$ +##@end iftex +##@item 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. +##@end enumerate +## outputs, inputs: the indices of the output(s) and input(s) to be used in +## the frequency response; see sysprune. +## +##@strong{Inputs} (pass as empty to get default values) +##@table @var +##@item 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. +##@end table +##@strong{Outputs} +##@table @var +##@item realp, imagp +##the real and imaginary parts of the frequency response +## @math{G(jw)} or @math{G(exp(jwT))} at the selected frequency values. +##@item w +## the vector of frequency values used +##@end table +## +## If no output arguments are given, nyquist plots the results to the screen. +## If @var{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. +## +##@end deftypefn function [realp,imagp,w] = nyquist(sys,w,outputs,inputs,atol) # [realp,imagp,w] = nyquist(sys[,w,outputs,inputs,atol])
--- a/scripts/control/obsv.m +++ b/scripts/control/obsv.m @@ -16,27 +16,27 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +##@deftypefn {Function File } { @var{Qb} =} obsv (@var{sys}@{, @var{c}@}) +## Build observability matrix +## @example +## @group +## | C | +## | CA | +## Qb = | CA^2 | +## | ... | +## | CA^(n-1) | +## @end group +## @end example +## of a system data structure or the pair (A, C). +## +## Note: @code{obsv()} forms the observability matrix. +## +## The numerical properties of is_observable() +## are much better for observability tests. +## @end deftypefn + function Qb = obsv(sys, c) - # ------------------------------------------------------ - # 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. - # See also: ctrb, is_observable, is_controllable - # ------------------------------------------------------ - # Written by Kai P. Mueller November 4, 1997 # modified by
--- a/scripts/control/ord2.m +++ b/scripts/control/ord2.m @@ -16,26 +16,33 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{outsys} =} ord2 (@var{nfreq}, @var{damp}@{[, @var{gain}@}) +## Creates a continuous 2nd order system with parameters: +## @strong{Inputs} +## @table @var +## @item nfreq: natural frequency [Hz]. (not in rad/s) +## @item damp: damping coefficient +## @item gain: dc-gain +## This is steady state value only for damp > 0. +## gain is assumed to be 1.0 if ommitted. +## @end table +## @strong{Outputs} +## @var{outsys} +## system data structure has representation with @math{w = 2 * pi * nfreq}: +## @example +## / \ +## | / -2w*damp -w \ / w \ | +## G = | | |, | |, [ 0 gain ], 0 | +## | \ w 0 / \ 0 / | +## \ / +## @end example +## @strong{See also} @code{jet707} (MIMO example, Boeing 707-321 aircraft model) +## @end deftypefn + +## See also: jet707 (MIMO example, Boeing 707-321 aircraft model) + function outsys = ord2(nfreq, damp, gain) - # function outsys = ord2(nfreq, damp[, gain]) - # Creates a continuous 2nd order system with parameters: - # - # 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. - # - # The system 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) - # Written by Kai P. Mueller September 28, 1997 # Updates
--- a/scripts/control/outlist.m +++ b/scripts/control/outlist.m @@ -15,24 +15,34 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { } outlist (@var{lmat}@{, @var{tabchar}, @var{yd}, @var{ilist} @}) +## Prints an enumerated list of strings. +## internal use only; minimal argument checking performed +## +## @strong{Inputs} +## @table @var +## @item lmat +## list of strings +## @item tabchar +## tab character (default: none) +## @item yd +## indices of strings to append with the string "(discrete)" +## (used by @var{sysout}; minimal checking of this argument) +## @math{yd = [] } indicates all outputs are continuous +## @item ilist +## index numbers to print with names. +## +## default: @code{1:rows(lmat)} +## @end table +## +## @strong{Outputs} +## prints the list to the screen, numbering each string in order. +## +## @end deftypefn + function str_val = outlist(name_list,tabchar,yd,ilist) -# function str_val = outlist(name_list[,tabchar,yd,ilist]) -# -# internal use only; minimal argument checking performed -# -# print an enumerated list of strings -# inputs: -# name_list: list of strings (one per entry) -# tabchar: tab character (default: none) -# yd: indices of entries to append with the string "(discrete)" -# (used by sysout; minimal checking of this argument) -# yd = [] => all continuous -# ilist: index numbers to print with names -# default: 1:length(name_list) -# outputs: -# prints the list to the screen, numbering each string in order. - # A. S. Hodel Dec. 1995, 1998 #save for restore later
--- a/scripts/control/pinv.m +++ b/scripts/control/pinv.m @@ -16,19 +16,18 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function retval = pinv (X, tol) +## -*- texinfo -*- +## @deftypefn {Function File } { } pinv ( @var{X}@{,@var{tol}@} ) +## Returns the pseudoinverse of X; singular values less than tol are ignored. +## +## If the second arguement is ommited , it is assummed that +## @example +## tol = max (size (X)) * sigma_max (X) * eps, +## @end example +## where sigma_max(X) is the maximal singular value of X. +## @end deftypefn -# usage: pinv (X, tol) -# -# Returns the pseudoinverse of X; singular values less than tol are -# ignored. -# -# If the second argument is omitted, it is assumed that -# -# tol = max (size (X)) * sigma_max (X) * eps, -# -# where sigma_max(X) is the maximal singular value of X. - +function retval = pinv (X, tol) # Written by Kurt Hornik (hornik@neuro.tuwien.ac.at) March 1993. # Dept of Probability Theory and Statistics TU Wien, Austria.
--- a/scripts/control/place.m +++ b/scripts/control/place.m @@ -15,18 +15,20 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{K} =} place (@var{sys}, @var{P}) +## Computes the matrix K such that if the state +## is feedback with gain K, then the eigenvalues of the closed loop +## system (i.e. A-BK) are those specified in the vector P. +## +## Version: Beta (May-1997): If you have any comments, please let me know. +## (see the file place.m for my address) +## +## Written by: Jose Daniel Munoz Frias. +## @end deftypefn function K = place(sys, P) - -%PLACE K = place(sys,P) Computes the matrix K such that if the state -%is feedback with gain K, then the eigenvalues of the closed loop -%system (i.e. A-BK) are those specified in the vector P. -% -% Version: Beta (May-1997): If you have any comments, please let me know. -% (see the file place.m for my address) -% -% Written by: Jose Daniel Munoz Frias. - % Universidad Pontificia Comillas % ICAIdea % Alberto Aguilera, 23
--- a/scripts/control/polyout.m +++ b/scripts/control/polyout.m @@ -16,17 +16,20 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{y} =} polyout ( @var{c}@{, @var{x}@}) +## write formatted polynomial +## @example +## c(x) = c(1) * x^n + ... + c(n) x + c(n+1) +## @end example +## to string @var{y} or to the screen (if @var{y} is omitted) +## @var{x} defaults to the string @code{"s"} +## @end deftypefn + +## See also: polyval, polyvalm, poly, roots, conv, deconv, residue, +## filter, polyderiv, polyinteg + function y = polyout(c,x) -# -# usage: [y=] polyout(c[,x]) -# -# print formatted polynomial -# c(x) = c(1) * x^n + ... + c(n) x + c(n+1) -# in a string or to the screen (if y is omitted) -# x defaults to the string "s" -# -# SEE ALSO: polyval, polyvalm, poly, roots, conv, deconv, residue, -# filter, polyderiv, polyinteg # Written by A. Scottedward Hodel (scotte@eng.auburn.edu) May 1995) # Nov 1998: Correctly handles complex coefficients
--- a/scripts/control/prompt.m +++ b/scripts/control/prompt.m @@ -15,14 +15,21 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} prompt ( inputs ) +## @format +## function prompt([str]) +## Prompt user to continue +## str: input string. Default value: "\n ---- Press a key to continue ---" +## Written by David Clem August 15, 1994 +## Modified A. S. Hodel June 1995 +## +## +## @end format +## @end deftypefn function prompt(str) -# function prompt([str]) -# Prompt user to continue -# str: input string. Default value: "\n ---- Press a key to continue ---" -# Written by David Clem August 15, 1994 -# Modified A. S. Hodel June 1995 - if(nargin > 1) usage("prompt([str])");
--- a/scripts/control/pzmap.m +++ b/scripts/control/pzmap.m @@ -15,15 +15,20 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{zer}, @var{pol}]=} pzmap (@var{sys}) +## Plots the zeros and poles of a system in the complex plane. +## @strong{Inputs} +## @var{sys} system data structure +## +## @strong{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) +## @end deftypefn function [zer,pol]=pzmap(sys) -# function [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) save_val = implicit_str_to_num_ok; # save for later save_emp = empty_list_elements_ok;
--- a/scripts/control/qzval.m +++ b/scripts/control/qzval.m @@ -15,16 +15,27 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{x} =} qzval (@var{A}, @var{B}) +## Compute generalized eigenvalues of the matrix pencil +## @ifinfo +## @example +## (A - lambda B). +## @end example +## @end ifinfo +## @iftex +## @tex +## $(A - \lambda B)$. +## @end tex +## @end iftex +## +## @var{A} and @var{B} must be real matrices. +## +## @strong{Note} @code{qzval} is obsolete; use @code{qz} instead. +## @end deftypefn function lam = qzval(A,B) -# X = qzval (A, B) -# -# compute generalized eigenvalues of the matrix pencil (A - lambda B). -# A and B must be real matrices. -# -# This function is superseded by qz. You should use qz instead. -# - # A. S. Hodel July 1998 warning("qzval is obsolete; calling qz instead")
--- a/scripts/control/rldemo.m +++ b/scripts/control/rldemo.m @@ -15,9 +15,13 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +##@deftypefn {Function File } { outputs =} rldemo ( inputs ) +##Octave Controls toolbox demo: Root Locus demo +##@end deftypefn function rldemo() -# Octave Controls toolbox demo: Root Locus demo # Written by David Clem August 15, 1994 # Updated by John Ingram December 1996
--- a/scripts/control/rlocus.m +++ b/scripts/control/rlocus.m @@ -15,29 +15,32 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} rlocus ( inputs ) +## @format +## [rldata, k] = rlocus(sys[,increment,min_k,max_k]) +## Displays root locus plot of the specified SISO system. +## +## ----- --- -------- +## --->| + |---|k|---->| SISO |-----------> +## ----- --- -------- | +## - ^ | +## |_____________________________| +## +## inputs: sys = system data structure +## min_k, max_k,increment: minimum, maximum values of k and +## the increment used in computing gain values +## Outputs: plots the root locus to the screen. +## rldata: Data points plotted column 1: real values, column 2: imaginary +## values) +## k: gains for real axis break points. +## +## +## @end format +## @end deftypefn + function [rldata,k_break,rlpol,gvec,real_ax_pts] = rlocus(sys,increment,min_k,max_k) - # [rldata,k_break,rlpol,gvec,real_ax_pts] = rlocus(sys,increment,min_k,max_k) - # Displays root locus plot of the specified SISO system. - # - # ----- --- -------- - # --->| + |---|k|---->| SISO |-----------> - # ----- --- -------- | - # - ^ | - # |_____________________________| - # - #inputs: sys = system data structure - # min_k, max_k,increment: minimum, maximum values of k and - # the increment used in computing gain values - # outputs: plots the root locus to the screen. - # rldata: Data points plotted column 1: real values, column 2: imaginary - # values) - # k_break: gains for real axis break points. - # rlpol: complex vector: column ii of pol is the set of poles - # corresponding to to gain gvec(ii) - # gvec: gains used to compute root locus - # real_ax_pts: breakpoints of the real axis locus. - # Convert the input to a transfer function if necessary # Written by Clem and Tenison # Updated by Kristi McGowan July 1996 for intelligent gain selection
--- a/scripts/control/sortcom.m +++ b/scripts/control/sortcom.m @@ -16,21 +16,26 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} sortcom ( inputs ) +## @format +## [yy,idx] = sortcom(xx[,opt]): sort a complex vector +## xx: complex vector +## opt: sorting option: +## "re": real part (default) +## "mag": by magnitude +## "im": by imaginary part +## +## if opt != "im" then complex conjugate pairs are grouped together, +## a - jb followed by a + jb. +## yy: sorted values +## idx: permutation vector: yy = xx(idx) +## +## +## @end format +## @end deftypefn + function [yy,idx] = sortcom(xx,opt) -# [yy,idx] = sortcom(xx[,opt]): sort a complex vector -# xx: complex vector -# opt: sorting option: -# "re": real part (default) -# "mag": by magnitude -# "im": by imaginary part -# -# if opt != "im" then values with common real part/magnitude are -# sorted by imaginary part, i.e. a - jb followed by a + jb. -# [Complex conjugate pairs may not be grouped consecutively if more than 2 -# numbers share a common real part/magnitude] -# yy: sorted values -# idx: permutation vector: yy = xx(idx) - # Written by A. S. Hodel June 1995 if( nargin < 1 | nargin > 2 )
--- a/scripts/control/ss2sys.m +++ b/scripts/control/ss2sys.m @@ -15,61 +15,180 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} ss2sys (@var{a},@var{b},@var{c}@{,@var{d}, @var{tsam}, @var{n}, @var{nz}, @var{stname}, @var{inname}, @var{outname}, @var{outlist}@}) +## Create system structure from state-space data. May be continous, +## discrete, or mixed (sampeled-data) +## +## @strong{Inputs} +## @table @var +## @item a, b, c, d +## usual state space matrices. +## +## default: @var{d} = zero matrix +## +## @item tsam +## sampling rate. Default: @math{tsam = 0} (continuous system) +## +## @item n, nz +## number of continuous, discrete states in the system +## +## default: +## @table @var +## @item tsam = 0 +## @math{n = @code{rows}(@var{a})}, @math{nz = 0} +## +## @item tsam > 0 +## @math{ n = 0}, @math{nz = @code{rows}(@var{a})} +## +## see below for system partitioning +## +## @end table +## +## @item stname +## list of strings of state signal names +## +## default (@var{stname}=[] on input): @code{x_n} for continuous states, +## @code{xd_n} for discrete states +## +## @item inname +## list of strings of input signal names +## +## default (@var{inname} = [] on input): @code{u_n} +## +## @item outname +## list of strings of input signal names +## +## default (@var{outname} = [] on input): @code{y_n} +## +## @item outlist +## +## list of indices of outputs y that are sampled +## +## default: +## @table @var +## @item tsam = 0 +## @math{outlist = []} +## @item tsam > 0 +## @math{outlist = 1:@code{rows}(@var{c})} +## @end table +## +## Unlike states, discrete/continous outputs may appear in any order. +## +## @strong{Note} @code{sys2ss} returns a vector @var{yd} where +## @var{yd}(@var{outlist}) = 1; all other entries of @var{yd} are 0. +## +## @end table +## +## @strong{Outputs} +## @var{outsys} = system data structure +## +## @strong{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 +## @example +## @group +## 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.) +## @end group +## @end example +## with dynamic equations: +## @ifinfo +## @math{ d/dt xc(t) = acc*xc(t) + acd*xd(k*tsam) + bc*u(t)} +## +## @math{ xd((k+1)*tsam) = adc*xc(k*tsam) + add*xd(k*tsam) + bd*u(k*tsam)} +## +## @math{ yc(t) = ccc*xc(t) + ccd*xd(k*tsam) + dc*u(t)} +## +## @math{ yd(k*tsam) = cdc*xc(k*tsam) + cdd*xd(k*tsam) + dd*u(k*tsam)} +## @end ifinfo +## @iftex +## @tex +## $$\eqalign{ +## {d \over dt} x_c(t) +## & = a_{cc} x_c(t) + a_{cd} x_d(k*t_{sam}) + bc*u(t) \cr +## x_d((k+1)*t_{sam}) +## & = a_{dc} x_c(k t_{sam}) + a_{dd} x_d(k t_{sam}) + b_d u(k t_{sam}) \cr +## y_c(t) +## & = c_{cc} x_c(t) + c_{cd} x_d(k t_{sam}) + d_c u(t) \cr +## y_d(k t_{sam}) +## & = c_{dc} x_c(k t_{sam}) + c_{dd} x_d(k t_{sam}) + d_d u(k t_{sam}) +## }$$ +## @end tex +## @end iftex +## +## @strong{Signal partitions} +## @example +## @group +## | continuous | discrete | +## ---------------------------------------------------- +## states | stname(1:n,:) | stname((n+1):(n+nz),:) | +## ---------------------------------------------------- +## outputs | outname(cout,:) | outname(outlist,:) | +## ---------------------------------------------------- +## @end group +## @end example +## where @math{cout} is the list of in 1:@code{rows}(@var{p}) +## that are not contained in outlist. (Discrete/continuous outputs +## may be entered in any order desired by the user.) +## +## @strong{Example} +## @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 +## @end example +## Notice that the @var{D} matrix is constructed by default to the +## correct dimensions. Default input and output signals names were assigned +## since none were given. +## +## @end deftypefn +## + function retsys = ss2sys (a,b,c,d,tsam,n,nz,stname,inname,outname,outlist) - # retsys = 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), n - # 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 output 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. - # - # 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 ] d = [ 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 = list if indices in 1:rows(p) not contained in outlist. - # # Written by John Ingram (ingraje@eng.auburn.edu) July 20, 1996
--- a/scripts/control/ss2tf.m +++ b/scripts/control/ss2tf.m @@ -15,23 +15,30 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} ss2tf ( inputs ) +## @format +## [num,den] = ss2tf(a,b,c,d) +## Conversion from tranfer function to state-space. +## The state space system +## . +## x = Ax + Bu +## y = Cx + Du +## +## is converted to a transfer function +## +## num(s) +## G(s)=------- +## den(s) +## +## used internally in system data structure format manipulations +## +## +## @end format +## @end deftypefn function [num,den] = ss2tf(a,b,c,d) -# [num,den] = ss2tf(a,b,c,d) -# Conversion from tranfer function to state-space. -# The state space system -# . -# x = Ax + Bu -# y = Cx + Du -# -# is converted to a transfer function -# -# num(s) -# G(s)=------- -# den(s) -# -# used internally in system data structure manipulations - # Written by R. Bruce Tenison (June 24, 1994) btenison@eng.auburn.edu # a s hodel: modified to allow for pure gain blocks Aug 1996
--- a/scripts/control/ss2zp.m +++ b/scripts/control/ss2zp.m @@ -15,15 +15,23 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} ss2zp ( inputs ) +## @format +## Converts a state space representation to a set of poles and zeros. +## +## [pol,zer,k] = ss2zp(a,b,c,d) returns the poles and zeros of the state space +## system (a,b,c,d). K is a gain associated with the zeros. +## +## used internally in system data structure format manipulations +## +## +## @end format +## @end deftypefn + function [zer,pol,k] = ss2zp(a,b,c,d) -# Converts a state space representation to a set of poles and zeros. -# -# [pol,zer,k] = ss2zp(a,b,c,d) returns the poles and zeros of the state space -# system (a,b,c,d). K is a gain associated with the zeros. -# -# used internally in system data structure manipulations - # Written by David Clem August 15, 1994 # Hodel: changed order of output arguments to zer, pol, k. July 1996 # a s hodel: added argument checking, allow for pure gain blocks aug 1996
--- a/scripts/control/starp.m +++ b/scripts/control/starp.m @@ -16,35 +16,40 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} starp ( inputs ) +## @format +## +## [sys] = starp(P, K, ny, nu) +## +## Redheffer star product or upper/lower LFT, respectively. +## +## +## +-------+ +## --------->| |---------> +## | P | +## +--->| |---+ ny +## | +-------+ | +## +-------------------+ +## | | +## +----------------+ | +## | | +## | +-------+ | +## +--->| |------+ nu +## | K | +## --------->| |---------> +## +-------+ +## +## If ny and nu "consume" all inputs and outputs of K then the result +## is a lower fractional transformation. If ny and nu "consume" all +## inputs and outputs of P then the result is an upper fractional +## transformation. +## +## ny and/or nu may be negative (= negative feedback) +## @end format +## @end deftypefn + function [sys] = starp(P, K, ny, nu); -# -# [sys] = starp(P, K, ny, nu) -# -# Redheffer star product or upper/lower LFT, respectively. -# -# -# +-------+ -# --------->| |---------> -# | P | -# +--->| |---+ ny -# | +-------+ | -# +-------------------+ -# | | -# +----------------+ | -# | | -# | +-------+ | -# +--->| |------+ nu -# | K | -# --------->| |---------> -# +-------+ -# -# If ny and nu "consume" all inputs and outputs of K then the result -# is a lower fractional transformation. If ny and nu "consume" all -# inputs and outputs of P then the result is an upper fractional -# transformation. -# -# ny and/or nu may be negative (= negative feedback) - # Written by Kai Mueller May 1998 if((nargin != 2) && (nargin != 4))
--- a/scripts/control/step.m +++ b/scripts/control/step.m @@ -15,8 +15,37 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{y}, @var{t}] =} impulse (@var{sys}@{, @var{inp},@var{tstop}, @var{n}@}) +## Step response for a linear system. +## The system can be discrete or multivariable (or both). +## If no output arguments are specified, @code{impulse} +## produces a plot or the step response data for system @var{sys}. +## +## @strong{Inputs} +## @table @var +## @item sys +## System data structure. +## @item inp +## Index of input being excited +## @item tstop +## The argument @var{tstop} (scalar value) denotes the time when the +## simulation should end. +## @item n +## the number of data values. +## +## Both parameters @var{tstop} and @var{n} can be omitted and will be +## computed from the eigenvalues of the A-Matrix. +## @end table +## @strong{Outputs} +## @var{y}, @var{t}: impulse response +## +## When invoked with the output paramter y the plot is not displayed. +## @end deftypefn -function [y, t] = step(sys, inp, tstop, n) +## See also: impulse, stepimp + # step: Step response for a linear system. # The system can be discrete or multivariable (or both). # @@ -33,6 +62,7 @@ # # See also: impulse, stepimp +function [y, t] = step(sys, inp, tstop, n) # Written by Kai P. Mueller September 30, 1997 # based on lsim.m of Scottedward Hodel # modified by
--- a/scripts/control/stepimp.m +++ b/scripts/control/stepimp.m @@ -15,20 +15,24 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {[y, t] = } stepimp(@var{sitype},@var{sys}[, @var{inp}, @var{tstop}, @var{n}]) +## Impulse or step response for a linear system. +## The system can be discrete or multivariable (or both). +## This m-file contains the "common code" of step and impulse. +## +## Produces a plot or the response data for system sys. +## +## Limited argument checking; "do not attempt to do this at home". +## Used internally in @code{impulse}, @code{step}. Use @code{step} +## or @code{impulse} instead. +## +## @end deftypefn +## +## ## See also: step, impulse + function [y, t] = stepimp(sitype, sys, inp, tstop, n) -# step: Impulse or step response for a linear system. -# The system can be discrete or multivariable (or both). -# This m-file contains the "common code" of step and impulse. -# -# [y, t] = stepimp(sitype, sys[, inp, tstop, n]) -# Produces a plot or the response data for system sys. -# -# Limited argument checking; "do not attempt to do this at home". -# Use step or impulse instead. -# -# See also: step, impulse - # Written by Kai P. Mueller October 2, 1997 # based on lsim.m of Scottedward Hodel
--- a/scripts/control/susball.m +++ b/scripts/control/susball.m @@ -15,7 +15,38 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} susball ( inputs ) +## @format +## +## @end format +## @end deftypefn +## @deftypefn {Function File } { outputs =} swap ( inputs ) +## @format +## [a1,b1] = swap(a,b) +## interchange a and b +## +## +## @end format +## @end deftypefn +## @deftypefn {Function File } { outputs =} swapcols ( inputs ) +## @format +## function B = swapcols(A) +## permute columns of A into reverse order +## +## +## @end format +## @end deftypefn +## @deftypefn {Function File } { outputs =} swaprows ( inputs ) +## @format +## function B = swaprows(A) +## permute rows of A into reverse order +## +## +## @end format +## @end deftypefn + cmd = "ballsys = margetsys(""disc"")"; eval(cmd);
--- a/scripts/control/sys2fir.m +++ b/scripts/control/sys2fir.m @@ -15,11 +15,18 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{c}, @var{tsam}, @var{input}, @var{output}] =} sys2fir (@var{sys}) +## +## Extract FIR data from system data structure; see @ref{fir2sys} for +## parameter descriptions. +## +## @end deftypefn + +## See also: fir2sys function [c,tsam,inname,outname] = sys2fir(sys) -# function [c,tsam,inname,outname] = sys2fir(sys) -# extract fir system from system data structure - # a s hodel July 1996 # let sys2tf do most of the work
--- a/scripts/control/sys2ss.m +++ b/scripts/control/sys2ss.m @@ -15,29 +15,54 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{a},@var{b},@var{c},@var{d},@var{tsam},@var{n},@var{nz},@var{stname},@var{inname},@var{outname},@var{yd}] =} sys2ss (@var{sys}) +## Extract state space representation from system data structure. +## +## @strong{Inputs} +## @var{sys} system data structure (@xref{sysstruct}) +## +## @strong{Outputs} +## @table @var +## @item a,b,c,d +## state space matrices for sys +## +## @item tsam +## sampling time of sys (0 if continuous) +## +## @item n, nz +## number of continuous, discrete states (discrete states come +## last in state vector @var{x}) +## +## @item stname, inname, outname +## signal names (lists of strings); names of states, +## inputs, and outputs, respectively +## +## @item yd +## binary vector; @var{yd}(@var{ii}) is 1 if output @var{y}(@var{ii})$ +## is discrete (sampled); otherwise @var{yd}(@var{ii}) 0. +## +## @end table +## A warning massage is printed if the system is a mixed +## continuous and discrete system +## +## @strong{Example} +## @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 +## @end example +## @end deftypefn function [a,b,c,d,tsam,n,nz,stname,inname,outname,yd] = sys2ss(sys) - # function [a,b,c,d(,tsam,n,nz,stname,inname,outname,yd)] = sys2ss(sys) - # Convert from system data structure to state space form - # inputs: - # sys: system data structure for the state space system - # - # x' = Ax + Bu - # y = Cx + Du - # - # or a similar discrete-time system. - # - # 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 (strings); names of states, - # inputs, and outputs, respectively - # yd: binary vector; yd(ii) is nonzero if output y is discrete. - # - # A warning message is printed if the system is a mixed - # continuous/discrete system. # Written by David Clem August 19, 1994 # Updates by John Ingram July 14, 1996
--- a/scripts/control/sys2tf.m +++ b/scripts/control/sys2tf.m @@ -16,18 +16,22 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{num},@var{den},@var{tsam},@var{inname},@var{outname}] =} sys2tf (@var{sys}) +## Extract transfer function data from a system data structure +## +## See @ref{tf2sys} for parameter descriptions. +## +## @strong{Example} +## @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 +## @end example +## @end deftypefn + function [num,den,tsam,inname,outname] = sys2tf(Asys) -# function [num,den,tsam,inname,outname] = sys2tf(Asys) -# Conversion from a system data structure format to a transfer function. The -# transfer function part of ASYS is returned to the user in the form: -# -# num(s) -# G(s)=------- -# den(s) -# -# The user can also have the sampling time (TSAM), the name of the input -# (INNAME), and the output name (OUTNAME) - # Written by R. Bruce Tenison (June 24, 1994) btenison@eng.auburn.edu # modified to make sys2tf by A. S. Hodel Aug 1995 # modified again for updated system format by John Ingram July 1996
--- a/scripts/control/sys2zp.m +++ b/scripts/control/sys2zp.m @@ -15,19 +15,27 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +##@deftypefn {Function File } {[@var{zer}, @var{pol}, @var{k}, @var{tsam}, @var{inname}, @var{outname}] =} sys2zp (@var{sys}) +## Extract zero/pole/leading coefficient information from a system data +## structure +## +## See @ref{zp2sys} for parameter descriptions. +## +## @strong{Example} +## @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 +## @end example +## @end deftypefn function [zer,pol,k,tsam,inname,outname] = sys2zp(sys) -# [zer,pol,k,tsam,inname,outname] = sys2zp(sys) -# extract zero/pole/leading coefficient information from a system data -# structure -# inputs: sys: system data structure -# outputs: -# 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 (strings) - # Created by John Ingram July 15 1996 if(nargin != 1)
--- a/scripts/control/sysadd.m +++ b/scripts/control/sysadd.m @@ -15,26 +15,31 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} sysadd ( @var{Gsys},@var{Hsys}) +## returns @var{sys} = @var{Gsys} + @var{Hsys}. +## @itemize @bullet +## @item Exits with +## an error if @var{Gsys} and @var{Hsys} are not compatibly dimensioned. +## @item Prints a warning message is system states have identical names; +## duplicate names are given a suffix to make them unique. +## @item @var{sys} input/output names are taken from @var{Gsys}. +## @end itemize +## @example +## @group +## ________ +## ----| Gsys |--- +## u | ---------- +| +## ----- (_)----> y +## | ________ +| +## ----| Hsys |--- +## -------- +## @end group +## @end example +## @end deftypefn function sys = sysadd(...) -# -# sys = sysadd(Gsys{,Hsys,...}) -# -# returns transfer function sys = Gsys + Hsys + ... -# -# Method: sysgroup used to connect systems in parallel -# The input vector is connected to all systems; the outputs are summed. -# Returned system input/output signal names are those of Gsys. For -# example, sysadd(Gsys,Hsys) results in -# -# ________ -# ----| Gsys |--- -# u | ---------- +| -# ----- (_)----> y -# | ________ +| -# ----| Hsys |--- -# -------- - # Written by John Ingram July 1996 # Updated for variable number of arguments July 1999 A. S. Hodel
--- a/scripts/control/sysappend.m +++ b/scripts/control/sysappend.m @@ -16,37 +16,65 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {@var{retsys} =} sysappend (@var{sys},@var{b}@{, @var{c}, @var{d}, @var{outname}, @var{inname}, @var{yd}@}) +## appends new inputs and/or outputs to a system +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## +## @item b +## matrix to be appended to sys "B" matrix (empty if none) +## +## @item c +## matrix to be appended to sys "C" matrix (empty if none) +## +## @item d +## revised sys d matrix (can be passed as [] if the revised d is all zeros) +## +## @item outname +## list of names for new outputs +## +## @item inname +## list of names for new inputs +## +## @item yd +## binary vector; @math{yd(ii)=0} indicates a continuous output; +## @math{yd(ii)=1} indicates a discrete output. +## @end table +## +## @strong{Outputs} @var{sys} +## @example +## @group +## sys.b := [sys.b , b] +## sys.c := [sys.c ] +## [ c ] +## sys.d := [sys.d | D12 ] +## [D21 | D22 ] +## @end group +## @end example +## where @var{D12}, @var{D21}, and @var{D22} are the appropriate dimensioned +## blocks of the input parameter @var{d}. +## @itemize @bullet +## @item The leading block @var{D11} of @var{d} is ignored. +## @item If @var{inname} and @var{outname} are not given as arguments, +## the new inputs and outputs are be assigned default names. +## @item @var{yd} is a binary vector of length rows(c) that indicates +## continuous/sampled outputs. Default value for @var{yd} is: +## +## @item @var{sys} = continuous or mixed +## @var{yd} = @code{zeros(1,rows(c))} +## +## @item @var{sys} = discrete +## @var{yd} = @code{ones(1,rows(c))} +## +## @end itemize +## +## @end deftypefn + function retsys = sysappend(sys,b,c,d,outname,inname,yd) - # - # function retsys = sysappend(sys,b[,c,d,outname,inname,yd]) - # - # This function 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: names for new outputs - # inname: names for new inputs - # yd: indicator for which new outputs are continuous/discrete - # (yd(i) = 0 or , respectively) - # result: - # 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 vector of length rows(c), and indicates which new outputs are - # discrete (yd(ii) = 1) and which are continuous (yd(ii) = 0). - # Default value for yd is: - # sys = continuous or mixed: yd = zeros(1,rows(c)) - # sys = discrete: yd = ones(1,rows(c)) - # written by John Ingram August 1996 sav_implicit_str_to_num_ok = implicit_str_to_num_ok; # save for later
--- a/scripts/control/syschnames.m +++ b/scripts/control/syschnames.m @@ -15,30 +15,13 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {@var{retsys} =} syschnames (@var{sys}, @var{opt}, @var{list}, @var{names}) +## Superseded by @code{syssetsignals} +## @end deftypefn + function retsys = syschnames(sys,opt,list,names) -# retsys = syschnames(sys,opt,list,names) -# 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. -# -# list: vector of indices of outputs, yd, inputs, or -# states whose respective names should be changed -# -# names: strings or string arrays containing -# names corresponding to the lists above. To -# change yd, use a vector. Set the name to 0 for continuous, -# or 1 for discrete. -# outputs: -# retsys=sys with appropriate signal names changed -# (or yd values, where appropriate) - # Written by John Ingram August 1996; updated by A. S. Hodel 1998 retsys = syssetsignals(sys,opt,names,list);
--- a/scripts/control/syschnamesl.m +++ b/scripts/control/syschnamesl.m @@ -15,16 +15,19 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { } syschnamesl +## used internally in syschnames +## item olist: index list +## old_names: original list names +## inames: new names +## listname: name of index list +## +## combines the two string lists old_names and inames +## @end deftypefn function old_names = syschnamesl(olist,old_names,inames,listname) - # used internally in syschnames - # olist: index list - # old_names: original list names - # inames: new names - # listname: name of index list - # - # combines the two string lists old_names and inames - # $Revision: 2.1.14.5 $ # $Log: syschnamesl.m,v $ # Revision 2.1.14.5 1999/09/22 21:55:46 scotte
--- a/scripts/control/syschtsam.m +++ b/scripts/control/syschtsam.m @@ -15,13 +15,14 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {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. +## @end deftypefn function retsys = syschtsam(sys,tsam) -# -# retsys = syschtsam(sys,tsam); -# -# This function changes the sampling time (tsam) of the system. - # Written by John Ingram August 1996 if (nargin != 2)
--- a/scripts/control/sysconnect.m +++ b/scripts/control/sysconnect.m @@ -15,39 +15,55 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {@var{retsys} =} sysconnect (@var{sys}, @var{out_idx},@var{in_idx}@{,@var{order}, @var{tol}@}) +## Close the loop from specified outputs to respective specified inputs +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## @item out_idx, in_idx +## list of connections indices; @math{y(out_idx(ii))} +## is connected to @math{u(in_idx(ii))}. +## @item order +## logical flag (default = 0) +## @table @code +## @item 0 +## leave inputs and outputs in their original order +## @item 1 +## permute inputs and outputs to the order shown in the diagram below +## @end table +## @item tol +## tolerance for singularities in algebraic loops default: 200@var{eps} +## @end table +## +## @strong{Outputs} +## @var{sys}: resulting closed loop system. +## +## @strong{Method} +## @code{sysconnect} internally permutes selected inputs, outputs as shown +## below, closes the loop, and then permutes inputs and outputs back to their +## original order +## @example +## @group +## ____________________ +## u_1 ----->| |----> y_1 +## | sys | +## old u_2 | | +## u_2* ---->(+)--->| |----->y_2 +## (in_idx) ^ -------------------| | (out_idx) +## | | +## ------------------------------- +## @end group +## @end example +## The input that has the summing junction added to it has an * added to the end +## of the input name. +## +## @end deftypefn + function sys = sysconnect(sys,output_list,input_list,order,tol) -# function retsys = sysconnect(sys,output_list,input_list[,order,tol]) -# Close the loop from specified outputs to respective specified inputs -# -# inputs: -# sys: system data structure -# output_list,input_list: list of connections indices; y(output_list(ii)) -# is connected to u(input_list(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: 200*eps -# output: sys: resulting closed loop system: -# -# Operation: 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 -# (input_list) ^ | | | (output_list) -# | -------------------- | -# | | -# ------------------------------- -# -# The input that has the summing junction added to it has an * added to the end -# of the input name. - # A. S. Hodel August 1995 # modified by John Ingram July 1996
--- a/scripts/control/syscont.m +++ b/scripts/control/syscont.m @@ -15,19 +15,28 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File} { [@var{csys}, @var{Acd}, @var{Ccd}] = } syscont (@var{sys}) +## Extract the purely continuous subsystem of an input system. +## +## @strong{Inputs} +## @var{sys} is a system data structure +## +## @strong{Outputs} +## @table @var +## @item csys +## is the purely continuous input/output connections of @var{sys} +## @item Acd, Ccd: +## connections from discrete states to continuous states, +## discrete states to continuous outputs, respectively. +## +## returns @var{csys} empty if no continuous/continous path exists +## @end table +## +## @end deftypefn function [csys,Acd,Ccd] = syscont(sys) -# function [csys,Acd,Ccd] = syscont(sys) -# returns csys = sys with discrete states./utputs omitted. -# -# 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 - # Written by John Ingram August 1996 save_val = implicit_str_to_num_ok; # save for later
--- a/scripts/control/syscont_disc.m +++ b/scripts/control/syscont_disc.m @@ -15,18 +15,31 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{n_tot}, @var{st_c}, @var{st_d}, @var{y_c}, @var{y_d}] =} syscont_disc(@var{sys}) +## Used internally in syscont and sysdisc. +## +## @strong{Inputs} +## @var{ sys} is a system data structure. +## +## @strong{Outputs} +## @table @var +## @item n_tot +## total number of states +## @item st_c +## vector of continuous state indices (empty if none) +## @item st_d +## vector of discrete state indices (empty if none) +## @item y_c +## vector of continuous output indices +## @item y_d +## vector of discrete output indices +## @end table +## +## @end deftypefn function [n_tot,st_c,st_d,y_c,y_d] = syscont_disc(sys) -# function [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 - # Written by A. S. Hodel (a.s.hodel@eng.auburn.edu) Feb 1997 # get ranges for discrete/continuous states and outputs
--- a/scripts/control/sysdefioname.m +++ b/scripts/control/sysdefioname.m @@ -15,20 +15,28 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{ioname} =} sysdefioname (@var{n},@var{str} @{,@var{m}@}) +## return default input or output names given @var{n}, @var{str}, @var{m}. +## @var{n} is the final value, @var{str} is the string prefix, and @var{m} +## is start value +## +## used internally, minimal argument checking +## +## @strong{Example} @code{ioname = sysdefioname(5,"u",3)} +## returns the list: +## @example +## ioname = +## ( +## [1] = u_3 +## [2] = u_4 +## [3] = u_5 +## ) +## @end example +## @end deftypefn function ioname = sysdefioname(n,str,m) -# function ioname = sysdefioname(n,str[,m]) -# return list of default input or output names given n, str, m -# n is the final value, str is the string prefix, and m is start value -# ex: ioname = sysdefioname(5,"u",3) -# -# returns: ioname = -# ( -# [1] = u_3 -# [2] = u_4 -# [3] = u_5 -# ) -# used internally, minimal argument checking if (nargin < 2 | nargin > 3) usage("ioname = sysdefioname(n,str[,m])");
--- a/scripts/control/sysdefstname.m +++ b/scripts/control/sysdefstname.m @@ -15,11 +15,15 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{stname} =} sysdefstname (@var{n}, @var{nz}) +## return default state names given @var{n}, @var{nz} +## +## used internally, minimal argument checking +## @end deftypefn + function stname = sysdefstname(n,nz) -# function stname = sysdefstname(n,nz) -# return default state names given n, nz -# used internally, minimal argument checking stname = list(); if(n > 0)
--- a/scripts/control/sysdimensions.m +++ b/scripts/control/sysdimensions.m @@ -16,27 +16,57 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{n}, @var{nz}, @var{m}, @var{p},@var{yd}] =} sysdimensions (@var{sys}@{, @var{opt}@}) +## return the number of states, inputs, and/or outputs in the system @var{sys}. +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## +## @item opt +## String indicating which dimensions are desired. Values: +## @table @code +## @item "all" +## (default) return all parameters as specified under Outputs below. +## +## @item "cst" +## return @var{n}= number of continuous states +## +## @item "dst" +## return @var{n}= number of discrete states +## +## @item "in" +## return @var{n}= number of inputs +## +## @item "out" +## return @var{n}= number of outputs +## @end table +## @end table +## +## @strong{Outputs} +## @table @var +## @item n +## number of continuous states (or individual requested dimension as specified +## by @var{opt}). +## @item nz +## number of discrete states +## @item m +## number of system inputs +## @item p +## number of system outputs +## @item yd +## binary vector; @var{yd}(@var{ii}) is nonzero if output @var{ii} is +## discrete. +## @math{yd(ii) = 0} if output @var{ii} is continous +## @end table +## +## @end deftypefn + +## See also: sysgetsignals, sysgettsam + function [n,nz,m,p,yd] = sysdimensions(sys,opt) -# [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 -# "all" (default): return all output arguments (see below) -# "cst": return n=number of continuous states -# "dst": return n=number of discrete states -# "st": return n=number of states (continuous and discrete) -# "in": return n=number of inputs -# "out": return n=number of outputs -# outputs: -# n: number of continuous states (or the specified dimension as shown above) -# nz: number of discrete states -# m: number of system inputs -# p: number of system outputs -# yd: is the discrete output vector: yd(ii) = 1 if output ii is sampled, -# yd(ii) = 0 if output ii is continous -# -# see also: sysgetsignals, sysgettsam - if(nargout > 5 | nargin < 1 | nargin > 2) usage("[n,nz,m,p[,yd]] = sysdimensions(sys{,opt})"); elseif(!is_struct(sys))
--- a/scripts/control/sysdisc.m +++ b/scripts/control/sysdisc.m @@ -15,6 +15,24 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{dsys}, @var{Adc}, @var{Cdc}] =} sysdisc (@var{sys}) +## +## @strong{Inputs} +## @var{sys} = system data structure +## +## @strong{Outputs} +## @table @var +## @item dsys +## purely discrete portion of sys (returned empty if there is +## no purely discrete path from inputs to outputs) +## @item Adc, Cdc +## connections from continuous states to discrete states and discrete +## outputs, respectively. +## @end table +## +## @end deftypefn function [dsys,Adc,Cdc] = sysdisc(sys) # function [dsys,Adc,Cdc] = sysdisc(sys)
--- a/scripts/control/sysdup.m +++ b/scripts/control/sysdup.m @@ -16,31 +16,42 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retsys} =} sysdup (@var{Asys}, @var{out_idx}, @var{in_idx}) +## Duplicate specified input/output connections of a system +## +## @strong{Inputs} +## @table @var +## @item Asys +## system data structure (@xref{ss2sys}) +## @item out_idx,in_idx +## list of connections indices; +## duplicates are made of @var{y(out_idx(ii))} and @var{u(in_idx(ii))}. +## @end table +## +## @strong{Outputs} +## @var{retsys}: resulting closed loop system: +## duplicated i/o names are appended with a @code{"+"} suffix. +## +## +## @strong{Method} +## @code{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 @var{in_idx}, @var{out_idx}, respectively +## @example +## @group +## ____________________ +## u1 ----->| |----> y1 +## | Asys | +## u2 ------>| |----->y2 +## (in_idx) -------------------| (out_idx) +## @end group +## @end example +## +## @end deftypefn + function retsys = sysdup(Asys,output_list,input_list) -# function retsys = sysdup(Asys,output_list,input_list) -# Duplicate specified input/output connections of a system -# -# -# inputs: -# Asys: system data structure (see ss2sys) -# output_list,input_list: list of connections indices; -# duplicates are made of y(output_list(ii)) and u(input_list(ii)). -# output: retsys: resulting closed loop system: -# duplicated i/o names are appended with a "+" suffix. -# -# Operation: 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 input_list,output_list, respectively -# ____________________ -# | | -# u1 ----->| |----> y1 -# | Asys | -# | | -# u2 ------------->| |----->y2 -# (input_list) | | (output_list) -# -------------------- - # A. S. Hodel August 1995 # modified by John Ingram July 1996
--- a/scripts/control/sysgetsignals.m +++ b/scripts/control/sysgetsignals.m @@ -16,41 +16,126 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{stname}, @var{inname}, @var{outname}, @var{yd}] =} sysgetsignals (@var{sys}) +## @deftypefnx{Function File } { @var{siglist} =} sysgetsignals (@var{sys},@var{sigid}) +## @deftypefnx{Function File } { @var{signame} =} sysgetsignals (@var{sys},@var{sigid},@var{signum}@{, @var{strflg}@}) +## Get signal names from a system +## +## @strong{Inputs} +## @table @var +## @item sys +## system data structure for the state space system +## +## @item sigid +## signal id. String. Must be one of +## @table @code +## @item "in" +## input signals +## @item "out" +## output signals +## @item "st" +## stage signals +## @item "yd" +## value of logical vector @var{yd} +## @end table +## +## @item signum +## Index of signal (or indices of signals if signum is a vector) +## +## @item strflg +## flag to return a string instead of a list; Values: +## @table @code +## @item 0 +## (default) return a list (even if signum is a scalar) +## +## @item 1 +## return a string. Exits with an error if signum is not a scalar. +## @end table +## +## @end table +## +## @strong{Outputs} +## @table @bullet +## @item If @var{sigid} is not specified +## @table @var +## @item stname, inname, outname +## signal names (lists of strings); names of states, +## inputs, and outputs, respectively +## @item yd +## binary vector; @var{yd}(@var{ii}) is nonzero if output @var{ii} is +## discrete. +## @end table +## +## @item If @var{sigid} is specified but @var{signum} is not specified, then +## @table @code +## @item sigid="in" +## @var{siglist} is set to the list of input names +## +## @item sigid="out" +## @var{siglist} is set to the list of output names +## +## @item sigid="st" +## @var{siglist} is set to the list of state names +## +## stage signals +## @item sigid="yd" +## @var{siglist} is set to logical vector indicating discrete outputs; +## @var{siglist(ii) = 0} indicates that output @var{ii} is continuous +## (unsampled), otherwise it is discrete. +## +## @end table +## +## @item if the first three input arguments are specified, then @var{signame} is +## a list of the specified signal names (@var{sigid} is @code{"in"}, +## @code{"out"}, or @code{"st"}), or else the logical flag +## indicating whether output(s) @var{signum} is(are) discrete (@var{sigval}=1) +## or continuous (@var{sigval}=0). +## @end table +## +## @strong{Examples} (From @code{sysrepdemo}) +## @example +## 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 +## @end example +## +## @end deftypefn + function [stname,inname,outname,yd] = sysgetsignals(sys,sigid,signum,strflg) - # [stname,inname,outname,yd] = sysgetsignals(sys) - # -or- siglist = sysgetsignals(sys,sigid) - # -or- 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": state signals - # "yd": value of yd - # signum: index of signal (e.g., out4 = sysgetsignals(sys,"out",4) - # sets out4 to the name of the 4th output) - # strflg: flag to return a string instead of a list; - # strflg = 0: (default) return a list - # strflg = 1: return a string; exits with an error if - # length(signum) > 1 - # outputs: - # if sigid is not specified: - # stname, inname, outname: signal names (lists); names of states, - # inputs, and outputs, respectively - # yd: binary vector; yd(ii) is nonzero if output y is discrete. - # if sigid is specified but signum is not specified: - # stname: - # is the list of state names (sigid = "st") - # is the list input names (sigid = "in") - # is the list output names (sigid = "out") - # is the logical vector indicate discrete outputs (sigid = "yd") - # if all three input arguments are specified: - # is the list of specified state, input, or output name(s) - # (sigid = "st", "in", or "out"). - # is a logical flag indicating if output signum is continous - # (sigval=0) or discrete (sigval = 1) - # # Adapted from ss2sys
--- a/scripts/control/sysgettype.m +++ b/scripts/control/sysgettype.m @@ -15,16 +15,25 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{systype} =} sysgettype ( @var{sys} ) +## return the initial system type of the system +## +## @strong{Inputs} +## @var{sys}: system data structure +## +## @strong{Outputs} +## @var{systype}: string indicating how the structure was initially +## constructed: +## values: @code{"ss"}, @code{"zp"}, or @code{"tf"} +## +## @strong{Note} FIR initialized systems return @code{systype="tf"}. +## +## +## @end deftypefn + function systype = sysgettype(sys) -# systype = sysgetype(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" if(!is_struct(sys)) error("sysgettype: input sys is not a structure");
--- a/scripts/control/sysgroup.m +++ b/scripts/control/sysgroup.m @@ -15,32 +15,38 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} sysgroup ( @var{Asys}, @var{Bsys}) +## Combines two systems into a single system +## +## @strong{Inputs} +## @var{Asys}, @var{Bsys}: system data structures +## +## @strong{Outputs} +## @math{sys = @r{block diag}(Asys,Bsys)} +## @example +## @group +## __________________ +## | ________ | +## u1 ----->|--> | Asys |--->|----> y1 +## | -------- | +## | ________ | +## u2 ----->|--> | Bsys |--->|----> y2 +## | -------- | +## ------------------ +## Ksys +## @end group +## @end example +## The function also rearranges the internal state-space realization of @var{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. +## +## @end deftypefn function sys = sysgroup(...) -# function sys = sysgroup(Asys{,Bsys,...}) -# Parallel connection of systems -# -# inputs: All input arguments must be system data structures; -# exits with an error if there is not at least one argument -# output: sys: all systems are combined into a single system; e.g., -# if two systems are passed as sysgroup(Asys,Bsys), the result -# is -# -# __________________ -# | ________ | -# u1 ----->|--> | Asys |--->|----> y1 -# | -------- | -# | ________ | -# u2 ----->|--> | Bsys |--->|----> y2 -# | -------- | -# ------------------ -# Ksys -# -# The function also rearranges the A,B,C matrices 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 (a warning message is printed). - # A. S. Hodel August 1995 # modified by John Ingram July 1996 # A. S. Hodel: modified for variable number of arguments 1999
--- a/scripts/control/sysgroupn.m +++ b/scripts/control/sysgroupn.m @@ -15,18 +15,23 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{names} =} sysgroupn (@var{names}) +## names = sysgroupn(names) +## Locate and mark duplicate names +## inputs: +## names: list of signal names +## kind: kind of signal name (used for diagnostic message purposes only) +## outputs: +## returns names with unique suffixes added; diagnostic warning +## message is printed to inform the user of the new signal name +## +## used internally in sysgroup and elsewhere. +## +## @end deftypefn function names = sysgroupn(names,kind) -# names = sysgroupn(names) -# locate and mark duplicate names -# inputs: -# names: list of signal names -# kind: kind of signal name (used for diagnostic message purposes only) -# outputs: -# returns names with unique suffixes added; diagnostic warning -# message is printed to inform the user of the new signal name -# -# used internally in sysgroup # check for duplicate names l = length(names);
--- a/scripts/control/sysmult.m +++ b/scripts/control/sysmult.m @@ -15,26 +15,24 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} sysmult( @var{Asys}, @var{Bsys}) +## Compute @math{sys = Asys*Bsys} (series connection): +## @example +## @group +## u ---------- ---------- +## --->| Bsys |---->| Asys |---> +## ---------- ---------- +## @end group +## @end example +## 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). +## @end deftypefn + function sys = sysmult(...) -# -# sys = sysmult(Asys{,Bsys,...}) -# -# returns transfer function sys = Asys*Bsys* ... -# -# Same as series connection of systems; for example, sysmult(Asys,Bsys) -# returns sys = Asys*Bsys with block diagram -# -# -# 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 form -# does not recognize discrete inputs) - # Written by John Ingram July 1996 # updated for variable number of arguments by A. S. Hodel July 1999
--- a/scripts/control/sysout.m +++ b/scripts/control/sysout.m @@ -16,17 +16,30 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { } sysout ( @var{sys}@{, @var{opt}@}) +## print out a system data structure in desired format +## @table @var +## @item sys +## system data structure +## @item opt +## Display option +## @table @code +## @item [] +## primary system form (default); see @ref{sysgettype}. +## @item "ss" +## state space form +## @item "tf" +## transfer function form +## @item "zp" +## zero-pole form +## @item "all" +## all of the above +## @end table +## @end table +## @end deftypefn + function retsys = sysout(sys,opt) -# function sysout(sys[,opt]) -# print out a system data structure in desired format -# -# sys: system data structure -# opt: []: primary system form (default) -# "ss": state space form -# "tf": transfer function form -# "zp": zero-pole form -# "all": all of the above - # Written by A S Hodel: 1995-1996 # save for restoring at end of routine
--- a/scripts/control/sysprune.m +++ b/scripts/control/sysprune.m @@ -15,30 +15,37 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{retsys} =} sysprune ( @var{Asys}, @var{out_idx}, @var{in_idx}) +## Extract specified inputs/outputs from a system +## +## @strong{Inputs} +## @table @var +## @item Asys +## system data structure +## @item 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. +## @end table +## +## @strong{Outputs} +## @var{retsys}: resulting system +## @example +## @group +## ____________________ +## u1 ------->| |----> y1 +## (in_idx) | Asys | (out_idx) +## u2 ------->| |----| y2 +## (deleted)-------------------- (deleted) +## @end group +## @end example +## +## @end deftypefn +## function sys = sysprune(sys,output_idx,input_idx,state_idx) -# function retsys = sysprune(Asys,output_idx,input_idx{,state_idx}) -# Extract/permute specified inputs, outputs, and/or states of a system. -# -# inputs: -# Asys: system data structure -# output_idx,input_idx: list of connections indices; the new -# system has outputs y(output_idx(ii)) and inputs u(input_idx(ii)). -# May select as [] (empty matrix) to specify all outputs/inputs. -# state_idx: optional argument; list of indices of states to keep -# in the reduced model. May omit this argument or pass [] (empty -# matrix) to keep all states in the returned model -# -# output: retsys: resulting system: -# ____________________ -# | | -# u1 ----->| |----> y1 -# (input_idx) | Asys | (output_idx) -# | | -# u2 (deleted) |---->| |----| y2 (deleted) -# | | -# -------------------- - # A. S. Hodel August 1995 # Updated by John Ingram 7-15-96
--- a/scripts/control/sysreorder.m +++ b/scripts/control/sysreorder.m @@ -15,18 +15,22 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{pv} =} sysreorder( @var{vlen}, @{var{list}) +## +## @strong{Inputs} +## @var{vlen}=vector length, @var{list}= a subset of @code{[1:vlen]}, +## +## @strong{Outputs} +## @var{pv}: a permutation vector to order elements of @code{[1:vlen]} in +## @code{list} to the end of a vector. +## +## Used internally by @code{sysconnect} to permute vector elements to their +## desired locations. +## @end deftypefn function pv = sysreorder(vlen,list) -# function pv = sysreorder(vlen,list) -# -# inputs: vlen: vector length -# list: a subset of {1:vlen} -# 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. No user-serviceable parts inside; do not attempt -# to use this at home! - # A. S. Hodel, Aug 1995 #disp('sysreorder: entry')
--- a/scripts/control/sysrepdemo.m +++ b/scripts/control/sysrepdemo.m @@ -15,13 +15,18 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - -function sysrepdemo() + +## -*- texinfo -*- +## @deftypefn {Function File } {} sysrepdemo +## Tutorial for the use of the system data structure functions. +## @end deftypefn # Octave Controls toolbox demo: System representation - # Written by A. S. Hodel June 1995 # Revised Aug 1995 for system data structure format +function sysrepdemo() + + save_val = page_screen_output; page_screen_output = 1;
--- a/scripts/control/sysscale.m +++ b/scripts/control/sysscale.m @@ -15,28 +15,33 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {@var{sys} =} sysscale (@var{sys}, @var{outscale}, @var{inscale}@{, @var{outname}, @var{inname}@}) +## scale inputs/outputs of a system. +## +## @strong{Inputs} +## sys: structured system +## outscale, inscale: constant matrices of appropriate dimension +## +## @strong{Outputs} +## @var{sys}: resulting open loop system: +## @example +## ----------- ------- ----------- +## u --->| inscale |--->| sys |--->| outscale |---> y +## ----------- ------- ----------- +## @end example +## 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 @var{yd} is +## set appropriately in the returned value of @var{sys}. +## @end deftypefn + function sys = sysscale(sys,outscale,inscale,outname,inname) -# -# function sys = sysscale(sys,outscale,inscale[,outname,inname]) -# scale inputs/outputs of a system. -# -# inputs: -# sys: system data structure -# outscale, inscale: constant matrices of appropriate dimension -# output: sys: resulting open loop system: -# -# ----------- ------- ----------- -# u --->| inscale |--->| sys |--->| outscale |---> y -# ----------- ------- ----------- -# -# If the input names and output names 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 - # A. S. Hodel August 1995 # modified by John Ingram 7-15-96
--- a/scripts/control/syssetsignals.m +++ b/scripts/control/syssetsignals.m @@ -16,28 +16,77 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } {@var{retsys} =} syssetsignals (@var{sys}, @var{opt}, @var{names}@{, @var{sig_idx}@}) +## change the names of selected inputs, outputs and states. +## @strong{Inputs} +## @table @var +## @item sys +## system data structure +## +## @item opt +## change default name (output) +## +## @table @code +## @item "out" +## change selected output names +## @item "in" +## change selected input names +## @item "st" +## change selected state names +## @item "yd" +## change selected outputs from discrete to continuous or +## from continuous to discrete. +## @end table +## +## @item names +## @table @code +## @item opt = "out", "in", or "st" +## string or string array containing desired signal names or values. +## @item opt = "yd" +## To desired output continuous/discrete flag. +## Set name to 0 for continuous, or 1 for discrete. +## @end table +## @item 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. +## @end table +## @strong{Outputs} +## @var{retsys=sys} with appropriate signal names changed +## (or yd values, where appropriate) +## +## +## @strong{Example} +## @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 +## @end example +## +## @end deftypefn + function retsys = syssetsignals(sys,opt,names,sig_idx) -# 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 or list of strings -# opt = "yd": desired output continuous/discrete flag. -# names(ii) = 0: output ii is continuous -# names(ii) = 1: output ii is discrete -# list: vector of indices of outputs, yd, inputs, or -# states whose respective names should be changed. -# Default: replace entire signal list/vector value -# outputs: -# retsys=sys with appropriate signal names changed -# (or yd values, where appropriate) - # Written by John Ingram August 1996 save_val = implicit_str_to_num_ok; # save for later
--- a/scripts/control/syssub.m +++ b/scripts/control/syssub.m @@ -15,28 +15,28 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} syssub (@var{Gsys}, @var{Hsys}) +## returns @math{sys = Gsys - Hsys} +## +## Method: @var{Gsys} and @var{Hsys} are connected in parallel +## The input vector is connected to both systems; the outputs are +## subtracted. Returned system names are those of @var{Gsys}. +## @example +## @group +## ________ +## ----| Gsys |--- +## u | ---------- +| +## ----- (_)----> y +## | ________ -| +## ----| Hsys |--- +## -------- +## @end group +## @end example +## @end deftypefn function sys = syssub(...) -# -# sys = syssub(Gsys{,Hsys, ...}) -# -# returns transfer function sys = Gsys - Hsys - ... -# -# Method: sysgroup used to connect systems in parallel -# The input vector is connected to all systems; the outputs of all -# systems are connected to a summing junction with the first system's -# outputs added, all other outputs subtracted. -# Returned system input/output signal names are those of Gsys. -# Example: syssub(Gsys, Hsys) results in -# -# ________ -# ----| Gsys |--- -# u | ---------- +| -# ----- (_)----> y -# | ________ -| -# ----| Hsys |--- -# -------- - # Written by John Ingram July 1996 # updated for variable numbers of input arguments by July 1999 A. S. Hodel
--- a/scripts/control/sysupdate.m +++ b/scripts/control/sysupdate.m @@ -14,25 +14,41 @@ # # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free -# Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - +# Software Foundation, 59 Temple Place, Suite 330, Boston, MA 0211 + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} sysupdate ( @var{sys}, @var{opt} ) +## Update the internal representation of a system. +## +## @strong{Inputs} +## @table @var +## @item sys: +## system data structure +## @item opt +## string: +## @table @code +## @item "tf" +## update transfer function form +## @item "zp" +## update zero-pole form +## @item "ss" +## update state space form +## @item "all" +## all of the above +## @end table +## @end table +## +## @strong{Outputs} +## @var{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 @code{tf} or @code{zp} exits with an error if the system is +## mixed continuous/digital. +## @end deftypefn + +## See also: tf2sys, ss2sys, zp2sys, sysout, sys2ss, sys2tf, sys2zp + function sys = sysupdate(sys,opt) -# function retsys = sysupdate(sys,opt) -# Update the internal representation of a system. -# inputs: -# sys: system data structure -# opt: string: "tf" -> update transfer function -# "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 -# -# see also: tf2sys, ss2sys, zp2sys, sysout, sys2ss, sys2tf, sys2zp - # Written by John Ingram 7-9-96 # check for correct number of inputs
--- a/scripts/control/tf2ss.m +++ b/scripts/control/tf2ss.m @@ -16,27 +16,33 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} tf2ss ( inputs ) +## @format +## Conversion from tranfer function to state-space. +## The state space system +## . +## x = Ax + Bu +## y = Cx + Du +## +## is obtained from a transfer function +## +## num(s) +## G(s)=------- +## den(s) +## +## via the function call [a,b,c,d] = tf2ss(num,den). +## The vector 'den' must contain only one row, whereas the vector 'num' +## may contain as many rows as there are outputs of the system 'y'. +## The state space system matrices obtained from this function will be +## in controllable canonical form as described in "Modern Control Theory", +## [Brogan, 1991]. +## +## +## @end format +## @end deftypefn + function [a,b,c,d] = tf2ss(num,den) - # Conversion from tranfer function to state-space. - # The state space system - # . - # x = Ax + Bu - # y = Cx + Du - # - # is obtained from a transfer function - # - # num(s) - # G(s)=------- - # den(s) - # - # via the function call [a,b,c,d] = tf2ss(num,den). - # The vector 'den' must contain only one row, whereas the vector 'num' - # may contain as many rows as there are outputs of the system 'y'. - # The state space system matrices obtained from this function will be - # in controllable canonical form as described in "Modern Control Theory", - # [Brogan, 1991]. - - # Written by R. Bruce Tenison (June 22, 1994) btenison@eng.auburn.edu # mod A S Hodel July, Aug 1995
--- a/scripts/control/tf2sys.m +++ b/scripts/control/tf2sys.m @@ -15,17 +15,42 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} = } tf2sys( @var{num}, @var{den} @{, @var{tsam}, @var{inname}, @var{outname} @}) +## build system data structure from transfer function format data +## +## @strong{Inputs} +## @table @var +## @item num, den +## coefficients of numerator/denominator polynomials +## @item tsam +## sampling interval. default: 0 (continuous time) +## @item inname, outname +## input/output signal names; may be a string or list with a single string +## entry. +## @end table +## +## @strong{Outputs} +## @var{sys} = system data structure +## +## @strong{Example} +## @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 +## @end example +## @end deftypefn + function outsys = tf2sys(num,den,tsam,inname,outname) - # - # 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 (string variables) - # outputs: sys = system data structure - # Written by R. Bruce Tenison July 29, 1994 # Name changed to TF2SYS July 1995 # updated for new system data structure format July 1996
--- a/scripts/control/tf2sysl.m +++ b/scripts/control/tf2sysl.m @@ -16,6 +16,12 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{vec} = } tf2sysl (@var{vec}) +## used internally in @ref{tf2sys}. +## strip leading zero coefficients to get the true polynomial length +## @end deftypefn + function vec = tf2sysl(vec) # vec = tf2sysl(vec) #
--- a/scripts/control/tf2zp.m +++ b/scripts/control/tf2zp.m @@ -16,12 +16,19 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { outputs =} tf2zp ( inputs ) +## @format +## Converts transfer functions to poles / zeros. +## +## [zer,pol,k] = tf2zp(num,den) returns the zeros and poles of the SISO system +## defined by num/den. K is a gain associated with the system zeros. +## +## +## @end format +## @end deftypefn + function [zer,pol,k] = tf2zp(num,den) -# Converts transfer functions to poles / zeros. -# -# [zer,pol,k] = tf2zp(num,den) returns the zeros and poles of the SISO system -# defined by num/den. K is a gain associated with the system zeros. - # Written by A. S. Hodel, etc. if(nargin == 2)
--- a/scripts/control/tfout.m +++ b/scripts/control/tfout.m @@ -16,17 +16,16 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { } tfout (@var{num}, @var{denom}@{, @var{x}@}) +## print formatted transfer function @math{n(s)/d(s) } to the screen +## @var{x} defaults to the string @code{"s"} +## @end deftypefn + +## See also: polyval, polyvalm, poly, roots, conv, deconv, residue, +## filter, polyderiv, polyinteg, polyout + function tfout(num,denom,x) -# -# usage: tfout(num,denom[,x]) -# -# print formatted transfer function num(s)/d(s) -# to the screen -# x defaults to the string "s" -# -# SEE ALSO: polyval, polyvalm, poly, roots, conv, deconv, residue, -# filter, polyderiv, polyinteg, polyout - # Written by A. Scottedward Hodel (scotte@eng.auburn.edu) June 1995) save_val = implicit_str_to_num_ok;
--- a/scripts/control/tzero.m +++ b/scripts/control/tzero.m @@ -16,27 +16,38 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +##@deftypefn {Function File} {} tzero (@var{a}, @var{b}, @var{c}, @var{d}@{, @var{opt}@}) +##@deftypefnx {Function File} {} tzero (@var{sys}@{,@var{opt}@}) +## Compute transmission zeros of a continuous +##@example +##. +##x = Ax + Bu +##y = Cx + Du +##@end example +##or discrete +##@example +##x(k+1) = A x(k) + B u(k) +##y(k) = C x(k) + D u(k) +##@end example +##system. +##@strong{Outputs} +##@table @var +##@item zer +## transmission zeros of the system +##@item gain +##leading coefficient (pole-zero form) of SISO transfer function +##returns gain=0 if system is multivariable +##@end table +##@strong{References} +##@enumerate +##@item Emami-Naeini and Van Dooren, Automatica, 1982. +##@item Hodel, "Computation of Zeros with Balancing," 1992 Lin. Alg. Appl. +##@end enumerate +##@end deftypefn + + function [zer, gain] = tzero(A,B,C,D) - # [zer{,gain}] = tzero(A,B,C,D) -or- - # [zer{,gain}] = tzero(Asys) - # 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: - # Hodel, "Computation of Zeros with Balancing," 1992 Lin. Alg. Appl. - # R. Bruce Tenison July 4, 1994 # A. S. Hodel Aug 1995: allow for MIMO and system data structures
--- a/scripts/control/tzero2.m +++ b/scripts/control/tzero2.m @@ -16,16 +16,17 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. -function zr = tzero2 (a, b, c, d, bal) +## -*- texinfo -*- +##@deftypefn {Function File } { @var{zr} =} tzero2 (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal}) +##Compute the transmission zeros of a, b, c, d. +## +##bal = balancing option (see balance); default is "B". +## +##Needs to incorporate @code{mvzero} algorithm to isolate finite zeros; use +##@code{tzero} instead. +##@end deftypefn -# Usage: 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. - +function zr = tzero2 (a, b, c, d, bal) # Written by A. S. Hodel (scotte@eng.auburn.edu) August 1993. if (nargin == 4)
--- a/scripts/control/ugain.m +++ b/scripts/control/ugain.m @@ -16,16 +16,19 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{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) +## +## @end deftypefn + function outsys = ugain(n) - # function 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) - # Written by Kai P. Mueller April, 1998 # Updates
--- a/scripts/control/wgt1o.m +++ b/scripts/control/wgt1o.m @@ -15,20 +15,23 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{wsys} =} wgt1o (@var{vl}, @var{vh}, @var{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) +## @end deftypefn function wsys = wgt1o(vl, vh, fc) -# wgt10 State space description of a first order weighting function. -# -# wsys = wgt1o(vl, vh, fc) -# -# 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) - # Written by Kai P. Mueller September 30, 1997 if (nargin != 3)
--- a/scripts/control/zgfmul.m +++ b/scripts/control/zgfmul.m @@ -15,19 +15,20 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } @var{y} = zgfmul(@var{a},@var{b},@var{c},@var{d},@var{x}) +## +## Compute product of zgep incidence matrix @var{F} with vector @var{x}. +## Used by zgepbal (in zgscal) as part of generalized conjugate gradient +## iteration. +## @end deftypefn + +## References: +## ZGEP: Hodel, "Computation of Zeros with Balancing," 1992, submitted to LAA +## Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 + function y = zgfmul(a,b,c,d,x) - # y = zgfmul(a,b,c,d,x) - # - # Compute product of zgep incidence matrix F with vector x. - # Used by zgepbal (in zgscal) as part of generalized conjugate gradient - # iteration. - # - # References: - # ZGEP: Hodel, "Computation of Zeros with Balancing," Linear algebra and - # its Applications, 1993 - # Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 - # A. S. Hodel July 24 1992 # Conversion to Octave July 3, 1994
--- a/scripts/control/zgfslv.m +++ b/scripts/control/zgfslv.m @@ -15,11 +15,13 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {x =} zgfslv(@var{n},@var{m},@var{p},@var{b}) +## solve system of equations for dense zgep problem +## @end deftypefn function x = zgfslv(n,m,p,b) - # x = zgfslv(n,m,p,b) - # solve system of equations for dense zgep problem - # Written by A. Scotte Hodel # Converted to Octave by R Bruce Tenison, July 3, 1994
--- a/scripts/control/zginit.m +++ b/scripts/control/zginit.m @@ -15,18 +15,21 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {zz =} zginit(@var{a},@var{b},@var{c},@var{d}) +## construct right hand side vector zz +## for the zero-computation generalized eigenvalue problem +## balancing procedure +## called by zgepbal +## +## @end deftypefn + +## References: +## ZGEP: Hodel, "Computation of Zeros with Balancing," 1992, submitted to LAA +## Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 + function zz = zginit(a,b,c,d) - # zz = zginit(a,b,c,d) - # construct right hand side vector zz - # for the zero-computation generalized eigenvalue problem - # balancing procedure - # called by zgepbal - # References: - # ZGEP: Hodel, "Computation of Zeros with Balancing," Linear Algebra and - # its Applications, 1993 - # Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 - # A. S. Hodel July 24 1992 # Conversion to Octave by R. Bruce Tenison, July 3, 1994
--- a/scripts/control/zgpbal.m +++ b/scripts/control/zgpbal.m @@ -15,27 +15,30 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - -function [retsys] = zgpbal(Asys) - # function [retsys] = zgpbal(Asys) - # - # used internally in tzero; minimal argument checking performed - # - # implementation of zero computation generalized eigenvalue problem - # balancing method (Hodel and Tiller, Allerton Conference, 1991) - # Based on Ward's balancing algorithm (SIAM J. Sci Stat. Comput., 1981) - # - # 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 - # 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 - + +## -*- texinfo -*- +## @deftypefn {Function File } {[retsys] =} zgpbal(Asys) +## +## used internally in @code{tzero}; minimal argument checking performed +## +## implementation of zero computation generalized eigenvalue problem +## balancing method (Hodel and Tiller, Allerton Conference, 1991) +## Based on Ward's balancing algorithm (SIAM J. Sci Stat. Comput., 1981) +## +## 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 +## +## @end deftypefn + +## References: +## ZGEP: Hodel, "Computation of Zeros with Balancing," 1992, submitted to LAA +## Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 + +function [retsys] = zgpbal(Asys) # A. S. Hodel July 24 1992 # Conversion to Octave by R. Bruce Tenison July 3, 1994
--- a/scripts/control/zgreduce.m +++ b/scripts/control/zgreduce.m @@ -15,14 +15,14 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { retsys = } zgreduce(@var{Asys},@var{meps}) +## Implementation of procedure REDUCE in (Emami-Naeini and Van Dooren, +## Automatica, # 1982). +## @end deftypefn function retsys = zgreduce(Asys,meps) -# function retsys = zgreduce(Asys,meps) -# implementation of procedure REDUCE in (Emami-Naeini and Van Dooren, -# Automatica, # 1982). -# -# used internally in tzero; minimal argument checking performed - # SYS_INTERNAL accesses members of system data structure is_digital(Asys); # make sure it's pure digital/continuous
--- a/scripts/control/zgrownorm.m +++ b/scripts/control/zgrownorm.m @@ -15,13 +15,14 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{nonz}, @var{zer}] =} zgrownorm (@var{mat}, @var{meps}) +## returns @var{nonz} = number of rows of @var{mat} whose two norm exceeds @var{meps} +## @var{zer} = number of rows of mat whose two norm is less than meps +## @end deftypefn + function [sig, tau] = zgrownorm(mat,meps) -# function [nonz, zer] = zgrownorm(mat,meps) -# used internally in tzero -# 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 - rownorm = []; for ii=1:rows(mat)
--- a/scripts/control/zgscal.m +++ b/scripts/control/zgscal.m @@ -16,16 +16,19 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { x =} zgscal (@var{f}, @var{z}, @var{n}, @var{m}, @var{p}) +## Generalized conjugate gradient iteration to +## solve zero-computation generalized eigenvalue problem balancing equation +## @math{fx=z}; +## called by @code{zgepbal} +## @end deftypefn + +## References: +## ZGEP: Hodel, "Computation of Zeros with Balancing," 1992, submitted to LAA +## Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 + function x = zgscal(a,b,c,d,z,n,m,p) - # x = zgscal(f,z,n,m,p) generalized conjugate gradient iteration to - # solve zero-computation generalized eigenvalue problem balancing equation - # fx=z - # called by zgepbal - # - # References: - # ZGEP: Hodel, "Computation of Zeros with Balancing," 1992, submitted to LAA - # Generalized CG: Golub and Van Loan, "Matrix Computations, 2nd ed" 1989 - # A. S. Hodel July 24 1992 # Conversion to Octave R. Bruce Tenison July 3, 1994
--- a/scripts/control/zgsgiv.m +++ b/scripts/control/zgsgiv.m @@ -15,12 +15,14 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {[a ,b ] =} zgsgiv(@var{c},@var{s},@var{a},@var{b}) +## apply givens rotation c,s to row vectors @var{a},@var{b} +## No longer used in zero-balancing (zgpbal); kept for backward compatibility +## @end deftypefn + function [a,b] = zgsgiv(c,s,a,b) - # [a,b] = zgsgiv(c,s,a,b) - # apply givens rotation c,s to row vectors a,b - # No longer used in zero-balancing (zgpbal); kept for backward compatibility - # A. S. Hodel July 29, 1992 # Convertion to Octave by R. Bruce Tenison July 3, 1994
--- a/scripts/control/zgshsr.m +++ b/scripts/control/zgshsr.m @@ -16,12 +16,14 @@ # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. +## -*- texinfo -*- +## @deftypefn {Function File } { @var{x} =} zgshsr( @var{y}) +## apply householder vector based on @math{e^(m)} to +## (column vector) y. +## Called by zgfslv +## @end deftypefn + function x = zgshsr(y) - # x = zgshsr(y) - # apply householder vector based on e^(m) to - # (column vector) y. - # Called by zgfslv - # A. S. Hodel July 24, 1992 # Conversion to Octave by R. Bruce Tenison July 3, 1994
--- a/scripts/control/zp2ss.m +++ b/scripts/control/zp2ss.m @@ -15,29 +15,37 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{A}, @var{B}, @var{C}, @var{D}] =} zp2ss (@var{zer}, @var{pol}, @var{k}) +## Conversion from zero / pole to state space. +## @strong{Inputs} +## @table +## @item zer, pol +## vectors of (possibly) complex poles and zeros of a transfer +## function. Complex values must come in conjugate pairs +## (i.e., x+jy in zer means that x-jy is also in zer) +## @item k +## real scalar (leading coefficient) +## @end table +## @strong{Outputs} +## @var{A}, @var{B}, @var{C}, @var{D} +## The state space system +## @example +## . +## x = Ax + Bu +## y = Cx + Du +## @end example +## is obtained from a vector of zeros and a vector of poles via the +## function call @code{[a,b,c,d] = zp2ss(zer,pol,k)}. +## The vectors @samp{zer} and +## @samp{pol} may either be row or column vectors. Each zero and pole that +## has an imaginary part must have a conjugate in the list. +## The number of zeros must not exceed the number of poles. +## @samp{k} is @code{zp}-form leading coefficient. +## @end deftypefn function [a,b,c,d] = zp2ss(zer,pol,k) -# [A,B,C,D] = zp2ss(zer,pol,k) -# Conversion from zero / pole to state space. -# Inputs: -# zer, pol: vectors of (possibly) complex poles and zeros of a transfer -# function. Complex values must come in conjugate pairs -# (i.e., x+jy in zer means that x-jy is also in zer) -# k: real scalar (leading coefficient) -# Outputs: -# A, B, C, D: -# The state space system -# . -# x = Ax + Bu -# y = Cx + Du -# -# is obtained from a vector of zeros and a vector of poles via the -# function call [a,b,c,d] = zp2ss(zer,pol,k). The vectors 'zer' and -# 'pol' may either be row or column vectors. Each zero and pole that -# has an imaginary part must have a conjugate in the list. -# The number of poles must at least equal the number of zeros. -# k is a gain that is associated with the zero vector. - # Written by David Clem August 15, 1994 sav_val = empty_list_elements_ok;
--- a/scripts/control/zp2ssg2.m +++ b/scripts/control/zp2ssg2.m @@ -15,14 +15,15 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { [@var{poly}, @var{rvals}] =} zp2ssg2 (@var{rvals}) +## Used internally in @code{zp2ss} +## Extract 2 values from @var{rvals} (if possible) and construct +## a polynomial with those roots. +## @end deftypefn + function [poly,rvals] = zp2ssg2(rvals) -# [poly,rvals] = zp2ssg2(rvals) -# -# used internally in zp2ss -# extract 2 values from rvals (if possible) and construct -# a polynomial with those roots. - # A. S. Hodel Aug 1996 # locate imaginary roots (if any)
--- a/scripts/control/zp2sys.m +++ b/scripts/control/zp2sys.m @@ -15,18 +15,44 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. + +## -*- texinfo -*- +## @deftypefn {Function File } { @var{sys} =} zp2sys (@var{zer},@var{pol},@var{k}@{,@var{tsam},@var{inname},@var{outname}@}) +## Create system data structure from zero-pole data +## +## @strong{Inputs} +## @table @var +## @item zer +## vector of system zeros +## @item pol +## vector of system poles +## @item k +## scalar leading coefficient +## @item tsam +## sampling period. default: 0 (continuous system) +## @item inname, outname +## input/output signal names (lists of strings) +## @end table +## +## @strong{Outputs} +## sys: system data structure +## +## @strong{Example} +## @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) +## @end example +## @end deftypefn function outsys = zp2sys (zer,pol,k,tsam,inname,outname) - # 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 (strings) - # outputs: sys: system data structure - # Modified by John Ingram July 20, 1996 save_val = implicit_str_to_num_ok; # save for restoring later
--- a/scripts/control/zp2tf.m +++ b/scripts/control/zp2tf.m @@ -15,19 +15,23 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } {[@var{num}, @var{den}] =} zp2tf (@var{zer}, @var{pol}, @var{k}) +## Converts zeros / poles to a transfer function. +## @strong{Inputs} +## @table +## @item zer, pol +## vectors of (possibly complex) poles and zeros of a transfer +## function. Complex values should appear in conjugate pairs +## @item k +## real scalar (leading coefficient) +## @end table +## @code{[num,den] = zp2tf(zer,pol,k)} forms the transfer function +## @code{num/den} from the vectors of poles and zeros. +## @end deftypefn + function [num,den] = zp2tf(zer,pol,k) -# [num,den] = zp2tf(zer,pol,k) -# Converts zeros / poles to a transfer function. -# -# Inputs: -# zer, pol: vectors of (possibly complex) poles and zeros of a transfer -# function. Complex values should appear in conjugate pairs -# k: real scalar (leading coefficient) -# Forms the transfer function num/den from -# the vectors of poles and zeros. K is a scalar gain associated with the -# zeros. - # Find out whether data was entered as a row or a column vector and # convert to a column vector if necessary # Written by A. S. Hodel with help from students Ingram, McGowan.
--- a/scripts/control/zpout.m +++ b/scripts/control/zpout.m @@ -15,18 +15,17 @@ # You should have received a copy of the GNU General Public License # along with Octave; see the file COPYING. If not, write to the Free # Software Foundation, 59 Temple Place, Suite 330, Boston, MA 02111 USA. - + +## -*- texinfo -*- +## @deftypefn {Function File } { } zpout (@var{zer}, @var{pol}, @var{k}@{, @var{x}@}) +## print formatted zero-pole form to the screen. +## @var{x} defaults to the string @code{"s"} +## @end deftypefn + +## See also: polyval, polyvalm, poly, roots, conv, deconv, residue, +## filter, polyderiv, polyinteg, polyout + function zpout(zer,pol,k,x) -# -# usage: zpout(zer,pol,k,[,x]) -# -# print formatted zero-pole form -# to the screen -# x defaults to the string "s" -# -# SEE ALSO: polyval, polyvalm, poly, roots, conv, deconv, residue, -# filter, polyderiv, polyinteg, polyout - # Written by A. Scottedward Hodel (scotte@eng.auburn.edu) June 1995) save_val = implicit_str_to_num_ok;