Control System Toolbox

Reference

R2014a

How to Contact MathWorks

Web
Newsgroup
www.mathworks.com/contact_TS.html Technical Support
www.mathworks.com

comp.soft-sys.matlab

suggest@mathworks.com
bugs@mathworks.com
doc@mathworks.com
service@mathworks.com
info@mathworks.com

Product enhancement suggestions

Bug reports
Documentation error reports
Order status, license renewals, passcodes
Sales, pricing, and general information

508-647-7000 (Phone)
508-647-7001 (Fax)
The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098
For contact information about worldwide offices, see the MathWorks Web site.
Control System Toolbox Reference
COPYRIGHT 20012014 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or
reproduced in any form without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation
by, for, or through the federal government of the United States. By accepting delivery of the Program
or Documentation, the government hereby agrees that this software or documentation qualifies as
commercial computer software or commercial computer software documentation as such terms are used
or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and
conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern
the use, modification, reproduction, release, performance, display, and disclosure of the Program and
Documentation by the federal government (or other entity acquiring for or through the federal government)
and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the
governments needs or is inconsistent in any respect with federal procurement law, the government agrees
to return the Program and Documentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See
www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand
names may be trademarks or registered trademarks of their respective holders.
Patents

MathWorks products are protected by one or more U.S. patents. Please see
www.mathworks.com/patents for more information.

Revision History

June 2001
July 2002
June 2004
March 2005
September 2005
March 2006
September 2006
March 2007
September 2007
March 2008
October 2008
March 2009
September 2009
March 2010
September 2010
April 2011
September 2011
March 2012
September 2012
March 2013
September 2013
March 2014

Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online
Online

only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only
only

New for Version 5.1 (Release 12.1)

Revised for Version 5.2 (Release 13)
Revised for Version 6.0 (Release 14)
Revised for Version 6.2 (Release 14SP2)
Revised for Version 6.2.1 (Release 14SP3)
Revised for Version 7.0 (Release 2006a)
Revised for Version 7.1 (Release 2006b)
Revised for Version 8.0 (Release 2007a)
Revised for Version 8.0.1 (Release 2007b)
Revised for Version 8.1 (Release 2008a)
Revised for Version 8.2 (Release 2008b)
Revised for Version 8.3 (Release 2009a)
Revised for Version 8.4 (Release 2009b)
Revised for Version 8.5 (Release 2010a)
Revised for Version 9.0 (Release 2010b)
Revised for Version 9.1 (Release 2011a)
Revised for Version 9.2 (Release 2011b)
Revised for Version 9.3 (Release 2012a)
Revised for Version 9.4 (Release 2012b)
Revised for Version 9.5 (Release 2013a)
Revised for Version 9.6 (Release 2013b)
Revised for Version 9.7 (Release 2014a)

Contents
Functions Alphabetical List

1
Block Reference

vi

Contents

1
Functions Alphabetical
List

abs

1-2

Purpose

Entrywise magnitude of frequency response

Syntax

absfrd = abs(sys)

Description

absfrd = abs(sys) computes the magnitude of the frequency response

contained in the FRD model sys. For MIMO models, the magnitude
is computed for each entry. The output absfrd is an FRD object
containing the magnitude data across frequencies.

See Also

bodemag | sigma | fnorm

absorbDelay

Purpose

Replace time delays by poles at z = 0 or phase shift

Syntax

sysnd = absorbDelay(sysd)
[sysnd,G] = absorbDelay(sysd)

Description

sysnd = absorbDelay(sysd) absorbs all time delays of the dynamic

system model sysd into the system dynamics or the frequency response
data.
For discrete-time models (other than frequency response data models),
a delay of k sampling periods is replaced by k poles at z = 0. For
continuous-time models (other than frequency response data models),
time delays have no exact representation with a finite number of poles
and zeros. Therefore, use pade to compute a rational approximation of
the time delay.
For frequency response data models in both continuous and discrete
time, absorbDelay absorbs all time delays into the frequency response
data as a phase shift.
[sysnd,G] = absorbDelay(sysd) returns the matrix G that maps the
initial states of the ss model sysd to the initial states of the sysnd.

Examples

Example 1
Create a discrete-time transfer function that has a time delay and
absorb the time delay into the system dynamics as poles at z = 0.
z = tf('z',-1);
sysd = (-.4*z -.1)/(z^2 + 1.05*z + .08);
sysd.InputDelay = 3

These commands produce the result:

Transfer function:
-0.4 z - 0.1
z^(-3) * ------------------z^2 + 1.05 z + 0.08

1-3

absorbDelay

Sampling time: unspecified

The display of sysd represents the InputDelay as a factor of z^(-3),

separate from the system poles that appear in the transfer function
denominator.
Absorb the delay into the system dynamics.
sysnd = absorbDelay(sysd)

The display of sysnd shows that the factor of z^(-3) has been absorbed
as additional poles in the denominator.
Transfer function:
-0.4 z - 0.1
------------------------z^5 + 1.05 z^4 + 0.08 z^3
Sampling time: unspecified

Additionally, sysnd has no input delay:

sysnd.InputDelay
ans =
0

Example 2
Convert "nk" into regular coefficients of a polynomial model.
Consider the discrete-time polynomial model:
m = idpoly(1,[0 0 0 2 3]);

The value of the B polynomial, m.b, has 3 leading zeros. Two of these
zeros are treated as input-output delays. Consequently:
sys = tf(m)

1-4

absorbDelay

creates a transfer function such that the numerator is [0 2 3] and the IO

delay is 2. In order to treat the leading zeros as regular B coefficients,
use absorbDelay:
m2 = absorbDelay(m);
sys2 = tf(m2);
sys2's numerator is [0 0 0 2 3] and IO delay is 0. The model m2

treats the leading zeros as regular coefficients by freeing their values.

m2.Structure.b.Free(1:2) is TRUE while m.Structure.b.Free(1:2)
is FALSE.

See Also

hasdelay | pade | totaldelay

1-5

allmargin

Purpose

Gain margin, phase margin, delay margin and crossover frequencies

Syntax

S = allmargin(sys)
S = allmargin(mag,phase,w,ts)

Description

S = allmargin(sys)
allmargin computes the gain margin, phase margin, delay margin

and the corresponding crossover frequencies of the SISO open-loop

model sys. The allmargin command is applicable to any SISO model,
including models with delays.
The output S is a structure with the following fields:
GMFrequency All 180 (modulo 360) crossover frequencies
in rad/TimeUnit, where TimeUnit is the time units of the input
dynamic system, specified in the TimeUnit property of sys.
GainMargin Corresponding gain margins, defined as 1/G, where
G is the gain at the 180 crossover frequency. Gain margins are in
absolute units.
PMFrequency All 0 dB crossover frequencies in rad/TimeUnit,
where TimeUnit is the time units of the input dynamic system,
specified in the TimeUnit property of sys).
PhaseMargin Corresponding phase margins in degrees.
DMFrequency and DelayMargin Critical frequencies and the
corresponding delay margins. Delay margins are specified in the
time units of the system for continuous-time systems and multiples
of the sample time for discrete-time systems.
Stable 1 if the nominal closed-loop system is stable, 0 otherwise.
Where stability cannot be assessed, Stable is set to NaN. In general,
stability cannot be assessed for an frd system.
S = allmargin(mag,phase,w,ts) computes the stability margins
from the frequency response data mag, phase, w, and the sampling
time, ts. Provide magnitude values mag in absolute units, and phase
values phase in degrees. You can provide the frequency vector w in any

1-6

allmargin

units; allmargin returns frequencies in the same units. allmargin

interpolates between frequency points to approximate the true stability
margins.

See Also

ltiview | margin

1-7

append

Purpose

Group models by appending their inputs and outputs

Syntax

sys = append(sys1,sys2,...,sysN)

Description

sys = append(sys1,sys2,...,sysN)
append appends the inputs and outputs of the models sys1,...,sysN to
form the augmented model sys depicted below.

For systems with transfer functions H1(s), . . . , HN(s), the resulting

system sys has the block-diagonal transfer function

0
H1 (s)
0
H
(
s
)

0 H N (s)
0
For state-space models sys1 and sys2 with data (A1, B1, C1, D1) and
(A2, B2, C2, D2), append(sys1,sys2) produces the following state-space
model:

1-8

append

x1 A1 0 x1 B1
x = 0 A x + 0
2
2 2
y1 C1 0 x1 D1
y = 0 C x + 0
2
2 2

Arguments

0 u1
B2 u2
0 u1
D2 u2

The input arguments sys1,..., sysN can be model objects s of any type.
Regular matrices are also accepted as a representation of static gains,
but there should be at least one model in the input list. The models
should be either all continuous, or all discrete with the same sample
time. When appending models of different types, the resulting type is
determined by the precedence rules (see Rules That Determine Model
Type for details).
There is no limitation on the number of inputs.

Examples

The commands
sys1 = tf(1,[1 0]);
sys2 = ss(1,2,3,4);
sys = append(sys1,10,sys2)

produce the state-space model

a =
x1
x2

x1
0
0

x2
0
1

x1
x2

u1
1
0

u2
0
0

y1

x1
1

x2
0

b =
u3
0
2

c =

1-9

append

y2
y3

0
0

0
3

y1
y2
y3

u1
0
0
0

u2
0
10
0

d =
u3
0
0
4

Continuous-time model.

See Also

1-10

connect | feedback | parallel | series

augstate

Purpose

Append state vector to output vector

Syntax

asys = augstate(sys)

Description

asys = augstate(sys)

Given a state-space model sys with equations

x = Ax + Bu
y = Cx + Du
(or their discrete-time counterpart), augstate appends the states x to
the outputs y to form the model

x = Ax + Bu
y C
D
x = I x + 0 u


This command prepares the plant so that you can use the feedback
command to close the loop on a full-state feedback u = Kx.

Limitation

Because augstate is only meaningful for state-space models, it cannot

be used with TF, ZPK or FRD models.

See Also

feedback | parallel | series

1-11

balreal

Purpose

Gramian-based input/output balancing of state-space realizations

Syntax

[sysb, g] = balreal(sys)
[sysb, g] =
balreal(sys,'AbsTol',ATOL,'RelTol',RTOL,'Offset',ALPHA)
[sysb, g] = balreal(sys, condmax)
[sysb, g, T, Ti] = balreal(sys)

[sysb, g] = balreal(sys, opts)

Description

[sysb, g] = balreal(sys) computes a balanced realization sysb

for the stable portion of the LTI model sys. balreal handles both
continuous and discrete systems. If sys is not a state-space model, it is
first and automatically converted to state space using ss.

For stable systems, sysb is an equivalent realization for which the

controllability and observability Gramians are equal and diagonal, their
diagonal entries forming the vector G of Hankel singular values. Small
entries in G indicate states that can be removed to simplify the model
(use modred to reduce the model order).
If sys has unstable poles, its stable part is isolated, balanced, and added
back to its unstable part to form sysb. The entries of g corresponding
to unstable modes are set to Inf.
[sysb, g] =
balreal(sys,'AbsTol',ATOL,'RelTol',RTOL,'Offset',ALPHA)

specifies additional options for the stable/unstable decomposition. See

the stabsep reference page for more information about these options.
The default values are ATOL = 0, RTOL = 1e-8, and ALPHA = 1e-8.
[sysb, g] = balreal(sys, condmax) controls the condition number
of the stable/unstable decomposition. Increasing condmax helps

separate close by stable and unstable modes at the expense of accuracy.

By default condmax=1e8.
[sysb, g, T, Ti] = balreal(sys) also returns the vector g

containing the diagonal of the balanced gramian, the state similarity

transformation xb = Tx used to convert sys to sysb, and the inverse
transformation Ti = T-1.

1-12

balreal

If the system is normalized properly, the diagonal g of the joint gramian

can be used to reduce the model order. Because g reflects the combined
controllability and observability of individual states of the balanced
model, you can delete those states with a small g(i) while retaining
the most important input-output characteristics of the original system.
Use modred to perform the state elimination.
[sysb, g] = balreal(sys, opts) computes the balanced realization
using the options specified in the hsvdOptions object opts.

Examples

Example 1
Consider the zero-pole-gain model
sys = zpk([-10 -20.01],[-5 -9.9 -20.1],1)
Zero/pole/gain:
(s+10) (s+20.01)
---------------------(s+5) (s+9.9) (s+20.1)

A state-space realization with balanced gramians is obtained by

[sysb,g] = balreal(sys)

The diagonal entries of the joint gramian are

g'
ans =
0.1006

0.0001

0.0000

which indicates that the last two states of sysb are weakly coupled to
the input and output. You can then delete these states by
sysr = modred(sysb,[2 3],'del')

to obtain the following first-order approximation of the original system.

1-13

balreal

zpk(sysr)
Zero/pole/gain:
1.0001
-------(s+4.97)

Compare the Bode responses of the original and reduced-order models.

bode(sys,'-',sysr,'x')

1-14

balreal

Example 2
Create this unstable system:
sys1=tf(1,[1 0 -1])
Transfer function:
1
------s^2 - 1

Apply balreal to create a balanced gramian realization.

[sysb,g]=balreal(sys1)
a =
x1
x2

x1
1
0

x2
0
-1

x1
x2

u1
0.7071
0.7071

b =

c =
y1

x1
0.7071

x2
-0.7071

d =
y1

u1
0

Continuous-time model.

1-15

balreal

g =
Inf
0.2500

The unstable pole shows up as Inf in vector g.

Algorithms

Consider the model

x = Ax + Bu
y = Cx + Du
with controllability and observability gramians Wc and Wo. The state
coordinate transformation x = Tx produces the equivalent model

x = TAT 1 x + TBu
y = CT 1 x + Du
and transforms the gramians to

Wc = TWcT T , Wo = T T Wo T 1
The function balreal computes a particular similarity transformation
T such that

Wc = Wo = diag( g)
See [1], [2] for details on the algorithm.

References

1-16

[1] Laub, A.J., M.T. Heath, C.C. Paige, and R.C. Ward, "Computation
of System Balancing Transformations and Other Applications of
Simultaneous Diagonalization Algorithms," IEEE Trans. Automatic
Control, AC-32 (1987), pp. 115-122.

balreal

[2] Moore, B., "Principal Component Analysis in Linear Systems:

Controllability, Observability, and Model Reduction," IEEE
Transactions on Automatic Control, AC-26 (1981), pp. 17-31.
[3] Laub, A.J., "Computation of Balancing Transformations," Proc.
ACC, San Francisco, Vol.1, paper FA8-E, 1980.

See Also

hsvdOptions | gram | modred | ss

1-17

balred

Purpose

Model order reduction

Syntax

rsys = balred(sys,ORDERS)
rsys = balred(sys,ORDERS,BALDATA)
rsys = balred( ___ ,opts)

Description

rsys = balred(sys,ORDERS) computes a reduced-order approximation

rsys of the LTI model sys. The desired order (number of states) for
rsys is specified by ORDERS. You can try multiple orders at once by
setting ORDERS to a vector of integers, in which case rsys is a vector of
reduced-order models. balred uses implicit balancing techniques to
compute the reduced- order approximation rsys. Use hsvd to plot the

Hankel singular values and pick an adequate approximation order.

States with relatively small Hankel singular values can be safely
discarded.
When sys has unstable poles, it is first decomposed into its stable and
unstable parts using stabsep, and only the stable part is approximated.
Use balredOptions to specify additional options for the stable/unstable
decomposition.
rsys = balred(sys,ORDERS,BALDATA) uses balancing data returned
by hsvd. Because hsvd does most of the work needed to compute rsys,
this syntax is more efficient when using hsvd and balred jointly.
rsys = balred( ___ ,opts) computes the model reduction using the

specified options for the stable/unstable decomposition and state

elimination method. Use the balredOptions command to create the
option setopts.
Note The order of the approximate model is always at least the number
of unstable poles and at most the minimal order of the original model
(number NNZ of nonzero Hankel singular values using an eps-level
relative threshold)

1-18

balred

References

[1] Varga, A., "Balancing-Free Square-Root Algorithm for Computing

Singular Perturbation Approximations," Proc. of 30th IEEE CDC,
Brighton, UK (1991), pp. 1062-1065.

See Also

balredOptions | hsvd | order | minreal | sminreal

Related
Examples

Approximate Model with Lower-Order Model

Approximate Model with Unstable or Near-Unstable Pole

Concepts

Why Simplify Models?

1-19

balredOptions

Purpose

Create option set for model order reduction

Syntax

opts = balredOptions
opts = balredOptions('OptionName', OptionValue)

Description

opts = balredOptions returns the default option set for the balred

command.
opts = balredOptions('OptionName', OptionValue) accepts one or
more comma-separated name/value pairs. Specify OptionName inside
single quotes.

Input
Arguments

Name-Value Pair Arguments

StateElimMethod

State elimination method. Specifies how to eliminate the weakly

coupled states (states with smallest Hankel singular values). Specified
as one of the following values:
'MatchDC'

Discards the specified states and alters the remaining

states to preserve the DC gain.

'Truncate'

Discards the specified states without altering the

remaining states. This method tends to product a
better approximation in the frequency domain, but
the DC gains are not guaranteed to match.

Default: 'MatchDC'
AbsTol, RelTol

Absolute and relative error tolerance for stable/unstable decomposition.

Positive scalar values. For an input model G with unstable
poles, balred first extracts the stable dynamics by computing the
stable/unstable decomposition G GS + GU. The AbsTol and RelTol
tolerances control the accuracy of this decomposition by ensuring that
the frequency responses of G and GS + GU differ by no more than

1-20

balredOptions

AbsTol + RelTol*abs(G). Increasing these tolerances helps separate

nearby stable and unstable modes at the expense of accuracy. See
stabsep for more information.

Default: AbsTol = 0; RelTol = 1e-8

Offset

Offset for the stable/unstable boundary. Positive scalar value. In the

stable/unstable decomposition, the stable term includes only poles
satisfying
Re(s) < -Offset * max(1,|Im(s)|) (Continuous time)
|z| < 1 - Offset (Discrete time)
Increase the value of Offset to treat poles close to the stability
boundary as unstable.
Default: 1e-8
For additional information on the options and how to use them, see
the balred reference page.

Examples

Compute a reduced-order approximation of the system given by:

G ( s) =

( s + 0 .5 ) ( s + 1 .1 ) ( s + 2 .9 )
.
( s + 106 ) ( s + 1) ( s + 2) ( s + 3)

Use the Offset option to exclude the pole at s = 106 from the stable
term of the stable/unstable decomposition.
sys = zpk([-.5 -1.1 -2.9],[-1e-6 -2 -1 -3],1);
% Create balredOptions
opt = balredOptions('Offset',.001,'StateElimMethod','Truncate');
% Compute second-order approximation
rsys = balred(sys,2,opt)

Compare the original and reduced-order models with bode:

1-21

balredOptions

bode(sys,rsys)

See Also

1-22

balred | stabsep

bandwidth

Purpose

Frequency response bandwidth

Syntax

fb = bandwidth(sys)
fb = bandwidth(sys,dbdrop)

Description

fb = bandwidth(sys) computes the bandwidth fb of the SISO dynamic

system model sys, defined as the first frequency where the gain drops
below 70.79 percent (-3 dB) of its DC value. The frequency fb is
expressed in rad/TimeUnit, where TimeUnit is the time units of the
input dynamic system, specified in the TimeUnit property of sys.

For FRD models, bandwidth uses the first frequency point to

approximate the DC gain.
fb = bandwidth(sys,dbdrop) further specifies the critical gain drop

in dB. The default value is -3 dB, or a 70.79 percent drop.

If sys is an S1-by...-by-Sp array of models, bandwidth returns an array
of the same size such that
fb(j1,...,jp) = bandwidth(sys(:,:,j1,...,jp))

See Also

dcgain | issiso

1-23

bdschur

Purpose

Block-diagonal Schur factorization

Syntax

[T,B,BLKS] = bdschur(A,CONDMAX)
[T,B] = bdschur(A,[],BLKS)

Description

[T,B,BLKS] = bdschur(A,CONDMAX) computes a transformation

matrix T such that B = T \ A * T is block diagonal and each diagonal

block is a quasi upper-triangular Schur matrix.
[T,B] = bdschur(A,[],BLKS) pre-specifies the desired block sizes.
The input matrix A should already be in Schur form when you use this
syntax.

Input
Arguments

Output
Arguments

A: Matrix for block-diagonal Schur factorization.

CONDMAX: Specifies an upper bound on the condition number of T.
By default, CONDMAX = 1/sqrt(eps). Use CONDMAX to control the
tradeoff between block size and conditioning of T with respect to
inversion. When CONDMAX is a larger value, the blocks are smaller
and T becomes more ill-conditioned.
T: Transformation matrix.
B: Matrix B = T \ A * T.
BLKS: Vector of block sizes.

See Also

1-24

ordschur | schur

blkdiag

Purpose

Block-diagonal concatenation of models

Syntax

sys = blkdiag(sys1,sys2,...,sysN)

Description

sys = blkdiag(sys1,sys2,...,sysN) produces the aggregate system

0
..
0
sys1
0
sys2 .
:

:
.
.
0

0
..
0
sysN

blkdiag is equivalent to append.

Examples

The commands
sys1 = tf(1,[1 0]);
sys2 = ss(1,2,3,4);
sys = blkdiag(sys1,10,sys2)

produce the state-space model

a =
x1
x2

x1
0
0

x2
0
1

x1
x2

u1
1
0

u2
0
0

y1
y2
y3

x1
1
0
0

x2
0
0
3

b =
u3
0
2

c =

1-25

blkdiag

d =
y1
y2
y3

u1
0
0
0

u2
0
10
0

u3
0
0
4

Continuous-time model.

See Also

1-26

append | series | parallel | feedback

bode

Purpose

Bode plot of frequency response, magnitude and phase of frequency

response

Syntax

bode(sys)
bode(sys1,...,sysN)
bode(sys1,PlotStyle1,...,sysN,PlotStyleN)
bode(...,w)
[mag,phase] = bode(sys,w)
[mag,phase,wout] = bode(sys)
[mag,phase,wout,sdmag,sdphase] = bode(sys)

Description

bode(sys) creates a Bode plot of the frequency response of a dynamic

system model sys. The plot displays the magnitude (in dB) and phase
(in degrees) of the system response as a function of frequency.

When sys is a multi-input, multi-output (MIMO) model, bode produces

an array of Bode plots, each plot showing the frequency response of
one I/O pair.
bode automatically determines the plot frequency range based on

system dynamics.

1-27

bode

bode(sys1,...,sysN) plots the frequency response of multiple dynamic

systems in a single figure. All systems must have the same number of
inputs and outputs.
bode(sys1,PlotStyle1,...,sysN,PlotStyleN) plots system
responses using the color, linestyle, and markers specified by the
PlotStyle strings.
bode(...,w) plots system responses at frequencies determined by w.

If w is a cell array {wmin,wmax}, bode(sys,w) plots the system

response at frequency values in the range {wmin,wmax}.
If w is a vector of frequencies, bode(sys,w) plots the system response
at each of the frequencies specified in w.
[mag,phase] = bode(sys,w) returns magnitudes mag in absolute

units and phase values phase in degrees. The response values in mag
and phase correspond to the frequencies specified by w as follows:
If w is a cell array {wmin,wmax}, [mag,phase] = bode(sys,w)
returns the system response at frequency values in the range
{wmin,wmax}.
If w is a vector of frequencies, [mag,phase] = bode(sys,w) returns
the system response at each of the frequencies specified in w.
[mag,phase,wout] = bode(sys) returns magnitudes, phase values,
and frequency values wout corresponding to bode(sys).
[mag,phase,wout,sdmag,sdphase] = bode(sys) additionally returns
the estimated standard deviation of the magnitude and phase values
when sys is an identified model and [] otherwise.

Input
Arguments

sys

Dynamic system model, such as a Numeric LTI model, or an array of

such models.
PlotStyle

1-28

bode

Line style, marker, and color of both the line and marker, specified as
a one-, two-, or three-part string enclosed in single quotes (' '). The
elements of the string can appear in any order. The string can specify
only the line style, the marker, or the color.
For more information about configuring the PlotStyle string,
see Specify Line Style, Color, and Markers in the MATLAB
documentation.
w

Input frequency values, specified as a row vector or a two-element cell

array.
Possible values of w:
Two-element cell array {wmin,wmax}, where wmin is the minimum
frequency value and wmax is the maximum frequency value.
Row vector of frequency values.
For example, use logspace to generate a row vector with
logarithmically-spaced frequency values.
Specify frequency values in radians per TimeUnit, where TimeUnit is
the time units of the input dynamic system, specified in the TimeUnit
property of sys.

Output
Arguments

mag

Bode magnitude of the system response in absolute units, returned as a

3-D array with dimensions (number of outputs) (number of inputs)
(number of frequency points).
For a single-input, single-output (SISO) sys, mag(1,1,k) gives the
magnitude of the response at the kth frequency.
For MIMO systems, mag(i,j,k) gives the magnitude of the response
from the jth input to the ith output.
You can convert the magnitude from absolute units to decibels using:

1-29

bode

magdb = 20*log10(mag)
phase

Phase of the system response in degrees, returned as a 3-D array with

dimensions are (number of outputs) (number of inputs) (number
of frequency points).
For SISO sys, phase(1,1,k) gives the phase of the response at the
kth frequency.
For MIMO systems, phase(i,j,k) gives the phase of the response
from the jth input to the ith output.
wout

Response frequencies, returned as a row vector of frequency points.

Frequency values are in radians per TimeUnit, where TimeUnit is the
value of the TimeUnit property of sys.
sdmag

Estimated standard deviation of the magnitude. sdmag has the same

dimensions as mag.
If sys is not an identified LTI model, sdmag is [].
sdphase

Estimated standard deviation of the phase. sdphase has the same

dimensions as phase.
If sys is not an identified LTI model, sdphase is [].

Examples

Bode Plot of Dynamic System

Create Bode plot of the dynamic system:

H (s) =

1-30

s2 + 0.1s + 7.5
s4 + 0.12s3 + 9 s2

bode

H(s) is a continuous-time SISO system.

H = tf([1 0.1 7.5],[1 0.12 9 0 0]);
bode(H)

bode automatically selects the plot range based on the system dynamics.

Bode Plot at Specified Frequencies

Create Bode plot over a specified frequency range. Use this approach
when you want to focus on the dynamics in a particular range of
frequencies.
H = tf([1 0.1 7.5],[1 0.12 9 0 0]);
bode(H,{0.1,10})

The cell array {0.1,10} specifies the minimum and maximum

frequency values in the Bode plot.

1-31

bode

Alternatively, you can specify a vector of frequencies to use for

evaluating and plotting the frequency response.
w = logspace(-1,1,50);
bode(H,w)
logspace defines a logarithmically spaced frequency vector in the range

of 0.1-10 rad/s.
Compare Bode Plots of Several Dynamic Systems
Compare the frequency response of a continuous-time system to an
equivalent discretized system on the same Bode plot.
1 Create continuous-time and discrete-time dynamic systems.

H = tf([1 0.1 7.5],[1 0.12 9 0 0]);

Hd = c2d(H,0.5,'zoh');
2 Create Bode plot that includes both systems.

1-32

bode

bode(H,Hd)

Bode Plot with Specified Line and Marker Attributes

Specify the color, linestyle, or marker for each system in a Bode plot
using the PlotStyle input arguments.
H = tf([1 0.1 7.5],[1 0.12 9 0 0]);
Hd = c2d(H,0.5,'zoh');
H and Hd are two different systems.
bode(H,'r',Hd,'b--')

The string 'r' specifies a solid red line for the response of H. The string
'b--' specifies a dashed blue line for the response of Hd.

1-33

bode

Obtain Magnitude and Phase Data

Compute the magnitude and phase of the frequency response of a
dynamic system.
H = tf([1 0.1 7.5],[1 0.12 9 0 0]);
[mag phase wout] = bode(H);

Because H is a SISO model, the first two dimensions of mag and phase
are both 1. The third dimension is the number of frequencies in wout.
Bode Plot of Identified Model
Compare the frequency response of a parametric model, identified
from input/output data, to a non-parametric model identified using
the same data.
1 Identify parametric and non-parametric models based on data.

load iddata2 z2;

1-34

bode

w = linspace(0,10*pi,128);
sys_np = spa(z2,[],w);
sys_p = tfest(z2,2);
spa and tfest require System Identification Toolbox software.
sys_np is a non-parametric identified model. sys_p is a parametric

identified model.
2 Create a Bode plot that includes both systems.

bode(sys_np,sys_p,w);

Obtain Magnitude and Phase Standard Deviation Data of

Identified Model
Compute the standard deviation of the magnitude and phase of an
identified model. Use this data to create a 3 plot of the response
uncertainty.

1-35

bode

1 Identify a transfer function model based on data. Obtain the

standard deviation data for the magnitude and phase of the frequency
response.
load iddata2 z2;
sys_p = tfest(z2,2);
w = linspace(0,10*pi,128);
[mag,ph,w,sdmag,sdphase] = bode(sys_p,w);
tfest requires System Identification Toolbox software.
sys_p is an identified transfer function model.
sdmag and sdphase contain the standard deviation data for the

magnitude and phase of the frequency response, respectively.

2 Create a 3 plot corresponding to the confidence region.

mag = squeeze(mag);
sdmag = squeeze(sdmag);
semilogx(w,mag,'b',w,mag+3*sdmag,'k:',w,mag-3*sdmag,'k:');

1-36

bode

Algorithms

bode computes the frequency response using these steps:

1 Computes the zero-pole-gain (zpk) representation of the dynamic

system.
2 Evaluates the gain and phase of the frequency response based on the

zero, pole, and gain data for each input/output channel of the system.
a For continuous-time systems, bode evaluates the frequency

response on the imaginary axis s = j and considers only positive

frequencies.
b For discrete-time systems, bode evaluates the frequency response

on the unit circle. To facilitate interpretation, the command

parameterizes the upper half of the unit circle as

z e jTs ,

0 N

,
Ts

where Ts is the sampling time. N is the Nyquist frequency. The

equivalent continuous-time frequency is then used as the x-axis
variable. Because H (e jTs ) is periodic and has a period 2 N, bode
plots the response only up to the Nyquist frequency N. If you do
not specify a sampling time, bode uses Ts = 1.

Alternatives

Use bodeplot when you need additional plot customization options.

See Also

bodeplot | freqresp | nichols | nyquist

How To

Dynamic System Models

1-37

bodemag

Purpose

Bode magnitude response of LTI models

Syntax

bodemag(sys)
bodemag(sys,{wmin,wmax})
bodemag(sys,w)
bodemag(sys1,sys2,...,sysN,w)

Description

bodemag(sys) plots the magnitude of the frequency response of the

dynamic system model sys (Bode plot without the phase diagram). The
frequency range and number of points are chosen automatically.
bodemag(sys,{wmin,wmax}) draws the magnitude plot for frequencies
between wmin and wmax (in rad/TimeUnit, where TimeUnit is the time
units of the input dynamic system, specified in the TimeUnit property
of sys).
bodemag(sys,w) uses the user-supplied vector W of frequencies, in
rad/TimeUnit, at which the frequency response is to be evaluated.
bodemag(sys1,sys2,...,sysN,w) shows the frequency response
magnitude of several models sys1,sys2,...,sysN on a single plot. The
frequency vector w is optional. You can also specify a color, line style,
and marker for each model. For example:
bodemag(sys1,'r',sys2,'y--',sys3,'gx')

See Also

1-38

bode | ltiview

bodeoptions

Purpose

Create list of Bode plot options

Syntax

P = bodeoptions
P = bodeoptions('cstprefs')

Description

P = bodeoptions returns a list of available options for Bode plots with

default values set. You can use these options to customize the Bode plot
appearance using the command line.
P = bodeoptions('cstprefs') initializes the plot options with the
options you selected in the Control System Toolbox Preferences Editor.
For more information about the editor, see Toolbox Preferences Editor
in the Users Guide documentation.

The following table summarizes the Bode plot options.

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid

Show or hide the grid

Specified as one of the following strings: 'off' | 'on'
Default: 'off'

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

IOGrouping

Grouping of input-output pairs

Specified as one of the following strings: 'none'
|'inputs'|'output'|'all'
Default: 'none'

InputLabels,
OutputLabels

Input and output label styles

InputVisible,
OutputVisible

Visibility of input and output channels

1-39

bodeoptions

Option

Description

ConfidenceRegionNumberSD
Number of standard deviations to use to plotting the response
confidence region (identified models only).
Default: 1.
FreqUnits

Frequency units, specified as one of the following strings:

'Hz'
'rad/second'
'rpm'
'kHz'
'MHz'
'GHz'
'rad/nanosecond'
'rad/microsecond'
'rad/millisecond'
'rad/minute'
'rad/hour'
'rad/day'
'rad/week'
'rad/month'
'rad/year'
'cycles/nanosecond'
'cycles/microsecond'
'cycles/millisecond'
'cycles/hour'
'cycles/day'

1-40

bodeoptions

Option

Description
'cycles/week'
'cycles/month'
'cycles/year'
Default: 'rad/s'
You can also specify 'auto' which uses frequency units
rad/TimeUnit relative to system time units specified in the
TimeUnit property. For multiple systems with different time
units, the units of the first system are used.

FreqScale

Frequency scale
Specified as one of the following strings: 'linear' | 'log'
Default: 'log'

MagUnits

Magnitude units
Specified as one of the following strings: 'dB' | 'abs'
Default: 'dB'

MagScale

Magnitude scale
Specified as one of the following strings: 'linear' | 'log'
Default: 'linear'

MagVisible

Magnitude plot visibility

Specified as one of the following strings: 'on' | 'off'
Default: 'on'

MagLowerLimMode

Enables a lower magnitude limit

Specified as one of the following strings: 'auto' | 'manual'
Default: 'auto'

MagLowerLim

Specifies the lower magnitude limit

PhaseUnits

Phase units
Specified as one of the following strings: 'deg' | 'rad'
Default: 'deg'

1-41

bodeoptions

Option

Description

PhaseVisible

Phase plot visibility

Specified as one of the following strings: 'on' | 'off'
Default: 'on'

PhaseWrapping

Enables phase wrapping

Specified as one of the following strings: 'on' | 'off'
Default: 'off'

PhaseMatching

Enables phase matching

Specified as one of the following strings: 'on' | 'off'
Default: 'off'

PhaseMatchingFreq

Frequency for matching phase

PhaseMatchingValue

The value to which phase responses are matched closely

Examples

In this example, set phase visibility and frequency units in the Bode
plot options.
P = bodeoptions; % Set phase visiblity to off and frequency units to Hz in options
P.PhaseVisible = 'off';
P.FreqUnits = 'Hz'; % Create plot with the options specified by P
h = bodeplot(tf(1,[1,1]),P);

The following plot is created, with the phase plot visibility turned off
and the frequency units in Hz.

1-42

bodeoptions

See Also

bode | bodeplot | getoptions | setoptions

1-43

bodeplot

Purpose

Plot Bode frequency response with additional plot customization options

Syntax

h = bodeplot(sys)
bodeplot(sys)
bodeplot(sys1,sys2,...)
bodeplot(AX,...)
bodeplot(..., plotoptions)
bodeplot(sys,w)

Description

h = bodeplot(sys) plot the Bode magnitude and phase of the dynamic

system model sys and returns the plot handle h to the plot. You can use
this handle to customize the plot with the getoptions and setoptions
commands.
bodeplot(sys) draws the Bode plot of the model sys. The frequency
range and number of points are chosen automatically.
bodeplot(sys1,sys2,...) graphs the Bode response of multiple
models sys1,sys2,... on a single plot. You can specify a color, line style,
and marker for each model, as in
bodeplot(sys1,'r',sys2,'y--',sys3,'gx')
bodeplot(AX,...) plots into the axes with handle AX.
bodeplot(..., plotoptions) plots the Bode response with the options
specified in plotoptions. Type
help bodeoptions

for a list of available plot options. See Example 2 on page 1-45 for
an example of phase matching using the PhaseMatchingFreq and
PhaseMatchingValue options.
bodeplot(sys,w) draws the Bode plot for frequencies specified by w.
When w = {wmin,wmax}, the Bode plot is drawn for frequencies between
wmin and wmax (in rad/TimeUnit, where TimeUnit is the time units of

the input dynamic system, specified in the TimeUnit property of sys.).

1-44

bodeplot

When w is a user-supplied vector w of frequencies, in rad/TimeUnit, the

Bode response is drawn for the specified frequencies.
See logspace to generate logarithmically spaced frequency vectors.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Use the plot handle to change options in a Bode plot.
sys = rss(5);
h = bodeplot(sys);
% Change units to Hz and make phase plot invisible
setoptions(h,'FreqUnits','Hz','PhaseVisible','off');

Example 2
The properties PhaseMatchingFreq and PhaseMatchingValue are
parameters you can use to specify the phase at a specified frequency.
For example, enter the following commands.
sys = tf(1,[1 1]);
h = bodeplot(sys) % This displays a Bode plot.

1-45

bodeplot

Use this code to match a phase of 750 degrees to 1 rad/s.

p = getoptions(h);
p.PhaseMatching = 'on';
p.PhaseMatchingFreq = 1;
p.PhaseMatchingValue = 750; % Set the phase to 750 degrees at 1
% rad/s.
setoptions(h,p); % Update the Bode plot.

1-46

bodeplot

The first bode plot has a phase of -45 degrees at a frequency of 1 rad/s.
Setting the phase matching options so that at 1 rad/s the phase is near
750 degrees yields the second Bode plot. Note that, however, the phase
can only be -45 + N*360, where N is an integer, and so the plot is set to
the nearest allowable phase, namely 675 degrees (or 2*360 - 45 = 675).

Example 3
Compare the frequency responses of identified state-space models of
order 2 and 6 along with their 2 std confidence regions.
load iddata1
sys1 = n4sid(z1, 2) % discrete-time IDSS model of order 2
sys2 = n4sid(z1, 6) % discrete-time IDSS model of order 6

Both models produce about 76% fit to data. However, sys2 shows
higher uncertainty in its frequency response, especially close to Nyquist
frequency as shown by the plot:

1-47

bodeplot

w = linspace(8,10*pi,256);
h = bodeplot(sys1,sys2,w);
setoptions(h, 'PhaseMatching', 'on', 'ConfidenceRegionNumberSD', 2);

Use the context menu by right-clicking Characteristics > Confidence

Region to turn on the confidence region characteristic.

Example 4
Compare the frequency response of a parametric model, identified
from input/output data, to a nonparametric model identified using
the same data.
1 Identify parametric and non-parametric models based on data.

load iddata2 z2;

w = linspace(0,10*pi,128);
sys_np = spa(z2,[],w);
sys_p = tfest(z2,2);
spa and tfest require System Identification Toolbox software.
sys_np is a non-parametric identified model. sys_p is a parametric

identified model.
2 Create a Bode plot that includes both systems.

opt = bodeoptions; opt.PhaseMatching = 'on';

bodeplot(sys_np,sys_p,w, opt);

See Also

1-48

bode | bodeoptions | getoptions | setoptions

c2d

Purpose

Convert model from continuous to discrete time

Syntax

sysd = c2d(sys,Ts)
sysd = c2d(sys,Ts,method)
sysd = c2d(sys,Ts,opts)
[sysd,G] = c2d(sys,Ts,method)
[sysd,G] = c2d(sys,Ts,opts)

Description

sysd = c2d(sys,Ts) discretizes the continuous-time dynamic system

model sys using zero-order hold on the inputs and a sample time of
Ts seconds.
sysd = c2d(sys,Ts,method) discretizes sys using the specified

discretization method method.

sysd = c2d(sys,Ts,opts) discretizes sys using the option set opts,
specified using the c2dOptions command.
[sysd,G] = c2d(sys,Ts,method) returns a matrix, G that maps the

continuous initial conditions x0 and u0 of the state-space model sys to

the discrete-time initial state vector x [0]. method is optional. To specify
additional discretization options, use [sysd,G] = c2d(sys,Ts,opts).

Tips

Use the syntax sysd = c2d(sys,Ts,method) to discretize sys using

the default options for method. To specify additional discretization
options, use the syntax sysd = c2d(sys,Ts,opts).
To specify the tustin method with frequency prewarping (formerly
known as the 'prewarp' method), use the PrewarpFrequency option
of c2dOptions.

Input
Arguments

sys

Continuous-time dynamic system model (except frequency response

data models). sys can represent a SISO or MIMO system, except that
the 'matched' discretization method supports SISO systems only.

1-49

c2d

sys can have input/output or internal time delays; however, the

'matched' and 'impulse' methods do not support state-space models
with internal time delays.
The following identified linear systems cannot be discretized directly:
idgrey models with FcnType is 'c'. Convert to idss model first.
idproc models. Convert to idtf or idpoly model first.
For the syntax [sysd,G] = c2d(sys,Ts,opts), sys must be a
state-space model.
Ts

Sample time.
method

String specifying a discretization method:

'zoh' Zero-order hold (default). Assumes the control inputs are
piecewise constant over the sampling period Ts.
'foh' Triangle approximation (modified first-order hold). Assumes
the control inputs are piecewise linear over the sampling period Ts.
'impulse' Impulse invariant discretization.
'tustin' Bilinear (Tustin) method.
'matched' Zero-pole matching method.
For more information about discretization methods, see
Continuous-Discrete Conversion Methods.
opts

Discretization options. Create opts using c2dOptions.

Output
Arguments

1-50

sysd

Discrete-time model of the same type as the input system sys.

c2d

When sys is an identified (IDLTI) model, sysd:

Includes both measured and noise components of sys. The
innovations variance of the continuous-time identified model sys,
stored in its NoiseVarianceproperty, is interpreted as the intensity
of the spectral density of the noise spectrum. The noise variance in
sysd is thus /Ts.
Does not include the estimated parameter covariance of sys. If you
want to translate the covariance while discretizing the model, use
translatecov.
G

Matrix relating continuous-time initial conditions x0 and u0 of the

state-space model sys to the discrete-time initial state vector x [0],
as follows:

x0
x [ 0] = G
u0
For state-space models with time delays, c2d pads the matrix G with
zeroes to account for additional states introduced by discretizing those
delays. See Continuous-Discrete Conversion Methods for a discussion
of modeling time delays in discretized systems.

Examples

Discretize the continuous-time transfer function:

H ( s) =

s 1
2

s + 4s + 5

with input delay Td = 0.35 second. To discretize this system using the
triangle (first-order hold) approximation with sample time Ts = 0.1
second, type
H = tf([1 -1], [1 4 5], 'inputdelay', 0.35);
Hd = c2d(H, 0.1, 'foh'); % discretize with FOH method and
% 0.1 second sample time

1-51

c2d

Transfer function:
0.0115 z^3 + 0.0456 z^2 - 0.0562 z - 0.009104
--------------------------------------------z^6 - 1.629 z^5 + 0.6703 z^4
Sampling time: 0.1

The next command compares the continuous and discretized step

responses.
step(H,'-',Hd,'--')

Discretize the delayed transfer function

1-52

c2d

H ( s ) = e0.25 s

10
2

s + 3s + 10

using zero-order hold on the input, and a 10-Hz sampling rate.

h = tf(10,[1 3 10],'iodelay',0.25); % create transfer function
hd = c2d(h, 0.1) % zoh is the default method

These commands produce the discrete-time transfer function

Transfer function:
0.01187 z^2 + 0.06408 z + 0.009721
z^(-3) * ---------------------------------z^2 - 1.655 z + 0.7408
Sampling time: 0.1

In this example, the discretized model hd has a delay of three sampling

periods. The discretization algorithm absorbs the residual half-period
delay into the coefficients of hd.
Compare the step responses of the continuous and discretized models
using
step(h,'--',hd,'-')

1-53

c2d

Discretize a state-space model with time delay, using a Thiran filter

to model fractional delays:
sys = ss(tf([1, 2], [1, 4, 2]));
sys.InputDelay = 2.7

%
%

create a state-space model

add input delay

This command creates a continuous-time state-space model with two

states, as the output shows:
a =
x1
x2

x1
-4
1

b =
u1

1-54

x2
-2
0

c2d

x1
x2

2
0

y1

x1
0.5

y1

u1
0

c =
x2
1

d =

Input delays (listed by channel): 2.7

Continuous-time model.

Use c2dOptions to create a set of discretization options, and discretize

the model. This example uses the Tustin discretization method.
opt = c2dOptions('Method', 'tustin', 'FractDelayApproxOrder', 3);
sysd1 = c2d(sys, 1, opt)
% 1s sampling time

These commands yield the result

a =
x1
x2
x3
x4
x5

x1
-0.4286
0.2857
0
0
0

x2
-0.5714
0.7143
0
0
0

x3
-0.00265
-0.001325
-0.2432
0.25
0

x4
0.06954
0.03477
0.1449
0
0.125

x5
2.286
1.143
-0.1153
0
0

b =
x1
x2
x3
x4
x5

u1
0.002058
0.001029
8
0
0

1-55

c2d

c =
y1

x1
0.2857

x2
0.7143

x3
-0.001325

x4
0.03477

x5
1.143

d =
y1

u1
0.001029

Sampling time: 1
Discrete-time model.

The discretized model now contains three additional states x3, x4,
and x5 corresponding to a third-order Thiran filter. Since the time
delay divided by the sampling time is 2.7, the third-order Thiran filter
(FractDelayApproxOrder = 3) can approximate the entire time delay.
Discretize an identified, continuous-time transfer function and compare
its performance against a directly estimated discrete-time model
Estimate a continuous-time transfer function and discretize it.
load iddata1
sys1c = tfest(z1, 2);
sys1d = c2d(sys1c, 0.1, 'zoh');

Estimate a second order discrete-time transfer function.

sys2d = tfest(z1, 2, 'Ts', 0.1);

Compare the two models.

compare(z1, sys1d, sys2d)

1-56

c2d

The two systems are virtually identical.

Discretize an identified state-space model to build a one-step ahead
predictor of its response.
load iddata2
sysc = ssest(z2, 4);
sysd = c2d(sysc, 0.1, 'zoh');
[A,B,C,D,K] = idssdata(sysd);
Predictor = ss(A-K*C, [K B-K*D], C, [0 D], 0.1);

The Predictor is a two input model which uses the measured output
and input signals ([z1.y z1.u]) to compute the 1-steap predicted
response of sysc.

Algorithms

For information about the algorithms for each c2d conversion method,
see Continuous-Discrete Conversion Methods.

1-57

c2d

See Also

c2dOptions | d2c | d2d | thiran | translatecov

How To

Dynamic System Models

Discretize a Compensator
Continuous-Discrete Conversion Methods

1-58

c2dOptions

Purpose

Create option set for continuous- to discrete-time conversions

Syntax

opts = c2dOptions
opts = c2dOptions('OptionName', OptionValue)

Description

opts = c2dOptions returns the default options for c2d.

opts = c2dOptions('OptionName', OptionValue) accepts one or

more comma-separated name/value pairs that specify options for the

c2d command. Specify OptionName inside single quotes.

Input
Arguments

Name-Value Pair Arguments

Method

Discretization method, specified as one of the following values:

'zoh'

Zero-order hold, where c2d assumes the control inputs

are piecewise constant over the sampling period Ts.

'foh'

Triangle approximation (modified first-order hold),

where c2d assumes the control inputs are piecewise
linear over the sampling period Ts. (See [1], p. 228.)

'impulse'

Impulse-invariant discretization.

'tustin'

Bilinear (Tustin) approximation. By default, c2d

discretizes with no prewarp and rounds any fractional
time delays to the nearest multiple of the sample
time. To include prewarp, use the PrewarpFrequency
option. To approximate fractional time delays, use
theFractDelayApproxOrder option.

'matched'

Zero-pole matching method. (See [1], p. 224.) By

default, c2d rounds any fractional time delays
to the nearest multiple of the sample time. To
approximate fractional time delays, use the
FractDelayApproxOrder option.

1-59

c2dOptions

Default: 'zoh'
PrewarpFrequency

Prewarp frequency for 'tustin' method, specified in rad/TimeUnit,

where TimeUnit is the time units, specified in the TimeUnit property,
of the discretized system. Takes positive scalar values. A value of 0
corresponds to the standard 'tustin' method without prewarp.
Default: 0
FractDelayApproxOrder

Maximum order of the Thiran filter used to approximate fractional

delays in the 'tustin' and 'matched' methods. Takes integer values.
A value of 0 means that c2d rounds fractional delays to the nearest
integer multiple of the sample time.
Default: 0

Examples

Discretize two models using identical discretization options.

% generate two arbitrary continuous-time state-space models
sys1 = rss(3, 2, 2);
sys2 = rss(4, 4, 1);

Use c2dOptions to create a set of discretization options.

opt = c2dOptions('Method', 'tustin', 'PrewarpFrequency', 3.4);

Then, discretize both models using the option set.

dsys1 = c2d(sys1, 0.1, opt);
dsys2 = c2d(sys2, 0.2, opt);

% 0.1s sampling time

% 0.2s sampling time

The c2dOptions option set does not include the sampling time Ts. You
can use the same discretization options to discretize systems using a
different sampling time.

1-60

c2dOptions

References

[1] Franklin, G.F., Powell, D.J., and Workman, M.L., Digital Control of
Dynamic Systems (3rd Edition), Prentice Hall, 1997.

See Also

c2d

1-61

canon

Purpose

State-space canonical realization

Syntax

csys = canon(sys,type)
[csys,T]= canon(sys,type)
csys = canon(sys,'modal',condt)

Description

csys = canon(sys,type) transforms the linear model sys into a

canonical state-space model csys. The argument type specifies

whether csys is in modal or companion form.
[csys,T]= canon(sys,type) also returns the state-coordinate
transformation T that relates the states of the state-space model sys to
the states of csys.
csys = canon(sys,'modal',condt) specifies an upper bound condt
on the condition number of the block-diagonalizing transformation.

Input
Arguments

sys

Any linear dynamic system model, except for frd models.

type

String specifying the type of canonical form of csys. type can take
one of the two following values:
'modal' convert sys to modal form.
'companion' convert sys to companion form.
condt

Positive scalar value specifying an upper bound on the condition

number of the block-diagonalizing transformation that converts sys to
csys. This argument is available only when type is 'modal'.
Increase condt to reduce the size of the eigenvalue clusters in the A
matrix of csys. Setting condt = Inf diagonalizes A.
Default: 1e8

1-62

canon

Output
Arguments

csys

State-space (ss) model. csys is a state-space realization of sys in the

canonical form specified by type.
T

Matrix specifying the transformation between the state vector x of the

state-space model sys and the state vector xc of csys:
xc = Tx
.
This argument is available only when sys is state-space model.

Definitions

Modal Form
In modal form, A is a block-diagonal matrix. The block size is typically
1-by-1 for real eigenvalues and 2-by-2 for complex eigenvalues.
However, if there are repeated eigenvalues or clusters of nearby
eigenvalues, the block size can be larger.
For example, for a system with eigenvalues (1 , j, 2 ) , the modal A
matrix is of the form

1
0

0
0

0 0 2
0

Companion Form
In the companion realization, the characteristic polynomial of the
system appears explicitly in the rightmost column of the A matrix. For
a system with characteristic polynomial

p(s) = sn + 1 sn 1 + + n 1 s + n

1-63

canon

the corresponding companion A matrix is

0
1

0
A=
:
0

0 .. .. 0
n
0 0 .. 0 n 1

1 0 . :
:

0 . . :
:
2
. . 1 0

1
.. .. 0 1

The companion transformation requires that the system be controllable

from the first input. The companion form is poorly conditioned for most
state-space computations; avoid using it when possible.

Examples

This example uses canon to convert a system having doubled poles and
clusters of close poles to modal canonical form.
Consider the system G having the following transfer function:

G ( s ) = 100

( s 1) ( s + 1)
.
2
2
s ( s + 10 ) ( s + 10.0001) ( s (1 + i ) ) ( s (1 i ) )

To create a linear model of this system and convert it to modal canonical

form, enter:
G = zpk([1 -1],[0 -10 -10.0001 1+1i 1-1i 1+1i 1-1i],100);
Gc = canon(G,'modal');

The system G has a pair of nearby poles at s = 10 and s = 10.0001. G

also has two complex poles of multiplicity 2 at s = 1 + i and s = 1 i.
As a result, the modal form, has a block of size 2 for the two poles near
s = 10, and a block of size 4 for the complex eigenvalues. To see this,
enter the following command:
Gc.A
ans =

1-64

canon

1.0000

1.0000

-1.0000

1.0000

2.0548

1.0000

1.0000

-1.0000

1.0000

-10.0000

8.0573

-10.0001

To separate the two poles near s = 10, you can increase the value of
condt. For example:
Gc2 = canon(G,'modal',1e10);
Gc2.A
ans =
0

1.0000

1.0000

-1.0000

1.0000

2.0548

1.0000

1.0000

-1.0000

1.0000

-10.0000

-10.0001

The A matrix of Gc2 includes separate diagonal elements for the poles
near s = 10. The cost of increasing the maximum condition number of
A is that the B matrix includes some large values.
format shortE
Gc2.B
ans =
3.2000e-001
-6.5691e-003
5.4046e-002
-1.9502e-001

1-65

canon

1.0637e+000
3.2533e+005
3.2533e+005

This example estimates a state-space model that is freely parameterized

and convert to companion form after estimation.
load icEngine.mat
z = iddata(y,u,0.04);
FreeModel = n4sid(z,4,'InputDelay',2);
CanonicalModel = canon(FreeModel, 'companion')

Obtain the covariance of the resulting form by running a zero-iteration

update to model parameters.
opt = ssestOptions; opt.SearchOption.MaxIter = 0;
CanonicalModel = ssest(z, CanonicalModel, opt)

Compare frequency response confidence bounds of FreeModel to

CanonicalModel.
h = bodeplot(FreeModel, CanonicalModel)

the bounds are identical.

Algorithms

The canon command uses the bdschur command to convert sys into
modal form and to compute the transformation T. If sys is not a
state-space model, the algorithm first converts it to state space using ss.
The reduction to companion form uses a state similarity transformation
based on the controllability matrix [1].

1-66

References

[1] Kailath, T. Linear Systems, Prentice-Hall, 1980.

See Also

ctrb | ctrbf | ss2ss

care

Purpose

Continuous-time algebraic Riccati equation solution

Syntax

[X,L,G] = care(A,B,Q)
[X,L,G] = care(A,B,Q,R,S,E)
[X,L,G,report] = care(A,B,Q,...)
[X1,X2,D,L] = care(A,B,Q,...,'factor')

Description

[X,L,G] = care(A,B,Q) computes the unique solution X of the

continuous-time algebraic Riccati equation

AT X + XA XBBT X + Q = 0
The care function also returns the gain matrix, G = R1 BT XE .
[X,L,G] = care(A,B,Q,R,S,E) solves the more general Riccati

equation

AT XE + ET XA ( ET XB + S) R1 ( BT XE + ST ) + Q = 0
When omitted, R, S, and E are set to the default values R=I, S=0,
and E=I. Along with the solution X, care returns the gain matrix

G = R1 ( BT XE + ST ) and a vector L of closed-loop eigenvalues, where

L=eig(A-B*G,E)
[X,L,G,report] = care(A,B,Q,...) returns a diagnosis report with:

-1 when the associated Hamiltonian pencil has eigenvalues on or

very near the imaginary axis (failure)
-2 when there is no finite stabilizing solution X
The Frobenius norm of the relative residual if X exists and is finite.
This syntax does not issue any error message when X fails to exist.
[X1,X2,D,L] = care(A,B,Q,...,'factor') returns two matrices X1,
X2 and a diagonal scaling matrix D such that X = D*(X2/X1)*D.

1-67

care

The vector L contains the closed-loop eigenvalues. All outputs are

empty when the associated Hamiltonian matrix has eigenvalues on
the imaginary axis.

Examples

Example 1
Solve Algebraic Riccati Equation
Given

3 2
A=

1 1

0
B=
1

C = [1 1]

R=3

you can solve the Riccati equation

AT X + XA XBR1 BT X + C T C = 0
by
a = [-3 2;1 1]
b = [0 ; 1]
c = [1 -1]
r = 3
[x,l,g] = care(a,b,c'*c,r)

This yields the solution

x
x =
0.5895
1.8216

1.8216
8.8188

You can verify that this solution is indeed stabilizing by comparing

the eigenvalues of a and a-b*g.
[eig(a)

1-68

eig(a-b*g)]

care

ans =
-3.4495
1.4495

-3.5026
-1.4370

Finally, note that the variable l contains the closed-loop eigenvalues

eig(a-b*g).
l
l =
-3.5026
-1.4370

Example 2
Solve H-infinity ( H )-like Riccati Equation
To solve the H -like Riccati equation

AT X + XA + X ( 2 B1 B1T B2 B2T ) X + C T C = 0
rewrite it in the care format as

2 I 0
AT X + XA X [ B1 , B2 ]

0
I

B1T

X + CT C = 0
T
B2

You can now compute the stabilizing solution X by

B = [B1 , B2]
m1 = size(B1,2)
m2 = size(B2,2)
R = [-g^2*eye(m1) zeros(m1,m2) ; zeros(m2,m1) eye(m2)]
X = care(A,B,C'*C,R)

1-69

care

Algorithms

care implements the algorithms described in [1]. It works with the

Hamiltonian matrix when R is well-conditioned and E = I ; otherwise it

uses the extended Hamiltonian pencil and QZ algorithm.

Limitations

The ( A, B) pair must be stabilizable (that is, all unstable modes are
controllable). In addition, the associated Hamiltonian matrix or pencil
must have no eigenvalue on the imaginary axis. Sufficient conditions
for this to hold are (Q, A) detectable when S = 0 and R > 0 , or

Q
T
S

1-70

S
>0
R

References

[1] Arnold, W.F., III and A.J. Laub, "Generalized Eigenproblem

Algorithms and Software for Algebraic Riccati Equations," Proc. IEEE,
72 (1984), pp. 1746-1754

See Also

dare | lyap

chgFreqUnit

Purpose

Change frequency units of frequency-response data model

Syntax

sys_new = chgFreqUnit(sys,newfrequnits)

Description

sys_new = chgFreqUnit(sys,newfrequnits) changes units of the

frequency points in sys to newfrequnits. Both Frequency and
FrequencyUnit properties of sys adjust so that the frequency responses

of sys and sys_new match.

Tips

Use chgFreqUnit to change the units of frequency points without

modifying system behavior.

Input
Arguments

sys

Frequency-response data (frd, idfrd, or genfrd) model

newfrequnits

New units of frequency points, specified as one of the following strings:

'rad/TimeUnit'
'cycles/TimeUnit'
'rad/s'
'Hz'
'kHz'
'MHz'
'GHz'
'rpm'
rad/TimeUnit and cycles/TimeUnit express frequency units relative
to the system time units specified in the TimeUnit property.

Default: 'rad/TimeUnit'

1-71

chgFreqUnit

Output
Arguments

sys_new

Examples

This example shows how to change units of the frequency points in a

frequency-response data model.

Frequency-response data model of the same type as sys with new units
of frequency points. The frequency response of sys_new is same as sys.

1 Create a frequency-response data model.

load AnalyzerData;
sys = frd(resp,freq);

The data file AnalyzerData has column vectors freq and resp.
These vectors contain 256 test frequencies and corresponding
complex-valued frequency response points, respectively. The default
frequency units of sys is rad/TimeUnit, where TimeUnit is the
system time units.
2 Change the frequency units.

sys1 = chgFreqUnit(sys,'rpm');

The FrequencyUnit property of sys1 is rpm.

3 Compare the Bode responses of sys and sys1.

bode(sys,'r',sys1,'y--');
legend('sys','sys1')

The magnitude and phase of sys and sys1 match.

1-72

chgFreqUnit

4 (Optional) Change the FrequencyUnit property of sys to compare

the Bode response with the original system.

sys2=sys;
sys2.FrequencyUnit = 'rpm';
bode(sys,'r',sys2,'gx');
legend('sys','sys2');

Changing the FrequencyUnit property changes the original system.

Therefore, the Bode responses of sys and sys2 do not match. For
example, the original corner frequency at 2 rad/s changes to 2 rpm
(or 0.2 rad/s).

1-73

chgFreqUnit

See Also

chgTimeUnit | frd

Tutorials

Specify Frequency Units of Frequency-Response Data Model1

1.

1-74

chgTimeUnit

Purpose

Change time units of dynamic system

Syntax

sys_new = chgTimeUnit(sys,newtimeunits)

Description

sys_new = chgTimeUnit(sys,newtimeunits) changes the time

units of sys to newtimeunits. The time- and frequency-domain
characteristics of sys and sys_new match.

Tips

Use chgTimeUnit to change the time units without modifying system

behavior.

Input
Arguments

sys

Dynamic system model

newtimeunits

New time units, specified as one of the following strings:

'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Default: 'seconds'

1-75

chgTimeUnit

Output
Arguments

sys_new

Dynamic system model of the same type as sys with new time units.
The time response of sys_new is same as sys.
If sys is an identified linear model, both the model parameters as and
their minimum and maximum bounds are scaled to the new time units.

Examples

This example shows how to change the time units of a transfer function
model.
1 Create a transfer function model.

num = [4 2];
den = [1 3 10];
sys = tf(num,den);

The default time units of sys is seconds.

2 Change the time units.

sys1 = chgTimeUnit(sys,'minutes');

The TimeUnit property of sys1 is milliseconds.

3 Compare the step responses of sys and sys1.

step(sys,'r',sys1,'y--');
legend('sys','sys1');

1-76

chgTimeUnit

The step responses of sys and sys1 match.

4 (Optional) Change the TimeUnit property of sys, and compare the

step response with the original system.

sys2=sys;
sys2.TimeUnit = 'minutes';
step(sys,'r', sys2,'gx');
legend('sys','sys2');

Changing the TimeUnit property changes the original system.

Therefore, the step responses of sys and sys2 do not match. For
example, the original rise time of 0.04 seconds changes to 0.04
minutes.

1-77

chgTimeUnit

1-78

See Also

chgFreqUnit | tf | zpk | ss | frd | pid

Tutorials

Specify Model Time Units

conj

Purpose

Form model with complex conjugate coefficients

Syntax

sysc = conj(sys)

Description

sysc = conj(sys) constructs a complex conjugate model sysc by

applying complex conjugation to all coefficients of the LTI model
sys. This function accepts LTI models in transfer function (TF),
zero/pole/gain (ZPK), and state space (SS) formats.

Examples

If sys is the transfer function

(2+i)/(s+i)

then conj(sys) produces the transfer function

(2-i)/(s-i)

This operation is useful for manipulating partial fraction expansions.

See Also

append | ss | tf | zpk

1-79

connect

Purpose

Block diagram interconnections of dynamic systems

Syntax

sysc = connect(sys1,...,sysN,inputs,outputs)
sysc = connect(blksys,connections,inputs,outputs)
sysc = connect( ___ ,opts)

Description

sysc = connect(sys1,...,sysN,inputs,outputs) connects the

block diagram elements sys1,...,sysN based on signal names. The

block diagram elements sys1,...,sysN are dynamic system models.
These models can include summing junctions you create using sumblk.
The connect command interconnects the block diagram elements by
matching the input and output signals you specify in the InputName
and OutputName properties of sys1,...,sysN. The aggregate model
sysc is a dynamic system model having inputs and outputs specified by
inputs and outputs respectively.
sysc = connect(blksys,connections,inputs,outputs) uses
index-based interconnection to build sysc out of an aggregate,
unconnected model blksys. The matrix connections specifies how
the outputs and inputs of blksys interconnect. For index-based
interconnections, inputs and outputs are index vectors that specify
which inputs and outputs of blksys are the external inputs and
outputs of sysc. This syntax is not recommended.
sysc = connect( ___ ,opts) builds the interconnected model using
additional options. You can use opts with the input arguments of
either of the previous syntaxes.

Input
Arguments

1-80

sys1,...,sysN

Dynamic system models corresponding to the elements of your block

diagram. For example, the elements of your block diagram can include
one or more tf or ss model representing plant dynamics. Block diagram
elements can also include a pid or ltiblock.pid model representing
a controller. You can also include one or more summing junction you
create using sumblk. Provide multiple arguments sys1,...,sysN to
represent all of the block diagram elements and summing junctions.

connect

inputs

For name-based interconnection, a string or cell array of strings

specifying the inputs of the aggregate model sysc. The strings in
inputs must correspond to entries in the InputName or OutputName
property of one or more of the block diagram elements sys1,...,sysN.
outputs

For name-based interconnection, a string or cell array of strings

specifying the outputs of the aggregate model sysc. The strings in
outputs must correspond to entries in the OutputName property of one
or more of the block diagram elements sys1,...,sysN.
blksys

Unconnected aggregate model. To obtain blksys, use append to join

dynamic system models of the elements of your block diagram. For
example, if your block diagram contains dynamic system models C, G,
and S, create blksys with the following command:
blksys = append(C,G,S)
connections

Matrix specifying the connections and summing junctions of the block

diagram. Each row of connections specifies one connection or
summing junction in terms of the input vector u and output vector y of
the unconnected aggregate model blksys. For example, the row:
[3 2 0 0]

specifies that y(2) connects into u(3). The row

[7 2 -15 6]

indicates that y(2)-y(15)+y(6) feeds into u(7).

If you do not specify any connection for a particular input or output,
connect omits that input or output from the aggregate model.

1-81

connect

opts

Additional options for interconnection, specified as an options set you

create with connectOptions.

Output
Arguments

sysc

Interconnected system, returned as either a state-space model or

frequency-response model. The type of model returned depends on the
input models. For example:
Interconnecting numeric LTI models (other than frd models) returns
an ss model.
Interconnecting a numeric LTI model with a Control Design Block
returns a generalized LTI model. For instance, interconnecting a tf
model with an ltiblock.pid Control Design Block returns a genss.
Interconnecting any model with frequency-response data model
returns a frequency response data model.
By default, connect automatically discards states that do not contribute
to the I/O transfer function from the specified inputs to the specified
outputs of the interconnected model. To retain the unconnected states,
set the Simplify option of connectOptions to false. For example:
opt = connectOptions('Simplify',false);
sysc = connect(sys1,sys2,sys3,'r','y',opt);

Examples

SISO Feedback Loop

Create an aggregate model of the following block diagram from r to y.

Create C and G, and name the inputs and outputs.

1-82

connect

C =
C.u
G =
G.u

pid(2,1);
= 'e'; C.y = 'u';
zpk([],[-1,-1],1);
= 'u'; G.y = 'y';

The notations C.u and C.y are shorthand expressions equivalent to

C.InputName and C.OutputName, respectively. For example, entering
C.u = 'e' is equivalent to entering C.InputName = 'e'. The command
sets the InputName property of C to the value 'e'.
Create the summing junction.
Sum = sumblk('e = r - y');

Combine C, G, and the summing junction to create the aggregate model

from r to y.
T = connect(G,C,Sum,'r','y');
connect automatically joins inputs and outputs with matching names.

MIMO Feedback Loop

Create the control system of the previous example where G and C are
both 2-input, 2-output models.
C = [pid(2,1),0;0,pid(5,6)];
C.InputName = 'e'; C.OutputName = 'u';
G = ss(-1,[1,2],[1;-1],0);
G.InputName = 'u'; G.OutputName = 'y';

When you specify single names for vector-valued signals, the software
automatically performs vector expansion of the signal names. For
example, examine the names of the inputs to C.
C.InputName
ans =

1-83

connect

'e(1)'
'e(2)'

Create a 2-input, 2-output summing junction.

Sum = sumblk('e = r-y',2);
sumblk also performs vector expansion of the signal names.

Interconnect the models to obtain the closed-loop system.

T = connect(G,C,Sum,'r','y');

The block diagram elements G, C, and Sum are all 2-input, 2-output
models. Therefore, connect performs the same vector expansion.
connect selects all entries of the two-input signals 'r' and 'y' as
inputs and outputs to T, respectively. For example, examine the input
names of T.
T.InputName
ans =
'r(1)'
'r(2)'

Index-Based Interconnection
Create an aggregate model of the following block diagram from r to y
using index-based interconnection.

Create C, G, and the unconnected aggregate model blksys.

1-84

connect

C = pid(2,1);
G = zpk([],[-1,-1],1);
blksys = append(C,G);

The inputs u(1),u(2) of blksys correspond to the inputs of C and

G, respectively. The outputs w(1),w(2) of blksys correspond to the
outputs of C and G, respectively.
Create the matrix connections, which specifies which outputs of
blksys connect to which inputs of blksys.
connections = [2 1; 1 -2];

The first row indicates that w(1) connects to u(2); in other words, that
the output of C connects to the input of G. The second row indicates
that -w(2) connects to u(1); in other words, that the negative of the
output of G connects to the input of C.
Create the connected aggregate model from r to y.
T = connect(blksys,connections,1,2)

The last two arguments specify the external inputs and outputs in
terms of the indices of blksys. 1 specifies that the external input
connects to u(1). The last argument, 2, specifies that the external
output connects from w(2).

See Also

sumblk | | append | feedback | parallel | series | lft |

connectOptions

How To

Multi-Loop Control System

MIMO Control System
MIMO Feedback Loop

1-85

connectOptions

Purpose

Options for the connect command

Syntax

opt = connectOptions
opt = connectOptions(Name,Value)

Description

opt = connectOptions returns the default options for connect.

opt = connectOptions(Name,Value) returns an options set with the
options specified by one or more Name,Value pair arguments.

Input
Arguments

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments.
Name is the argument name and Value is the corresponding
value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
Example: 'Simplify',false
Simplify - Automatic elimination of unconnected states
true (default) | false

Automatic elimination of unconnected states, specified as either true or

false.
true connect eliminates all states that do not contribute to the I/O
transfer function from the specified inputs to the specified outputs of
the interconnected system.
false connect retains unconnected states. This option can be
useful, for example, when you want to compute the interconnected
system response from known initial state values of the components.
Data Types
logical

1-86

connectOptions

Output
Arguments

opt - Options for connect

connectOptions options set

Options for connect, returned as a connectOptions options set. Use

opt as the last argument to connect when interconnecting models.

Examples

Retain Unconnected States in Model Interconnection

Use connectOptions to cause the connect command to retain
unconnected states in an interconnected model.
Suppose you have dynamic system models sys1, sys2, and sys3.
Combine these dynamic system models to build an interconnected
model with input 'r' and output 'y'. Set the option to retain states
in the model that do not contribute to the dynamics in the path from
'r' or 'y'.
opt = connectOptions('Simplify',false);
sysc = connect(sys1,sys2,sys3,'r','y',opt);

See Also

connect

1-87

covar

Purpose

Output and state covariance of system driven by white noise

Syntax

P = covar(sys,W)
[P,Q] = covar(sys,W)

Description

covar calculates the stationary covariance of the output y of an LTI

model sys driven by Gaussian white noise inputs w. This function
handles both continuous- and discrete-time cases.
P = covar(sys,W) returns the steady-state output response covariance

P = E( yyT )
given the noise intensity

E(w(t)w( )T ) = W (t ) (continuous time)

E(w [ k] w [ l] ) = W kl
T

(disccrete time)

[P,Q] = covar(sys,W) also returns the steady-state state covariance

Q = E( xxT )
when sys is a state-space model (otherwise Q is set to []).
When applied to an N-dimensional LTI array sys, covar returns
multidimensional arrays P, Q such that
P(:,:,i1,...iN) and Q(:,:,i1,...iN) are the covariance matrices
for the model sys(:,:,i1,...iN).

Examples

Compute the output response covariance of the discrete SISO system

H ( z) =

2z + 1
2

z + 0.2 z + 0.5

, Ts = 0.1

due to Gaussian white noise of intensity W = 5. Type

1-88

covar

sys = tf([2 1],[1 0.2 0.5],0.1);

p = covar(sys,5)

These commands produce the following result.

p =
30.3167

You can compare this output of covar to simulation results.

randn('seed',0)
w = sqrt(5)*randn(1,1000);

% 1000 samples

% Simulate response to w with LSIM:

y = lsim(sys,w);
% Compute covariance of y values
psim = sum(y .* y)/length(w);

This yields
psim =
32.6269

The two covariance values p and psim do not agree perfectly due to the
finite simulation horizon.

Algorithms

Transfer functions and zero-pole-gain models are first converted to

state space with ss.
For continuous-time state-space models

x Ax Bw
y Cx Dw,
the steady-state state covariance Q is obtained by solving the Lyapunov
equation

1-89

covar

AQ QAT BWBT 0.
In discrete time, the state covariance Q solves the discrete Lyapunov
equation

AQAT Q BWBT 0.
In both continuous and discrete time, the output response covariance is
given by P = CQCT + DWDT. For unstable systems, P and Q are infinite.

1-90

References

[1] Bryson, A.E. and Y.C. Ho, Applied Optimal Control, Hemisphere
Publishing, 1975, pp. 458-459.

See Also

dlyap | lyap

ctrb

Purpose

Controllability matrix

Syntax

Co = ctrb(sys)

Description

ctrb computes the controllability matrix for state-space systems. For

an n-by-n matrix A and an n-by-m matrix B, ctrb(A,B) returns the
controllability matrix

Co = B AB A2 B An 1 B

(1-1)

where Co has n rows and nm columns.

Co = ctrb(sys) calculates the controllability matrix of the state-space
LTI object sys. This syntax is equivalent to executing
Co = ctrb(sys.A,sys.B)

The system is controllable if Co has full rank n.

Examples

Check if the system with the following data

A =
1
4

1
-2

1
1

-1
-1

B =

is controllable. Type
Co=ctrb(A,B);
% Number of uncontrollable states
unco=length(A)-rank(Co)

These commands produce the following result.

1-91

ctrb

unco =
1

Limitations

Estimating the rank of the controllability matrix is ill-conditioned; that

is, it is very sensitive to roundoff errors and errors in the data. An
indication of this can be seen from this simple example.

1
1
A=
, B=

0 1

This pair is controllable if 0 but if < eps , where eps is the
relative machine precision. ctrb(A,B) returns

[B

1 1
AB] =

which is not full rank. For cases like these, it is better to determine the
controllability of a system using ctrbf.

See Also

1-92

ctrbf | obsv

ctrbf

Purpose

Compute controllability staircase form

Syntax

[Abar,Bbar,Cbar,T,k] = ctrbf(A,B,C)
ctrbf(A,B,C,tol)

Description

If the controllability matrix of (A, B) has rank r n, where n is the size

of A, then there exists a similarity transformation such that

A = TAT T , B = TB, C = CT T
where T is unitary, and the transformed system has a staircase form,
in which the uncontrollable modes, if there are any, are in the upper
left corner.

A
A = uc
A21

0
0
, B = , C = [CncCc ]

Ac
Bc

where (Ac, Bc) is controllable, all eigenvalues of Auc are uncontrollable,

and Cc (sI Ac )1 Bc = C (sI A)1 B .
[Abar,Bbar,Cbar,T,k] = ctrbf(A,B,C) decomposes the state-space
system represented by A, B, and C into the controllability staircase
form, Abar, Bbar, and Cbar, described above. T is the similarity
transformation matrix and k is a vector of length n, where n is the order
of the system represented by A. Each entry of k represents the number
of controllable states factored out during each step of the transformation
matrix calculation. The number of nonzero elements in k indicates
how many iterations were necessary to calculate T, and sum(k) is the
number of states in Ac, the controllable portion of Abar.
ctrbf(A,B,C,tol) uses the tolerance tol when calculating the

controllable/uncontrollable subspaces. When the tolerance is not

specified, it defaults to 10*n*norm(A,1)*eps.

Examples

Compute the controllability staircase form for

A =

1-93

ctrbf

1
4

1
-2

1
1

-1
-1

1
0

0
1

B =

C =

and locate the uncontrollable mode.

[Abar,Bbar,Cbar,T,k]=ctrbf(A,B,C)
Abar =
-3.0000
-3.0000

0
2.0000

Bbar =
0.0000
1.4142

0.0000
-1.4142

Cbar =
-0.7071
0.7071

0.7071
0.7071

T =
-0.7071
0.7071

0.7071
0.7071

k =
1

The decomposed system Abar shows an uncontrollable mode located at

-3 and a controllable mode located at 2.

Algorithms

1-94

ctrbf implements the Staircase Algorithm of [1].

ctrbf

References

[1] Rosenbrock, M.M., State-Space and Multivariable Theory, John

Wiley, 1970.

See Also

ctrb | minreal

1-95

ctrlpref

Purpose

Set Control System Toolbox preferences

Syntax

ctrlpref

Description

ctrlpref opens a Graphical User Interface (GUI) which allows you to

change the Control System Toolbox preferences. Preferences set in
this GUI affect future plots only (existing plots are not altered).

Your preferences are stored to disk (in a system-dependent location)

and will be automatically reloaded in future MATLAB sessions using
the Control System Toolbox software.

See Also

1-96

sisotool | ltiview

d2c

Purpose

Convert model from discrete to continuous time

Syntax

sysc = d2c(sysd)
sysc = d2c(sysd,method)
sysc = d2c(sysd,opts)
[sysc,G] = d2c(sysd,method,opts)

Description

sysc = d2c(sysd) produces a continuous-time model sysc that is

equivalent to the discrete-time dynamic system model sysd using
zero-order hold on the inputs.
sysc = d2c(sysd,method) uses the specified conversion method
method.
sysc = d2c(sysd,opts) converts sysd using the option set opts,
specified using the d2cOptions command.
[sysc,G] = d2c(sysd,method,opts) returns a matrix G that maps the
states xd[k] of the state-space model sysd to the states xc(t) of sysc.

Tips

Use the syntax sysc = d2c(sysd,'method') to convert sysd using

the default options for'method'. To specify tustin conversion with a
frequency prewarp (formerly the 'prewarp' method), use the syntax
sysc = d2c(sysd,opts). See the d2cOptions reference page for
more information.

Input
Arguments

sysd

Discrete-time dynamic system model

You cannot directly use an idgrey model with FcnType='d' with d2c.
Convert the model into idss form first.
method

String specifying a discrete-to-continuous time conversion method:

'zoh' Zero-order hold on the inputs. Assumes the control inputs
are piecewise constant over the sampling period.

1-97

d2c

'foh' Linear interpolation of the inputs (modified first-order

hold). Assumes the control inputs are piecewise linear over the
sampling period.
'tustin' Bilinear (Tustin) approximation to the derivative.
'matched' Zero-pole matching method of [1] (for SISO systems
only).
Default: 'zoh'
opts

Discrete-to-continuous time conversion options, created using

d2cOptions.

Output
Arguments

sysc

Continuous-time model of the same type as the input system sysd.

When sysd is an identified (IDLTI) model, sysc:
Includes both the measured and noise components of sysd. If the
noise variance is in sysd, then the continuous-time model sysc has
an indicated level of noise spectral density equal to Ts*.
Does not include the estimated parameter covariance of sysd. If you
want to translate the covariance while converting the model, use
translatecov.
G

Matrix mapping the states xd[k] of the state-space model sysd to the
states xc(t) of sysc:

x k
xc kTs G d .
u k

1-98

d2c

Given an initial condition x0 for sysd and an initial input u0 = u[0],

the corresponding initial condition for sysc (assuming u[k] = 0 for k
< 0 is given by:

x
xc 0 G 0 .
u0

Examples

Example 1
Consider the discrete-time model with transfer function

H ( z) =

z 1
2

z + z + 0 .3

and sample time Ts = 0.1 s. You can derive a continuous-time

zero-order-hold equivalent model by typing
Hc = d2c(H)

Discretizing the resulting model Hc with the default zero-order hold

method and sampling time Ts = 0.1s returns the original discrete model
H(z):
c2d(Hc,0.1)

To use the Tustin approximation instead of zero-order hold, type

Hc = d2c(H,'tustin')

As with zero-order hold, the inverse discretization operation

c2d(Hc,0.1,'tustin')

gives back the original H(z).

1-99

d2c

Example 2
Convert an identified transfer function and compare its performance
against a directly estimated continuous-time model.
load iddata1
sys1d = tfest(z1, 2, 'Ts', 0.1);
sys1c = d2c(sys1d, 'zoh');
sys2c = tfest(z1, 2);
compare(z1, sys1c, sys2c)

The two systems are virtually identical.

Example 3
Analyze the effect of parameter uncertainty on frequency response
across d2c operation on an identified model.
load iddata1

1-100

d2c

sysd = tfest(z1, 2, 'Ts', 0.1);

sysc = d2c(sysd, 'zoh');
sys1c has no covariance information. Regenerate it using a zero
iteration update with the same estimation command and estimation
data:
opt = tfestOptions;
opt.SearchOption.MaxIter = 0;
sys1c = tfest(z1, sysc, opt);
h = bodeplot(sysd, sysc);
showConfidence(h)

The uncertainties of sysc and sysd are comparable up to the Nyquist

frequency. However, sysc exhibits large uncertainty in the frequency
range for which the estimation data does not provide any information.
If you do not have access to the estimation data, use translatecov
which is a Gauss-approximation formula based translation of covariance
across model type conversion operations.

Algorithms

d2c performs the 'zoh' conversion in state space, and relies on the
matrix logarithm (see logm in the MATLAB documentation).

See Continuous-Discrete Conversion Methods for more details on the

conversion methods.

Limitations

The Tustin approximation is not defined for systems with poles at z = 1

and is ill-conditioned for systems with poles near z = 1.
The zero-order hold method cannot handle systems with poles at z = 0.
In addition, the 'zoh' conversion increases the model order for systems
with negative real poles, [2]. The model order increases because the
matrix logarithm maps real negative poles to complex poles. Single
complex poles are not physically meaningful because of their complex
time response.

1-101

d2c

Instead, to ensure that all complex poles of the continuous model

come in conjugate pairs, d2c replaces negative real poles z = with
a pair of complex conjugate poles near . The conversion then yields
a continuous model with higher order. For example, to convert the
discrete-time transfer function

H ( z) =

z + 0 .2

( z + 0.5 ) ( z2 + z + 0.4 )

type:
Ts = 0.1 % sample time 0.1 s
H = zpk(-0.2,-0.5,1,Ts) * tf(1,[1 1 0.4],Ts)
Hc = d2c(H)

These commands produce the following result.

Warning: System order was increased to handle real negative poles.

Zero/pole/gain:
-33.6556 (s-6.273) (s^2 + 28.29s + 1041)
-------------------------------------------(s^2 + 9.163s + 637.3) (s^2 + 13.86s + 1035)

To convert Hc back to discrete time, type:

c2d(Hc,Ts)

yielding
Zero/pole/gain:
(z+0.5) (z+0.2)
------------------------(z+0.5)^2 (z^2 + z + 0.4)
Sampling time: 0.1

1-102

d2c

This discrete model coincides with H(z) after canceling the pole/zero
pair at z = 0.5.

References

[1] Franklin, G.F., Powell,D.J., and Workman, M.L., Digital Control of

Dynamic Systems (3rd Edition), Prentice Hall, 1997..
[2] Kollr, I., G.F. Franklin, and R. Pintelon, "On the Equivalence of
z-domain and s-domain Models in System Identification," Proceedings
of the IEEE Instrumentation and Measurement Technology Conference,
Brussels, Belgium, June, 1996, Vol. 1, pp. 14-19.

See Also

d2cOptions | c2d | d2d | translatecov | logm

1-103

d2cOptions

Purpose

Create option set for discrete- to continuous-time conversions

Syntax

opts = d2cOptions
opts = d2cOptions(Name,Value)

Description

opts = d2cOptions returns the default options for d2c.

opts = d2cOptions(Name,Value) creates an option set with the
options specified by one or more Name,Value pair arguments.

Input
Arguments

Name-Value Pair Arguments

method

Discretization method, specified as one of the following values:

'zoh'

Zero-order hold, where d2c assumes the control inputs

are piecewise constant over the sampling period Ts.

'foh'

Linear interpolation of the inputs (modified first-order

hold). Assumes the control inputs are piecewise linear
over the sampling period.

'tustin'

Bilinear (Tustin) approximation. By default, d2c

converts with no prewarp. To include prewarp, use
the PrewarpFrequency option.

'matched'

Zero-pole matching method. (See [1], p. 224.)

Default: 'zoh'
PrewarpFrequency

Prewarp frequency for 'tustin' method, specified in rad/TimeUnit,

where TimeUnit is the time units, specified in the TimeUnit property,
of the discrete-time system. Specify the prewarp frequency as a positive
scalar value. A value of 0 corresponds to the 'tustin' method without
prewarp.

1-104

d2cOptions

Default: 0
For additional information about conversion methods, see
Continuous-Discrete Conversion Methods.

Examples

Convert a discrete-time model to continuous-time using the 'tustin'

method with frequency prewarping.
Create the discrete-time transfer function

z+1
2

z + z+1
hd = tf([1 1], [1 1 1], 0.1);

% 0.1s sampling time

To convert to continuous-time, use d2cOptions to create the option set.

opts = d2cOptions('Method', 'tustin', 'PrewarpFrequency', 20);
hc = d2c(hd, opts);

You can use opts to resample additional models using the same options.

References

[1] Franklin, G.F., Powell,D.J., and Workman, M.L., Digital Control of

Dynamic Systems (3rd Edition), Prentice Hall, 1997.

See Also

d2c

1-105

d2d

Purpose

Resample discrete-time model

Syntax

sys1 = d2d(sys, Ts)

sys1 = d2d(sys, Ts, 'method')
sys1 = d2d(sys, Ts, opts)

Description

sys1 = d2d(sys, Ts) resamples the discrete-time dynamic system

model sys to produce an equivalent discrete-time model sys1 with the
new sample time Ts (in seconds), using zero-order hold on the inputs.
sys1 = d2d(sys, Ts, 'method') uses the specified resampling
method 'method':

'zoh' Zero-order hold on the inputs

'tustin' Bilinear (Tustin) approximation
sys1 = d2d(sys, Ts, opts) resamples sys using the option set with
d2dOptions.

Tips

Use the syntax sys1 = d2d(sys, Ts, 'method') to resample sys

using the default options for'method'. To specify tustin resampling
with a frequency prewarp (formerly the 'prewarp' method), use the
syntax sys1 = d2d(sys, Ts, opts). See the d2dOptions reference
page.
When sys is an identified (IDLTI) model, sys1 does not include the
estimated parameter covariance of sys. If you want to translate the
covariance while converting the model, use translatecov.

Examples

Example 1
Consider the zero-pole-gain model

H ( z) =

z 0 .7
z 0 .5

with sample time 0.1 s. You can resample this model at 0.05 s by typing
H = zpk(0.7,0.5,1,0.1)

1-106

d2d

H2 = d2d(H,0.05)
Zero/pole/gain:
(z-0.8243)
---------(z-0.7071)
Sampling time: 0.05

The inverse resampling operation, performed by typing d2d(H2,0.1),

yields back the initial model H(z).
Zero/pole/gain:
(z-0.7)
------(z-0.5)
Sampling time: 0.1

Example 2
Suppose you estimates a discrete-time model of a sample time
commensurate with the estimation data (Ts = 0.1 seconds). However,
your deployment application demands a faster sampling frequency (Ts
= 0.01 seconds).
load iddata1
sys = oe(z1, [2 2 1]);
sysFast = d2d(sys, 0.01, 'zoh')
bode(sys, sysFast)

See Also

d2dOptions | c2d | d2c | upsample | translatecov

1-107

d2dOptions

Purpose

Create option set for discrete-time resampling

Syntax

opts = d2dOptions
opts = d2dOptions('OptionName', OptionValue)

Description

opts = d2dOptions returns the default options for d2d.

opts = d2dOptions('OptionName', OptionValue) accepts one or

more comma-separated name/value pairs that specify options for the

d2d command. Specify OptionName inside single quotes.

This table summarizes the options that the d2d command supports.

Input
Arguments

Name-Value Pair Arguments

Method

Discretization method, specified as one of the following values:

'zoh'

Zero-order hold, where d2d assumes the control inputs

are piecewise constant over the sampling period Ts.

'tustin'

Bilinear (Tustin) approximation. By default, d2d

resamples with no prewarp. To include prewarp, use
the PrewarpFrequency option.

Default: 'zoh'
PrewarpFrequency

Prewarp frequency for 'tustin' method, specified in rad/TimeUnit,

where TimeUnit is the time units, specified in the TimeUnit property,
of the resampled system. Takes positive scalar values. The prewarp
frequency must be smaller than the Nyquist frequency before and after
resampling. A value of 0 corresponds to the standard 'tustin' method
without prewarp.
Default: 0

1-108

d2dOptions

Examples

Resample a discrete-time model using the 'tustin' method with

frequency prewarping.
Create the discrete-time transfer function

z+1
2

z + z+1
h1 = tf([1 1], [1 1 1], 0.1);

% 0.1s sampling time

To resample to a different sampling time, use d2dOptions to create

the option set.
opts = d2dOptions('Method', 'tustin', 'PrewarpFrequency', 20);
h2 = d2d(h1, 0.05, opts);

You can use opts to resample additional models using the same options.

See Also

d2d

1-109

damp

Purpose

Natural frequency and damping ratio

Syntax

damp(sys)
[Wn,zeta] = damp(sys)
[Wn,zeta,P] = damp(sys)

Description

damp(sys) displays a table of the damping ratio (also called damping

factor), natural frequency, and time constant of the poles of the

linear model sys. For a discrete-time model, the table also includes
the magnitude of each pole. Frequencies are expressed in units of
the reciprocal of the TimeUnit property of sys. Time constants are
expressed in the same units as the TimeUnit property of sys.
[Wn,zeta] = damp(sys) returns the natural frequencies, Wn, and

damping ratios,zeta, of the poles of sys.

[Wn,zeta,P] = damp(sys) returns the poles of sys.

Input
Arguments

sys

Output
Arguments

Wn

Any linear dynamic system model.

Vector containing the natural frequencies of each pole of sys, in order

of increasing frequency. Frequencies are expressed in units of the
reciprocal of the TimeUnit property of sys.
If sys is a discrete-time model with specified sampling time, Wn
contains the natural frequencies of the equivalent continuous-time
poles (see Algorithms on page 1-113). If sys has an unspecified
sampling time (Ts = -1), then the software uses Ts = 1 and calculates
Wn accordingly.
zeta

Vector containing the damping ratios of each pole of sys, in the same
order as Wn.

1-110

damp

If sys is a discrete-time model with specified sampling time, zeta

contains the damping ratios of the equivalent continuous-time poles
(see Algorithms on page 1-113). If sys has an unspecified sampling
time (Ts = -1), then the software uses Ts = 1 and calculates zeta
accordingly.
P

Vector containing the poles of sys, in order of increasing natural

frequency. P is the same as the output of pole(sys), except for the
order.

Examples

Natural Frequency, Damping Ratio, and Poles of

Continuous-Time System
Calculate the natural frequency, damping ratio, time constant, and
poles of the continuous-time transfer function:

H (s)

2s2 5s 1
s2 2s 3

H = tf([2 5 1],[1 2 3]);

Display the natural frequencies, damping ratios, time constants, and

poles of H.
damp(H)
Pole

-1.00e+00 + 1.41e+00i
-1.00e+00 - 1.41e+00i

Damping

Frequency
(rad/seconds)

Time Constant
(seconds)

5.77e-01
5.77e-01

1.73e+00
1.73e+00

1.00e+00
1.00e+00

Obtain vectors containing the natural frequencies and damping ratios

of the poles.

1-111

damp

[Wn,zeta] = damp(H);

Calculate the associated time constants.

tau = 1./(zeta.*Wn);

Natural Frequency, Damping Ratio, and Poles of

Discrete-Time System
Calculate the natural frequency, damping ratio, time constant, and
poles of a discrete-time transfer function.
H = tf([5 3 1],[1 6 4 4],0.01);

Display information about the poles of H.

damp(H)
Pole

-3.02e-01 + 8.06e-01i
-3.02e-01 - 8.06e-01i
-5.40e+00

Magnitude

Damping

Frequency
(rad/seconds)

8.61e-01
8.61e-01
5.40e+00

7.74e-02
7.74e-02
-4.73e-01

1.93e+02
1.93e+02
3.57e+02

The Magnitude column displays the discrete-time pole magnitudes.

The Damping, Frequency, and Time Constant columns display values
calculated using the equivalent continuous-time poles.
Obtain vectors containing the natural frequencies and damping ratios
of the poles.
[Wn,zeta] = damp(H);

Calculate the associated time constants.

tau = 1./(zeta.*Wn);

1-112

Time
(s

6
6
-5

damp

Algorithms

The natural frequency, time constant, and damping ratio of the system
poles are defined in the following table:
Continuous Time

Discrete Time with

Sample Time Ts

Pole Location
Equivalent
Continuous-Time
Pole

Not applicable

ln( z)
Ts

Natural Frequency

n s

n s

ln( z)
Ts

Damping Ratio

cos(s)

cos(s) cos(ln( z))

1
n

Time Constant

See Also

1
n

eig | esort | dsort | pole | pzmap | zero

1-113

dare

Purpose

Solve discrete-time algebraic Riccati equations (DAREs)

Syntax

[X,L,G] = dare(A,B,Q,R)
[X,L,G] = dare(A,B,Q,R,S,E)

[X,L,G,report] = dare(A,B,Q,...)
[X1,X2,L,report] = dare(A,B,Q,...,'factor')

Description

[X,L,G] = dare(A,B,Q,R) computes the unique stabilizing solution X

of the discrete-time algebraic Riccati equation

AT XA X AT XB( BT XB + R)1 BT XA + Q = 0
The dare function also returns the gain matrix,

G = ( BT XB + R)1 BT XA , and the vector L of closed loop eigenvalues,

where
L=eig(A-B*G,E)
[X,L,G] = dare(A,B,Q,R,S,E) solves the more general discrete-time

algebraic Riccati equation,

AT XA ET XE ( AT XB + S)( BT XB + R)1 ( BT XA + ST ) + Q = 0
or, equivalently, if R is nonsingular,

ET XE = F T XF F T XB( BT XB + R)1 BT XF + Q SR1 ST

where F = A BR1 ST . When omitted, R, S, and E are set to the default
values R=I, S=0, and E=I.
The dare function returns the corresponding gain matrix

G = ( BT XB + R)1 ( BT XA + ST )
and a vector L of closed-loop eigenvalues, where
L= eig(A-B*G,E)

1-114

dare

[X,L,G,report] = dare(A,B,Q,...) returns a diagnosis report

with value:
-1 when the associated symplectic pencil has eigenvalues on or very
near the unit circle
-2 when there is no finite stabilizing solution X
The Frobenius norm if X exists and is finite
[X1,X2,L,report] = dare(A,B,Q,...,'factor') returns two
matrices, X1 and X2, and a diagonal scaling matrix D such that X
= D*(X2/X1)*D. The vector L contains the closed-loop eigenvalues.
All outputs are empty when the associated Symplectic matrix has
eigenvalues on the unit circle.

Algorithms

dare implements the algorithms described in [1]. It uses the QZ

algorithm to deflate the extended symplectic pencil and compute its
stable invariant subspace.

Limitations

The (A, B) pair must be stabilizable (that is, all eigenvalues of A

outside the unit disk must be controllable). In addition, the associated
symplectic pencil must have no eigenvalue on the unit circle. Sufficient
conditions for this to hold are (Q, A) detectable when S = 0 and R > 0, or

Q S
T
>0
S R

References

[1] Arnold, W.F., III and A.J. Laub, "Generalized Eigenproblem

Algorithms and Software for Algebraic Riccati Equations," Proc. IEEE,
72 (1984), pp. 1746-1754.

See Also

care | dlyap | gdare

1-115

db2mag

Purpose

Convert decibels (dB) to magnitude

Syntax

y = db2mag(ydb)

Description

y = db2mag(ydb) returns the corresponding magnitude y for a given

decibel (dB) value ydb . The relationship between magnitude and

decibels is ydb = 20 log10 ( y) .

See Also

1-116

mag2db

dcgain

Purpose

Low-frequency (DC) gain of LTI system

Syntax

k = dcgain(sys)

Description

k = dcgain(sys) computes the DC gain k of the LTI model sys.

Continuous Time
The continuous-time DC gain is the transfer function value at the
frequency s = 0. For state-space models with matrices (A, B, C, D),
this value is
K = D CA1B

Discrete Time
The discrete-time DC gain is the transfer function value at z = 1. For
state-space models with matrices (A, B, C, D), this value is
K = D + C (I A)1B

Tips

The DC gain is infinite for systems with integrators.

Examples

Example 1
To compute the DC gain of the MIMO transfer function

1
H ( s) =
1
s + 1

s 1

s + s + 3
s+2
s 3
2

type
H = [1 tf([1 -1],[1 1 3]) ; tf(1,[1 1]) tf([1 2],[1 -3])];
dcgain(H)

to get the result:

1-117

dcgain

ans =
1.0000
1.0000

-0.3333
-0.6667

Example 2
To compute the DC gain of an identified process model, type;
load iddata1
sys = idproc('p1d');
syse = procest(z1, sys)
dcgain(syse)

The DC gain is stored same as syse.Kp.

See Also

1-118

evalfr | norm

delay2z

Purpose

Replace delays of discrete-time TF, SS, or ZPK models by poles at z=0,

or replace delays of FRD models by phase shift
Note delay2z has been removed. Use absorbDelay instead.

1-119

delayss

Purpose

Create state-space models with delayed inputs, outputs, and states

Syntax

sys=delayss(A,B,C,D,delayterms)
sys=delayss(A,B,C,D,ts,delayterms)

Description

sys=delayss(A,B,C,D,delayterms)constructs a continuous-time

state-space model of the form:

N
dx
= Ax(t ) + Bu (t ) + ( Ajx(t tj ) + Bju (t tj ))
dt
j =1
N

y (t ) = Cx(t ) + Du (t ) + (Cjx(t tj ) + Dju (t tj ))

j =1

where tj, j=1,..,N are time delays expressed in seconds. delayterms

is a struct array with fields delay, a, b, c, d where the fields of
delayterms(j) contain the values of tj, Aj, Bj, Cj, and Dj, respectively.
The resulting model sys is a state-space (SS) model with internal delays.
sys=delayss(A,B,C,D,ts,delayterms)constructs the discrete-time

counterpart:
N

x[k + 1] = Ax[k ] + Bu[k ] + { Ajx[k nj ] + Bju[k nj ]}

j =1

y[k ] = Cx[k ] + Du[k ] + {Cjx[k nj ] + Dju[k nj ]}

j =1

where Nj, j=1,..,N are time delays expressed as integer multiples of the
sampling period ts.

1-120

delayss

Examples

To create the model:

dx
= x(t ) x(t 1.2) + 2u (t 0.5)
dt
y (t ) = x(t 0.5) + u (t )
type
DelayT(1) = struct('delay',0.5,'a',0,'b',2,'c',1,'d',0);
DelayT(2) = struct('delay',1.2,'a',-1,'b',0,'c',0,'d',0);
sys = delayss(1,0,0,1,DelayT)
a =
x1

x1
0

x1

u1
2

y1

x1
1

y1

u1
1

b =

c =

d =

(values computed with all internal delays set to zero)

Internal delays: 0.5

0.5

1.2

Continuous-time model.

See Also

getdelaymodel | ss

1-121

dlqr

Purpose

Linear-quadratic (LQ) state-feedback regulator for discrete-time

state-space system

Syntax

[K,S,e] = dlqr(A,B,Q,R,N)

Description

[K,S,e] = dlqr(A,B,Q,R,N) calculates the optimal gain matrix K such

that the state-feedback law

u [ n] = Kx [ n]
minimizes the quadratic cost function

J (u) =

( x [ n]

n =1

Qx [ n] + u [ n] Ru [ n] + 2 x [ n] Nu [ n])
T

for the discrete-time state-space mode

x [ n + 1] = Ax [ n] + Bu [ n]
The default value N=0 is assumed when N is omitted.
In addition to the state-feedback gain K, dlqr returns the infinite
horizon solution S of the associated discrete-time Riccati equation

AT SA S ( AT SB + N )( BT SB + R)1 ( BT SA + N T ) + Q = 0
and the closed-loop eigenvalues e = eig(A-B*K). Note that K is derived
from S by

K = ( BT SB + R)1 ( BT SA + N T )

Limitations

The problem data must satisfy:

The pair (A, B) is stabilizable.
R > 0 and Q NR1NT 0

1-122

dlqr

(Q NR1NT, A BR1NT) has no unobservable mode on the unit

circle.

See Also

dare | lqgreg | lqr | lqrd | lqry

1-123

dlyap

Purpose

Solve discrete-time Lyapunov equations

Syntax

X = dlyap(A,Q)
X = dlyap(A,B,C)
X = dlyap(A,Q,[],E)

Description

X = dlyap(A,Q) solves the discrete-time Lyapunov equation AXAT

X + Q = 0,
where A and Q are n-by-n matrices.
The solution X is symmetric when Q is symmetric, and positive definite
when Q is positive definite and A has all its eigenvalues inside the unit
disk.
X = dlyap(A,B,C) solves the Sylvester equation AXB X + C = 0,

where A, B, and C must have compatible dimensions but need not be

square.
X = dlyap(A,Q,[],E) solves the generalized discrete-time Lyapunov

equation AXAT EXET + Q = 0,

where Q is a symmetric matrix. The empty square brackets, [], are
mandatory. If you place any values inside them, the function will error
out.

Algorithms

dlyap uses SLICOT routines SB03MD and SG03AD for Lyapunov

Diagnostics

The discrete-time Lyapunov equation has a (unique) solution if the

eigenvalues 1, 2, , N of A satisfy ij 1 for all (i, j).

equations and SB04QD (SLICOT) for Sylvester equations.

If this condition is violated, dlyap produces the error message

Solution does not exist or is not unique.

References

1-124

[1] Barraud, A.Y., A numerical algorithm to solve A XA - X = Q, IEEE

Trans. Auto. Contr., AC-22, pp. 883-885, 1977.

dlyap

[2] Bartels, R.H. and G.W. Stewart, "Solution of the Matrix Equation
AX + XB = C," Comm. of the ACM, Vol. 15, No. 9, 1972.
[3] Hammarling, S.J., Numerical solution of the stable, non-negative
definite Lyapunov equation, IMA J. Num. Anal., Vol. 2, pp. 303-325,
1982.
[4] Higham, N.J., FORTRAN codes for estimating the one-norm of
a real or complex matrix, with applications to condition estimation,
A.C.M. Trans. Math. Soft., Vol. 14, No. 4, pp. 381-396, 1988.
[5] Penzl, T., Numerical solution of generalized Lyapunov equations,
Advances in Comp. Math., Vol. 8, pp. 33-48, 1998.
[6] Golub, G.H., Nash, S. and Van Loan, C.F. A Hessenberg-Schur
method for the problem AX + XB = C, IEEE Trans. Auto. Contr.,
AC-24, pp. 909-913, 1979.
[7] Sima, V. C, Algorithms for Linear-quadratic Optimization, Marcel
Dekker, Inc., New York, 1996.

See Also

covar | lyap

1-125

dlyapchol

Purpose

Square-root solver for discrete-time Lyapunov equations

Syntax

R = dlyapchol(A,B)
X = dlyapchol(A,B,E)

Description

R = dlyapchol(A,B) computes a Cholesky factorization X = R'*R of

the solution X to the Lyapunov matrix equation:
A*X*A'- X + B*B' = 0

All eigenvalues of A matrix must lie in the open unit disk for R to exist.
X = dlyapchol(A,B,E) computes a Cholesky factorization X = R'*R of
X solving the Sylvester equation
A*X*A' - E*X*E' + B*B' = 0

All generalized eigenvalues of (A,E) must lie in the open unit disk for R
to exist.

Algorithms

dlyapchol uses SLICOT routines SB03OD and SG03BD.

References

[1] Bartels, R.H. and G.W. Stewart, "Solution of the Matrix Equation
AX + XB = C," Comm. of the ACM, Vol. 15, No. 9, 1972.
[2] Hammarling, S.J., Numerical solution of the stable, non-negative
definite Lyapunov equation, IMA J. Num. Anal., Vol. 2, pp. 303-325,
1982.
[3] Penzl, T., Numerical solution of generalized Lyapunov equations,
Advances in Comp. Math., Vol. 8, pp. 33-48, 1998.

See Also

1-126

dlyap | lyapchol

drss

Purpose

Generate random discrete test model

Syntax

sys = drss(n)
drss(n,p)
drss(n,p,m)
drss(n,p,m,s1,...sn)

Description

sys = drss(n) generates an n-th order model with one input and one
output, and returns the model in the state-space object sys. The poles
of sys are random and stable with the possible exception of poles at
z = 1 (integrators).
drss(n,p) generates an n-th order model with one input and p outputs.
drss(n,p,m) generates an n-th order model with p outputs and m

inputs.
drss(n,p,m,s1,...sn) generates a s1-by-sn array of n-th order
models with m inputs and p outputs.

In all cases, the discrete-time state-space model or array returned by

drss has an unspecified sampling time. To generate transfer function
or zero-pole-gain systems, convert sys using tf or zpk.

Examples

Generate a discrete LTI system with three states, four outputs, and
two inputs.
sys = drss(3,4,2)
a =
x1
x2
x3

x1
0.4766
0.1102
-0.7222

x2
0.1102
0.9115
0.1628

x1
x2

u1
-0.4326
-0

u2
0.2877
-0

x3
-0.7222
0.1628
-0.202

b =

1-127

drss

x3

1.191

c =
y1
y2
y3
y4

x1
1.189
-0.03763
0.3273
0.1746

x2
-0.1867
0.7258
-0.5883
2.183

y1
y2
y3
y4

u1
-0.09565
-0.8323
0.2944
-0

u2
0
1.624
-0.6918
0.858

d =

Sampling time: unspecified

Discrete-time model.

See Also

1-128

rss | tf | zpk

x3
-0
0.1139
1.067
0

dsort

Purpose

Sort discrete-time poles by magnitude

Syntax

dsort
[s,ndx] = dsort(p)

Description

dsort sorts the discrete-time poles contained in the vector p in

descending order by magnitude. Unstable poles appear first.

When called with one lefthand argument, dsort returns the sorted
poles in s.
[s,ndx] = dsort(p) also returns the vector ndx containing the indices

used in the sort.

Examples

Sort the following discrete poles.

p =
-0.2410 + 0.5573i
-0.2410 - 0.5573i
0.1503
-0.0972
-0.2590
s = dsort(p)
s =
-0.2410 + 0.5573i
-0.2410 - 0.5573i
-0.2590
0.1503
-0.0972

Limitations

The poles in the vector p must appear in complex conjugate pairs.

See Also

eig | esort | sort | pole | pzmap | zero

1-129

dss

Purpose

Create descriptor state-space models

Syntax

sys = dss(A,B,C,D,E)
sys = dss(A,B,C,D,E,Ts)
sys = dss(A,B,C,D,E,ltisys)

Description

sys = dss(A,B,C,D,E) creates the continuous-time descriptor

state-space model

dx
Ax Bu
dt
y Cx Du

The output sys is an SS model storing the model data (see State-Space
Models ). Note that ss produces the same type of object. If the matrix
D = 0, you can simply set d to the scalar 0 (zero).
sys = dss(A,B,C,D,E,Ts) creates the discrete-time descriptor model

Ex [ n + 1] = Ax [ n] + Bu[ n]
y[ n] = Cx [ n] + Du[ n]
with sample time Ts (in seconds).
sys = dss(A,B,C,D,E,ltisys) creates a descriptor model with
properties inherited from the LTI model ltisys (including the sample
time).

Any of the previous syntaxes can be followed by property name/property

value pairs
'Property',Value

Each pair specifies a particular LTI property of the model, for example,
the input names or some notes on the model history. See set and the
example below for details.

1-130

dss

Examples

The command
sys = dss(1,2,3,4,5,'inputdelay',0.1,'inputname','voltage',...
'notes','Just an example');

creates the model

5 x = x + 2u
y = 3 x + 4u
with a 0.1 second input delay. The input is labeled 'voltage', and a
note is attached to tell you that this is just an example.

See Also

dssdata | get | set | ss

1-131

dssdata

Purpose

Extract descriptor state-space data

Syntax

[A,B,C,D,E] = dssdata(sys)
[A,B,C,D,E,Ts] = dssdata(sys)

Description

[A,B,C,D,E] = dssdata(sys) returns the values of the A, B, C, D, and

E matrices for the descriptor state-space model sys (see dss). dssdata
equals ssdata for regular state-space models (i.e., when E=I).

If sys has internal delays, A, B, C, D are obtained by first setting all

internal delays to zero (creating a zero-order Pad approximation).
For some systems, setting delays to zero creates singular algebraic
loops, which result in either improper or ill-defined, zero-delay
approximations. For these systems, dssdata cannot display the
matrices and returns an error. This error does not imply a problem
with the model sys itself.
[A,B,C,D,E,Ts] = dssdata(sys) also returns the sample time Ts.

You can access other properties of sys using get or direct structure-like
referencing (e.g., sys.Ts).
For arrays of SS models with variable order, use the syntax
[A,B,C,D,E] = dssdata(sys,'cell')

to extract the state-space matrices of each model as separate cells in

the cell arrays A, B, C, D, and E.

See Also

1-132

dss | get | getdelaymodel | ssdata

esort

Purpose

Sort continuous-time poles by real part

Syntax

s = esort(p)
[s,ndx] = esort(p)

Description

esort sorts the continuous-time poles contained in the vector p by real

part. Unstable eigenvalues appear first and the remaining poles are
ordered by decreasing real parts.

When called with one left-hand argument, s = esort(p) returns the

sorted eigenvalues in s.
[s,ndx] = esort(p) returns the additional argument ndx, a vector
containing the indices used in the sort.

Examples

Sort the following continuous eigenvalues.

p
p =
-0.2410+ 0.5573i
-0.2410- 0.5573i
0.1503
-0.0972
-0.2590
esort(p)
ans =
0.1503
-0.0972
-0.2410+ 0.5573i
-0.2410- 0.5573i
-0.2590

Limitations

The eigenvalues in the vector p must appear in complex conjugate pairs.

See Also

dsort | sort | eig | pole | pzmap | zero

1-133

estim

Purpose

Form state estimator given estimator gain

Syntax

est = estim(sys,L)
est = estim(sys,L,sensors,known)

Description

est = estim(sys,L) produces a state/output estimator est given the

plant state-space model sys and the estimator gain L. All inputs w of
sys are assumed stochastic (process and/or measurement noise), and all
outputs y are measured. The estimator est is returned in state-space

form (SS object).

For a continuous-time plant sys with equations

x = Ax + Bw
y = Cx + Dw
estim uses the following equations to generate a plant output estimate

y and a state estimate x , which are estimates of y(t)=C and x(t),

respectively:
x = Ax + L( y Cx )
y C
x = I x

For a discrete-time plant sys with the following equations:

x[ n + 1] = Ax[ n] + Bw[ n]
y[ n] = Cx[ n] + Dw[ n]
estim uses estimator equations similar to those for continuous-time

to generate a plant output estimate y[ n| n 1] and a state estimate

x[ n| n 1] , which are estimates of y[n] and x[n], respectively. These

estimates are based on past measurements up to y[n-1].

1-134

estim

est = estim(sys,L,sensors,known) handles more general plants

sys with both known (deterministic) inputs u and stochastic inputs w,

and both measured outputs y and nonmeasured outputs z.

x = Ax + B1w + B2u
z C1
D11
D12
y = C x + D w + D u
2
21
22
The index vectors sensors and known specify which outputs of sys are
measured (y), and which inputs of sys are known (u). The resulting
estimator est, found using the following equations, uses both u and y to
produce the output and state estimates.

x = Ax + B2u + L( y C2 x D22u)
y C2
D22
x = I x + 0 u

Tips

You can use the functions place (pole placement) or kalman (Kalman
filtering) to design an adequate estimator gain L. Note that the
estimator poles (eigenvalues of A-LC) should be faster than the plant
dynamics (eigenvalues of A) to ensure accurate estimation.

Examples

Consider a state-space model sys with seven outputs and four inputs.
Suppose you designed a Kalman gain matrix L using outputs 4, 7, and
1 of the plant as sensor measurements and inputs 1, 4, and 3 of the
plant as known (deterministic) inputs. You can then form the Kalman
estimator by
sensors = [4,7,1];

1-135

estim

known = [1,4,3];
est = estim(sys,L,sensors,known)

See the function kalman for direct Kalman estimator design.

See Also

1-136

kalman | place | reg | kalmd | lqgreg | ss | ssest | predict

evalfr

Purpose

Evaluate frequency response at given frequency

Syntax

frsp = evalfr(sys,f)

Description

frsp = evalfr(sys,f) evaluates the transfer function of the TF, SS,

or ZPK model sys at the complex number f. For state-space models
with data (A, B, C, D), the result is

H(f) = D + C (fI A)1B

evalfr is a simplified version of freqresp meant for quick evaluation of
the response at a single point. Use freqresp to compute the frequency
response over a set of frequencies.

Examples

Example 1
To evaluate the discrete-time transfer function

H ( z) =

z 1
2

z + z+1

at z = 1 + j, type
H = tf([1 -1],[1 1 1],-1);
z = 1+j;
evalfr(H,z)

to get the result:

ans =
2.3077e-01 +

1.5385e-01i

Example 2
To evaluate the frequency response of a continuous-time IDTF model at
frequency w = 0.1 rad/s, type:
sys = idtf(1,[1 2 1]);

1-137

evalfr

w = 0.1;
s = 1j*w;
evalfr(sys, s)

The result is same as freqresp(sys, w).

Limitations

The response is not finite when f is a pole of sys.

See Also

bode | freqresp | sigma

1-138

lti/exp

Purpose

Create pure continuous-time delays

Syntax

d = exp(tau,s)

Description

d = exp(tau,s) creates pure continuous-time delays. The transfer

function of a pure delay tau is:
d(s) = exp(-tau*s)

You can specify this transfer function using exp.

s = zpk('s')
d = exp(-tau*s)

More generally, given a 2D array M,

s = zpk('s')
D = exp(-M*s)

creates an array D of pure delays where

D(i,j) = exp(M(i,j)s).
All entries of M should be non negative for causality.

See Also

zpk | tf

1-139

fcat

Purpose

Concatenate FRD models along frequency dimension

Syntax

sys = fcat(sys1,sys2,...)

Description

sys = fcat(sys1,sys2,...) takes two or more frd models and

merges their frequency responses into a single frd model sys. The
resulting frequency vector is sorted by increasing frequency. The
frequency vectors of sys1, sys2,... should not intersect. If the
frequency vectors do intersect, use fdel to remove intersecting data
from one or more of the models.

See Also

fdel | fselect | interp | frd

1-140

fdel

Purpose

Delete specified data from frequency response data (FRD) models

Syntax

sysout = fdel(sys, freq)

Description

sysout = fdel(sys, freq) removes from the frd model sys the data
nearest to the frequency values specified in the vector freq.

Tips

Use fdel to remove unwanted data (for example, outlier points) at

specified frequencies.
Use fdel to remove data at intersecting frequencies from frd models
before merging them with fcat. fcat produces an error when you
attempt to merge frd models that have intersecting frequency data.
To remove data from an frd model within a range of frequencies,
use fselect.

Input
Arguments

sys
frd model.
freq

Vector of frequency values.

Output
Arguments

sysout

Examples

Remove selected data from a frd model. In this example, first obtain an
frd model:

frd model containing the data remaining in sys after removing the
frequency points closest to the entries of freq.

sys = frd(tf([1],[1 1]), logspace(0,1,10))

Frequency(rad/s)
---------------1.0000
1.2915

Response
-------0.5000 - 0.5000i
0.3748 - 0.4841i

1-141

fdel

1.6681
2.1544
2.7826
3.5938
4.6416
5.9948
7.7426
10.0000

0.2644
0.1773
0.1144
0.0719
0.0444
0.0271
0.0164
0.0099

0.4410i
0.3819i
0.3183i
0.2583i
0.2059i
0.1623i
0.1270i
0.0990i

Continuous-time frequency response.

The following commands remove the data nearest 2, 3.5, and 6 rad/s
from sys.
freq = [2, 3.5, 6];
sysout = fdel(sys, freq)
Frequency(rad/s)
---------------1.0000
1.2915
1.6681
2.7826
4.6416
7.7426
10.0000

Response
-------0.5000 - 0.5000i
0.3748 - 0.4841i
0.2644 - 0.4410i
0.1144 - 0.3183i
0.0444 - 0.2059i
0.0164 - 0.1270i
0.0099 - 0.0990i

Continuous-time frequency response.

You do not have to specify the exact frequency of the data to remove.
fdel removes the data nearest to the specified frequencies.

See Also

1-142

fcat | fselect | frd

feedback

Purpose

Feedback connection of two models

Syntax

sys = feedback(sys1,sys2)

Description

sys = feedback(sys1,sys2) returns a model object sys for the

negative feedback interconnection of model objects sys1 and sys2.

The closed-loop model sys has u as input vector and y as output vector.
The models sys1 and sys2 must be both continuous or both discrete
with identical sample times. Precedence rules are used to determine
the resulting model type (see Rules That Determine Model Type).
To apply positive feedback, use the syntax
sys = feedback(sys1,sys2,+1)

By default, feedback(sys1,sys2) assumes negative feedback and is

equivalent to feedback(sys1,sys2,-1).
Finally,
sys = feedback(sys1,sys2,feedin,feedout)

computes a closed-loop model sys for the more general feedback loop.

1-143

feedback

The vector feedin contains indices into the input vector of sys1 and
specifies which inputs u are involved in the feedback loop. Similarly,
feedout specifies which outputs y of sys1 are used for feedback. The
resulting model sys has the same inputs and outputs as sys1 (with
their order preserved). As before, negative feedback is applied by
default and you must use
sys = feedback(sys1,sys2,feedin,feedout,+1)

to apply positive feedback.

For more complicated feedback structures, use append and connect.

Examples

Example 1

To connect the plant

1-144

feedback

G(s) =

2s2 + 5s + 1
s2 + 2s + 3

with the controller

H (s) =

5(s + 2)
s + 10

using negative feedback, type

G = tf([2 5 1],[1 2 3],'inputname','torque',...
'outputname','velocity');
H = zpk(-2,-10,5)
Cloop = feedback(G,H)

These commands produce the following result.

Zero/pole/gain from input "torque" to output "velocity":
0.18182 (s+10) (s+2.281) (s+0.2192)
----------------------------------(s+3.419) (s^2 + 1.763s + 1.064)

The result is a zero-pole-gain model as expected from the precedence

rules. Note that Cloop inherited the input and output names from G.

Example 2
Consider a state-space plant P with five inputs and four outputs and a
state-space feedback controller K with three inputs and two outputs. To
connect outputs 1, 3, and 4 of the plant to the controller inputs, and the
controller outputs to inputs 4 and 2 of the plant, use
feedin = [4 2];
feedout = [1 3 4];
Cloop = feedback(P,K,feedin,feedout)

Example 3
You can form the following negative-feedback loops

1-145

feedback

by
Cloop = feedback(G,1)
Cloop = feedback(1,G)

Limitations

% left diagram
% right diagram

The feedback connection should be free of algebraic loop. If D1 and

D2 are the feedthrough matrices of sys1 and sys2, this condition is
equivalent to:
I + D1D2 nonsingular when using negative feedback
I D1D2 nonsingular when using positive feedback.

See Also

1-146

series | parallel | connect

filt

Purpose

Specify discrete transfer functions in DSP format

Syntax

sys = filt(num,den)
sys = filt(num,den,Ts)
sys = filt(M)

Description

In digital signal processing (DSP), it is customary to write transfer

functions as rational expressions in z1 and to order the numerator and
denominator terms in ascending powers of z1. For example:

( )

H z1 =

2 + z1
1 + 0.4 z1 + 2 z2

The function filt is provided to facilitate the specification of transfer

functions in DSP format.
sys = filt(num,den) creates a discrete-time transfer function sys
with numerator(s) num and denominator(s) den. The sample time is left
unspecified (sys.Ts = -1) and the output sys is a TF object.
sys = filt(num,den,Ts) further specifies the sample time Ts (in

seconds).
sys = filt(M) specifies a static filter with gain matrix M.

Any of the previous syntaxes can be followed by property name/property

value pairs of the form
'Property',Value

Each pair specifies a particular property of the model, for example, the
input names or the transfer function variable. For information about
the available properties and their values, see the tf reference page.

Arguments

For SISO transfer functions, num and den are row vectors containing the
numerator and denominator coefficients ordered in ascending powers
of z1. For example, den = [1 0.4 2] represents the polynomial
1 + 0.4z1 + 2z2.

1-147

filt

MIMO transfer functions are regarded as arrays of SISO transfer

functions (one per I/O channel), each of which is characterized by its
numerator and denominator. The input arguments num and den are
then cell arrays of row vectors such that:
num and den have as many rows as outputs and as many columns as
inputs.
Their (i, j) entries num{i,j} and den{i,j} specify the numerator and
denominator of the transfer function from input j to output i.
If all SISO entries have the same denominator, you can also set den to
the row vector representation of this common denominator.

Tips

filt behaves as tf with the Variable property set to 'z^-1'. See tf

Examples

Create a two-input digital filter with input names 'channel1' and

'channel2':

entry below for details.

num = {1 , [1 0.3]};
den = {[1 1 2] ,[5 2]};
H = filt(num,den,'inputname',{'channel1' 'channel2'})

This syntax returns:

Transfer function from input "channel1" to output:
1
----------------1 + z^-1 + 2 z^-2
Transfer function from input "channel2" to output:
1 + 0.3 z^-1
-----------5 + 2 z^-1
Sampling time: unspecified

1-148

filt

See Also

tf | zpk | ss

1-149

fnorm

Purpose

Pointwise peak gain of FRD model

Syntax

fnrm = fnorm(sys)
fnrm = fnorm(sys,ntype)

Description

fnrm = fnorm(sys) computes the pointwise 2-norm of the frequency

response contained in the FRD model sys, that is, the peak gain at
each frequency point. The output fnrm is an FRD object containing

the peak gain across frequencies.

fnrm = fnorm(sys,ntype) computes the frequency response gains
using the matrix norm specified by ntype. See norm for valid matrix
norms and corresponding NTYPE values.

See Also

1-150

norm | abs

frd

Purpose

Create frequency-response data model, convert to frequency-response

data model

Syntax

sys = frd(response,frequency)
sys = frd(response,frequency,Ts)
sys = frd
sysfrd = frd(sys,frequency)
sysfrd = frd(sys,frequency,units)

Description

sys = frd(response,frequency) creates a frequency-response data

(frd) model object sys from the frequency response data stored in the
multidimensional array response. The vector frequency represents
the underlying frequencies for the frequency response data. See Data
Format for the Argument Response in FRD Models on page 1-152 for a
list of response data formats.
sys = frd(response,frequency,Ts) creates a discrete-time frd
model object sys with scalar sample time Ts. Set Ts = -1 to create a
discrete-time frd model object without specifying the sample time.
sys = frd creates an empty frd model object.

The input argument list for any of these syntaxes can be followed by
property name/property value pairs of the form
'PropertyName',PropertyValue

You can use these extra arguments to set the various properties the
model. For more information about available properties of frd models,
see Properties on page 1-152.
To force an FRD model sys to inherit all of its generic LTI properties
from any existing LTI model refsys, use the syntax
sys = frd(response,frequency,ltisys)
sysfrd = frd(sys,frequency) converts a dynamic system model sys

to frequency response data form. The frequency response is computed

at the frequencies provided by the vector frequency, in rad/TimeUnit,

1-151

frd

where TimeUnit is the time units of the input dynamic system, specified
in the TimeUnit property of sys.
sysfrd = frd(sys,frequency,units) converts a dynamic system
model to an frd model and interprets frequencies in the frequency
vector to have the units specified by the string units. For a list of values
for the string units, see the FrequencyUnit property in Properties
on page 1-152.

Arguments

When you specify a SISO or MIMO FRD model, or an array of FRD

models, the input argument frequency is always a vector of length
Nf, where Nf is the number of frequency data points in the FRD. The
specification of the input argument response is summarized in the
following table.
Data Format for the Argument Response in FRD Models
Model Form

Response Data Format

SISO model

Vector of length Nf for which response(i)

is the frequency response at the frequency
frequency(i)

MIMO model with

Ny outputs and Nu
inputs

Ny-by-Nu-by-Nf multidimensional array for

which response(i,j,k) specifies the frequency
response from input j to output i at frequency
frequency(k)

S1-by-...-by-Sn

Multidimensional array of size [Ny Nu S1 ...

Sn] for which response(i,j,k,:) specifies the
array of frequency response data from input j to
output i at frequency frequency(k)

array of models
with Ny outputs
and Nu inputs

Properties

frd objects have the following properties:

Frequency

1-152

frd

Frequency points of the frequency response data. Specify Frequency

values in the units specified by the FrequencyUnit property.
FrequencyUnit

Frequency units of the model.

FrequencyUnit is a string that specifies the units of the frequency
vector in the Frequency property. Set FrequencyUnit to one of the
following values:

'rad/TimeUnit'
'cycles/TimeUnit'
'rad/s'
'Hz'
'kHz'
'MHz'
'GHz'
'rpm'
The units 'rad/TimeUnit' and 'cycles/TimeUnit' are relative to the
time units specified in the TimeUnit property.
Changing this property changes the overall system behavior. Use
chgFreqUnit to convert between frequency units without modifying

system behavior.
Default: 'rad/TimeUnit'
ResponseData

Frequency response data.

The 'ResponseData' property stores the frequency response data as a
3-D array of complex numbers. For SISO systems, 'ResponseData' is a
vector of frequency response values at the frequency points specified in
the 'Frequency' property. For MIMO systems with Nu inputs and Ny

1-153

frd

outputs, 'ResponseData' is an array of size [Ny Nu Nw], where Nw is

the number of frequency points.
ioDelay

Transport delays. ioDelay is a numeric array specifying a separate

transport delay for each input/output pair.
For continuous-time systems, specify transport delays in the time unit
stored in the TimeUnit property. For discrete-time systems, specify
transport delays in integer multiples of the sampling period, Ts.
For a MIMO system with Ny outputs and Nu inputs, set ioDelay to
a Ny-by-Nu array. Each entry of this array is a numerical value that
represents the transport delay for the corresponding input/output pair.
You can also set ioDelay to a scalar value to apply the same delay to all
input/output pairs.
Default: 0 for all input/output pairs
InputDelay - Input delays
0 (default) | scalar | vector

Input delay for each input channel, specified as a numeric vector. For
continuous-time systems, specify input delays in the time unit stored
in the TimeUnit property. For discrete-time systems, specify input
delays in integer multiples of the sampling period Ts. For example,
InputDelay = 3 means a delay of three sampling periods.
For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each
entry of this vector is a numerical value that represents the input delay
for the corresponding input channel.
You can also set InputDelay to a scalar value to apply the same delay
to all channels.
OutputDelay

Output delays. OutputDelay is a numeric vector specifying a time

delay for each output channel. For continuous-time systems, specify

1-154

frd

output delays in the time unit stored in the TimeUnit property. For
discrete-time systems, specify output delays in integer multiples of the
sampling period Ts. For example, OutputDelay = 3 means a delay
of three sampling periods.
For a system with Ny outputs, set OutputDelay to an Ny-by-1 vector,
where each entry is a numerical value representing the output delay for
the corresponding output channel. You can also set OutputDelay to a
scalar value to apply the same delay to all channels.
Default: 0 for all output channels
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'

1-155

frd

'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels

1-156

frd

InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

1-157

frd

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

1-158

frd

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times

1-159

frd

t = 0:10. The following code stores the time samples with the linear

models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Examples

Create Frequency-Response Model

Create a SISO FRD model from a frequency vector and response data:
% generate a frequency vector and response data

1-160

frd

freq = logspace(1,2);
resp = .05*(freq).*exp(i*2*freq);
% Create a FRD model
sys = frd(resp,freq);

See Also

chgTimeUnit | chgFreqUnit | frdata | set | ss | tf | zpk | idfrd

Tutorials

Frequency-Response Model
MIMO Frequency Response Data Model

How To

What Are Model Objects?

Frequency Response Data (FRD) Models

1-161

frdata

Purpose

Access data for frequency response data (FRD) object

Syntax

[response,freq] = frdata(sys)
[response,freq,covresp] = frdata(sys)
[response,freq,Ts,covresp] = frdata(sys,'v')
[response,freq,Ts] = frdata(sys)

Description

[response,freq] = frdata(sys) returns the response data and

frequency samples of the FRD model sys. For an FRD model with Ny
outputs and Nu inputs at Nf frequencies:

response is an Ny-by-Nu-by-Nf multidimensional array where the

(i,j) entry specifies the response from input j to output i.
freq is a column vector of length Nf that contains the frequency
samples of the FRD model.
See the frd reference page for more information on the data format for
FRD response data.
[response,freq,covresp] = frdata(sys) also returns the
covariance covresp of the response data resp for idfrd model sys.
(Using idfrd models requires System Identification Toolbox software.)
The covariance covresp is a 5D-array where covH(i,j,k,:,:) contains
the 2-by-2 covariance matrix of the response resp(i,j,k). The (1,1)
element is the variance of the real part, the (2,2) element the variance
of the imaginary part and the (1,2) and (2,1) elements the covariance
between the real and imaginary parts.

For SISO FRD models, the syntax

[response,freq] = frdata(sys,'v')

forces frdata to return the response data as a column vector rather

than a 3-dimensional array (see example below). Similarly
[response,freq,Ts,covresp] = frdata(sys,'v') for an IDFRD

model sys returns covresp as a 3-dimensional rather than a

5-dimensional array.

1-162

frdata

[response,freq,Ts] = frdata(sys) also returns the sample time Ts.

Other properties of sys can be accessed with get or by direct

structure-like referencing (e.g., sys.Frequency).

Arguments

The input argument sys to frdata must be an FRD model.

Examples

Extract Data from Frequency Response Data Model

Create a frequency response data model and extract the frequency
response data.
Create a frequency response data by computing the response of a
transfer function on a grid of frequencies.
H = tf([-1.2,-2.4,-1.5],[1,20,9.1]);
w = logspace(-2,3,101);
sys = frd(H,w);
sys is a SISO frequency response data (frd) model containing the

frequency response at 101 frequencies.

Extract the frequency response data from sys.
[response,freq] = frdata(sys);
response is a 1-by-1-by-101 array. response(1,1,k) is the complex
frequency response at the frequency freq(k).

See Also

frd | get | set | freqresp

1-163

freqresp

Purpose

Frequency response over grid

Syntax

[H,wout] = freqresp(sys)
H = freqresp(sys,w)
H = freqresp(sys,w,units)
[H,wout,covH] = freqresp(idsys,...)

Description

[H,wout] = freqresp(sys) returns the frequency response of the

dynamic system model sys at frequencies wout. The freqresp
command automatically determines the frequencies based on the
dynamics of sys.
H = freqresp(sys,w) returns the frequency response on the real
frequency grid specified by the vector w.
H = freqresp(sys,w,units) explicitly specifies the frequency units of

w with the string units.

[H,wout,covH] = freqresp(idsys,...) also returns the covariance
covH of the frequency response of the identified model idsys.

Input
Arguments

sys

Any dynamic system model or model array.

w

Vector of real frequencies at which to evaluate the frequency response.

Specify frequencies in units of rad/TimeUnit, where TimeUnit is the
time units specified in the TimeUnit property of sys.
units

String specifying the units of the frequencies in the input frequency

vector w. Units can take the following values:
'rad/TimeUnit' radians per the time unit specified in the
TimeUnit property of sys

1-164

freqresp

'cycles/TimeUnit' cycles per the time unit specified in the

TimeUnit property of sys
'rad/s'
'Hz'
'kHz'
'MHz'
'GHz'
'rpm'
Default: 'rad/TimeUnit'
idsys

Any identified model.

Output
Arguments

Array containing the frequency response values.

If sys is an individual dynamic system model having Ny outputs and
Nu inputs, H is a 3D array with dimensions Ny-by-Nu-by-Nw, where Nw
is the number of frequency points. Thus, H(:,:,k) is the response at
the frequency w(k) or wout(k).
If sys is a model array of size [Ny Nu S1 ... Sn], H is an array with
dimensions Ny-by-Nu-by-Nw-by-S1-by-...-by-Sn] array.
If sys is a frequency response data model (such as frd, genfrd, or
idfrd), freqresp(sys,w) evaluates to NaN for values of w falling outside
the frequency interval defined by sys.frequency. The freqresp
command can interpolate between frequencies in sys.frequency.
However, freqresp cannot extrapolate beyond the frequency interval
defined by sys.frequency.
wout

1-165

freqresp

Vector of frequencies corresponding to the frequency response values

in H. If you omit w from the inputs to freqresp, the command
automatically determines the frequencies of wout based on the system
dynamics. If you specify w, then wout = w
covH

Covariance of the response H. The covariance is a 5D array where

covH(i,j,k,:,:) contains the 2-by-2 covariance matrix of the response
from the ith input to the jth output at frequency w(k). The (1,1)
element of this 2-by-2 matrix is the variance of the real part of the
response. The (2,2) element is the variance of the imaginary part.
The (1,2) and (2,1) elements are the covariance between the real and
imaginary parts of the response.

Definitions

Frequency Response
In continuous time, the frequency response at a frequency is the
transfer function value at s = j. For state-space models, this value
is given by

H ( j) = D + C ( j I A)1 B
In discrete time, the frequency response is the transfer function
evaluated at points on the unit circle that correspond to the real
frequencies. freqresp maps the real frequencies w(1),..., w(N) to points
on the unit circle using the transformation z = e jTs . Ts is the sample
time. The function returns the values of the transfer function at the
resulting z values. For models with unspecified sample time, freqresp
uses Ts = 1.

Examples

Frequency Response
Compute the frequency response of the 2-input, 2-output system

1-166

freqresp

0
sys
s 1
s 2
sys11
sys22
sys12
sys21
sys =

1
s 1

= 0;
= 1;
= tf(1,[1 1]);
= tf([1 -1],[1 2]);
[sys11,sys12;sys21,sys22];

[H,wout] = freqresp(sys);
H is a 2-by-2-by-45 array. Each entry H(:,:,k) in H is a 2-by-2 matrix
giving the complex frequency response of all input-output pairs of sys
at the corresponding frequency wout(k). The 45 frequencies in wout are
automatically selected based on the dynamics of sys.

Response on Specified Frequency Grid

Compute the frequency response of the 2-input, 2-output system

0
sys
s 1
s 2

1
s 1

on a logarithmically-spaced grid of 200 frequency points between 10

and 100 radians per second.
sys11
sys22
sys12
sys21
sys =

= 0;
= 1;
= tf(1,[1 1]);
= tf([1 -1],[1 2]);
[sys11,sys12;sys21,sys22];

w = logspace(1,2,200);

1-167

freqresp

H = freqresp(sys,w);
H is a 2-by-2-by-200 array. Each entry H(:,:,k) in H is a 2-by-2 matrix
giving the complex frequency response of all input-output pairs of sys
at the corresponding frequency w(k).

Frequency Response and Associated Covariance

Compute the frequency response and associated covariance for an
identified model at its peak response frequency.
load iddata1 z1
model = procest(z1, 'P2UZ');
w = 4.26;
[H,~,covH] = freqresp(model, w)

Algorithms

For transfer functions or zero-pole-gain models, freqresp evaluates the

numerator(s) and denominator(s) at the specified frequency points.
For continuous-time state-space models (A, B, C, D), the frequency
response is

D + C ( j A)1 B, = 1 ,, N
For efficiency, A is reduced to upper Hessenberg form and the linear
equation (j A)X = B is solved at each frequency point, taking
advantage of the Hessenberg structure. The reduction to Hessenberg
form provides a good compromise between efficiency and reliability. See
[1] for more details on this technique.

References

[1] Laub, A.J., "Efficient Multivariable Frequency Response

Computations," IEEE Transactions on Automatic Control, AC-26
(1981), pp. 407-408.

Alternatives

Use evalfr to evaluate the frequency response at individual

frequencies or small numbers of frequencies. freqresp is optimized for
medium-to-large vectors of frequencies.

1-168

freqresp

See Also

evalfr | bode | nyquist | nichols | sigma | ltiview | interp |

spectrum

1-169

freqsep

Purpose

Slow-fast decomposition

Syntax

[Gs,Gf] = freqsep(G,fcut)
[Gs,Gf] = freqsep(G,fcut,options)

Description

[Gs,Gf] = freqsep(G,fcut) decomposes a linear dynamic system into

slow and fast components around the specified cutoff frequency. The
decomposition is such that G = Gs + Gf.
[Gs,Gf] = freqsep(G,fcut,options) specifies additional options for

the decomposition.

Input
Arguments

G - Dynamic system to decompose

numeric LTI model

Dynamic system to decompose, specified as a numeric LTI model, such

as a ss or tf model.
fcut - Cutoff frequency
positive scalar

Cutoff frequency for fast-slow decomposition, specified as a positive

scalar. The output Gs contains all poles with natural frequency less
than fcut. The output Gf contains all poles with natural frequency
greater than or equal to fcut.
options - Options for decomposition
freqsepOptions options set

Options for the decomposition, specified as an options set you create

with freqsepOptions. Available options include absolute and relative
tolerance for accuracy of the decomposed systems.

1-170

freqsep

Output
Arguments

Gs - Slow dynamics

numeric LTI model

Slow dynamics of the decomposed system, returned as a numeric LTI

model of the same type as G. Gs contains all poles of G with natural
frequency less than fcut, and is such that G = Gs + Gf.
Gf - Fast dynamics
numeric LTI model

Fast dynamics of the decomposed system, returned as a numeric LTI

model of the same type as G. Gf contains all poles of G with natural
frequency greater than or equal to fcut, and is such that G = Gs + Gf.

Examples

Decompose Model into Fast and Slow Dynamics

Load a dynamic system model.
load numdemo Pd
bode(Pd)

1-171

freqsep

Pd has four complex poles and one real pole. The Bode plot shows a

resonance around 210 rad/s and a higher-frequency resonance below

10,000 rad/s.
Decompose this model around 1000 rad/s to separate these two
resonances.
[Gs,Gf] = freqsep(Pd,10^3);
bode(Pd,Gs,Gf)
legend('original','slow','fast','Location','Southwest')

1-172

freqsep

The Bode plot shows that the slow component, Gs, contains only the
lower-frequency resonance. This component also matches the DC
gain of the original model. The fast component, Gf, contains the
higher-frequency resonances and matches the response of the original
model at high frequencies. The sum of the two components Gs+Gf yields
the original model.

1-173

freqsep

Separate Nearby Modes by Adjusting Tolerance

Decompose a model into slow and fast components between poles that
are closely spaced.
The following system includes a real pole and a complex pair of poles
that are all close to s = -2.
G = zpk(-.5,[-1.9999 -2+1e-4i -2-1e-4i],10);

Try to decompose the model about 2 rad/s, so that the slow component
cotains the real pole and the fast component contains the complex pair.
[Gs,Gf] = freqsep(G,2);

Warning: One or more fast modes could not be separated from the slow mode
force separation, increase the absolute or relative tolerances ("AbsTol"
"RelTol" options). Type "help freqsepOptions" for more information.

These poles are too close together for freqsep to separate. Increase the
relative tolerance to allow the separation.
options = freqsepOptions('RelTol',1e-4);
[Gs,Gf] = freqsep(G,2,options);

Now freqsep successfully separates the dynamics about 2 rad/s.

slowpole = pole(Gs)
fastpole = pole(Gf)

slowpole =
-1.9999

fastpole =

1-174

freqsep

-2.0000 + 0.0001i
-2.0000 - 0.0001i

See Also

freqsepOptions

1-175

freqsepOptions

Purpose

Options for slow-fast decomposition

Syntax

opt = freqsepOptions
opt = freqsepOptions(Name,Value)

Description

opt = freqsepOptions returns the default options for freqsep.

opt = freqsepOptions(Name,Value) returns an options set with the
options specified by one or more Name,Value pair arguments.

Input
Arguments

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments.
Name is the argument name and Value is the corresponding
value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
Example: 'AbsTol',1e-4
AbsTol - Absolute tolerance for decomposition

0 (default) | nonnegative scalar

Absolute tolerance for slow-fast decomposition, specified as a

nonnegative scalar value. freqresp ensures that the frequency
responses of the original system, G, and the sum of the decomposed
systems Gs+Gf, differ by no more than AbsTol + RelTol*abs(G).
Increase AbsTol to help separate nearby modes, at the expense of the
accuracy of the decomposition.
RelTol - Relative tolerance for decomposition
1e-8 (default) | nonnegative scalar

Relative tolerance for slow-fast decomposition, specified as a

nonnegative scalar value. freqresp ensures that the frequency
responses of the original system, G, and the sum of the decomposed
systems Gs+Gf, differ by no more than AbsTol + RelTol*abs(G).

1-176

freqsepOptions

Increase RelTol to help separate nearby modes, at the expense of the

accuracy of the decomposition.

Output
Arguments

opt - Options for freqsep

freqsepOptions options set

Options for freqsep, returned as a freqsepOptions options set.

Use opt as the last argument to freqsep when computing slow-fast
decomposition.

Examples

Separate Nearby Modes by Adjusting Tolerance

Decompose a model into slow and fast components between poles that
are closely spaced.
The following system includes a real pole and a complex pair of poles
that are all close to s = -2.
G = zpk(-.5,[-1.9999 -2+1e-4i -2-1e-4i],10);

Try to decompose the model about 2 rad/s, so that the slow component
cotains the real pole and the fast component contains the complex pair.
[Gs,Gf] = freqsep(G,2);

Warning: One or more fast modes could not be separated from the slow m
force separation, increase the absolute or relative tolerances ("AbsTo
"RelTol" options). Type "help freqsepOptions" for more information.

These poles are too close together for freqsep to separate. Increase the
relative tolerance to allow the separation.
options = freqsepOptions('RelTol',1e-4);
[Gs,Gf] = freqsep(G,2,options);

Now freqsep successfully separates the dynamics about 2 rad/s.

slowpole = pole(Gs)
fastpole = pole(Gf)

1-177

freqsepOptions

slowpole =
-1.9999

fastpole =
-2.0000 + 0.0001i
-2.0000 - 0.0001i

See Also

1-178

freqsep

fselect

Purpose

Select frequency points or range in FRD model

Syntax

subsys = fselect(sys,fmin,fmax)
subsys = fselect(sys,index)

Description

subsys = fselect(sys,fmin,fmax) takes an FRD model sys and

selects the portion of the frequency response between the frequencies

fmin and fmax. The selected range [fmin,fmax] should be expressed

in the FRD model units. For an IDFRD model (requires System

Identification Toolbox software), the SpectrumData, CovarianceData
and NoiseCovariance values, if non-empty, are also selected in the
chosen range.
subsys = fselect(sys,index) selects the frequency points specified

by the vector of indices index. The resulting frequency grid is

sys.Frequency(index)

See Also

interp | fcat | fdel | frd

1-179

gcare

Purpose

Generalized solver for continuous-time algebraic Riccati equation

Syntax

[X,L,report] = gcare(H,J,ns)
[X1,X2,D,L] = gcare(H,...,'factor')

Description

[X,L,report] = gcare(H,J,ns) computes the unique stabilizing

solution X of the continuous-time algebraic Riccati equation associated

with a Hamiltonian pencil of the form

F
S1 E
A

H tJ = G A S2 0
S2 S1
R 0

0 0
E 0
0 0

The optional input ns is the row size of the A matrix. Default values for
J and ns correspond to E = I and R = [ ].
Optionally, gcare returns the vector L of closed-loop eigenvalues and a
diagnosis report with value:
-1 if the Hamiltonian pencil has jw-axis eigenvalues
-2 if there is no finite stabilizing solution X
0 if a finite stabilizing solution X exists
This syntax does not issue any error message when X fails to exist.
[X1,X2,D,L] = gcare(H,...,'factor') returns two matrices X1, X2
and a diagonal scaling matrix D such that X = D*(X2/X1)*D. The vector
L contains the closed-loop eigenvalues. All outputs are empty when the

associated Hamiltonian matrix has eigenvalues on the imaginary axis.

See Also

1-180

care | gdare

gdare

Purpose

Generalized solver for discrete-time algebraic Riccati equation

Syntax

[X,L,report] = gdare(H,J,ns)
[X1,X2,D,L] = gdare(H,J,NS,'factor')

Description

[X,L,report] = gdare(H,J,ns) computes the unique stabilizing

solution X of the discrete-time algebraic Riccati equation associated

with a Symplectic pencil of the form

A F B E
H tJ = Q E S 0

S 0 R 0

0
A 0

B 0
0

The third input ns is the row size of the A matrix.

Optionally, gdare returns the vector L of closed-loop eigenvalues and a
diagnosis report with value:
-1 if the Symplectic pencil has eigenvalues on the unit circle
-2 if there is no finite stabilizing solution X
0 if a finite stabilizing solution X exists
This syntax does not issue any error message when X fails to exist.
[X1,X2,D,L] = gdare(H,J,NS,'factor') returns two matrices X1, X2
and a diagonal scaling matrix D such that X = D*(X2/X1)*D. The vector
L contains the closed-loop eigenvalues. All outputs are empty when the

Symplectic pencil has eigenvalues on the unit circle.

See Also

dare | gcare

1-181

genfrd

Purpose

Generalized frequency response data (FRD) model

Description

Generalized FRD (genfrd) models arise when you combine numeric

FRD models with models containing tunable components (Control
Design Blocks). genfrd models keep track of how the tunable blocks
interact with the tunable components. For more information about
Control Design Blocks, see Generalized Models.

Construction

To construct a genfrd model, use series, parallel, lft, or connect, or

the arithmetic operators +, -, *, /, \, and ^, to combine a numeric FRD
model with control design blocks.
You can also convert any numeric LTI model or control design block
sys to genfrd form.
frdsys = genfrd(sys,freqs,frequnits) converts any static model

or dynamic system sys to a generalized FRD model. If sys is not an

frd model object, genfrd computes the frequency response of each

frequency point in the vector freqs. The frequencies freqs are in the
units specified by the optional argument frequnits. If frequnits is
omitted, the units of freqs are 'rad/TimeUnit'.
frdsys = genfrd(sys,freqs,frequnits,timeunits) further specifies

the time units for converting sys to genfrd form.

For more information about time and frequency units of genfrd models,
see Properties on page 1-184.

Input Arguments
sys

A static model or dynamic system model object.

freqs

Vector of frequency points. Express frequencies in the unit specified

in frequnits.
frequnits

1-182

genfrd

String specifying the frequency units of the genfrd model. Set

frequnits to one of the following values:
'rad/TimeUnit'
'cycles/TimeUnit'
'rad/s'
'Hz'
'kHz'
'MHz'
'GHz'
'rpm'
Default: 'rad/TimeUnit'
timeunits

String specifying the time units of the genfrd model. Set timeunits to
one of the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'

1-183

genfrd

Default: 'seconds'

Tips

You can manipulate genfrd models as ordinary frd models.

Frequency-domain analysis commands such as bode evaluate the
model by replacing each tunable parameter with its current value.

Properties

Blocks

Structure containing the control design blocks included in the

generalized LTI model or generalized matrix. The field names of Blocks
are the Name property of each control design block.
You can change some attributes of these control design blocks using dot
notation. For example, if the generalized LTI model or generalized
matrix M contains a realp tunable parameter a, you can change the
current value of a using:
M.Blocks.a.Value = -1;
Frequency

Frequency points of the frequency response data. Specify Frequency

values in the units specified by the FrequencyUnit property.
FrequencyUnit

Frequency units of the model.

FrequencyUnit is a string that specifies the units of the frequency
vector in the Frequency property. Set FrequencyUnit to one of the
following values:

'rad/TimeUnit'
'cycles/TimeUnit'
'rad/s'
'Hz'
'kHz'

1-184

genfrd

'MHz'
'GHz'
'rpm'
The units 'rad/TimeUnit' and 'cycles/TimeUnit' are relative to the
time units specified in the TimeUnit property.
Changing this property changes the overall system behavior. Use
chgFreqUnit to convert between frequency units without modifying

system behavior.
Default: 'rad/TimeUnit'
InputDelay - Input delays

0 (default) | scalar | vector

Input delay for each input channel, specified as a numeric vector. For
continuous-time systems, specify input delays in the time unit stored
in the TimeUnit property. For discrete-time systems, specify input
delays in integer multiples of the sampling period Ts. For example,
InputDelay = 3 means a delay of three sampling periods.
For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each
entry of this vector is a numerical value that represents the input delay
for the corresponding input channel.
You can also set InputDelay to a scalar value to apply the same delay
to all channels.
OutputDelay

Output delays. OutputDelay is a numeric vector specifying a time

delay for each output channel. For continuous-time systems, specify
output delays in the time unit stored in the TimeUnit property. For
discrete-time systems, specify output delays in integer multiples of the
sampling period Ts. For example, OutputDelay = 3 means a delay
of three sampling periods.

1-185

genfrd

For a system with Ny outputs, set OutputDelay to an Ny-by-1 vector,

where each entry is a numerical value representing the output delay for
the corresponding output channel. You can also set OutputDelay to a
scalar value to apply the same delay to all channels.
Default: 0 for all output channels
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'

1-186

genfrd

'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input

1-187

genfrd

model, set InputUnit to a cell array of strings. InputUnit has no effect

on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.

1-188

genfrd

You can use the shorthand notation y to refer to the OutputName

property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

1-189

genfrd

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.

1-190

genfrd

sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

See Also

frd | genss | getValue | chgFreqUnit

How To

Models with Tunable Coefficients

Generalized Models

1-191

genmat

Purpose

Generalized matrix with tunable parameters

Description

Generalized matrices (genmat) are matrices that depend on tunable

parameters (see realp). You can use generalized matrices for parameter
studies. You can also use generalized matrices for building generalized
LTI models (see genss) that represent control systems having a mixture
of fixed and tunable components.

Construction

Generalized matrices arise when you combine numeric values with

static blocks such as realpobjects. You create such combinations using
any of the arithmetic operators +, -, *, /, \, and ^. For example, if a and
b are tunable parameters, the expression M = a + b is represented as a
generalized matrix.
A generalized matrix can represent a tunable gain surface for
constructing gain-scheduled controllers. Use the Robust Control
Toolbox command gainsurf to create such a tunable gain surface.
The internal data structure of the genmat object M keeps track of how M
depends on the parameters a and b. The Blocks property of M lists the
parameters a and b.
M = genmat(A) converts the numeric array or tunable parameter A
into a genmat object.

Input Arguments
A

Static control design block, such as a realp object.

If A is a numeric array, M is a generalized matrix of the same dimensions
as A, with no tunable parameters.
If A is a static control design block, M is a generalized matrix whose
Blocks property lists A as the only block.

1-192

genmat

Properties

Blocks

Structure containing the control design blocks included in the

generalized LTI model or generalized matrix. The field names of Blocks
are the Name property of each control design block.
You can change some attributes of these control design blocks using dot
notation. For example, if the generalized LTI model or generalized
matrix M contains a realp tunable parameter a, you can change the
current value of a using:
M.Blocks.a.Value = -1;
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)

1-193

genmat

M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Examples

Generalized Matrix With Two Tunable Parameters

This example shows how to use algebraic combinations of tunable
parameters to create the generalized matrix:

1 a b
M
,
0 ab
where a and b are tunable parameters with initial values 1 and 3,
respectively.
1 Create the tunable parameters using realp.

a = realp('a',-1);

1-194

genmat

b = realp('b',3);
2 Define the generalized matrix using algebraic expressions of a and b.

M = [1 a+b;0 a*b]
M is a generalized matrix whose Blocks property contains a and b.
The initial value of M is M = [1 2;0 -3], from the initial values of
a and b.
3 (Optional) Change the initial value of the parameter a.

M.Blocks.a.Value = -3;
4 (Optional) Use double to display the new value of M.

double(M)

The new value of M is M = [1 0;0 -9].

See Also

realp | genss | getValue | gainsurf

How To

Models with Tunable Coefficients

Dynamic System Models

1-195

gensig

Purpose

Generate test input signals for lsim

Syntax

[u,t] = gensig(type,tau)
[u,t] = gensig(type,tau,Tf,Ts)

Description

[u,t] = gensig(type,tau) generates a scalar signal u of class type

and with period tau (in seconds). The following types of signals are

available.
'sin'

Sine wave.

'square' Square wave.

'pulse'

Periodic pulse.

gensig returns a vector t of time samples and the vector u of signal

values at these samples. All generated signals have unit amplitude.
[u,t] = gensig(type,tau,Tf,Ts) also specifies the time duration Tf
of the signal and the spacing Ts between the time samples t.

You can feed the outputs u and t directly to lsim and simulate the
response of a single-input linear system to the specified signal. Since t
is uniquely determined by Tf and Ts, you can also generate inputs for
multi-input systems by repeated calls to gensig.

Examples

Generate a square wave with period 5 seconds, duration 30 seconds,

and sampling every 0.1 second.
[u,t] = gensig('square',5,30,0.1)

Plot the resulting signal.

plot(t,u)
axis([0 30 -1 2])

1-196

gensig

See Also

lsim

1-197

genss

Purpose

Generalized state-space model

Description

Generalized state-space (genss) models are state-space models that

include tunable parameters or components. genss models arise when
you combine numeric LTI models with models containing tunable
components (control design blocks). For more information about
numeric LTI models and control design blocks, see Models with
Tunable Coefficients.
You can use generalized state-space models to represent control systems
having a mixture of fixed and tunable components. Use generalized
state-space models for control design tasks such as parameter studies
and parameter tuning with hinfstruct (requires Robust Control
Toolbox).

Construction

To construct a genss model:

Use series, parallel, lft, or connect, or the arithmetic operators
+, -, *, /, \, and ^, to combine numeric LTI models with control
design blocks.
Use tf or ss with one or more input arguments that is a generalized
matrix (genmat) instead of a numeric array
Convert any numeric LTI model, control design block, or slTuner
interface (requires Simulink Control Design), for example, sys, to
genss form using:
gensys = genss(sys)

When sys is an slTuner interface, gensys contains all the

tunable blocks and analysis points specified in this interface. To
compute a tunable model of a particular I/O transfer function, call
getIOTransfer(gensys,in,out). Here, in and out are the analysis
points of interest. (Use getPoints(sys) to get the full list of analysis
points.) Similarly, to compute a tunable model of a particular
open-loop transfer function, use getLoopTransfer(gensys,loc).
Here, loc is the analysis point of interest.

1-198

genss

Tips

You can manipulate genss models as ordinary ss models. Analysis

commands such as bode and step evaluate the model by replacing
each tunable parameter with its current value.

Properties

Blocks

Structure containing the control design blocks included in the

generalized LTI model or generalized matrix. The field names of Blocks
are the Name property of each control design block.
You can change some attributes of these control design blocks using dot
notation. For example, if the generalized LTI model or generalized
matrix M contains a realp tunable parameter a, you can change the
current value of a using:
M.Blocks.a.Value = -1;
InternalDelay

Vector storing internal delays.

Internal delays arise, for example, when closing feedback loops on
systems with delays, or when connecting delayed systems in series or
parallel. For more information about internal delays, see Closing
Feedback Loops with Time Delays in the Control System Toolbox Users
Guide.
For continuous-time models, internal delays are expressed in the time
unit specified by the TimeUnit property of the model. For discrete-time
models, internal delays are expressed as integer multiples of the
sampling period Ts. For example, InternalDelay = 3 means a delay
of three sampling periods.
You can modify the values of internal delays. However, the number of
entries in sys.InternalDelay cannot change, because it is a structural
property of the model.
InputDelay - Input delays
0 (default) | scalar | vector

1-199

genss

Input delay for each input channel, specified as a numeric vector. For
continuous-time systems, specify input delays in the time unit stored
in the TimeUnit property. For discrete-time systems, specify input
delays in integer multiples of the sampling period Ts. For example,
InputDelay = 3 means a delay of three sampling periods.
For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each
entry of this vector is a numerical value that represents the input delay
for the corresponding input channel.
You can also set InputDelay to a scalar value to apply the same delay
to all channels.
OutputDelay

Output delays. OutputDelay is a numeric vector specifying a time

delay for each output channel. For continuous-time systems, specify
output delays in the time unit stored in the TimeUnit property. For
discrete-time systems, specify output delays in integer multiples of the
sampling period Ts. For example, OutputDelay = 3 means a delay
of three sampling periods.
For a system with Ny outputs, set OutputDelay to an Ny-by-1 vector,
where each entry is a numerical value representing the output delay for
the corresponding output channel. You can also set OutputDelay to a
scalar value to apply the same delay to all channels.
Default: 0 for all output channels
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time

1-200

genss

representations. Use d2d to change the sampling time of a discrete-time

system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.

1-201

genss

Alternatively, use automatic vector expansion to assign input names for

multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

1-202

genss

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.

1-203

genss

Default: Empty string '' for all input channels

OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

1-204

genss

SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

1-205

genss

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Examples

Tunable Low-Pass Filter

This example shows how to create the low-pass filter F = a/(s + a) with
one tunable parameter a.
You cannot use ltiblock.tf to represent F, because the numerator
and denominator coefficients of an ltiblock.tf block are independent.
Instead, construct F using the tunable real parameter object realp.
1 Create a tunable real parameter.

a = realp('a',10);

The realp object a is a tunable parameter with initial value 10.

2 Use tf to create the tunable filter F:

F = tf(a,[1 a]);
F is a genss object which has the tunable parameter a in its Blocks
property. You can connect F with other tunable or numeric models to

create more complex models of control systems. For an example, see

Control System with Tunable Components.

State-Space Model With Both Fixed and Tunable Parameters

This example shows how to create a state-space (genss) model having
both fixed and tunable parameters.

1-206

genss

Create a state-space model having the following state-space matrices:

1 a b
A
,
0 ab

3.0
B
,
1 .5

C 0 .3 0 ,

D 0,

where a and b are tunable parameters, whose initial values are 1 and
3, respectively.
1 Create the tunable parameters using realp.

a = realp('a',-1);
b = realp('b',3);
2 Define a generalized matrix using algebraic expressions of a and b.

A = [1 a+b;0 a*b]
A is a generalized matrix whose Blocks property contains a and b.
The initial value of A is M = [1 2;0 -3], from the initial values of
a and b.
3 Create the fixed-value state-space matrices.

B = [-3.0;1.5];
C = [0.3 0];
D = 0;
4 Use ss to create the state-space model.

sys = ss(A,B,C,D)
sys is a generalized LTI model (genss) with tunable parameters a and b.

Control System With Both Numeric and Tunable Components

This example shows how to create a tunable model of the control system
in the following illustration.

1-207

genss

F(s)

+
-

C(s)

G(s)

S(s)
The plant response G(s) = 1/(s + 1)2. The model of sensor dynamics is
S(s) = 5/(s + 4). The controller C is a tunable PID controller, and the
prefilter F = a/(s + a) is a low-pass filter with one tunable parameter, a.
Create models representing the plant and sensor dynamics.
Because the plant and sensor dynamics are fixed, represent them using
numeric LTI models zpk and tf.
G = zpk([],[-1,-1],1);
S = tf(5,[1 4]);

Create a tunable representation of the controller C.

C = ltiblock.pid('C','PID');
C =
Parametric continuous-time PID controller "C" with formula:
1
s
Kp + Ki * --- + Kd * -------s
Tf*s+1
and tunable parameters Kp, Ki, Kd, Tf.

Type "pid(C)" to see the current value and "get(C)" to see all properties
C is a ltiblock.pid object, which is a Control Design Block with a

predefined proportional-integral-derivative (PID) structure.

1-208

genss

Create a model of the filter F = a/(s + a) with one tunable parameter.

a = realp('a',10);
F = tf(a,[1 a]);
a is a realp (real tunable parameter) object with initial value 10. Using
a as a coefficient in tf creates the tunable genss model object F.

Connect the models together to construct a model of the closed-loop

response from r to y.
T = feedback(G*C,S)*F
T is a genss model object. In contrast to an aggregate model formed
by connecting only Numeric LTI models, T keeps track of the tunable

elements of the control system. The tunable elements are stored in the
Blocks property of the genss model object.
Display the tunable elements of T.
T.Blocks
ans =
C: [1x1 ltiblock.pid]
a: [1x1 realp]

If you have Robust Control Toolbox software, you can use tuning
commands such as systune to tune the free parameters of T to meet
design requirements you specify.

See Also

realp | genmat | genfrd | tf | ss | getValue | ltiblock.pid |

feedback | connect

How To

Models with Tunable Coefficients

Dynamic System Models
Control Design Blocks

1-209

get

Purpose

Access model property values

Syntax

Value = get(sys,'PropertyName')

Struct = get(sys)

Description

Value = get(sys,'PropertyName') returns the current value of

the property PropertyName of the model object sys. The string

'PropertyName' can be the full property name (for example,
'UserData') or any unambiguous case-insensitive abbreviation (for
example, 'user'). See reference pages for the individual model object
types for a list of properties available for that model.
Struct = get(sys) converts the TF, SS, or ZPK object sys into a
standard MATLAB structure with the property names as field names
and the property values as field values.

Without left-side argument,

get(sys)

displays all properties of sys and their values.

Examples

Consider the discrete-time SISO transfer function defined by

h = tf(1,[1 2],0.1,'inputname','voltage','user','hello')

You can display all properties of h with

get(h)
num:
den:
ioDelay:
Variable:
Ts:
InputDelay:
OutputDelay:
InputName:
OutputName:

1-210

{[0 1]}
{[1 2]}
0
'z'
0.1
0
0
{'voltage'}
{''}

get

InputGroup:
OutputGroup:
Name:
Notes:
UserData:

[1x1 struct]
[1x1 struct]
''
{}
'hello'

or query only about the numerator and sample time values by

get(h,'num')
ans =
[1x2 double]

and
get(h,'ts')
ans =
0.1000

Because the numerator data (num property) is always stored as a cell

array, the first command evaluates to a cell array containing the row
vector [0 1].

Tips

An alternative to the syntax

Value = get(sys,'PropertyName')

is the structure-like referencing

Value = sys.PropertyName

For example,
sys.Ts
sys.a
sys.user

1-211

get

return the values of the sample time, A matrix, and UserData property
of the (state-space) model sys.

See Also

1-212

frdata | set | ssdata | tfdata | zpkdata | idssdata | polydata

getBlockValue

Purpose

Current value of Control Design Block in Generalized Model

Syntax

val = getBlockValue(M,blockname)

Description

val = getBlockValue(M,blockname) returns the current value of the

Control Design Block blockname in the Generalized Model M. (For
uncertain blocks, the current value is the nominal value of the block.)

Input
Arguments

Generalized LTI Model or Generalized matrix.

blockname

Name of the Control Design Block in the model M whose current value is
evaluated.
To get a list of the Control Design Blocks in M, enter M.Blocks.

Output
Arguments

val

Examples

Create a tunable genss model, and evaluate the current value of the
Control Design Blocks of the model.

Numerical LTI model or numerical value, equal to the current value of

the Control Design Block blockname.

G
C
a
F
T

=
=
=
=
=

zpk([],[-1,-1],1);
ltiblock.pid('C','PID');
realp('a',10);
tf(a,[1 a]);
feedback(G*C,1)*F;

Cval = getBlockValue(T,'C')
Continuous-time I-only controller:
1

1-213

getBlockValue

Ki * --s
With Ki = 0.001
Cval is a numeric pid controller object.
aval = getBlockValue(T,'a')
aval =
10
aval is a numeric scalar, because a is a real scalar parameter.

See Also

1-214

setBlockValue | showBlockValue | getValue

getCompSensitivity

Purpose

Complementary sensitivity function from generalized model of control

system

Syntax

T = getCompSensitivity(CL,location)
T = getSensitivity(CL,location,opening)

Description

T = getCompSensitivity(CL,location) returns the complementary

sensitivity measured at the specified location for a generalized model
of a control system.
T = getSensitivity(CL,location,opening) specifies loop openings

for the complementary sensitivity function calculation. Use an opening,

for example, to calculate the complementary sensitivity function of an
inner loop, with the outer loop open.
If opening and location list the same point, the software opens the
loop after adding the disturbance signal at the point.

Input
Arguments

CL - Model of control system

generalized state-space model

Model of a control system, specified as a Generalized State-Space Model

(genss).
Locations at which you can perform sensitivity analysis or open loops
are marked by loopswitch blocks in CL. Use getPoints(CL) to get
the list of such locations.
location - Location

string | cell array of strings

Location at which you calculate the complementary sensitivity
function, specified as a string or cell array of strings. To extract the
complementary sensitivity function at multiple locations, use a cell
array of strings.

1-215

getCompSensitivity

Each string in location must match an analysis point in CL. Analysis

points are marked using loopswitch blocks. Use getPoints(CL) to get
the list of available analysis points in CL.
Example: 'u' or {'u','y'}
opening - Additional loop opening
string | cell array of strings

Additional loop opening used to calculate the complementary sensitivity

function, specified as a string or cell array of strings. To open the loop
at multiple locations, use a cell array of strings.
Each string in opening must match an analysis point in CL. Analysis
points are marked using loopswitch blocks. Use getPoints(CL) to get
the list of available analysis points in CL.
Use an opening, for example, to calculate the complementary sensitivity
function of an inner loop, with the outer loop open.
If opening and location list the same point, the software opens the
loop after adding the disturbance signal at the point.
Example: 'y_outer' or {'y_outer','y_outer2'}

Output
Arguments

T - Complementary sensitivity function

generalized state-space model

Complementary sensitivity function of the control system, T, measured

at location, returned as a Generalized State-Space Model (genss).
If location is a string specifying a single loop opening location,
then T is a SISO genss model.
If location is a string specifying a vector signal, or a cell array
identifying multiple loop opening locations, then T is a MIMO genss
model.

Examples

Complementary Sensitivity Function at a Location

Compute the complementary sensitivity at the plant output, X.

1-216

getCompSensitivity

+
-

C(s)

G(s)

X
Create a model of the system by specifying and connecting a numeric
LTI plant model G, a tunable controller C, and the loopswitch block X.
Use the loopswitch block to mark the location where you assess the
complementary sensitivity (plant output in this example).
G = tf([1],[1 5]);
C = ltiblock.pid('C','p');
C.Kp.Value = 3;
X = loopswitch('X');
CL = feedback(G*C,X);
CL is a genss model that represents the closed-loop response of the
control system from r to y. The model contains the loopswitch block, X,
that identifies the potential loop-opening location.

Calculate the complementary sensitivity, T, at X.

T = getCompSensitivity(CL,'X');
tf(T)
ans =
From input "X" to output "X":
-3
----s + 8
Continuous-time transfer function.

1-217

getCompSensitivity

Specify Additional Loop Opening for Complementary

Sensitivity Function Calculation
Calculate the inner-loop sensitivity at the output of G2, with the outer
loop open.
+

C1

+
-

C2

G2

G1

X2
X1
Create a model of the system by specifying and connecting the numeric
plant models, tunable controllers, and loopswitch blocks. G1 and G2
are plant models, C1 and C2 are tunable controllers, and X1 and X2 are
loopswitch blocks that mark potential loop-opening locations.
G1
G2
C1
C2
X1
X2
CL

=
=
=
=
=
=
=

tf(10,[1 10]);
tf([1 2],[1 0.2 10]);
ltiblock.pid('C','pi');
ltiblock.gain('G',1);
loopswitch('X1');
loopswitch('X2');
feedback(G1*feedback(G2*C2,X2)*C1,X1);

Calculate the complementary sensitivity, T, at X2, with the outer-loop

open at X1.
T = getCompSensitivity(CL,'X2','X1');
tf(T)
ans =
From input "X2" to output "X2":

1-218

getCompSensitivity

-s - 2
---------------s^2 + 1.2 s + 12
Continuous-time transfer function.

Definitions

Complementary Sensitivity
The complementary sensitivity function, T, at a point is the closed-loop
transfer function around the feedback loop measured at the specified
location. It is related to the open-loop transfer function, L, and the
sensitivity function, S, at the same point as follows:

L
S 1.
1 L

Use getLoopTransfer and getSensitivity to compute L and S.

Consider the following model:

The complementary sensitivity, T, at y is defined as the transfer

function from dy to y.

y
r

+
+

dy

1-219

getCompSensitivity

Observe that, in contrast to the sensitivity function, the disturbance,

dy, is added after the measurement, y.

y GK ( y dy)
y GKy GKdy
( I GK ) y GKdy
y

GK
)1
GK
( I

dy.
T

Here, I is an identity matrix of the same size as GK. The complementary

sensitivity transfer function at y is equal to -1 times the closed-loop
transfer function from r to y.
Complementary sensitivity at multiple locations, for example, u and
y, is defined as the MIMO transfer function from the disturbances to
measurements:

y
du

1-220

See Also

Tduu
T
Tdu y

+
+

dy

Tdyu
.
Tdy y

getSwitches | loopswitch | genss | getLoopTransfer | systune | |

getIOTransfer | getSensitivity | getValue | getCompSensitivity

getDelayModel

Purpose

State-space representation of internal delays

Syntax

[H,tau] = getDelayModel(sys)
[A,B1,B2,C1,C2,D11,D12,D21,D22,E,tau] = getDelayModel(sys)

Description

[H,tau] = getDelayModel(sys) decomposes a state-space model sys

with internal delays into a delay-free state-space model, H, and a vector

of internal delays, tau. The relationship among sys, H, and tau is
shown in the following diagram.

sys
u

H
w

z
exp(-tau*s)

[A,B1,B2,C1,C2,D11,D12,D21,D22,E,tau] = getDelayModel(sys)

returns the set of state-space matrices and internal delay vector, tau,
that explicitly describe the state-space model sys. These state-space
matrices are defined by the state-space equations:
Continuous-time sys:

dx t

Ax t B1u t B2 w t
dt
y t C1 x t D11u t D12 w t

z t C2 x t D21u t D22 w t

wt z t
Discrete-time sys:

1-221

getDelayModel

Ex k 1 Ax k B1u k B2 w k

y k C1 x k D11u k D12 w k

z k C2 x k D21u k D22 w k

w k z k

Input
Arguments

sys

Output
Arguments

Any state-space (ss) model.

Delay-free state-space model (ss). H results from decomposing sys into

a delay-free component and a component exp(-tau*s) that represents
all internal delays.
If sys has no internal delays, H is equal to sys.
tau

Vector of internal delays of sys, expressed in the time units of sys. The
vector tau results from decomposing sys into a delay-free state-space
model H and a component exp(-tau*s) that represents all internal
delays.
If sys has no internal delays, tau is empty.
A,B1,B2,C1,C2,D11,D12,D21,D22,E

Set of state-space matrices that, with the internal delay vector tau,
explicitly describe the state-space model sys.
For explicit state-space models (E = I, or sys.e = []), the output E
= [].
If sys has no internal delays, the outputs B2, C2, D12, D21, and D22
are all empty ([]).

1-222

getDelayModel

Examples

Get Delay-Free State-Space Model and Internal Delay

Decompose the following closed-loop system with internal delay into a
delay-free component and a component representing the internal delay.

0.5 +

2.3
s

e-2.1s
s +10

Create the closed-loop model sys from r to y.

G = tf(1,[1 10],'InputDelay',2.1);
C = pid(0.5,2.3);
sys = feedback(C*G,1);
sys is a state-space (ss) model with an internal delay arising from the
feedback loop.

Decompose sys into a delay-free state-space model and the value of

the internal delay.
[H,tau] = getDelayModel(sys);

See Also

setDelayModel

Concepts

Internal Delays

1-223

getGainCrossover

Purpose

Crossover frequencies for specified gain

Syntax

wc = getGainCrossover(sys,gain)

Description

wc = getGainCrossover(sys,gain) returns the vector wc of

Input
Arguments

frequencies at which the frequency response of the dynamic system

model, sys, has principal gain of gain. For SISO systems, the principal
gain is the frequency response. For MIMO models, the principal gain is
the largest singular value of sys.
sys - Input dynamic system

dynamic system model

Input dynamic system, specified as any SISO or MIMO dynamic system

model.
gain - Input gain

positive real scalar

Input gain in absolute units, specified as a positive real scalar.
If sys is a SISO model, the gain is the frequency response magnitude
of sys.

If sys is a MIMO model, gain means the largest singular value of

sys.

Output
Arguments

wc - Crossover frequencies
column vector

Crossover frequencies, returned as a column vector. This vector lists the

frequencies at which the gain or largest singular value of sys is gain.

Examples

Unity Gain Crossover

Find the 0dB crossover of a single-loop control system with plant

1-224

getGainCrossover

G s

s 1 3

and PI controller

C s 1.14

0.454
.
s

G = zpk([],[-1,-1,-1],1);
C = pid(1.14,0.454);
sys = G*C;
wc = getGainCrossover(sys,1)
wc =
0.5214

The 0 dB crossovers are the frequencies at which the open-loop response

sys = G*C has unity gain. Because this system only crosses unity gain
once, getGainCrossover returns a single value.

Notch Filter Stopband

Find the 20 dB stopband of

sys

s2 0.05s 100

.
s2 5s 100
sys is a notch filter centered at 10 rad/s.
sys = tf([1 0.05 100],[1 5 100]);
gain = db2mag(-20);
wc = getGainCrossover(sys,gain)
wc =
9.7531
10.2531

1-225

getGainCrossover

The db2mag command converts the gain value of 20 dB to absolute

units. The getGainCrossover command returns the two frequencies
that define the stopband.

Algorithms

getGainCrossover computes gain crossover frequencies using

structure-preserving eigensolvers from the SLICOT library. For more
information about the SLICOT library, see http://slicot.org.

See Also

freqresp | bode | sigma | bandwidth | getPeakGain

Concepts

Dynamic System Models

1-226

getIOTransfer

Purpose

Closed-loop transfer function from generalized model of control system

Syntax

H = getIOTransfer(T,in,out)
H = getIOTransfer(T,in,out,openings)

Description

H = getIOTransfer(T,in,out) returns the transfer function from

specified inputs to specified outputs of a control system, computed from

a closed-loop generalized model of the control system.
H = getIOTransfer(T,in,out,openings) returns the transfer

function calculated with one or more loops open.

Input
Arguments

T - Model of control system

generalized state-space model

Model of a control system, specified as a Generalized State-Space

(genss) Model.
in - Input to extracted transfer function

string | cell array of strings

Input to extracted transfer function, specified as a string or cell array of

strings. To extract a multiple-input transfer function from the control
system, use a cell array of strings. Each string in in must match either:
An input of the control system model T (in other words, a string
contained in T.InputName).
A loop-opening site in T, corresponding to a channel of a loopswitch
block in T. Use getLoopID(T) to get a full list of available
loop-opening sites in T.
When you specify a loop-opening site as an input in, getIOTransfer
uses the input implicitly associated with the loopswitch channel,
arranged as follows.

1-227

getIOTransfer

in

out
loopswitch

+
+

This input signal models a disturbance entering at the output of the

switch.
If a loop-opening site has the same name as an input of T, then
getIOTransfer uses the input of T.

Example: {'r','X1'}
out - Output of extracted transfer function

string | cell array of strings

Output of extracted transfer function, specified as a string or cell array

of strings. To extract a multiple-output transfer function from the
control system, use a cell array of strings. Each string in out must
match either:
An output of the control system model T (in other words, a string
contained in T.OutputName).
A loop-opening site in T, corresponding to a channel of a loopswitch
block in T. Use getLoopID(T) to get a full list of available
loop-opening sites in T.
When you specify a loop-opening site as an output out,
getIOTransfer uses the output implicitly associated with the
loopswitch channel, arranged as follows.

in

out
loopswitch

1-228

+
+

getIOTransfer

If a loop-opening site has the same name as an output of T, then

getIOTransfer uses the output of T.
Example: {'y','X2'}
openings - Locations for opening feedback loops

string | cell array of strings

Locations for opening feedback loops for computation of the response

from in to out, specified as string or cell array of strings that identify
loop-opening sites in T. Loop-opening sites are marked by loopswitch
blocks in T. Use getLoopID(T) to get a full list of available loop-opening
sites in T.
Use openings when you want to compute the response from in to out
with some loops in the control system open. For example, in a cascaded
loop configuration, you can calculate the response from the system input
to the system output with the inner loop open.

Output
Arguments

H - Closed-loop transfer function

generalized state-space model

Closed-loop transfer function of the control system T from in to out,

returned as a Generalized State-Space (genss) model.
If both in and out specify a single signal, then T is a SISO genss
model.
If in or out identifies multiple signals, then T is a MIMO genss
model.

Examples

Closed-Loop Responses of Control System Model

Analyze responses of a control system by using getIOTransfer to
compute responses between various inputs and outputs of a closed-loop
model of the system.
Consider the following control system.

1-229

getIOTransfer

+
-

C1

+
-

C2

d2
d1

G2

G1

X2
X1

Create a genss model of the system by specifying and connecting the

numeric plant models G1 and G2, the tunable controllers C1, and the
loopswitch blocks X1 and X2 that mark potential loop-opening or signal
injection sites.
G1 = tf(10,[1 10]);
G2 = tf([1 2],[1 0.2 10]);
C1 = ltiblock.pid('C','pi');
C2 = ltiblock.gain('G',1);
X1 = loopswitch('X1');
X2 = loopswitch('X2');
T = feedback(G1*feedback(G2*C2,X2)*C1,X1);
T.InputName = 'r';
T.OutputName = 'y';

If you tuned the free parameters of this model (for example, using the
Robust Control Toolbox tuning command systune), you might want to
analyze the tuned system performance by examining various system
responses.
For example, examine the response at the output, y, to a disturbance
injected at the point d1.
H1 = getIOTransfer(T,'X1','y');
H1 represents the closed-loop response of the control system to

a disturbance injected at the implicit input associated with the

loopswitch block X1, which is the location of d1:

1-230

getIOTransfer

in

out
loopswitch

+
+

H1 is a genss model that includes the tunable blocks of T. If you have

tuned the free parameters of T, H1 allows you to validate the disturbance

response of your tuned system. For example, you can use analysis
commands such as bodeplot or stepplot to analyze H1. You can also
use getValue to obtain the current value of H1, in which all the tunable
blocks are evaluated to their current numeric values.
Similarly, examine the response at the output to a disturbance injected
at the point d2.
H2 = getIOTransfer(T,'X2','y');

You can also generate a two-input, one-output model representing the

response of the control system to simultaneous disturbances at both d1
and d2. To do so, provide getIOTransfer with a cell array that specifies
the multiple input locations.
H = getIOTransfer(T,{'X1','X2'},'y');

Responses with Some Loops Open and Others Closed

Compute the response from r to y of the following cascaded control
system, with the inner loop open, and the outer loop closed.

1-231

getIOTransfer

+
-

C1

+
-

C2

d2
d1

G2

G1

X2
X1

Create a genss model of the system by specifying and connecting the

numeric plant models G1 and G2, the tunable controllers C1, and the
loopswitch blocks X1 and X2 that mark potential loop-opening or signal
injection sites.
G1 = tf(10,[1 10]);
G2 = tf([1 2],[1 0.2 10]);
C1 = ltiblock.pid('C','pi');
C2 = ltiblock.gain('G',1);
X1 = loopswitch('X1');
X2 = loopswitch('X2');
T = feedback(G1*feedback(G2*C2,X2)*C1,X1);T.InputName = 'r';
T.OutputName = 'y';

If you tuned the free parameters of this model (for example, using the
Robust Control Toolbox tuning command systune), you might want to
analyze the tuned system performance by examining various system
responses.
For example, compute the response of the system with the inner loop
open, and the outer loop closed.
H = getIOTransfer(T,'r','y','X2');

By default, the loop-opening locations in T, X1 and X2, are closed.

Specifying 'X2' for the openings argument causes getIOTransfer to
open the loop at X2 for the purposes of computing the requested transfer
from r to y. The switch at X1 remains closed for this computation.

1-232

getIOTransfer

Tips

You can use getIOTransfer to extract various subsystem responses,

given a generalized model of the overall control system. This is useful
for validating responses of a control system that you tune with the
Robust Control Toolbox tuning command systune.
For example, in addition to evaluating the overall response of a tuned
control system from inputs to outputs, you can use getIOTransfer to
extract the transfer function from a disturbance input to a system
output. Evaluate the responses of that transfer function (such as
with step or bode) to confirm that the tuned system meets your
disturbance rejection requirements.
getIOTransfer is the genss equivalent to the Simulink Control
Design getIOTransfer command, which works with the slTuner
and slLinearizer interfaces. Use the Simulink Control Design
command when your control system is modeled in Simulink.

See Also

loopswitch | genss | getLoopTransfer | systune | | getIOTransfer

1-233

getLFTModel

Purpose

Decompose generalized LTI model

Syntax

[H,B,S] = getLFTModel(M)

Description

[H,B,S] = getLFTModel(M) extracts the components H, B, and S that

make up the Generalized matrix or Generalized LTI model M. The

model M decomposes into H, B, and S. These components are related to M
as shown in the following illustration.

. . .0
.
..
.
. .
. . . Bk-Sk

B1-S1

..
.

M
The cell array B contains the Control Design Blocks of M. The component
H is a numeric matrix, ss model, or frd model that describes the fixed
portion of M and the interconnections between the blocks of B. The
matrix S = blkdiag(S1,...,Sk) contains numerical offsets that ensure
that the interconnection is well-defined when the current (nominal)
value of M is finite.

1-234

getLFTModel

You can recombine H, B, and S into M using lft, as follows:

M = lft(H,blkdiag(B{:}-S));

Tips

getLFTModel gives you access to the internal representation of

Generalized LTI models and Generalized Matrices. For more
information about this representation, see Internal Structure of
Generalized Models.

Input
Arguments

Output
Arguments

Generalized LTI model (genss or genfrd) or Generalized matrix

(genmat).

Matrix, ss model, or frd model describing the numeric portion of M and

how it the numeric portion is connected to the Control Design Blocks
of M.
B

Cell array of Control Design Blocks (for example, realp or ltiblock.ss)

of M.
S

Matrix of offset values. The software might introduce offsets when you
build a Generalized model to ensure that H is finite when the current
(nominal) value of M is finite.

See Also

genfrd | genss | genmat | lft | getValue | nblocks

How To

Generalized Matrices
Generalized and Uncertain LTI Models
Models with Tunable Coefficients
Internal Structure of Generalized Models

1-235

getLoopTransfer

Purpose

Open-loop transfer function of control system

Syntax

L = getLoopTransfer(T,Locations)
L = getLoopTransfer(T,Locations,sign)
L = getLoopTransfer(T,Locations,sign,openings)

Description

L = getLoopTransfer(T,Locations) returns the point-to-point

open-loop transfer function of a control system measured at specified

loop-opening locations. The point-to-point open-loop transfer function
is the open-loop response obtained by injecting signals at the specified
locations and measuring the return signals at the same locations.
L = getLoopTransfer(T,Locations,sign) specifies the feedback

sign for calculating the open-loop response. The relationship between

the closed-loop response T and the open-loop response L is T =
feedback(L,1,sign).
L = getLoopTransfer(T,Locations,sign,openings) specifies
additional loop-opening locations to open for computing the open-loop
response at Locations.

Input
Arguments

T - Model of control system

generalized state-space model

Model of a control system, specified as a Generalized State-Space

(genss) Model. Locations at which you can open loops and perform
open-loop analysis are marked by loopswitch blocks in T.
Locations - Loop-opening locations

string | cell array of strings

Loop-opening locations in the control system model at which to compute

the open-loop point-to-point response, specified as a string or a cell
array of strings that identify loop-opening locations in T.

1-236

getLoopTransfer

Loop-opening locations are marked by loopswitch blocks in T. A

loopswitch block can have single or multiple channels. The Location
property of a loopswitch block gives names to these feedback channels.
The name of any channel in a loopswitch block in T is a valid entry for
the Locations argument to getLoopTransfer. Use getSwitches(T)
to get a full list of available loop-opening locations in T.
getLoopTransfer computes the open-loop response you would obtain by
injecting a signal at the implicit input associated with a loopswitch

channel, and measuring the response at the implicit output associated

with the channel. These implicit inputs and outputs are arranged as
follows.

in

out
loopswitch

+
+

L is the open-loop transfer function from in to out.

sign - Feedback sign
+1 (default) | -1

Feedback sign, specified as +1 or -1 The feedback sign determines the

sign of the open-loop transfer function.
+1 Compute the positive-feedback loop transfer. In this case, the
relationship between the closed-loop response T and the open-loop
response L is T = feedback(L,1,+1).
-1 Compute the negative-feedback loop transfer. In this case, the
relationship between the closed-loop response T and the open-loop
response L is T = feedback(L,1).
Choose a feedback sign that is consistent with the conventions of the
analysis you intend to perform with the loop transfer function. For

1-237

getLoopTransfer

example, consider the following system, where T is the closed-loop

transfer function from r to y.

+
-

C(s)

G(s)

To compute the stability margins of this system with the margin

command, which assumes negative feedback, you need to use the
negative-feedback open-loop response. Therefore, you can use L =
getLoopTransfer(T,'X',-1) to obtain the negative-feedback transfer
function L = GC.
openings - Additional locations for opening feedback loops

string | cell array of strings

Additional locations for opening feedback loops for computation of

the open-loop response, specified as string or cell array of strings
that identify loop-opening locations in T. Loop-opening locations are
marked by loopswitch blocks in T. Any channel name contained in
the Location property of a loopswitch block in T is a valid entry for
openings.
Use openings when you want to compute the open-loop response at
one loop-opening location with other loops also open at other locations.
For example, in a cascaded loop configuration, you can calculate the
inner loop open-loop response with the outer loop also open. Use
getSwitches(T) to get a full list of available loop-opening locations in T.

Output
Arguments

L - Point-to-point open-loop response

generalized state-space model

Point-to-point open-loop response of the control system T measured

at the loop-opening location specified by Locations, returned as a
Generalized State-Space (genss) Model.
If Locations is a string specifying a single loop-opening location,
then L is a SISO genss model. In this case, L represents the response

1-238

getLoopTransfer

obtained by opening the loop at Locations, injecting signals and

measuring the return signals at the same location.
If Locations is a string specifying a vector signal, or a cell array
identifying multiple loop-opening locations, then L is a MIMO genss
model. In this case, L represents the open-loop MIMO response
obtained by opening loops at all locations listed in Locations,
injecting signals and measuring the return signals at those locations.

Examples

Open-Loop Transfer Function at Loop-Opening Location

Compute the open-loop response of the following control system model
at a loop-opening location specified by a loopswitch block, X.
+

C(s)

G(s)

Create a model of the system by specifying and connecting a numeric

LTI plant model G, a tunable controller C, and the loopswitch block X.
G
C
X
T

=
=
=
=

tf([1 2],[1 0.2 10]);

ltiblock.pid('C','pi');
loopswitch('X');
feedback(G*X*C,1);

T is a genss model that represents the closed-loop response of the

control system from r to y. The model contains the loopswitch block X

that identifies the potential loop-opening location.

Calculate the open-loop point-to-point loop transfer at the location X.
L = getLoopTransfer(T,'X');

This command computes the positive-feedback transfer function you

would obtain by opening the loop at X, injecting a signal into G, and
measuring the resulting response at the output of C. By default,

1-239

getLoopTransfer

getLoopTransfer computes the positive feedback transfer function. In

this example, the positive feedback transfer function is L(s) = G(s)C(s)

The output L is a genss model that includes the tunable block C. You
can use getValue to obtain the current value of L, in which all the
tunable blocks of L are evaluated to their current numeric value.

Negative-Feedback Open-Loop Transfer Function

Compute the negative-feedback open-loop transfer of the following
control system model at a loop-opening location specified by a
loopswitch block, X.
+

C(s)

G(s)

Create a model of the system by specifying and connecting a numeric

LTI plant model G, a tunable controller C, and the loopswitch block X.
G
C
X
T

=
=
=
=

tf([1 2],[1 0.2 10]);

ltiblock.pid('C','pi');
loopswitch('X');
feedback(G*X*C,1);

T is a genss model that represents the closed-loop response of the

control system from r to y. The model contains the loopswitch block X

that identifies the potential loop-opening location.

Calculate the open-loop point-to-point loop transfer at the location X.
L = getLoopTransfer(T,'X',-1);

This command computes the open-loop transfer function from the input
of G to the output of C, assuming that the loop is closed with negative
feedback. That is, the relationships between L and T is given by T
= feedback(L,1). In this example, the positive feedback transfer
function is L(s) = G(s)C(s)

1-240

getLoopTransfer

Transfer Function with Additional Loop Openings

Compute the open-loop response of the inner loop of the following
cascaded control system, with the outer loop open.

+
-

C1

+
-

C2

G2

G1

X2
X1
Create a model of the system by specifying and connecting the numeric
plant models G1 and G2, the tunable controllers C1, and the loopswitch
blocks X1 and X2 that mark potential loop-opening locations.
G1 = tf(10,[1 10]);
G2 = tf([1 2],[1 0.2 10]);
C1 = ltiblock.pid('C','pi');
C2 = ltiblock.gain('G',1);
X1 = loopswitch('X1');
X2 = loopswitch('X2');
T = feedback(G1*feedback(G2*C2,X2)*C1,X1);

Compute the negative-feedback open-loop response of the inner loop, at

the location X2, with the outer loop opened at X1.
L = getLoopTransfer(T,'X2',-1,'X1');

By default, the loop-opening location marked the loopswitch block

X1 is closed. Specifying 'X1' for the openings argument causes
getLoopTransfer to open the loop at X1 for the purposes of computing
the requested loop transfer at X2. In this example, the negative-feedback
open-loop response L(s) = G2(s)C2(s).

1-241

getLoopTransfer

Tips

You can use getLoopTransfer to extract open-loop responses given a

generalized model of the overall control system. This is useful, for
example, for validating open-loop responses of a control system that
you tune with the Robust Control Toolbox tuning command systune.
getLoopTransfer is the genss equivalent to the Simulink Control
Design command getLoopTransfer, which works with the slTuner
and slLinearizer interfaces. Use the Simulink Control Design
command when your control system is modeled in Simulink.

See Also

1-242

loopswitch | genss | getIOTransfer | systune | getLoopTransfer

getNominal

Purpose

Nominal value of Generalized LTI model or Generalized matrix

Note getNominal has been removed. Use getValue instead.

1-243

getoptions

Purpose

Return @PlotOptions handle or plot options property

Syntax

p = getoptions(h)
p = getoptions(h,propertyname)

Description

p = getoptions(h) returns the plot options handle associated with plot

handle h. p contains all the settable options for a given response plot.
p = getoptions(h,propertyname) returns the specified options
property, propertyname, for the plot with handle h. You can use this to
interrogate a plot handle. For example,
p = getoptions(h,'Grid')

returns 'on' if a grid is visible, and 'off' when it is not.

For a list of the properties and values available for each plot type, see
Properties and Values Reference.

See Also

1-244

setoptions

getPeakGain

Purpose

Peak gain of dynamic system frequency response

Syntax

gpeak = getPeakGain(sys)
gpeak = getPeakGain(sys,tol)
gpeak = getPeakGain(sys,tol,fband)
[gpeak,fpeak] = getPeakGain( ___ )

Description

gpeak = getPeakGain(sys) returns the peak input/output gain in

absolute units of the dynamic system model, sys.

If sys is a SISO model, then the peak gain is the largest value of the
frequency response magnitude.
If sys is a MIMO model, then the peak gain is the largest value of
the frequency response 2-norm (the largest singular value across
frequency) of sys. This quantity is also called the L norm of sys,
and coincides with the H norm for stable systems.
If sys is a model that has tunable or uncertain parameters,
getPeakGain evaluates the peak gain at the current or nominal
value of sys.
If sys is a model array, getPeakGain returns an array of the same
size as sys, where gpeak(k) = getPeakGain(sys(:,:,k)) .
gpeak = getPeakGain(sys,tol) returns the peak gain of sys with

relative accuracy tol.

gpeak = getPeakGain(sys,tol,fband) returns the peak gain in the

frequency interval fband.

[gpeak,fpeak] = getPeakGain( ___ ) also returns the frequency

fpeak at which the gain achieves the peak value gpeak, and can
include any of the input arguments in previous syntaxes.

1-245

getPeakGain

Input
Arguments

sys - Input dynamic system

dynamic system model | model array

Input dynamic system, specified as any dynamic system model or model
array. sys can be SISO or MIMO.

tol - Relative accuracy

0.01 (default) | positive real scalar

Relative accuracy of the peak gain, specified as a positive real scalar

value. getPeakGain calculates gpeak such that the fractional difference
between gpeak and the true peak gain of sys is no greater than tol.
fband - Frequency interval
[0,Inf] (default) | 1-by-2 vector of positive real values

Frequency interval in which to calculate the peak gain, specified as a

1-by-2 vector of positive real values. Specify fband as a row vector
of the form [fmin,fmax].

Output
Arguments

gpeak - Peak gain of dynamic system

scalar | array

Peak gain of the dynamic system model or model array sys, returned as
a scalar value or an array.
If sys is a single model, then gpeak is a scalar value.
If sys is a model array, then gpeak is an array of the same size as
sys, where gpeak(k) = getPeakGain(sys(:,:,k)).
fpeak - Frequency of peak gain
nonnegative real scalar | array of nonnegative real values

Frequency at which the gain achieves the peak value gpeak, returned
as a nonnegative real scalar value or an array of nonnegative real
values. The frequency is expressed in units of rad/TimeUnit, relative
to the TimeUnit property of sys.
If sys is a single model, then fpeak is a scalar.

1-246

getPeakGain

If sys is a model array, then fpeak is an array of the same size as

sys, where fpeak(k) is the peak gain frequency of the kth model in
the array.

Examples

Peak Gain of Transfer Function

Compute the peak gain of the resonance in the transfer function

sys

90
2

s 1.5s 90

sys = tf(90,[1,1.5,90]);
gpeak = getPeakGain(sys);

The getPeakGain command returns the peak gain in absolute units.

Peak Gain with Specified Accuracy

Compute the peak gain of the resonance in the transfer function

sys

90
2

s 1.5s 90

. with a relative accuracy of 0.01%.

sys = tf(90,[1,1.5,90]);
gpeak = getPeakGain(sys,0.0001);

The second argument specifies a relative accuracy of 0.0001. The

getPeakGain command returns a value that is within 0.01% of the true
peak gain of the transfer function.

Peak Gain Within Specified Band

Compute the peak gain of the second resonance in the transfer function

1
100
sys
2
.
2
s 0.2s 1 s s 100
sys is the product of resonances at 1 rad/s and 10 rad/s.
sys = tf(1,[1,.2,1])*tf(100,[1,1,100]);

1-247

getPeakGain

fband = [8,12];
gpeak = getPeakGain(sys,0.01,fband);

The fband argument causes getPeakGain to return the local peak gain
between 8 and 12 rad/s.

Frequency of Peak Gain

Identify which of the two resonances has higher gain in the transfer
function

1
100
sys
2
.
2
s 0.2s 1 s s 100
sys is the product of resonances at 1 rad/s and 10 rad/s.
sys = tf(1,[1,.2,1])*tf(100,[1,1,100]);
[gpeak,fpeak] = getPeakGain(sys)
gpeak =
5.0502

fpeak =
1.0000
fpeak is the frequency corresponding to the peak gain gpeak. The peak
at 1 rad/s is the overall peak gain of sys.

Algorithms

1-248

getPeakGain uses the algorithm of [1]. All eigenvalue computations

are performed using structure-preserving algorithms from the

SLICOT library. For more information about the SLICOT library, see
http://slicot.org.

getPeakGain

References
[1] Bruisma, N.A. and M. Steinbuch, "A Fast Algorithm to Compute the
H-Norm of a Transfer Function Matrix," System Control Letters, 14
(1990), pp. 287-293.

See Also

freqresp | bode | sigma | getGainCrossover

Concepts

Dynamic System Models

1-249

getSensitivity

Purpose

Sensitivity function from generalized model of control system

Syntax

S = getSensitivity(T,location)
S = getSensitivity(T,location,opening)

Description

S = getSensitivity(T,location) returns the sensitivity function at

the specified location for a generalized model of a control system.
S = getSensitivity(T,location,opening) specifies additional loop
openings for the sensitivity function calculation. Use an opening, for
example, to calculate the sensitivity function of an inner loop, with
the outer loop open.

If opening and location list the same point, the software opens the
loop after measuring the signal at the point.

Input
Arguments

T - Model of control system

generalized state-space model

Model of a control system, specified as a Generalized State-Space Model

(genss).
Locations at which you can perform sensitivity analysis or open loops
are marked by loopswitch blocks in T. Use getPoints(T) to get the
list of such locations.
location - Location

string | cell array of strings

Location at which you calculate the sensitivity function, specified as a
string or cell array of strings. To extract the sensitivity function at
multiple locations, use a cell array of strings.

Each string in location must match an analysis point in T. Analysis

points are marked using loopswitch blocks. Use getPoints(T) to get
the list of available analysis points in T.
Example: 'u' or {'u','y'}

1-250

getSensitivity

opening - Additional loop opening

string | cell array of strings

Additional loop opening used to calculate the sensitivity function,

specified as a string or cell array of strings. To open the loop at multiple
locations, use a cell array of strings.
Each string in opening must match an analysis point in T. Analysis
points are marked using loopswitch blocks. Use getPoints(T) to get
the list of available analysis points in T.
Use an opening, for example, to calculate the sensitivity function of an
inner loop, with the outer loop open.
If opening and location list the same point, the software opens the
loop after measuring the signal at the point.
Example: 'y_outer' or {'y_outer','y_outer2'}

Output
Arguments

S - Sensitivity function
generalized state-space model

Sensitivity function of the control system, T, measured at location,

returned as a Generalized State-Space Model (genss).
If location is a string specifying a single loop opening location,
then S is a SISO genss model.
If location is a string specifying a vector signal, or a cell array
identifying multiple loop opening locations, then S is a MIMO genss
model.

Examples

Sensitivity Function at a Location

Compute the sensitivity at the plant input, X.

+
-

C(s)

G(s)

1-251

getSensitivity

Create a model of the system by specifying and connecting a numeric

LTI plant model G, a tunable controller C, and the loopswitch block X.
Use the loopswitch block to mark the location where you assess the
sensitivity (plant input in this example).
G = tf([1],[1 5]);
C = ltiblock.pid('C','p');
C.Kp.Value = 3;
X = loopswitch('X');
T = feedback(G*X*C,1);
T is a genss model that represents the closed-loop response of the
control system from r to y. The model contains the loopswitch block, X,

that identifies the potential loop-opening location.

Calculate the sensitivity, S, at X.
S = getSensitivity(T,'X');
tf(S)
ans =
From input "X" to output "X":
s + 5
----s + 8
Continuous-time transfer function.

Specify Additional Loop Opening for Sensitivity Function

Calculation
Calculate the inner-loop sensitivity at the output of G2, with the outer
loop open.

1-252

getSensitivity

+
-

C1

+
-

C2

G2

G1

X2
X1
Create a model of the system by specifying and connecting the numeric
plant models, tunable controllers, and loopswitch blocks. G1 and G2
are plant models, C1 and C2 are tunable controllers, and X1 and X2 are
loopswitch blocks that mark potential loop-opening locations.
G1 = tf(10,[1 10]);
G2 = tf([1 2],[1 0.2 10]);
C1 = ltiblock.pid('C','pi');
C2 = ltiblock.gain('G',1);
X1 = loopswitch('X1');
X2 = loopswitch('X2');
T = feedback(G1*feedback(G2*C2,X2)*C1,X1);

Calculate the sensitivity, S, at X2, with the outer-loop open at X1.

S = getSensitivity(T,'X2','X1');
tf(S)
ans =
From input "X2" to output "X2":
s^2 + 0.2 s + 10
---------------s^2 + 1.2 s + 12
Continuous-time transfer function.

1-253

getSensitivity

Definitions

Sensitivity Function
The sensitivity function, also referred to simply as sensitivity, measures
how sensitive a signal is to an added disturbance. Feedback reduces the
sensitivity in the frequency band where the open-loop gain is greater
than 1.
Consider the following model:

The sensitivity, Su, at u is defined as the transfer function from du to u:

u
du
r

+
+

u du KGu
( I KG)u du
1
u (
I

KG
) du.
Su

Here, I is an identity matrix of the same size as KG.

Sensitivity at multiple locations, for example, u and y, is defined
as the MIMO transfer function from the disturbances to sensitivity
measurements:

1-254

getSensitivity

u
du
r

Sduu
S
Sdu y

See Also

dy
y

Sdyu
.
Sdy y

getSwitches | loopswitch | genss | getLoopTransfer | systune | |

getIOTransfer | getCompSensitivity | getValue | getSensitivity

1-255

getSwitches

Purpose

Get list of loop opening sites in generalized model of control system

Syntax

Locations = getSwitches(T)

Description

Locations = getSwitches(T) returns the names of all loop-opening

Input
Arguments

T - Model of control system

sites in a Generalized State-Space Model of a control system. Use

these names to calculate open- or closed-loop responses using
getLoopTransfer or getIOTransfer.

generalized state-space model

Model of a control system, specified as a Generalized State-Space

(genss) Model. Locations at which you can open loops and perform
open-loop analysis are marked by loopswitch blocks in T.

Output
Arguments

Locations - Loop-opening sites

cell array of strings

Loop-opening sites in the control system model, returned as a cell array

of strings. The strings contain the loop channel names. These loop
channel names are the contents of the Location property of each
loopswitch block in the control system model.

Examples

Loop Opening Sites in Control System Model

Build a closed-loop model of a cascaded feedback loop system, and get a
list of loop-opening sites in the model.
Create a model of the following cascaded feedback loop. C1 and C2 are
tunable controllers. X1 and X2 are loop-opening sites.

1-256

getSwitches

+
-

C1

+
-

C2

G2

G1

X2
X1
G1 = tf(10,[1 10]);
G2 = tf([1 2],[1 0.2 10]);
C1 = ltiblock.pid('C','pi');
C2 = ltiblock.gain('G',1);
X1 = loopswitch('X1');
X2 = loopswitch('X2');
T = feedback(G1*feedback(G2*C2,X2)*C1,X1);
T is a genss model whose Control Design Blocks include the tunable
controllers and the switches X1 and X2.

Get a list of the loop-opening sites in T.

Locations = getSwitches(T)
Locations =
'X1'
'X2'
getSwitches returns a cell array listing loop-opening sites in the model.

For more complicated closed-loop models, you can use getSwitches to

keep track of a larger number of loop-opening sites. You can use these
loop-opening sites to specify an open-loop response to compute. For
instance, the following command computes the open-loop response of
the inner loop, with the outer loop open.

1-257

getSwitches

L = getLoopTransfer(T,'X2',-1,'X1');

See Also

loopswitch | genss | getLoopTransfer | getIOTransfer

Concepts

Generalized Models

1-258

getValue

Purpose

Current value of Generalized Model

Syntax

curval = getValue(M)
curval = getValue(M,blockvalues)
curval = getValue(M,Mref)

Description

curval = getValue(M) returns the current value curval of the

Generalized LTI model or Generalized matrix M. The current value is

obtained by replacing all Control Design Blocks in M by their current
value. (For uncertain blocks, the current value is the nominal value of
the block.)
curval = getValue(M,blockvalues) uses the block values specified

in the structure blockvalues to compute the current value. The

field names and values of blockvalues specify the block names and
corresponding values. Blocks of M not specified in blockvalues are
replaced by their current values.
curval = getValue(M,Mref) inherits block values from the
generalized model Mref. This syntax is equivalent to curval =
getValue(M,Mref.Blocks). Use this syntax to evaluate the current
value of M using block values computed elsewhere (for example, tuned
values obtained with Robust Control Toolbox tuning commands such as
systune, looptune, or hinfstruct).

Input
Arguments

Generalized LTI model or Generalized matrix.

blockvalues

Structure specifying blocks of M to replace and the values with which to

replace those blocks.
The field names of blockvalues match names of Control Design
Blocks of M. Use the field values to specify the replacement values for
the corresponding blocks of M. The field values can be numeric values,
dynamic system models, or static models. If some field values are

1-259

getValue

Control Design Blocks or Generalized LTI models, the current values

of those models are used to compute curval.
Mref

Generalized LTI model. If you provide Mref, getValue computes

curval using the current values of the blocks in Mref whose names
match blocks in M.

Output
Arguments

curval

Numeric array or Numeric LTI model representing the current value

of M.
If you do not specify a replacement value for a given Control Design
Block of M, getValue uses the current value of that block.

Examples

Evaluate Model for Specified Values of its Blocks

This example shows how to replace a Control Design Block in a
Generalized LTI model with a specified replacement value using
getValue.
Consider the following closed-loop system:

+
-

C(s)

G(s)

The following code creates a genss model of this system with

G s

s 1
s 1 3

and a tunable PI controller C.

G = zpk(1,[-1,-1,-1],1);
C = ltiblock.pid('C','pi');
Try = feedback(G*C,1)

1-260

getValue

The genss model Try has one Control Design Block, C. The block C is
initialized to default values, and the model Try has a current value that
depends on the current value of C. Use getValue to evaluate C and
Try to examine the current values.
1 Evaluate C to obtain its current value.

Cnow = getValue(C)

This command returns a numeric pid object whose coefficients reflect

the current values of the tunable parameters in C.
2 Evaluate Try to obtain its current value.

Tnow = getValue(Try)

This commend returns a numeric model that is equivalent to

feedback(G*Cnow,1).

Access Values of Tuned Models and Blocks

Propagate changes in block values from one model to another using
getValue.
This technique is useful for accessing values of models and blocks
tuned with Robust Control Toolbox tuning commands such as systune,
looptune, or hinfstruct. For example, if you have a closed-loop model
of your control system T0, with two tunable blocks, C1 and C2, you can
tune it using:
[T,fSoft] = systune(T0,SoftReqs);

You can then access the tuned values of C1 and C2, as well as any
closed-loop model H that depends on C1 and C2, using the following:
C1t = getValue(C1,T);
C2t = getValue(C2,T);
Ht = getValue(H,T);

1-261

getValue

See Also

1-262

genss | replaceBlock | systune | looptune | hinfstruct

gram

Purpose

Controllability and observability gramians

Syntax

Wc = gram(sys,'c')
Wc = gram(sys,'o')

Description

Wc = gram(sys,'c') calculates the controllability gramian of the

state-space (ss) model sys.
Wc = gram(sys,'o') calculates the observability gramian of the ss

model sys.
You can use gramians to study the controllability and observability
properties of state-space models and for model reduction [1] . They have
better numerical properties than the controllability and observability
matrices formed by ctrb and obsv.
Given the continuous-time state-space model

x = Ax + Bu
y = Cx + Du
the controllability gramian is defined by

Wc =

0 e

T
BBT e A d

The controllability gramian is positive definite if and only if (A, B) is

controllable.
The observability gramian is defined by

Wo =

AT

0 e

C T Ce A d

The observability gramian is positive definite if and only if (C, B) is

observable.
The discrete-time counterparts of the controllability and observability
gramians are

1-263

gram

Wc =

Ak BBT ( AT )k ,

k= 0

Wo = ( AT ) k C T CA k
k= 0

respectively.

Algorithms

The controllability gramian Wc is obtained by solving the

continuous-time Lyapunov equation

AWc + Wc AT + BBT = 0
or its discrete-time counterpart

AWc AT Wc + BBT = 0
Similarly, the observability gramian Wo solves the Lyapunov equation

AT Wo + Wo A + C T C = 0
in continuous time, and the Lyapunov equation

AT Wo A Wo + C T C = 0
in discrete time.

Limitations

The A matrix must be stable (all eigenvalues have negative real part in
continuous time, and magnitude strictly less than one in discrete time).

References

[1] Kailath, T., Linear Systems, Prentice-Hall, 1980.

See Also

balreal | ctrb | lyap | dlyap | obsv

1-264

hasdelay

Purpose

True for linear model with time delays

Syntax

B = hasdelay(sys)
B = hasdelay(sys,'elem')

Description

B = hasdelay(sys) returns 1 (true) if the model sys has input delays,

output delays, I/O delays, or internal delays, and 0 (false) otherwise. If

sys is a model array, then B is true if least one model in sys has delays.
B = hasdelay(sys,'elem') returns a logical array of the same size as
the model array sys. The logical array indicates which models in sys
have delays.

See Also

absorbDelay | totaldelay

1-265

hasInternalDelay

Purpose

Determine if model has internal delays

Syntax

B = hasInternalDelay(sys)
B = hasInternalDelay(sys,'elem')

Description

B = hasInternalDelay(sys) returns 1 (true) if the model sys has

internal delays, and 0 (false) otherwise. If sys is a model array, then

B is true if least one model in sys has delays.
B = hasInternalDelay(sys,'elem') checks each model in the model
array sys and returns a logical array of the same size as sys. The
logical array indicates which models in sys have internal delays.

Input
Arguments

sys - Model or array to check

dynamic system model | model array

Model or array to check for internal delays, specified as a dynamic
system model or array of dynamic system models.

Output
Arguments

B - Flag indicating presence of internal delays

logical | logical array

Flag indicating presence of internal delays in input model or array,

returned as a logical value or logical array.

Examples

Check model for internal delays

Build a dynamic system model of the following closed-loop system and
check the model for internal delays.

s = tf('s');
G = exp(-2.4*s)/(s-5);
C = pid(5,0.1);

1-266

hasInternalDelay

sys = feedback(G*C,1);
B = hasInternalDelay(sys)
B =
1

The model sys has an internal delay because of the transfer delay in
the plant G. Therefore, hasInternalDelay returns 1.

See Also

hasdelay | getDelayModel

1-267

hsvd

Purpose

Hankel singular values of dynamic system

Syntax

hsv = hsvd(sys)
hsv = hsvd(sys,'AbsTol',ATOL,'RelTol',RTOL,'Offset',ALPHA)
hsv = hsvd(sys, opts)
hsvd(sys)
[hsv,baldata] = hsvd(sys)

Description

hsv = hsvd(sys) computes the Hankel singular values hsv of

the dynamic system sys. In state coordinates that equalize the
input-to-state and state-to-output energy transfers, the Hankel singular
values measure the contribution of each state to the input/output
behavior. Hankel singular values are to model order what singular
values are to matrix rank. In particular, small Hankel singular values
signal states that can be discarded to simplify the model (see balred).

For models with unstable poles, hsvd only computes the Hankel
singular values of the stable part and entries of hsv corresponding to
unstable modes are set to Inf.
hsv = hsvd(sys,'AbsTol',ATOL,'RelTol',RTOL,'Offset',ALPHA)

specifies additional options for the stable/unstable decomposition. See

the stabsep reference page for more information about these options.
The default values are ATOL = 0, RTOL = 1e-8, and ALPHA = 1e-8.
hsv = hsvd(sys, opts) computes the Hankel singular values using
the options specified in the hsvdOptions object opts.
hsvd(sys) displays a Hankel singular values plot.
[hsv,baldata] = hsvd(sys) returns additional data to speed up
model order reduction with balred. For example
sys = rss(20);
% 20-th order model
[hsv,baldata] = hsvd(sys);
rsys = balred(sys,8:10,'Balancing',baldata);
bode(sys,'b',rsys,'r--')

computes three approximations of sys of orders 8, 9, 10.

1-268

hsvd

There is more than one hsvd available. Type

help lti/hsvd

for more information.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Algorithms

The AbsTol, RelTol, and ALPHA parameters are only used for models
with unstable or marginally stable dynamics. Because Hankel singular
values are only meaningful for stable dynamics, hsvd must first split
such models into the sum of their stable and unstable parts:
G = G_s + G_ns

This decomposition can be tricky when the model has modes close to
the stability boundary (e.g., a pole at s=-1e-10), or clusters of modes on
the stability boundary (e.g., double or triple integrators). While hsvd is
able to overcome these difficulties in most cases, it sometimes produces
unexpected results such as
1 Large Hankel singular values for the stable part.

This happens when the stable part G_s contains some poles very
close to the stability boundary. To force such modes into the unstable
group, increase the 'Offset' option to slightly grow the unstable
region.
2 Too many modes are labeled "unstable." For example, you see 5 red

bars in the HSV plot when your model had only 2 unstable poles.
The stable/unstable decomposition algorithm has built-in accuracy
checks that reject decompositions causing a significant loss of
accuracy in the frequency response. Such loss of accuracy arises,
e.g., when trying to split a cluster of stable and unstable modes near

1-269

hsvd

s=0. Because such clusters are numerically equivalent to a multiple

pole at s=0, it is actually desirable to treat the whole cluster as
unstable. In some cases, however, large relative errors in low-gain
frequency bands can trip the accuracy checks and lead to a rejection
of valid decompositions. Additional modes are then absorbed into the
unstable part G_ns, unduly increasing its order.

Such issues can be easily corrected by adjusting the AbsTol and

RelTol tolerances. By setting AbsTol to a fraction of smallest gain of
interest in your model, you tell the algorithm to ignore errors below a
certain gain threshold. By increasing RelTol, you tell the algorithm
to sacrifice some relative model accuracy in exchange for keeping
more modes in the stable part G_s.

Examples

Compute Hankel Singular Values

This example illustrates how to compute Hankel singular values.
First, create a system with a stable pole very near to 0, then calculate
the Hankel singular values.
sys = zpk([1 2],[-1 -2 -3 -10 -1e-7],1)
hsvd(sys)
Zero/pole/gain:
(s-1) (s-2)
----------------------------------(s+1) (s+2) (s+3) (s+10) (s+1e-007)

1-270

hsvd

For a better view of the Hankel singular values, switch the plot to log
scale by selecting Y Scale > Log from the right-click menu.

1-271

hsvd

Notice the dominant Hankel singular value with 1e5 magnitude, due
to the mode s=-1e-7 near the imaginary axis. Set the offset=1e-6 to
treat this mode as unstable
hsvd(sys,'Offset',1e-7)

1-272

hsvd

The dominant Hankel singular value is now shown as unstable.

See Also

hsvdOptions | balred | balreal

1-273

hsvdOptions

Purpose

Create option set for computing Hankel singular values and

input/output balancing

Syntax

opts = hsvdOptions
opts = hsvdOptions('OptionName', OptionValue)

Description

opts = hsvdOptions returns the default options for the hsvd and
balreal commands.
opts = hsvdOptions('OptionName', OptionValue) accepts one or
more comma-separated name/value pairs. Specify OptionName inside

single quotes.

Input
Arguments

Name-Value Pair Arguments

AbsTol, RelTol

Absolute and relative error tolerance for stable/unstable decomposition.

Positive scalar values. For an input model G with unstable poles,
hsvd and balreal first extract the stable dynamics by computing the
stable/unstable decomposition G GS + GU. The AbsTol and RelTol
tolerances control the accuracy of this decomposition by ensuring that
the frequency responses of G and GS + GU differ by no more than
AbsTol + RelTol*abs(G). Increasing these tolerances helps separate
nearby stable and unstable modes at the expense of accuracy. See
stabsep for more information.
Default: AbsTol = 0; RelTol = 1e-8
Offset

Offset for the stable/unstable boundary. Positive scalar value. In the

stable/unstable decomposition, the stable term includes only poles
satisfying:
Re(s) < -Offset * max(1,|Im(s)|) (Continuous time)
|z| < 1 - Offset (Discrete time)

1-274

hsvdOptions

Increase the value of Offset to treat poles close to the stability

boundary as unstable.
Default: 1e-8
For additional information on the options and how to use them, see the
hsvd and balreal reference pages.

Examples

Compute the Hankel singular values of the system given by:

sys =

( s + 0 .5 )
( s + 106 ) ( s + 2)

Use the Offset option to force hsvd to exclude the pole at s = 106 from
the stable term of the stable/unstable decomposition.
sys = zpk(-.5,[-1e-6 -2],1);
opts = hsvdOptions('Offset',.001); % create option set
hsvd(sys,opts) % treats -1e-6 as unstable

See Also

hsvd | balreal

1-275

hsvoptions

Purpose

Create list of Hankel singular value plot options

Syntax

P = hsvoptions
P = HSVOPTIONS('cstpref')

Description

P = hsvoptions returns a list of available options for Hankel singular

value (HSV) plots with default values set. You can use these options
to customize the Hankel singular value plot appearance using the
command line.
P = HSVOPTIONS('cstpref') initializes the plot options you selected in

the Control System Toolbox Preferences Editor dialog box. For more
information about the editor, see Toolbox Preferences Editor in the
Users Guide documentation.
This table summarizes the Hankel singular value plot options.

Examples

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid [off|on]

Show or hide the grid

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

YScale [linear|log]

Scale for Y-axis

AbsTol, RelTol, Offset

Parameters for the Hankel

singular value computation (used
only for models with unstable
dynamics). See hsvd and stabsep
for details.

In this example, you set the scale for the Y-axis in the HSV plot.
P = hsvoptions; % Set the Y-axis scale to linear in options
P.YScale = 'linear'; % Create plot with the options specified by P

1-276

hsvoptions

h = hsvplot(rss(2,2,3),P);

The following HSV plot is created, with a linear scale for the Y-axis.

See Also

hsvd | hsvplot | getoptions | setoptions | stabsep

1-277

hsvplot

Purpose

Plot Hankel singular values and return plot handle

Syntax

h = hsvplot(sys)
hsvplot(sys)
hsvplot(sys, AbsTol',ATOL,'RelTol',RTOL,'Offset',ALPHA)
hsvplot(AX,sys,...)

Description

h = hsvplot(sys) plots the Hankel singular values of an LTI system

sys and returns the plot handle h. You can use this handle to customize
the plot with the getoptions and setoptions commands. Type
help hsvoptions

for a list of available plot options.

hsvplot(sys) plots the Hankel singular values of the LTI model sys.
See hsvd for details on the meaning and purpose of Hankel singular
values. The Hankel singular values for the stable and unstable modes
of sys are shown in blue and red, respectively.
hsvplot(sys, AbsTol',ATOL,'RelTol',RTOL,'Offset',ALPHA)

specifies additional options for computing the Hankel singular values.

hsvplot(AX,sys,...) attaches the plot to the axes with handle AX.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Use the plot handle to change plot options in the Hankel singular
values plot.
sys = rss(20);
h = hsvplot(sys,'AbsTol',1e-6);
% Switch to log scale and modify Offset parameter
setoptions(h,'Yscale','log','Offset',0.3)

See Also

1-278

getoptions | hsvd | hsvoptions | setoptions

imp2exp

Purpose

Convert implicit linear relationship to explicit input-output relation

Syntax

B = imp2exp(A,yidx,uidx)

Description

B = imp2exp(A,yidx,uidx) transforms a linear constraint between

variables Y and U of the form A(:,[yidx;uidx])*[Y;U] = 0 into an
explicit input/output relationship Y = B*U. The vectors yidx and
uidx refer to the columns (inputs) of A as referenced by the explicit
relationship for B.

The constraint matrix A can be a double, ss, tf, zpk and frd object
as well as an uncertain object, including umat, uss and ufrd. The result
B will be of the same class.

Examples

Scalar Algebraic Constraint

Consider the constraint 4y + 7u = 0. Solving for y gives y = 1.75u.
You form the equation using imp2exp:
A = [4 7];
Yidx = 1;
Uidx = 2;

and then
B = imp2exp(A,Yidx,Uidx)
B =
-1.7500

yields B equal to -1.75.

Matrix Algebraic Constraint

Consider two motor/generator constraints among 4 variables [V;I;T;W],
namely [1 -1 0 -2e-3;0 -2e-3 1 0]*[V;I;T;W] = 0. You can find
the 2-by-2 matrix B so that [V;T] = B*[W;I] using imp2exp.
A = [1 -1 0 -2e-3;0 -2e-3 1 0];
Yidx = [1 3];

1-279

imp2exp

Uidx = [4 2];
B = imp2exp(A,Yidx,Uidx)
B =
0.0020
1.0000
0
0.0020

You can find the 2-by-2 matrix C so that [I;W] = C*[T;V]

Yidx = [2 4];
Uidx = [3 1];
C = imp2exp(A,Yidx,Uidx)
C =
500
0
-250000
500

Uncertain Matrix Algebraic Constraint

Consider two uncertain motor/generator constraints among 4 variables
[V;I;T;W], namely [1 -R 0 -K;0 -K 1 0]*[V;I;T;W] = 0. You can
find the uncertain 2-by-2 matrix B so that [V;T] = B*[W;I].
R = ureal('R',1,'Percentage',[-10 40]);
K = ureal('K',2e-3,'Percentage',[-30 30]);
A = [1 -R 0 -K;0 -K 1 0];
Yidx = [1 3];
Uidx = [4 2];
B = imp2exp(A,Yidx,Uidx)
UMAT: 2 Rows, 2 Columns
K: real, nominal = 0.002, variability = [-30 30]%, 2 occurrences
R: real, nominal = 1, variability = [-10 40]%, 1 occurrence

Scalar Dynamic System Constraint

Consider a standard single-loop feedback connection of controller C
and an uncertain plant P, described by the equations e=r-y, u=Ce;
f=d+u; y=Pf.

1-280

imp2exp

P = tf([1],[1 0]);
C = tf([2*.707*1 1^2],[1 0]);
A = [1 -1 0 0 0 -1;0 -C 1 0 0 0;0 0 -1 -1 1 0;0 0 0 0 -P 1];
OutputIndex = [6;3;2;5]; % [y;u;e;f]
InputIndex = [1;4];
% [r;d]
Sys = imp2exp(A,OutputIndex,InputIndex);
Sys.InputName = {'r';'d'};
Sys.OutputName = {'y';'u';'e';'f'};
pole(Sys)
ans =
-0.7070 + 0.7072i
-0.7070 - 0.7072i
step(Sys)

1-281

imp2exp

Algorithms

The number of rows of A must equal the length of yidx.

See Also

iconnect | inv

1-282

impulse

Purpose

Impulse response plot of dynamic system; impulse response data

Syntax

impulse(sys)
impulse(sys,Tfinal)
impulse(sys,t)
impulse(sys1,sys2,...,sysN)
impulse(sys1,sys2,...,sysN,Tfinal)
impulse(sys1,sys2,...,sysN,t)
[y,t] = impulse(sys)
[y,t] = impulse(sys,Tfinal)
y = impulse(sys,t)
[y,t,x] = impulse(sys)
[y,t,x,ysd] = impulse(sys)

Description

impulse calculates the unit impulse response of a dynamic system

model. For continuous-time dynamic systems, the impulse response
is the response to a Dirac input (t). For discrete-time systems, the
impulse response is the response to a unit area pulse of length Ts and
height 1/Ts, where Ts is the sampling time of the system. (This pulse
approaches (t) as Ts approaches zero.) For state-space models, impulse
assumes initial state values are zero.
impulse(sys) plots the impulse response of the dynamic system
model sys. This model can be continuous or discrete, and SISO or

MIMO. The impulse response of multi-input systems is the collection of

impulse responses for each input channel. The duration of simulation
is determined automatically to display the transient behavior of the
response.
impulse(sys,Tfinal) simulates the impulse response from t = 0 to
the final time t = Tfinal. Express Tfinal in the system time units,
specified in the TimeUnit property of sys. For discrete-time systems
with unspecified sampling time (Ts = -1), impulse interprets Tfinal

as the number of sampling periods to simulate.

impulse(sys,t) uses the user-supplied time vector t for simulation.
Express t in the system time units, specified in the TimeUnit property
of sys. For discrete-time models, t should be of the form Ti:Ts:Tf,

1-283

impulse

where Ts is the sample time. For continuous-time models, t should be

of the form Ti:dt:Tf, where dt becomes the sample time of a discrete
approximation to the continuous system (see Algorithms on page
1-288). The impulse command always applies the impulse at t=0,
regardless of Ti.
To plot the impulse responses of several models sys1,..., sysN on a
single figure, use:
impulse(sys1,sys2,...,sysN)
impulse(sys1,sys2,...,sysN,Tfinal)
impulse(sys1,sys2,...,sysN,t)

As with bode or plot, you can specify a particular color, linestyle,

and/or marker for each system, for example,
impulse(sys1,'y:',sys2,'g--')

See "Plotting and Comparing Multiple Systems" and the bode entry in
this section for more details.
When invoked with output arguments:
[y,t] = impulse(sys)
[y,t] = impulse(sys,Tfinal)
y = impulse(sys,t)
impulse returns the output response y and the time vector t used for
simulation (if not supplied as an argument to impulse). No plot is
drawn on the screen. For single-input systems, y has as many rows
as time samples (length of t), and as many columns as outputs. In
the multi-input case, the impulse responses of each input channel are
stacked up along the third dimension of y. The dimensions of y are then

For state-space models only:

[y,t,x] = impulse(sys)

(length of t) (number of outputs) (number of inputs)

1-284

impulse

and y(:,:,j) gives the response to an impulse disturbance entering

the jth input channel. Similarly, the dimensions of x are
(length of t) (number of states) (number of inputs)
[y,t,x,ysd] = impulse(sys) returns the standard deviation YSD of
the response Y of an identified system SYS. YSD is empty if SYS does not
contain parameter covariance information.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Impulse Response Plot of Second-Order State-Space Model
Plot the impulse response of the second-order state-space model

x1 0.5572 0.7814 x1 1 1 u1
x = 0.7814
x + 0 2 u
0
2
2
2
x1
y = [1.9691 6.4493]
x2
use the following commands.
a = [-0.5572 -0.7814;0.7814
b = [1 -1;0 2];
c = [1.9691 6.4493];
sys = ss(a,b,c,0);
impulse(sys)

0];

1-285

impulse

The left plot shows the impulse response of the first input channel, and
the right plot shows the impulse response of the second input channel.
You can store the impulse response data in MATLAB arrays by
[y,t] = impulse(sys);

Because this system has two inputs, y is a 3-D array with dimensions
size(y)

1-286

impulse

ans =
139

(the first dimension is the length of t). The impulse response of the first
input channel is then accessed by
ch1 = y(:,:,1);
size(ch1)

ans =
139

Example 2
Fetch the impulse response and the corresponding 1 std uncertainty of
an identified linear system.
load(fullfile(matlabroot, 'toolbox', 'ident', 'iddemos', 'data', 'dcmotordata'));
z = iddata(y, u, 0.1, 'Name', 'DC-motor');
set(z, 'InputName', 'Voltage', 'InputUnit', 'V');
set(z, 'OutputName', {'Angular position', 'Angular velocity'});
set(z, 'OutputUnit', {'rad', 'rad/s'});
set(z, 'Tstart', 0, 'TimeUnit', 's');

model = tfest(z,2);
[y,t,~,ysd] = impulse(model,2);

% Plot 3 std uncertainty

subplot(211)
plot(t,y(:,1), t,y(:,1)+3*ysd(:,1),'k:', t,y(:,1)-3*ysd(:,1),'k:')

1-287

impulse

subplot(212)
plot(t,y(:,2), t,y(:,2)+3*ysd(:,2),'k:', t,y(:,2)-3*ysd(:,2),'k:')

Algorithms

Continuous-time models are first converted to state space. The impulse

response of a single-input state-space model

x = Ax + bu
y = Cx
is equivalent to the following unforced response with initial state b.

x = Ax, x(0) = b
y = Cx
To simulate this response, the system is discretized using zero-order
hold on the inputs. The sampling period is chosen automatically based
on the system dynamics, except when a time vector t = 0:dt:Tf is
supplied (dt is then used as sampling period).

Limitations

The impulse response of a continuous system with nonzero D matrix

is infinite at t = 0. impulse ignores this discontinuity and returns the
lower continuity value Cb at t = 0.

See Also

ltiview | step | initial | lsim

1-288

impulseplot

Purpose

Plot impulse response and return plot handle

Syntax

impulseplot(sys)
impulseplot(sys,Tfinal)
impulseplot(sys,t)
impulseplot(sys1,sys2,...,sysN)
impulseplot(sys1,sys2,...,sysN,Tfinal)
impulseplot(sys1,sys2,...,sysN,t)
impulseplot(AX,...)
impulseplot(..., plotoptions)
h = impulseplot(...)

Description

impulseplot plots the impulse response of the dynamic system model

sys. For multi-input models, independent impulse commands are

applied to each input channel. The time range and number of points are
chosen automatically. For continuous systems with direct feedthrough,
the infinite pulse at t=0 is disregarded. impulseplot can also return
the plot handle, h. You can use this handle to customize the plot with
the getoptions and setoptions commands. Type
help timeoptions

for a list of available plot options.

impulseplot(sys) plots the impulse response of the LTI model without

returning the plot handle.

impulseplot(sys,Tfinal) simulates the impulse response from t = 0
to the final time t = Tfinal. Express Tfinal in the system time units,
specified in the TimeUnit property of sys. For discrete-time systems
with unspecified sampling time (Ts = -1), impulseplot interprets
Tfinal as the number of sampling intervals to simulate.
impulseplot(sys,t) uses the user-supplied time vector t for
simulation. Express t in the system time units, specified in the
TimeUnit property of sys. For discrete-time models, t should be of
the form Ti:Ts:Tf, where Ts is the sample time. For continuous-time
models, t should be of the form Ti:dt:Tf, where dt becomes the

1-289

impulseplot

sample time of a discrete approximation to the continuous system (see

impulse). The impulseplot command always applies the impulse at
t=0, regardless of Ti.
To plot the impulse response of multiple LTI models sys1,sys2,... on a
single plot, use:
impulseplot(sys1,sys2,...,sysN)
impulseplot(sys1,sys2,...,sysN,Tfinal)
impulseplot(sys1,sys2,...,sysN,t)

You can also specify a color, line style, and marker for each system, as in
impulseplot(sys1,'r',sys2,'y--',sys3,'gx')
impulseplot(AX,...) plots into the axes with handle AX.
impulseplot(..., plotoptions) plots the impulse response with the
options specified in plotoptions. Type
help timeoptions

for more detail.

h = impulseplot(...) plots the impulse response and returns the

plot handle h.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Normalize the impulse response of a third-order system.
sys = rss(3);
h = impulseplot(sys);
% Normalize responses
setoptions(h,'Normalize','on');

1-290

impulseplot

Example 2
Plot the impulse response and the corresponding 1 std "zero interval" of
an identified linear system.
load(fullfile(matlabroot, 'toolbox', 'ident', 'iddemos', 'data', 'dcmotordata'));
z = iddata(y, u, 0.1, 'Name', 'DC-motor');
set(z, 'InputName', 'Voltage', 'InputUnit', 'V');
set(z, 'OutputName', {'Angular position', 'Angular velocity'});
set(z, 'OutputUnit', {'rad', 'rad/s'});
set(z, 'Tstart', 0, 'TimeUnit', 's');
model = n4sid(z,4,n4sidOptions('Focus', 'simulation'));
h = impulseplot(model,2);
showConfidence(h);

See Also

getoptions | impulse | setoptions

1-291

initial

Purpose

Initial condition response of state-space model

Syntax

initial(sys,x0)
initial(sys,x0,Tfinal)
initial(sys,x0,t)
initial(sys1,sys2,...,sysN,x0)
initial(sys1,sys2,...,sysN,x0,Tfinal)
initial(sys1,sys2,...,sysN,x0,t)
[y,t,x] = initial(sys,x0)
[y,t,x] = initial(sys,x0,Tfinal)
[y,t,x] = initial(sys,x0,t)

Description

initial(sys,x0) calculates the unforced response of a state-space

(ss) model sys with an initial condition on the states specified by the
vector x0:

x = Ax, x(0) = x0
y = Cx
This function is applicable to either continuous- or discrete-time models.
When invoked without output arguments, initial plots the initial
condition response on the screen.
initial(sys,x0,Tfinal) simulates the response from t = 0 to the
final time t = Tfinal. Express Tfinal in the system time units,
specified in the TimeUnit property of sys. For discrete-time systems
with unspecified sampling time (Ts = -1), initial interprets Tfinal
as the number of sampling periods to simulate.
initial(sys,x0,t) uses the user-supplied time vector t for simulation.
Express t in the system time units, specified in the TimeUnit property
of sys. For discrete-time models, t should be of the form 0:Ts:Tf,
where Ts is the sample time. For continuous-time models, t should be
of the form 0:dt:Tf, where dt becomes the sample time of a discrete
approximation to the continuous system (see impulse).

To plot the initial condition responses of several LTI models on a single

figure, use

1-292

initial

initial(sys1,sys2,...,sysN,x0)
initial(sys1,sys2,...,sysN,x0,Tfinal)
initial(sys1,sys2,...,sysN,x0,t)

(see impulse for details).

When invoked with output arguments,
[y,t,x] = initial(sys,x0)
[y,t,x] = initial(sys,x0,Tfinal)
[y,t,x] = initial(sys,x0,t)

return the output response y, the time vector t used for simulation, and
the state trajectories x. No plot is drawn on the screen. The array y has
as many rows as time samples (length of t) and as many columns as
outputs. Similarly, x has length(t) rows and as many columns as
states.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Plot the response of the state-space model

x1 0.5572 0.7814 x1
x = 0.7814
x
0
2
2
x

y = [1.9691 6.4493] 1
x2
to the initial condition

1
x(0) =
0
a = [-0.5572

-0.7814;0.7814

0];

1-293

initial

c = [1.9691 6.4493];
x0 = [1 ; 0]
sys = ss(a,[],c,[]);
initial(sys,x0)

See Also

1-294

impulse | lsim | ltiview | step

initialplot

Purpose

Plot initial condition response and return plot handle

Syntax

initialplot(sys,x0)
initialplot(sys,x0,Tfinal)
initialplot(sys,x0,t)
initialplot(sys1,sys2,...,sysN,x0)
initialplot(sys1,sys2,...,sysN,x0,Tfinal)
initialplot(sys1,sys2,...,sysN,x0,t)
initialplot(AX,...)
initialplot(..., plotoptions)
h = initialplot(...)

Description

initialplot(sys,x0) plots the undriven response of the state-space

(ss) model sys with initial condition x0 on the states. This response is
characterized by these equations:

Continuous time: x = A x, y = C x, x(0) = x0

Discrete time: x[k+1] = A x[k], y[k] = C x[k], x[0] = x0
The time range and number of points are chosen automatically.
initialplot also returns the plot handle h. You can use this handle to
customize the plot with the getoptions and setoptions commands.

Type
help timeoptions

for a list of available plot options.

initialplot(sys,x0,Tfinal) simulates the response from t = 0 to
the final time t = Tfinal. Express Tfinal in the system time units,
specified in the TimeUnit property of sys. For discrete-time systems
with unspecified sampling time (Ts = -1), initialplot interprets
Tfinal as the number of sampling periods to simulate.
initialplot(sys,x0,t) uses the user-supplied time vector t for
simulation. Express t in the system time units, specified in the
TimeUnit property of sys. For discrete-time models, t should be of
the form 0:Ts:Tf, where Ts is the sample time. For continuous-time

1-295

initialplot

models, t should be of the form 0:dt:Tf, where dt becomes the sample

time of a discrete approximation to the continuous system (see impulse).
To plot the initial condition responses of several LTI models on a single
figure, use
initialplot(sys1,sys2,...,sysN,x0)
initialplot(sys1,sys2,...,sysN,x0,Tfinal)
initialplot(sys1,sys2,...,sysN,x0,t)

You can also specify a color, line style, and marker for each system, as in
initialplot(sys1,'r',sys2,'y--',sys3,'gx',x0).
initialplot(AX,...) plots into the axes with handle AX.
initialplot(..., plotoptions) plots the initial condition response
with the options specified in plotoptions. Type
help timeoptions

for more detail.

h = initialplot(...) plots the system response and returns the

plot handle h.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Plot a third-order systems response to initial conditions and use the

plot handle to change the plots title.
sys = rss(3);
h = initialplot(sys,[1,1,1])
p = getoptions(h); % Get options for plot.
p.Title.String = 'My Title'; % Change title in options.
setoptions(h,p); % Apply options to the plot.

1-296

initialplot

See Also

getoptions | initial | setoptions

1-297

interp

Purpose

Interpolate FRD model

Syntax

isys = interp(sys,freqs)

Description

isys = interp(sys,freqs) interpolates the frequency response data

contained in the FRD model sys at the frequencies freqs. interp,
which is an overloaded version of the MATLAB function interp, uses
linear interpolation and returns an FRD model isys containing the
interpolated data at the new frequencies freqs. If sys is an IDFRD
model (requires System Identification Toolbox software), the noise
spectrum, if non-empty, is also interpolated. The response and noise
covariance data, if available, are also interpolated.

You should express the frequency values freqs in the same units as
sys.frequency. The frequency values must lie between the smallest
and largest frequency points in sys (extrapolation is not supported).

See Also

1-298

freqresp | frd

inv

Purpose

Invert models

Syntax

inv

Description

inv inverts the input/output relation

y = G(s)u
to produce the model with the transfer matrix H (s) = G(s)1 .

u = H (s) y
This operation is defined only for square systems (same number of
inputs and outputs) with an invertible feedthrough matrix D. inv
handles both continuous- and discrete-time systems.

Examples

Consider

1
H (s) =

1
s + 1

At the MATLAB prompt, type

H = [1 tf(1,[1 1]);0 1]
Hi = inv(H)

to invert it. These commands produce the following result.

Transfer function from input 1 to output...
#1: 1
#2:

Transfer function from input 2 to output...

-1
#1: -----

1-299

inv

s + 1
#2:

You can verify that

H * Hi

is the identity transfer function (static gain I).

Limitations

Do not use inv to model feedback connections such as

While it seems reasonable to evaluate the corresponding closed-loop

transfer function ( I + GH )1 G as
inv(1+g*h) * g

this typically leads to nonminimal closed-loop models. For example,

g = zpk([],1,1)
h = tf([2 1],[1 0])
cloop = inv(1+g*h) * g

yields a third-order closed-loop model with an unstable pole-zero

cancellation at s = 1.
cloop
Zero/pole/gain:
s (s-1)

1-300

inv

------------------(s-1) (s^2 + s + 1)

Use feedback to avoid such pitfalls.

cloop = feedback(g,h)
Zero/pole/gain:
s
------------(s^2 + s + 1)

1-301

iopzmap

Purpose

Plot pole-zero map for I/O pairs of model

Syntax

iopzmap(sys)
iopzmap(sys1,sys2,...)

Description

iopzmap(sys) computes and plots the poles and zeros of each

input/output pair of the dynamic system model sys. The poles are
plotted as xs and the zeros are plotted as os.
iopzmap(sys1,sys2,...) shows the poles and zeros of multiple models
sys1,sys2,... on a single plot. You can specify distinctive colors for each
model, as in iopzmap(sys1,'r',sys2,'y',sys3,'g').

The functions sgrid or zgrid can be used to plot lines of constant

damping ratio and natural frequency in the s or z plane.
For model arrays, iopzmap plots the poles and zeros of each model in
the array on the same diagram.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Create a one-input, two-output system and plot pole-zero maps for I/O
pairs.
H = [tf(-5 ,[1 -1]); tf([1 -5 6],[1 1 0])];
iopzmap(H)

1-302

iopzmap

Example 2
View the poles and zeros of an over-parameterized state-space model
estimated using input-output data.
load iddata1
sys = ssest(z1,6,ssestOptions('focus','simulation'))
iopzmap(sys)

The plot shows that there are two pole-zero pairs that almost overlap,
which hints are their potential redundancy.

See Also

pzmap | pole | zero | sgrid | zgrid | iopzplot

1-303

iopzplot

Purpose

Plot pole-zero map for I/O pairs and return plot handle

Syntax

h = iopzplot(sys)
iopzplot(sys1,sys2,...)
iopzplot(AX,...)
iopzplot(..., plotoptions)

Description

h = iopzplot(sys) computes and plots the poles and zeros of each

input/output pair of the LTI model SYS. The poles are plotted as xs
and the zeros are plotted as os. It also returns the plot handle h. You
can use this handle to customize the plot with the getoptions and
setoptions commands. Type
help pzoptions

for a list of available plot options.

shows the poles and zeros of multiple
LTI models SYS1,SYS2,... on a single plot. You can specify distinctive
colors for each model, as in

iopzplot(sys1,sys2,...)

iopzplot(sys1,'r',sys2,'y',sys3,'g')
iopzplot(AX,...) plots into the axes with handle AX.
iopzplot(..., plotoptions) plots the poles and zeros with the
options specified in plotoptions. Type
help pzoptions

for more detail.

The function sgrid or zgrid can be used to plot lines of constant
damping ratio and natural frequency in the s or z plane.
For arrays sys of LTI models, iopzplot plots the poles and zeros of
each model in the array on the same diagram.

1-304

iopzplot

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Use the plot handle to change the I/O grouping of a pole/zero map.
sys = rss(3,2,2);
h = iopzplot(sys);
% View all input-output pairs on a single axis.
setoptions(h,'IOGrouping','all')

Example 2
View the poles and zeros of an over-parameterized state-space model
estimated using input-output data.
load iddata1
sys = ssest(z1,6,ssestOptions('focus','simulation'));
h = iopzplot(sys);
showConfidence(h)

There is at least one pair of complex-conjugate poles whose locations

overlap with those of a complex zero, within 1std confidence region.
This suggests their redundancy. Hence a lower (4th) order model might
be more robust for the given data.
sys2 = ssest(z1,4,ssestOptions('focus','simulation'));
h = iopzplot(sys,sys2);
showConfidence(h)
axis([-20, 10 -30 30])

The variability in the pole-zero locations of the second model sys2 are
reduced.

See Also

getoptions | iopzmap | setoptions

1-305

isct

Purpose

Determine if dynamic system model is in continuous time

Syntax

bool = isct(sys)

Description

bool = isct(sys) returns a logical value of 1 (true) if the dynamic

system model sys is a continuous-time model. The function returns a
logical value of 0 (false) otherwise.

Input
Arguments

sys

Output
Arguments

bool

Dynamic system model or array of such models.

Logical value indicating whether sys is a continuous-time model.

bool = 1 (true) if sys is a continuous-time model (sys.Ts = 0). If sys
is a discrete-time model, bool = 0 (false).
For a static gain, both isct and isdt return true unless you explicitly
set the sampling time to a nonzero value. If you do so, isdt returns
true and isct returns false.
For arrays of models, bool is true if the models in the array are
continuous.

See Also

1-306

isdt | isstable

isdt

Purpose

Determine if dynamic system model is in discrete time

Syntax

bool = isdt(sys)

Description

bool = isdt(sys) returns a logical value of 1 (true) if the dynamic

system model sys is a discrete-time model. The function returns a
logical value of 0 (false) otherwise.

Input
Arguments

sys

Output
Arguments

bool

Dynamic system model or array of such models.

Logical value indicating whether sys is a discrete-time model.

bool = 1 (true) if sys is a discrete-time model (sys.Ts
is a continuous-time model, bool = 0 (false).

0). If sys

For a static gain, both isct and isdt return true unless you explicitly
set the sampling time to a nonzero value. If you do so, isdt returns
true and isct returns false.
For arrays of models, bool is true if the models in the array are
discrete.

See Also

isct | isstable

1-307

isempty

Purpose

Determine whether dynamic system model is empty

Syntax

isempty(sys)

Description

isempty(sys) returns TRUE (logical 1) if the dynamic system model

sys has no input or no output, and FALSE (logical 0) otherwise. Where
sys is a FRD model, isempty(sys) returns TRUE when the frequency
vector is empty. Where sys is a model array, isempty(sys) returns
TRUE when the array has empty dimensions or when the LTI models in

the array are empty.

Examples

Both commands
isempty(tf)

% tf by itself returns an empty transfer function

isempty(ss(1,2,[],[]))

return TRUE (logical 1) while

isempty(ss(1,2,3,4))

returns FALSE (logical 0).

See Also

1-308

issiso | size

isfinite

Purpose

Determine if model has finite coefficients

Syntax

B = isfinite(sys)
B = isfinite(sys,'elem')

Description

B = isfinite(sys) returns 1 (true) if the model sys has finite

coefficients, and 0 (false) otherwise. If sys is a model array, then B is
true if all models in sys have finite coefficients.
B = isfinite(sys,'elem') checks each model in the model array sys
and returns a logical array of the same size as sys. The logical array
indicates which models in sys have finite coefficients.

Input
Arguments

sys - Model or array to check

input-output model | model array

Model or array to check, specified as an input-output model or model
array. Input-output models include dynamic system models such as
numeric LTI models and generalized models. Input-output models
also include static models such as tunable parameters or generalized
matrices.

Output
Arguments

B - Flag indicating whether model has finite coefficients

logical | logical array

Flag indicating whether model has finite coefficients, returned as a

logical value or logical array.

Examples

Check Model for Finite Coefficients

Create model and check whether its coefficients are all finite.
sys = rss(3);
B = isfinite(sys)
B =
1

1-309

isfinite

Check Each Model in Array

Create a 1-by-5 array of models and check each model for finite
coefficients.
sys = rss(2,2,2,1,5);
B = isfinite(sys,'elem')
B =
1

When you use the 'elem' input, isfinite checks each model
individually and returns a logical array indicating which models have
all finite coefficients.

See Also

1-310

isreal

isParametric

Purpose

Determine if model has tunable parameters

Syntax

bool = isParametric(M)

Description

bool = isParametric(M) returns a logical value of 1 (true) if the

model M contains parametric (tunable) Control Design Blocks. The
function returns a logical value of 0 (false) otherwise.

Input
Arguments

Output
Arguments

bool

A Dynamic System model or Static model, or an array of such models.

Logical value indicating whether M contains tunable parameters.

bool = 1 (true) if the model M contains parametric (tunable) Control
Design Blocks such as realp or ltiblock.ss. If M does not contain
parametric Control Design Blocks, bool = 0 (false).

See Also

nblocks

How To

Control Design Blocks

Dynamic System Models
Static Models

1-311

isproper

Purpose

Determine if dynamic system model is proper

Syntax

B = isproper(sys)
B = isproper(sys,'elem')
[B, sysr] = isproper(sys)

Description

B = isproper(sys) returns TRUE (logical 1) if the dynamic system

model sys is proper and FALSE (logical 0) otherwise.

A proper model has relative degree 0 and is causal. SISO transfer

functions and zero-pole-gain models are proper if the degree of their
numerator is less than or equal to the degree of their denominator (in
other words, if they have at least as many poles as zeroes). MIMO
transfer functions are proper if all their SISO entries are proper.
Regular state-space models (state-space models having no E matrix) are
always proper. A descriptor state-space model that has an invertible
E matrix is always proper. A descriptor state-space model having a
singular (non-invertible) E matrix is proper if the model has at least
as many poles as zeroes.
If sys is a model array, then B is TRUE if all models in the array are
proper.
B = isproper(sys,'elem') checks each model in a model array sys
and returns a logical array of the same size as sys. The logical array
indicates which models in sys are proper.

If sys is a proper descriptor state-space model with a non-invertible E

matrix, [B, sysr] = isproper(sys) also returns an equivalent model
sysr with fewer states (reduced order) and a non-singular E matrix.
If sys is not proper, sysr = sys.

Examples

Example 1
The following commands
isproper(tf([1 0],1))
isproper(tf([1 0],[1 1]))

1-312

% transfer function s
% transfer function s/(s+1)

isproper

return FALSE (logical 0) and TRUE (logical 1), respectively.

Example 2
Combining state-space models can yield results that include more states
than necessary. Use isproper to compute an equivalent lower-order
model.
H1 = ss(tf([1 1],[1 2 5]));
H2 = ss(tf([1 7],[1]));
H = H1*H2
a =
x1
-2
2
0
0

x1
x2
x3
x4

x2
-2.5
0
0
0

x3
0.5
0
1
0

x4
1.75
0
0
1

b =
x1
x2
x3
x4

u1
0
0
0
-4

c =
y1

x1
1

x2
0.5

x3
0

x4
0

x2
0
1

x3
0
0

x4
0
0

d =
y1

u1
0

e =
x1
x2

x1
1
0

1-313

isproper

x3
x4

0
0

0
0

0
0

0.5
0

H is proper and reducible:

[isprop, Hr] = isproper(H)
isprop =
1

a =
x1
x2

x1
0
-0.06988

x1
x2

u1
-0.125
-0.1398

x2
0.1398
-0.0625

b =

c =
x1
-0.5

y1

x2
-1.118

d =
y1

u1
1

e =
x1
x2

x1
0.0625
0

x2
0
0.03125

Continuous-time model.

1-314

isproper

H and Hr are equivalent, as a Bode plot demonstrates:

bode(H, Hr)

See Also

ss | dss

1-315

isreal

Purpose

Determine if model has real-valued coefficients

Syntax

B = isreal(sys)
B = isreal(sys,'elem')

Description

B = isreal(sys) returns 1 (true) if the model sys has real-valued

coefficients, and 0 (false) otherwise. If sys is a model array, then B is

true if all models in sys have real-valued coefficients.
B = isreal(sys,'elem') checks each model in the model array sys

and returns a logical array of the same size as sys. The logical array
indicates which models in sys have real coefficients.

Input
Arguments

sys - Model or array to check

input-output model | model array

Model or array to check, specified as an input-output model or model
array. Input-output models include dynamic system models such as
numeric LTI models and generalized models. Input-output models
also include static models such as tunable parameters or generalized
matrices.

Output
Arguments

B - Flag indicating whether model has real-valued coefficients

logical | logical array

Flag indicating whether model has real-valued coefficients, returned

as a logical value or logical array.

Examples

Check Model for Real-Valued Coefficients

Create model and check whether its coefficients are all real-valued.
sys = rss(3);
B = isreal(sys)
B =
1

1-316

isreal

Check Each Model in Array

Create a 1-by-5 array of models and check each model for real-valued
coefficients.
sys = rss(2,2,2,1,5);
B = isreal(sys,'elem')
B =
1

When you use the 'elem' input, isreal checks each model individually
and returns a logical array indicating which models have all real-valued
coefficients.

See Also

isfinite

1-317

isstable

Purpose

Determine whether system is stable

Syntax

B = isstable(sys)
B = isstable(sys,'elem')

Description

B = isstable(sys) returns 1 (true) if the dynamic system model sys

has stable dynamics, and 0 (false) otherwise. If sys is a model array,
then B is true if all models in sys are stable.
B = isstable(sys,'elem') returns a logical array of the same size as
the model array sys. The logical array indicates which models in sys
are stable.
isstable is only supported for analytical models with a finite number

of poles.

See Also

1-318

pole

issiso

Purpose

Determine if dynamic system model is single-input/single-output (SISO)

Syntax

issiso(sys)

Description

issiso(sys) returns 1 (true) if the dynamic system model sys is SISO

and 0 (false) otherwise.

See Also

isempty | size

1-319

isstatic

Purpose

Determine if model is static or dynamic

Syntax

B = isstatic(sys)
B = isstatic(sys,'elem')

Description

B = isstatic(sys) returns 1 (true) if the model sys is a static model,

and and 0 (false) if sys has dynamics such as states or delays. If sys is
a model array, then B is true if all models in sys are static.
B = isstatic(sys,'elem') checks each model in the model array sys
and returns a logical array of the same size as sys. The logical array
indicates which models in sys are static.

Input
Arguments

sys - Model or array to check

input-output model | model array

Model or array to check, specified as an input-output model or model
array. Input-output models include dynamic system models such as
numeric LTI models and generalized models. Input-output models
also include static models such as tunable parameters or generalized
matrices.

Output
Arguments

B - Flag indicating whether input model is static

logical | logical array

Flag indicating whether input model is static, returned as a logical

value or logical array.

See Also

pole | zero | hasdelay

Concepts

Types of Model Objects

1-320

kalman

Purpose

Kalman filter design, Kalman estimator

Syntax

[kest,L,P] = kalman(sys,Qn,Rn,Nn)
[kest,L,P] = kalman(sys,Qn,Rn,Nn,sensors,known)
[kest,L,P,M,Z] = kalman(sys,Qn,Rn,...,type)

Description

kalman designs a Kalman filter or Kalman state estimator given a

state-space model of the plant and the process and measurement noise
covariance data. The Kalman estimator provides the optimal solution to
the following continuous or discrete estimation problems.

Continuous-Time Estimation
Given the continuous plant

x = Ax + Bu + Gw
y = Cx + Du + Hw + v

(state equation)
(measurement equation))

with known inputs u, white process noise w, and white measurement

noise v satisfying

E(w) = E(v) = 0,

E(wwT ) = Q,

E(vvT ) = R,

E(wvT ) = N

construct a state estimate x (t) that minimizes the steady-state error

covariance

T
P = lim E {x x }{x x }
t

The optimal solution is the Kalman filter with equations

x = Ax + Bu + L( y Cx Du)
y C
D
x = I x + 0 u


The filter gain L is determined by solving an algebraic Riccati equation
to be

1-321

kalman

L = ( PC T + N ) R1
where
R = R + HN + N T H T + HQH T
N = G(QH T + N )
and P solves the corresponding algebraic Riccati equation.
The estimator uses the known inputs u and the measurements y
to generate the output and state estimates y and x . Note that y
estimates the true plant output

y = Cx + Du + Hw + v
u

u
w

Kalman
Filter
y

Plant

y
x

v
Kalman Estimator
Discrete-Time Estimation
Given the discrete plant

x[ n + 1] = Ax[ n] + Bu[ n] + Gw[ n]

y[ n] = Cx[ n] + Du[ n] + Hw[ n] + v[ n]
and the noise covariance data

E(w[ n]w[ n]T ) = Q,

E(v[ n]v[ n]T ) = R,

E(w[ n]v[ n]T ) = N

The estimator has the following state equation:

1-322

kalman

x[ n + 1| n] = Ax[ n| n 1] + Bu[ n] + L( y[ n] Cx[ n| n 1] Du[ n])

The gain matrix L is derived by solving a discrete Riccati equation to be

L = ( APC T + N )(CPC T + R)1

where

R = R + HN + N T H T + HQH T
N = G(QH T + N )
There are two variants of discrete-time Kalman estimators:
The current estimator generates output estimates y[ n| n] and state
estimates x[ n| n] using all available measurements up to y[ n] . This
estimator has the output equation

y[ n| n] C( I MC)
( I CM ) D CM u[ n]
x[ n| n] = I MC x[ n| n 1] + MD
M y[ n]

where the innovation gain M is defined as
M = PC T (CPC T + R)1
M updates the prediction x[ n| n 1] using the new measurement

y[ n] .
x[ n| n] = x[ n| n 1] + M ( y[ n] Cx[ n| n 1] Du[ n])

innovation

The delayed estimator generates output estimates y[ n| n 1] and

state estimates x[ n| n 1] using measurements only up to yv[n-1].
This estimator is easier to implement inside control loops and has
the output equation

1-323

kalman

y[ n| n 1] C
D 0 u[ n]
x[ n| n 1] = I x[ n| n 1] + 0 0 y[ n]

[kest,L,P] = kalman(sys,Qn,Rn,Nn) creates a state-space model
kest of the Kalman estimator given the plant model sys and the noise
covariance data Qn, Rn, Nn (matrices Q, R, N described in Description
on page 1-321). sys must be a state-space model with matrices

A,[ B G ], C,[ D H ] .
The resulting estimator kest has inputs [u; y] and outputs [ y ; x ] (or
their discrete-time counterparts). You can omit the last input argument
Nn when N = 0.
The function kalman handles both continuous and discrete problems
and produces a continuous estimator when sys is continuous and a
discrete estimator otherwise. In continuous time, kalman also returns
the Kalman gain L and the steady-state error covariance matrix P. P
solves the associated Riccati equation.
[kest,L,P] = kalman(sys,Qn,Rn,Nn,sensors,known) handles the

more general situation when

Not all outputs of sys are measured.
The disturbance inputs w are not the last inputs of sys.
The index vectors sensors and known specify which outputs y of sys
are measured and which inputs u are known (deterministic). All other
inputs or sys are assumed stochastic.
[kest,L,P,M,Z] = kalman(sys,Qn,Rn,...,type) specifies the
estimator type for discrete-time plants sys. The string type is
either 'current' (default) or 'delayed'. For discrete-time plants,
kalman returns the estimator and innovation gains L and M and the

steady-state error covariances

1-324

kalman

P = lim E(e[ n| n 1]e[ n| n 1]T ),

e[ n| n 1] = x[ n] x[ n| n 1]

Z = lim E(e[ n| n]e[ n| n]T ),

e[ n| n] = x[ n] x[ n| n]

Examples

See LQG Design for the x-Axis and Kalman Filtering for examples that
use the kalman function.

Limitations

The plant and noise data must satisfy:

(C,A) detectable
R > 0 and Q NR1 N T 0
( A NR1C, Q NR1 N T ) has no uncontrollable mode on the
imaginary axis (or unit circle in discrete time) with the notation

Q = GQG T
R = R + HN + N T H T + HQH T
N = G(QH T + N )

References

[1] Franklin, G.F., J.D. Powell, and M.L. Workman, Digital Control of
Dynamic Systems, Second Edition, Addison-Wesley, 1990.
[2] Lewis, F., Optimal Estimation, John Wiley & Sons, Inc, 1986.

See Also

kalmd | estim | care | dare | lqgreg | lqg | ss

1-325

kalmd

Purpose

Design discrete Kalman estimator for continuous plant

Syntax

kalmd
[kest,L,P,M,Z] = kalmd(sys,Qn,Rn,Ts)

Description

kalmd designs a discrete-time Kalman estimator that has response

characteristics similar to a continuous-time estimator designed with
kalman. This command is useful to derive a discrete estimator for
digital implementation after a satisfactory continuous estimator has
been designed.
[kest,L,P,M,Z] = kalmd(sys,Qn,Rn,Ts) produces a discrete Kalman
estimator kest with sample time Ts for the continuous-time plant

x = Ax + Bu + gw (state equation)
(measurement equation))
yv = Cx + Du + v
with process noise w and measurement noise v satisfying

E(w) = E(v) = 0, E(wwT ) = Qn , E(vvT ) = Rn , E(wvT ) = 0

The estimator kest is derived as follows. The continuous plant sys is
first discretized using zero-order hold with sample time Ts (see c2d
entry), and the continuous noise covariance matrices Qn and Rn are
replaced by their discrete equivalents

Qd =

Ts A

T
GQG T e A d

Rd = R / Ts
The integral is computed using the matrix exponential formulas in [2].
A discrete-time estimator is then designed for the discretized plant and
noise. See kalman for details on discrete-time Kalman estimation.
kalmd also returns the estimator gains L and M, and the discrete error
covariance matrices P and Z (see kalman for details).

1-326

kalmd

Limitations

The discretized problem data should satisfy the requirements for

kalman.

References

[1] Franklin, G.F., J.D. Powell, and M.L. Workman, Digital Control of
Dynamic Systems, Second Edition, Addison-Wesley, 1990.
[2] Van Loan, C.F., "Computing Integrals Involving the Matrix
Exponential," IEEE Trans. Automatic Control, AC-15, October 1970.

See Also

kalman | lqgreg | lqrd

1-327

lft

Purpose

Generalized feedback interconnection of two models (Redheffer star

product)

Syntax

lft
sys = lft(sys1,sys2,nu,ny)

Description

lft forms the star product or linear fractional transformation (LFT) of

two model objects or model arrays. Such interconnections are widely

used in robust control techniques.
sys = lft(sys1,sys2,nu,ny) forms the star product sys of the two

models (or arrays) sys1 and sys2. The star product amounts to the
following feedback connection for single models (or for each model in an
array).

This feedback loop connects the first nu outputs of sys2 to the last nu
inputs of sys1 (signals u), and the last ny outputs of sys1 to the first
ny inputs of sys2 (signals y). The resulting system sys maps the input
vector [w1 ; w2] to the output vector [z1 ; z2].
The abbreviated syntax

1-328

lft

sys = lft(sys1,sys2)

produces:
The lower LFT of sys1 and sys2 if sys2 has fewer inputs and outputs
than sys1. This amounts to deleting w2 and z2 in the above diagram.
The upper LFT of sys1 and sys2 if sys1 has fewer inputs and outputs
than sys2. This amounts to deleting w1 and z1 in the above diagram.

Algorithms

The closed-loop model is derived by elementary state-space

manipulations.

Limitations

There should be no algebraic loop in the feedback connection.

See Also

connect | feedback

1-329

loopswitch

Purpose

Switch for opening and closing feedback loops

Syntax

S = loopswitch(name)
S = loopswitch(name,N)

Description

Control Design Block for creating loop-opening locations in a model of a

control system. You can combine a loopswitch block with numeric LTI
models, tunable LTI models, and other Control Design Blocks to build
tunable models of control systems. A loopswitch block in your control
system marks a location where you can optionally open a feedback loop.
You can use an optional loop opening to compute open-loop quantities
such as point-to-point transfer functions (see getLoopTransfer) or
stability margins. You can also use a loopswitch block to mark an
input or output location for computing closed-loop transfer functions
with getIOTransfer.
loopswitch blocks are also useful when tuning a control system using
Robust Control Toolbox tuning commands such as systune. You can use
a loopswitch block to mark a loop-opening location for open-loop tuning
requirements such as TuningGoal.LoopShape or TuningGoal.Margins.
You can also use a loopswitch block to mark the specified input or
output for tuning requirements such as TuningGoal.Gain.

Construction

S = loopswitch(name) creates a switch block for opening or closing a

SISO feedback loop.

S = loopswitch(name,N) creates a switch for a MIMO feedback loop

with N channels.

Input Arguments
name

Switch block name, specified as a string. This input argument sets

the value of the Name property of the switch block. (See Properties
on page 1-331.)
N

1-330

loopswitch

Number of channels for a multichannel switch, specified as a scalar

integer.

Tips

By default, the switch S is closed. Set S.Open = true to create a

switch location that is open by default. For a multichannel switch,
you can set S.Open to a logical vector with N entries. Doing so opens
only a subset of the feedback loops.

Properties

Location

Names of feedback channels in the switch block, specified as a string

or a cell array of strings.
By default, the feedback loops are named after the block. For example,
if you have a SISO switch block, X that has name 'X', then X.Location
= 'X' by default. If you have a a multi-channel switch block, then
X.Location = {'X(1)','X(2)',...} by default. Set X.Location to a
different value if you want to customize the channel names.
Open

Switch state, specified as a logical value or vector of logical values. For

example, if you have a SISO switch block, X, then the value X.Open = 1
opens the switch. if you have a multi-channel switch block, then X.Open
is a logical vector with as many entries as X has channels.
Default: 0 for all channels
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time

1-331

loopswitch

representations. Use d2d to change the sampling time of a discrete-time

system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.

1-332

loopswitch

Alternatively, use automatic vector expansion to assign input names for

multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

1-333

loopswitch

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.

1-334

loopswitch

Default: Empty string '' for all input channels

OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

1-335

loopswitch

Examples

Feedback Loop with Loop-Opening Switch

Create a model of the following feedback loop with a loop-opening
switch in the feedback path.
+

C(s)

G(s)

X
G = 1/(s+2) is the plant model, C is a tunable PI controller, and X is a
loop-opening switch.
G
C
X
T

=
=
=
=

tf(1,[1 2]);
ltiblock.pid('C','pi');
loopswitch('X');
feedback(G*C,X);

T is a tunable genss model. T.Blocks contains the Control Design

Blocks of the model, C, and the switch, X. By default, X is closed.

Examine the step response of T.

stepplot(T)

1-336

loopswitch

With X closed, the response of T is stable.

Open the switch to obtain the open-loop response from r to y.
T.Blocks.X.Open = true;
stepplot(T)

1-337

loopswitch

Close the switch to continue working with the closed-loop model.

T.Blocks.X.Open = false;

See Also

genss | getSwitches

How To

Control Design Blocks

Models with Tunable Coefficients

1-338

lqg

Purpose

Linear-Quadratic-Gaussian (LQG) design

Syntax

reg
reg
reg
reg

Description

reg = lqg(sys,QXU,QWV) computes an optimal

linear-quadratic-Gaussian (LQG) regulator reg given a state-space
model sys of the plant and weighting matrices QXU and QWV. The
dynamic regulator sys uses the measurements y to generate a control

=
=
=
=

lqg(sys,QXU,QWV)
lqg(sys,QXU,QWV,QI)
lqg(sys,QXU,QWV,QI,'1dof')
lqg(sys,QXU,QWV,QI,'2dof')

signal u that regulates y around the zero value. Use positive feedback
to connect this regulator to the plant output y.
w

reg

sys

The LQG regulator minimizes the cost function

x
1
J E lim xT , uT Qxu dt

u
0
subject to the plant equations
dx/dt = Ax + Bu + w
y
= Cx + Du + v

where the process noise w and measurement noise v are Gaussian

white noises with covariance:
E([w;v] * [w',v']) = QWV

1-339

lqg

reg = lqg(sys,QXU,QWV,QI) uses the setpoint command r and

measurements y to generate the control signal u. reg has integral

action to ensure that y tracks the command r.

w
r
y

reg

sys

The LQG servo-controller minimizes the cost function

x
1
J E lim xT , uT Qxu xiT Qi xi dt

0
u


where xi is the integral of the tracking error r - y. For MIMO systems, r,
y, and xi must have the same length.
reg = lqg(sys,QXU,QWV,QI,'1dof') computes a
one-degree-of-freedom servo controller that takes e = r - y
rather than [r ; y] as input.
reg = lqg(sys,QXU,QWV,QI,'2dof') is equivalent to
LQG(sys,QXU,QWV,QI) and produces the two-degree-of-freedom

servo-controller shown previously.

Tips

lqg can be used for both continuous- and discrete-time plants. In

discrete-time, lqg uses x[n|n-1] as state estimate (see kalman for
details).

To compute the LQG regulator, lqg uses the commands lqr and
kalman. To compute the servo-controller, lqg uses the commands lqi
and kalman.

1-340

lqg

When you want more flexibility for designing regulators you can use the
lqr, kalman, and lqgreg commands. When you want more flexibility for
designing servo controllers, you can use the lqi, kalman, and lqgtrack
commands. For more information on using these commands and how
to decide when to use them, see Linear-Quadratic-Gaussian (LQG)
Design for Regulation and Linear-Quadratic-Gaussian (LQG) Design
of Servo Controller with Integral Action.

Examples

Linear-Quadratic-Gaussian (LQG) Regulator and Servo

Controller Design
This example shows how to design an linear-quadratic-Gaussian
(LQG) regulator, a one-degree-of-freedom LQG servo controller, and a
two-degree-of-freedom LQG servo controller for the following system.

w
r

trksys

Plant

LQG Servo Controller

The plant has three states (x), two control inputs (u), three random
inputs (w), one output (y), measurement noise for the output (v), and
the following state and measurement equations.

dx
= Ax + Bu + w
dt
y = Cx + Du + v
where

1-341

lqg

0 1 0
A = 0 0 1
1 0 0

1
0 .3

B= 0
1
0.3 0.9

C = [1.9 1.3 1]

D = [0.53 0.61]

The system has the following noise covariance data:

Qn = E

( )

4 2 0
= 2 1 0
0 0 1

Rn = E vvT = 0.7
For the regulator, use the following cost function to define the tradeoff
between regulation performance and control effort:

J (u) =

0 0.1x

1 0
x + uT
u dt
0 2

For the servo controllers, use the following cost function to define the
tradeoff between tracker performance and control effort:

J (u) =

0 0.1x

1 0
x + xi2 + uT
u dt
0 2

To design the LQG controllers for this system:

1 Create the state-space system by typing the following in the

MATLAB Command Window:

A
B
C
D

1-342

=
=
=
=

[0 1 0;0 0 1;1 0 0];

[0.3 1;0 1;-0.3 0.9];
[1.9 1.3 1];
[0.53 -0.61];

lqg

sys = ss(A,B,C,D);
2 Define the noise covariance data and the weighting matrices by

typing the following commands:

nx = 3;
%Number of states
ny = 1;
%Number of outputs
Qn = [4 2 0; 2 1 0; 0 0 1];
Rn = 0.7;
R = [1 0;0 2]
QXU = blkdiag(0.1*eye(nx),R);
QWV = blkdiag(Qn,Rn);
QI = eye(ny);
3 Form the LQG regulator by typing the following command:

KLQG = lqg(sys,QXU,QWV)

This command returns the following LQG regulator:

a =
x1_e
x2_e
x3_e

x1_e
-6.212
-4.038
-1.418

x1_e
x2_e
x3_e

y1
2.365
1.432
0.7684

x2_e
-3.814
-3.196
-1.973

x3_e
-4.136
-1.791
-1.766

b =

c =
u1
u2

x1_e
-0.02904
-0.7147

x2_e
0.0008272
-0.7115

x3_e
0.0303
-0.7132

d =

1-343

lqg

u1
u2

y1
0
0

Input groups:
Name
Measurement
Output groups:
Name
Controls

Channels
1

Channels
1,2

Continuous-time model.
4 Form the one-degree-of-freedom LQG servo controller by typing the

following command:
KLQG1 = lqg(sys,QXU,QWV,QI,'1dof')

This command returns the following LQG servo controller:

a =
x1_e
x2_e
x3_e
xi1

x1_e
-7.626
-5.108
-2.121
0

x1_e
x2_e
x3_e
xi1

e1
-2.365
-1.432
-0.7684
1

x2_e
-5.068
-4.146
-2.604
0

x3_e
-4.891
-2.362
-2.141
0

xi1
0.9018
0.6762
0.4088
0

b =

c =
u1

1-344

x1_e
-0.5388

x2_e
-0.4173

x3_e
-0.2481

xi1
0.5578

lqg

u2

-1.492

-1.388

-1.131

0.5869

d =
u1
u2

e1
0
0

Input groups:
Name
Channels
Error
1
Output groups:
Name
Controls

Channels
1,2

Continuous-time model.
5 Form the two-degree-of-freedom LQG servo controller by typing the

following command:
KLQG2 = lqg(sys,QXU,QWV,QI,'2dof')

This command returns the following LQG servo controller:

a =
x1_e
x2_e
x3_e
xi1

x1_e
-7.626
-5.108
-2.121
0

x2_e
-5.068
-4.146
-2.604
0

x1_e
x2_e
x3_e
xi1

r1
0
0
0
1

y1
2.365
1.432
0.7684
-1

x3_e
-4.891
-2.362
-2.141
0

xi1
0.9018
0.6762
0.4088
0

b =

1-345

lqg

c =
u1
u2

x1_e
-0.5388
-1.492

u1
u2

r1
0
0

x2_e
-0.4173
-1.388

x3_e
-0.2481
-1.131

xi1
0.5578
0.5869

d =
y1
0
0

Input groups:
Name
Setpoint
Measurement
Output groups:
Name
Controls

Channels
1
2

Channels
1,2

Continuous-time model.

See Also

1-346

lqr | lqi | kalman | lqry | ss | care | dare

lqgreg

Purpose

Form linear-quadratic-Gaussian (LQG) regulator

Syntax

rlqg = lqgreg(kest,k)
rlqg = lqgreg(kest,k,controls)

Description

lqgreg forms the linear-quadratic-Gaussian (LQG) regulator by

connecting the Kalman estimator designed with kalman and the
optimal state-feedback gain designed with lqr, dlqr, or lqry. The
LQG regulator minimizes some quadratic cost function that trades off
regulation performance and control effort. This regulator is dynamic
and relies on noisy output measurements to generate the regulating
commands.

In continuous time, the LQG regulator generates the commands

u = Kx
where x is the Kalman state estimate. The regulator state-space
equations are

x = [ A LC ( B LD) K ]x + Ly
u = Kx
where y is the vector of plant output measurements (see kalman for
background and notation). The following diagram shows this dynamic
regulator in relation to the plant.
w

kest

-K

sys

LQG Regulator

1-347

lqgreg

In discrete time, you can form the LQG regulator using either the
delayed state estimate x[ n| n 1] of x[n], based on measurements up
to y[n1], or the current state estimate x[ n| n] , based on all available
measurements including y[n]. While the regulator

u [ n] = Kx [ n| n 1]
is always well-defined, the current regulator

u [ n] = Kx [ n| n]
is causal only when I-KMD is invertible (see kalman for the notation).
In addition, practical implementations of the current regulator should
allow for the processing time required to compute u[n] after the
measurements y[n] become available (this amounts to a time delay in
the feedback loop).

Tips

rlqg = lqgreg(kest,k) returns the LQG regulator rlqg (a state-space

model) given the Kalman estimator kest and the state-feedback gain
matrix k. The same function handles both continuous- and discrete-time
cases. Use consistent tools to design kest and k:

Continuous regulator for continuous plant: use lqr or lqry and

kalman

Discrete regulator for discrete plant: use dlqr or lqry and kalman
Discrete regulator for continuous plant: use lqrd and kalmd
In discrete time, lqgreg produces the regulator
u [ n] = Kx [ n| n] when kest is the current Kalman estimator
u [ n] = Kx [ n| n 1] when kest is the delayed Kalman estimator
For more information on Kalman estimators, see the kalman reference
page.

1-348

lqgreg

rlqg = lqgreg(kest,k,controls) handles estimators that have

access to additional deterministic known plant inputs ud. The index

vector controls then specifies which estimator inputs are the controls
u, and the resulting LQG regulator rlqg has ud and y as inputs (see
the next figure).
Note Always use positive feedback to connect the LQG regulator to
the plant.

u
ud
y

kest

-K

LQG Regulator

Examples

See the example LQG Regulation.

See Also

kalman | kalmd | lqr | dlqr | lqrd | lqry | reg

1-349

lqgtrack

Purpose

Form Linear-Quadratic-Gaussian (LQG) servo controller

Syntax

C
C
C
C

Description

lqgtrack forms a Linear-Quadratic-Gaussian (LQG) servo controller

with integral action for the loop shown in the following figure. This
compensator ensures that the output y tracks the reference command r
and rejects process disturbances w and measurement noise v. lqgtrack
assumes that r and y have the same length.

=
=
=
=

lqgtrack(kest,k)
lqgtrack(kest,k,'2dof')
lqgtrack(kest,k,'1dof')
lqgtrack(kest,k,...CONTROLS)

w
r
y

Plant

Note Always use positive feedback to connect the LQG servo controller
C to the plant output y.
C = lqgtrack(kest,k) forms a two-degree-of-freedom LQG servo
controller C by connecting the Kalman estimator kest and the
state-feedback gain k, as shown in the following figure. C has inputs

[ r; y] and generates the command u = K [ x ; xi ] , where x is the Kalman

estimate of the plant state, and xi is the integrator output.

1-350

lqgtrack

kest
r

r-y
-

Integrator

-K

xi

y
LQG Servo Controller

The size of the gain matrix k determines the length of xi. xi, y, and r
all have the same length.
The two-degree-of-freedom LQG servo controller state-space equations
are

x A BK x LC + LDK x
=
0
x i
x
u = [ K x Ki ]
xi

BK i + LDK i x 0 L r
x + I I y
0

i

Note The syntax C = lqgtrack(kest,k,'2dof') is equivalent to C =

lqgtrack(kest,k).
C = lqgtrack(kest,k,'1dof') forms a one-degree-of-freedom LQG
servo controller C that takes the tracking error e = r y as input instead
of [r ; y], as shown in the following figure.

1-351

lqgtrack

u
e

r-y

-1

kest
Integrator

-K

xi

LQG Servo Controller

The one-degree-of-freedom LQG servo controller state-space equations

are

x A BK x LC + LDK x
=
0
x i
x
u = [ K x Ki ]
xi

BK i + LDK i x L
x + I e
0
i

C = lqgtrack(kest,k,...CONTROLS) forms an LQG servo controller

C when the Kalman estimator kest has access to additional known
(deterministic) commands Ud of the plant. In the index vector CONTROLS,
specify which inputs of kest are the control channels u. The resulting

compensator C has inputs

[Ud ; r ; y] in the two-degree-of-freedom case
[Ud ; e] in the one-degree-of-freedom case
The corresponding compensator structure for the two-degree-of-freedom
cases appears in the following figure.

1-352

lqgtrack

u
Ud

kest
r-y
-

Integrator

-K

xi

y
LQG Servo Controller

Tips

You can use lqgtrack for both continuous- and discrete-time systems.
In discrete-time systems, integrators are based on forward Euler (see
lqi for details). The state estimate x is either x[n|n] or x[n|n1],
depending on the type of estimator (see kalman for details).

Examples

See the example Design an LQG Servo Controller.

See Also

lqg | lqi | kalman | lqgreg | lqr

1-353

lqi

Purpose

Linear-Quadratic-Integral control

Syntax

[K,S,e] = lqi(SYS,Q,R,N)

Description

lqi computes an optimal state-feedback control law for the tracking

loop shown in the following figure.

x
r

e = r-y

Integrator

xi

-K

sys

For a plant sys with the state-space equations (or their discrete
counterpart):

dx
= Ax + Bu
dt
y = Cx + Du
the state-feedback control is of the form

u = K[ x; xi ]
where xi is the integrator output. This control law ensures that the
output y tracks the reference command r. For MIMO systems, the
number of integrators equals the dimension of the output y.
[K,S,e] = lqi(SYS,Q,R,N) calculates the optimal gain matrix K,
given a state-space model SYS for the plant and weighting matrices Q,
R, N. The control law u = Kz = K[x;xi] minimizes the following cost
functions (for r = 0)

J (u) =

1-354

0 { z

Qz + uT Ru + 2 zT Nu}dt for continuous time

lqi

{ zT Qz + uT Ru + 2 zT Nu} for discrete time

J (u) =
n=time,
0
In discrete
lqi computes the integrator output xi using the
forward Euler formula
xi[ n + 1] = xi[ n] + Ts(r[ n] y[ n])
where Ts is the sampling time of SYS.
When you omit the matrix N, N is set to 0. lqi also returns the solution
S of the associated algebraic Riccati equation and the closed-loop
eigenvalues e.

Tips

lqi supports descriptor models with nonsingular E. The output S of

lqi is the solution of the Riccati equation for the equivalent explicit

state-space model

dx
= E 1 Ax + E 1 Bu
dt

Limitations

For the following state-space system with a plant with augmented

integrator:

z
= Aa z + Ba u
t
y = Ca z + Da u
The problem data must satisfy:
The pair (Aa,Ba) is stabilizable.
R > 0 and Q NR1 N T 0 .

( Q NR1 N T , Aa Ba R1 N T ) has no unobservable mode on the

imaginary axis (or unit circle in discrete time).

1-355

lqi

References

[1] P. C. Young and J. C. Willems, An approach to the linear

multivariable servomechanism problem, International Journal of
Control, Volume 15, Issue 5, May 1972 , pages 961979.

See Also

lqr | lqgreg | lqgtrack | lqg | care | dare

1-356

lqr

Purpose

Linear-Quadratic Regulator (LQR) design

Syntax

[K,S,e] = lqr(SYS,Q,R,N)
[K,S,e] = LQR(A,B,Q,R,N)

Description

[K,S,e] = lqr(SYS,Q,R,N) calculates the optimal gain matrix K.

For a continuous time system, the state-feedback law u = Kx minimizes

the quadratic cost function

J (u) =

0 ( x

Qx + uT Ru + 2 xT Nu) dt

subject to the system dynamics

x = Ax + Bu.
In addition to the state-feedback gain K, lqr returns the solution S of
the associated Riccati equation

AT S + SA ( SB + N ) R1 ( BT S + N T ) + Q = 0
and the closed-loop eigenvalues e = eig(A-B*K). K is derived from
S using

K = R1 ( BT S + N T )
For a discrete-time state-space model, u[n] = Kx[n] minimizes

J=

{ xT Qx + uT Ru + 2 xT Nu}

n =0

subject to x[n + 1] = Ax[n] + Bu[n].

[K,S,e] = LQR(A,B,Q,R,N) is an equivalent syntax for continuous-time

models with dynamics x = Ax + Bu.

In all cases, when you omit the matrix N, N is set to 0.

1-357

lqr

Tips

lqr supports descriptor models with nonsingular E. The output S of

lqr is the solution of the Riccati equation for the equivalent explicit

state-space model:

dx
= E 1 Ax + E 1 Bu
dt

Limitations

The problem data must satisfy:

The pair (A,B) is stabilizable.
R > 0 and Q NR1 N T 0 .
(Q NR1 N T , A BR1 N T ) has no unobservable mode on the
imaginary axis (or unit circle in discrete time).

See Also

1-358

care | dlqr | lqgreg | lqrd | lqry | lqi

lqrd

Purpose

Design discrete linear-quadratic (LQ) regulator for continuous plant

Syntax

lqrd
[Kd,S,e] = lqrd(A,B,Q,R,Ts)
[Kd,S,e] = lqrd(A,B,Q,R,N,Ts)

Description

lqrd designs a discrete full-state-feedback regulator that has response

characteristics similar to a continuous state-feedback regulator

designed using lqr. This command is useful to design a gain matrix for
digital implementation after a satisfactory continuous state-feedback
gain has been designed.
[Kd,S,e] = lqrd(A,B,Q,R,Ts) calculates the discrete state-feedback

law

u[ n] = K d x[ n]
that minimizes a discrete cost function equivalent to the continuous
cost function

J=

0 ( x

Qx + uT Ru )dt

The matrices A and B specify the continuous plant dynamics

x = Ax + Bu
and Ts specifies the sample time of the discrete regulator. Also returned
are the solution S of the discrete Riccati equation for the discretized
problem and the discrete closed-loop eigenvalues e = eig(Ad-Bd*Kd).
[Kd,S,e] = lqrd(A,B,Q,R,N,Ts) solves the more general problem
with a cross-coupling term in the cost function.

J=

0 ( x

Qx + uT Ru + 2 xT Nu ) dt

1-359

lqrd

Algorithms

The equivalent discrete gain matrix Kd is determined by discretizing

the continuous plant and weighting matrices using the sample time Ts
and the zero-order hold approximation.
With the notation

( ) = e A ,
( ) =

Ad = (Ts )

A
e Bd ,
0

Bd = (Ts )

the discretized plant has equations

x[ n + 1] = Ad x[ n] + Bd u[ n]
and the weighting matrices for the equivalent discrete cost function are

Qd
T
N d

Nd
=
Rd

Ts

T
( ) 0 Q

T ( ) I N T

N ( ) ( )

d
I
R 0

The integrals are computed using matrix exponential formulas due to

Van Loan (see [2]). The plant is discretized using c2d and the gain
matrix is computed from the discretized data using dlqr.

Limitations

The discretized problem data should meet the requirements for dlqr.

References

[1] Franklin, G.F., J.D. Powell, and M.L. Workman, Digital Control of
Dynamic Systems, Second Edition, Addison-Wesley, 1980, pp. 439-440.
[2] Van Loan, C.F., "Computing Integrals Involving the Matrix
Exponential," IEEE Trans. Automatic Control, AC-23, June 1978.

See Also

1-360

c2d | dlqr | kalmd | lqr

lqry

Purpose

Form linear-quadratic (LQ) state-feedback regulator with output

weighting

Syntax

[K,S,e] = lqry(sys,Q,R,N)

Description

Given the plant

x = Ax + Bu
y = Cx + Du
or its discrete-time counterpart, lqry designs a state-feedback control

u = Kx
that minimizes the quadratic cost function with output weighting

J (u) = ( yT Qy + uT Ru + 2 yT Nu) dt
0

(or its discrete-time counterpart). The function lqry is equivalent to

lqr or dlqr with weighting matrices:

Q
T
N

N CT
=
R DT

0 Q
T
I N

N C

R 0

D
I

[K,S,e] = lqry(sys,Q,R,N) returns the optimal gain matrix K, the

Riccati solution S, and the closed-loop eigenvalues e = eig(A-B*K). The
state-space model sys specifies the continuous- or discrete-time plant
data (A, B, C, D). The default value N=0 is assumed when N is omitted.

Examples

See LQG Design for the x-Axis for an example.

Limitations

The data A, B, Q, R, N must satisfy the requirements for lqr or dlqr.

See Also

lqr | dlqr | kalman | lqgreg

1-361

lsim

Purpose

Simulate time response of dynamic system to arbitrary inputs

Syntax

lsim
lsim(sys,u,t)
lsim(sys,u,t,x0)
lsim(sys,u,t,x0,'zoh')
lsim(sys,u,t,x0,'foh')
lsim(sys)

Description

lsim simulates the (time) response of continuous or discrete linear

systems to arbitrary inputs. When invoked without left-hand

arguments, lsim plots the response on the screen.
lsim(sys,u,t) produces a plot of the time response of the dynamic
system model sys to the input time history t,u. The vector t specifies

the time samples for the simulation (in system time units, specified in
the TimeUnit property of sys), and consists of regularly spaced time
samples.
t = 0:dt:Tfinal

The matrix u must have as many rows as time samples (length(t))

and as many columns as system inputs. Each row u(i,:) specifies the
input value(s) at the time sample t(i).
The LTI model sys can be continuous or discrete, SISO or MIMO. In
discrete time, u must be sampled at the same rate as the system (t is
then redundant and can be omitted or set to the empty matrix). In
continuous time, the time sampling dt=t(2)-t(1) is used to discretize
the continuous model. If dt is too large (undersampling), lsim issues a
warning suggesting that you use a more appropriate sample time, but
will use the specified sample time. See Algorithms on page 1-365
for a discussion of sample times.
lsim(sys,u,t,x0) further specifies an initial condition x0 for the
system states. This syntax applies only to state-space models.
lsim(sys,u,t,x0,'zoh') or lsim(sys,u,t,x0,'foh') explicitly
specifies how the input values should be interpolated between samples

1-362

lsim

(zero-order hold or linear interpolation). By default, lsim selects the

interpolation method automatically based on the smoothness of the
signal U.
Finally,
lsim(sys1,sys2,...,sysN,u,t)

simulates the responses of several LTI models to the same input history
t,u and plots these responses on a single figure. As with bode or plot,
you can specify a particular color, linestyle, and/or marker for each
system, for example,
lsim(sys1,'y:',sys2,'g--',u,t,x0)

The multisystem behavior is similar to that of bode or step.

When invoked with left-hand arguments,
[y,t] = lsim(sys,u,t)
[y,t,x] = lsim(sys,u,t)
[y,t,x] = lsim(sys,u,t,x0)

% for state-space models only

% with initial state

return the output response y, the time vector t used for simulation,
and the state trajectories x (for state-space models only). No plot is
drawn on the screen. The matrix y has as many rows as time samples
(length(t)) and as many columns as system outputs. The same holds
for x with "outputs" replaced by states.
lsim(sys) opens the Linear Simulation Tool GUI. For more

information about working with this GUI, see Working with the Linear
Simulation Tool.

Examples

Example 1
Simulate and plot the response of the system

1-363

lsim

2s2 + 5s + 1
2

H (s) = s + 2s + 3

s 1
2

s + s+5
to a square wave with period of four seconds. First generate the square
wave with gensig. Sample every 0.1 second during 10 seconds:
[u,t] = gensig('square',4,10,0.1);

Then simulate with lsim.

H = [tf([2 5 1],[1 2 3]) ; tf([1 -1],[1 1 5])]
lsim(H,u,t)

1-364

lsim

Example 2
Simulate the response of an identified linear model using the same
input signal as the one used for estimation and the initial states
returned by the estimation command.

load(fullfile(matlabroot, 'toolbox', 'ident', 'iddemos', 'data', 'dcmo

z = iddata(y, u, 0.1, 'Name', 'DC-motor');
[sys, x0] = n4sid(z, 4);
[y,t,x] = lsim(sys, z.InputData, [], x0);

Compare the simulated response y to measured response z.OutputData.

plot(t,z.OutputData,'k', t,y, 'r')
legend('Measured', 'Simulated')

Algorithms

Discrete-time systems are simulated with ltitr (state space) or filter

(transfer function and zero-pole-gain).
Continuous-time systems are discretized with c2d using either the
'zoh' or 'foh' method ('foh' is used for smooth input signals and
'zoh' for discontinuous signals such as pulses or square waves). The
sampling period is set to the spacing dt between the user-supplied time
samples t.
The choice of sampling period can drastically affect simulation results.
To illustrate why, consider the second-order model

H (s) =

2
2

s + 2s + 2

, = 62.83

To simulate its response to a square wave with period 1 second, you can
proceed as follows:
w2 = 62.83^2
h = tf(w2,[1 2 w2])
t = 0:0.1:5;
u = (rem(t,1)>=0.5);

% vector of time samples

% square wave values

1-365

lsim

lsim(h,u,t)
lsim evaluates the specified sample time, gives this warning
Warning: Input signal is undersampled. Sample every 0.016 sec or
faster.

and produces this plot.

To improve on this response, discretize H(s) using the recommended
sampling period:
dt=0.016;
ts=0:dt:5;
us = (rem(ts,1)>=0.5)
hd = c2d(h,dt)
lsim(hd,us,ts)

1-366

lsim

This response exhibits strong oscillatory behavior hidden from the

undersampled version.

See Also

gensig | impulse | initial | ltiview | step | sim | lsiminfo

1-367

lsiminfo

Purpose

Compute linear response characteristics

Syntax

S = lsiminfo(y,t,yfinal)
S = lsiminfo(y,t)
S = lsiminfo(...,'SettlingTimeThreshold',ST)

Description

S = lsiminfo(y,t,yfinal) takes the response data (t,y) and a

steady-state value yfinal and returns a structure S containing the
following performance indicators:

SettlingTime Settling time

Min Minimum value of Y
MinTime Time at which the min value is reached
Max Maximum value of Y
MaxTime Time at which the max value is reached
For SISO responses, t and y are vectors with the same length NS. For
responses with NY outputs, you can specify y as an NS-by-NY array
and yfinal as a NY-by-1 array. lsiminfo then returns an NY-by-1
structure array S of performance metrics for each output channel.
S = lsiminfo(y,t) uses the last sample value of y as steady-state
value yfinal. s = lsiminfo(y) assumes t = 1:NS.
S = lsiminfo(...,'SettlingTimeThreshold',ST) lets you specify
the threshold ST used in the settling time calculation. The response
has settled when the error |y(t) - yfinal| becomes smaller than a
fraction ST of its peak value. The default value is ST=0.02 (2%).

Examples

Create a fourth order transfer function and ascertain the response

characteristics.
sys = tf([1 -1],[1 2 3 4]);
[y,t] = impulse(sys);
s = lsiminfo(y,t,0) % final value is 0
s =

1-368

lsiminfo

SettlingTime:
Min:
MinTime:
Max:
MaxTime:

See Also

22.8626
-0.4270
2.0309
0.2845
4.0619

lsim | impulse | initial | stepinfo

1-369

lsimplot

Purpose

Simulate response of dynamic system to arbitrary inputs and return

plot handle

Syntax

h = lsimplot(sys)
lsimplot(sys1,sys2,...)
lsimplot(sys,u,t)
lsimplot(sys,u,t,x0)
lsimplot(sys1,sys2,...,u,t,x0)
lsimplot(AX,...)
lsimplot(..., plotoptions)
lsimplot(sys,u,t,x0,'zoh')
lsimplot(sys,u,t,x0,'foh')

Description

h = lsimplot(sys) opens the Linear Simulation Tool for the dynamic

system model sys, which enables interactive specification of driving

input(s), the time vector, and initial state. It also returns the plot
handle h. You can use this handle to customize the plot with the
getoptions and setoptions commands. Type
help timeoptions

for a list of available plot options.

lsimplot(sys1,sys2,...) opens the Linear Simulation Tool for
multiple models sys1,sys2,.... Driving inputs are common to all
specified systems but initial conditions can be specified separately for
each.
lsimplot(sys,u,t) plots the time response of the model sys to
the input signal described by u and t. The time vector t consists of
regularly spaced time samples (in system time units, specified in the
TimeUnit property of sys). For MIMO systems, u is a matrix with as
many columns as inputs and whose ith row specifies the input value
at time t(i). For SISO systems u can be specified either as a row or
column vector. For example,
t = 0:0.01:5;
u = sin(t);

1-370

lsimplot

lsimplot(sys,u,t)

simulates the response of a single-input model sys to the input

u(t)=sin(t) during 5 seconds.
For discrete-time models, u should be sampled at the same rate as sys
(t is then redundant and can be omitted or set to the empty matrix).
For continuous-time models, choose the sampling period t(2)-t(1)
small enough to accurately describe the input u. lsim issues a warning
when u is undersampled, and hidden oscillations can occur.
lsimplot(sys,u,t,x0) specifies the initial state vector x0 at time t(1)
(for state-space models only). x0 is set to zero when omitted.
lsimplot(sys1,sys2,...,u,t,x0) simulates the responses of multiple
LTI models sys1,sys2,... on a single plot. The initial condition x0 is

optional. You can also specify a color, line style, and marker for each
system, as in
lsimplot(sys1,'r',sys2,'y--',sys3,'gx',u,t)
lsimplot(AX,...) plots into the axes with handle AX.
lsimplot(..., plotoptions) plots the initial condition response with
the options specified in plotoptions. Type
help timeoptions

for more detail.

For continuous-time models, lsimplot(sys,u,t,x0,'zoh') or
lsimplot(sys,u,t,x0,'foh') explicitly specifies how the input values
should be interpolated between samples (zero-order hold or linear
interpolation). By default, lsimplot selects the interpolation method
automatically based on the smoothness of the signal u.

See Also

getoptions | lsim | setoptions

1-371

ltiblock.gain

Purpose

Tunable static gain block

Syntax

blk = ltiblock.gain(name,Ny,Nu)
blk = ltiblock.gain(name,G)

Description

Model object for creating tunable static gains. ltiblock.gain lets you
parametrize tunable static gains for parameter studies or for automatic
tuning with Robust Control Toolbox tuning commands such as systune
or looptune.
ltiblock.gain is part of the Control Design Block family of
parametric models. Other Control Design Blocks includeltiblock.pid,
ltiblock.ss, and ltiblock.tf.

Construction

blk = ltiblock.gain(name,Ny,Nu) creates a parametric static gain

block named name. This block has Ny outputs and Nu inputs. The
tunable parameters are the gains across each of the Ny-by-Nu I/O
channels.
blk = ltiblock.gain(name,G) uses the double array G to dimension
the block and initialize the tunable parameters.

Input Arguments
name

String specifying the block Name. (See Properties on page 1-373.)

Ny

Non-negative integer specifying the number of outputs of the parametric

static gain block blk.
Nu

Non-negative integer specifying the number of inputs of the parametric

static gain block blk.
G

1-372

ltiblock.gain

Double array of static gain values. The number of rows and columns of
G determine the number of inputs and outputs of blk. The entries G are
the initial values of the parametric gain block parameters.

Tips

Use the blk.Gain.Free field of blk to specify additional structure or

fix the values of specific entries in the block. To fix the gain value
from input i to output j, set blk.Gain.Free(i,j) = 0. To allow
hinfstruct to tune this gain value, set blk.Gain.Free(i,j) = 1.
To convert an ltiblock.gain parametric model to a numeric
(non-tunable) model object, use model commands such as tf, zpk,
or ss.

Properties

Gain

Parametrization of the tunable gain.

blk.Gain is a param.Continuous object. For general information
about the properties of the param.Continuous object blk.Gain, see the

param.Continuous object reference page.

The following fields of blk.Gain are used when you tune blk using
hinfstruct:

Field

Description

Value

Current value of the gain matrix.

For a block that has Ny outputs
and Nu inputs, blk.Gain.Value
is a Ny-by-Nu matrix.
If you use the G input argument
to create blk, blk.Gain.Value
initializes to the values of
G. Otherwise, all entries of
blk.Gain.Value initialize to
zero.
hinfstruct tunes all entries
in blk.Gain.Value except
those whose values are fixed by

1-373

ltiblock.gain

Field

Description
blk.Gain.Free.
Default: Array of zero values.

Free

Array of logical values

determining whether the gain
entries in blk.Gain.Value are
fixed or free parameters.
If blk.Gain.Free(i,j) = 1,
then blk.Gain.Value(i,j) is
a tunable parameter.
If blk.Gain.Free(i,j) = 0,
then blk.Gain.Value(i,j) is
fixed.
Default: Array of 1 (true) values.

1-374

Minimum

Minimum value of the parameter.

This property places a lower
bound on the tuned value of the
parameter. For example, setting
blk.Gain.Minimum = 1 ensures
that all entries in the gain matrix
have gain greater than 1.
Default: -Inf.

Maximum

Maximum value of the parameter.

This property places an upper
bound on the tuned value of
the parameter. For example,
setting blk.Gain.Maximum =
100 ensures that all entries in the
gain matrix have gain less than
100.
Default: Inf.

ltiblock.gain

Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'

1-375

ltiblock.gain

Changing this property changes the overall system behavior. Use

chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels

1-376

ltiblock.gain

InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems

1-377

ltiblock.gain

Specifying connection points when interconnecting models

Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

1-378

ltiblock.gain

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

Examples

Create a 2-by-2 parametric gain block of the form

g1
0

0
g2

where g1 and g2 are tunable parameters, and the off-diagonal elements

are fixed to zero.
blk = ltiblock.gain('gainblock',2,2); % 2 outputs, 2 inputs
blk.Gain.Free = [1 0; 0 1];
% fix off-diagonal entries to zero

All entries in blk.Gain.Value initialize to zero. Initialize the diagonal

values to 1 as follows.
blk.Gain.Value = eye(2);

% set diagonals to 1

Create a two-input, three-output parametric gain block and initialize

all the parameter values to 1.
To do so, create a matrix to dimension the parametric gain block and
initialize the parameter values.
G = ones(3,2);
blk = ltiblock.gain('gainblock',G);

1-379

ltiblock.gain

Create a 2by-2 parametric gain block and assign names to the inputs.
blk = ltiblock.gain('gainblock',2,2)
blk.InputName = {'Xerror','Yerror'}

% 2 outputs, 2 inputs
% assign input names

See Also

ltiblock.pid | ltiblock.pid2 | ltiblock.ss | ltiblock.tf | genss

| systune | looptune | hinfstruct

How To

Control Design Blocks

Models with Tunable Coefficients

1-380

ltiblock.pid

Purpose

Tunable PID controller

Syntax

blk = ltiblock.pid(name,type)
blk = ltiblock.pid(name,type,Ts)
blk = ltiblock.pid(name,sys)

Description

Model object for creating tunable one-degree-of-freedom PID controllers.

ltiblock.pid lets you parametrize a tunable SISO PID controller for
parameter studies or for automatic tuning with requires Robust Control
Toolbox tuning commands such as systune, looptune, or hinfstruct.
ltiblock.pid2 is part of the family of parametric Control
Design Blocks. Other parametric Control Design Blocks include
ltiblock.gain, ltiblock.ss, and ltiblock.tf.

Construction

blk = ltiblock.pid(name,type) creates the one-degree-of-freedom

continuous-time PID controller:

blk = K p +

Ki
Kds
+
,
s 1 + Tf s

with tunable parameters Kp, Ki, Kd, and Tf. The string type sets
the controller type by fixing some of these values to zero (see Input
Arguments on page 1-382).
blk = ltiblock.pid(name,type,Ts) creates a discrete-time PID

controller with sampling time Ts:

blk = K p + K i IF ( z ) +

Kd
,
Tf + DF ( z )

where IF(z) and DF(z) are the discrete integrator formulas for the
integral and derivative terms, respectively. The values of the IFormula
and DFormula properties set the discrete integrator formulas (see
Properties on page 1-383).

1-381

ltiblock.pid

blk = ltiblock.pid(name,sys) uses the dynamic system model, sys,

to set the sampling time, Ts, and the initial values of the parameters
Kp, Ki, Kd, and Tf.

Input Arguments
name

PID controller Name, specified as a string. (See Properties on page

1-383.)
type

String specifying controller type. Specifying a controller type fixes up

to three of the PID controller parameters. type can take the following
values:
String

Controller Type

Effect on PID
Parameters

'P'

Proportional only

Ki and Kd are fixed to

zero; Tf is fixed to 1;
Kp is free

'PI'

Proportional-integral

Kd is fixed to zero; Tf
is fixed to 1; Kp and
Ki are free

'PD'

Proportional-derivative Ki is fixed to zero; Kp,

with first-order filter Kd, and Tf are free
on derivative action

'PID'

Proportional-integral-derivative
Kp, Ki, Kd, and Tf are
with first-order filter free
on derivative action

Ts

Sampling time, specified as a scalar.

sys

1-382

ltiblock.pid

Dynamic system model representing a PID controller.

Properties

Kp, Ki, Kd, Tf

Parametrization of the PID gains Kp, Ki, Kd, and filter time constant Tf
of the tunable PID controller blk.
The following fields of blk.Kp, blk.Ki, blk.Kd, and blk.Tf are used
when you tune blk using a tuning command such as systune:
Field

Description

Value

Current value of the parameter.

Free

Logical value determining

whether the parameter is fixed or
tunable. For example,
If blk.Kp.Free = 1, then
blk.Kp.Value is tunable.
If blk.Kp.Free = 0, then
blk.Kp.Value is fixed.

Minimum

Minimum value of the parameter.

This property places a lower
bound on the tuned value of the
parameter. For example, setting
blk.Kp.Minimum = 0 ensures
that Kp remains positive.
blk.Tf.Minimum must always be
positive.

Maximum

Maximum value of the parameter.

This property places an upper
bound on the tuned value of the
parameter. For example, setting
blk.Tf.Maximum = 100 ensures
that the filter time constant does
not exceed 100.

1-383

ltiblock.pid

blk.Kp, blk.Ki, blk.Kd, and blk.Tf are param.Continuous objects. For

general information about the properties of these param.Continuous
objects, see the param.Continuous object reference page.
IFormula, DFormula

Strings setting the discrete integrator formulas IF(z) and DF(z) for the
integral and derivative terms, respectively. IFormula and DFormula can
have the following values:
String

IF(z) or DF(z) Formula

'ForwardEuler'

Ts
z 1
'BackwardEuler'

Ts z
z 1
'Trapezoidal'

Ts z + 1
2 z 1
Default: 'ForwardEuler'
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time

1-384

ltiblock.pid

representations. Use d2d to change the sampling time of a discrete-time

system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.

1-385

ltiblock.pid

Alternatively, use automatic vector expansion to assign input names for

multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

1-386

ltiblock.pid

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.

1-387

ltiblock.pid

Default: Empty string '' for all input channels

OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

1-388

ltiblock.pid

Examples

Tunable Controller with a Fixed Parameter

Create a tunable PD controller. Then, initialize the parameter values,
and fix the filter time constant.
blk = ltiblock.pid('pdblock','PD');
blk.Kp.Value = 4;
% initialize Kp
blk.Kd.Value = 0.7;
% initialize Kd
blk.Tf.Value = 0.01;
% set parameter
blk.Tf.Free = false;
% fix parameter
blk

to
to
Tf
Tf

4
0.7
to 0.01
to this value

blk =
Parametric continuous-time PID controller "pdblock" with formula:
s
Kp + Kd * -------Tf*s+1
and tunable parameters Kp, Kd.

Type "pid(blk)" to see the current value and "get(blk)" to see all pro

Controller Initialized by Dynamic System Model

Create a tunable discrete-time PI controller. Use a pid object to
initialize the parameters and other properties.
C = pid(5,2.2,'Ts',0.1,'IFormula','BackwardEuler');
blk = ltiblock.pid('piblock',C)
blk =
Parametric discrete-time PID controller "piblock" with formula:
Ts*z

1-389

ltiblock.pid

Kp + Ki * -----z-1
and tunable parameters Kp, Ki.

Type "pid(blk)" to see the current value and "get(blk)" to see all proper
blk takes the value of properties, such as Ts and IFormula, from C.

Controller with Named Input and Output

Create a tunable PID controller, and assign names to the input and
output.
blk = ltiblock.pid('pidblock','pid')
blk.InputName = {'error'}
% assign input name
blk.OutputName = {'control'}
% assign output name

Tips

You can modify the PID structure by fixing or freeing any of the
parameters Kp, Ki, Kd, and Tf. For example, blk.Tf.Free = false
fixes Tf to its current value.
To convert an ltiblock.pid parametric model to a numeric
(nontunable) model object, use model commands such as pid, pidstd,
tf, or ss. You can also use getValue to obtain the current value
of a tunable model.

See Also

ltiblock.pid2 | ltiblock.ss | ltiblock.tf | systune | looptune

| hinfstruct | getValue

How To

Control Design Blocks

Models with Tunable Coefficients

1-390

ltiblock.pid2

Purpose

Tunable two-degree-of-freedom PID controller

Syntax

blk = ltiblock.pid2(name,type)
blk = ltiblock.pid2(name,type,Ts)
blk = ltiblock.pid2(name,sys)

Description

Model object for creating tunable two-degree-of-freedom PID

controllers. ltiblock.pid2 lets you parametrize a tunable SISO
two-degree-of-freedom PID controller. You can use this parametrized
controller for parameter studies or for automatic tuning with Robust
Control Toolbox tuning commands such as systune, looptune, or
hinfstruct.
ltiblock.pid2 is part of the family of parametric Control
Design Blocks. Other parametric Control Design Blocks include
ltiblock.gain, ltiblock.ss, and ltiblock.tf.

Construction

blk = ltiblock.pid2(name,type) creates the two-degree-of-freedom

continuous-time PID controller described by the equation:

u K p br y

Ki
K s
r y d cr y .
s
1 Tf s

r is the setpoint command, y is the measured response to that setpoint,

and u is the control signal, as shown in the following illustration.

r
y

blk

The tunable parameters of the block are:

Scalar gains Kp, Ki, and Kd
Filter time constant Tf
Scalar weights b and c

1-391

ltiblock.pid2

The string type sets the controller type by fixing some of these values
to zero (see Input Arguments on page 1-392).
blk = ltiblock.pid2(name,type,Ts) creates a discrete-time PID
controller with sampling time Ts. The equation describing this
controller is:

u K p br y K i IF z r y

Kd
cr y .
Tf DF z

IF(z) and DF(z) are the discrete integrator formulas for the integral
and derivative terms, respectively. The values of the IFormula
and DFormula properties set the discrete integrator formulas (see
Properties on page 1-393).
blk = ltiblock.pid2(name,sys) uses the dynamic system model,
sys, to set the sampling time, Ts, and the initial values of all the

tunable parameters. The model sys must be compatible with the

equation of a two-degree-of-freedom PID controller.

Input Arguments
name

PID controller Name, specified as a string. (See Properties on page

1-393.)
type

Controller type, specified as a string. Specifying a controller type

fixes up to three of the PID controller parameters. type can take the
following values:

1-392

ltiblock.pid2

String

Controller Type

Effect on PID
Parameters

'P'

Proportional only

Ki and Kd are fixed to

zero; Tf is fixed to 1;
Kp is free

'PI'

Proportional-integral

Kd is fixed to zero; Tf
is fixed to 1; Kp and
Ki are free

'PD'

Proportional-derivative Ki is fixed to zero; Kp,

with first-order filter Kd, and Tf are free
on derivative action

'PID'

Proportional-integral-derivative
Kp, Ki, Kd, and Tf are
with first-order filter free
on derivative action

Ts

Sampling time, specified as a scalar.

sys

Dynamic system model representing a two-degree-of-freedom PID

controller.

Properties

Kp,Ki,Kd,Tf,b,c

Parametrization of the PID gains Kp, Ki, Kd, the filter time constant,
Tf, and the scalar gains, b and c.
The following fields of blk.Kp, blk.Ki, blk.Kd, blk.Tf, blk.b, and
blk.c are used when you tune blk using a tuning command such as
systune:

1-393

ltiblock.pid2

Field

Description

Value

Current value of the parameter.

blk.b.Value, and blk.c.Value
are always nonnegative.

Free

Logical value determining

whether the parameter is fixed or
tunable. For example,
If blk.Kp.Free = 1, then
blk.Kp.Value is tunable.
If blk.Kp.Free = 0, then
blk.Kp.Value is fixed.

Minimum

Minimum value of the parameter.

This property places a lower
bound on the tuned value of the
parameter. For example, setting
blk.Kp.Minimum = 0 ensures
that Kp remains positive.
blk.Tf.Minimum must always be
positive.

Maximum

Maximum value of the parameter.

This property places an upper
bound on the tuned value of the
parameter. For example, setting
blk.c.Maximum = 1 ensures that
c does not exceed unity.

blk.Kp, blk.Ki, blk.Kd, blk.Tf, blk.b, and blk.c are

param.Continuous objects. For more information about the properties
of these param.Continuous objects, see the param.Continuous object

reference page.
IFormula, DFormula

1-394

ltiblock.pid2

Strings setting the discrete integrator formulas IF(z) and DF(z) for the
integral and derivative terms, respectively. IFormula and DFormula can
have the following values:
String

IF(z) or DF(z) Formula

'ForwardEuler'

Ts
z 1
'BackwardEuler'

Ts z
z 1
'Trapezoidal'

Ts z + 1
2 z 1
Default: 'ForwardEuler'
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

1-395

ltiblock.pid2

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.

1-396

ltiblock.pid2

You can use the shorthand notation u to refer to the InputName

property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

1-397

ltiblock.pid2

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field

1-398

ltiblock.pid2

names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

Examples

Tunable Two-Degree-of-Freedom Controller with a Fixed

Parameter
Create a tunable two-degree-of-freedom PD controller. Then, initialize
the parameter values, and fix the filter time constant.

1-399

ltiblock.pid2

blk = ltiblock.pid2('pdblock','PD');
blk.b.Value = 1;
blk.c.Value = 0.5;
blk.Tf.Value = 0.01;
blk.Tf.Free = false;
blk
blk =

Parametric continuous-time 2-DOF PID controller "pdblock" with equation

s
u = Kp (b*r-y) + Kd -------- (c*r-y)
Tf*s+1

where r,y are the controller inputs and Kp, Kd, b, c are tunable gains.

Type "showBlockValue(blk)" to see the current value and "get(blk)" to see

Controller Initialized by Dynamic System Model

Create a tunable two-degree-of-freedom PI controller. Use a two-input,
one-output tf model to initialize the parameters and other properties.
s = tf('s');
Kp = 10;
Ki = 0.1;
b = 0.7;
sys = [(b*Kp + Ki/s), (-Kp - Ki/s)];
blk = ltiblock.pid2('PI2dof',sys)
blk =

Parametric continuous-time 2-DOF PID controller "PI2dof" with equation:

1

1-400

ltiblock.pid2

u = Kp (b*r-y) + Ki --- (r-y)

s

where r,y are the controller inputs and Kp, Ki, b are tunable gains.
Type "showBlockValue(blk)" to see the current value and "get(blk)" to
blk takes initial parameter values from sys.

If sys is a discrete-time system, blk takes the value of properties, such

as Ts and IFormula, from sys.
Controller with Named Inputs and Output
Create a tunable PID controller, and assign names to the inputs and
output.
blk = ltiblock.pid2('pidblock','pid');
blk.InputName = {'reference','measurement'};
blk.OutputName = {'control'};
blk.InputName is a cell array containing two strings, because a
two-degree-of-freedom PID controller has two inputs.

Tips

You can modify the PID structure by fixing or freeing any of the
parameters. For example, blk.Tf.Free = false fixes Tf to its
current value.
To convert a ltiblock.pid2 parametric model to a numeric
(nontunable) model object, use model commands such as tf or ss.
You can also use getValue to obtain the current value of a tunable
model.

See Also

ltiblock.pid | ltiblock.ss | ltiblock.tf | systune | looptune

| hinfstruct | getValue

How To

Control Design Blocks

1-401

ltiblock.pid2

Models with Tunable Coefficients

1-402

ltiblock.ss

Purpose

Tunable fixed-order state-space model

Syntax

blk
blk
blk
blk

Description

Model object for creating tunable fixed-order state-space models.

ltiblock.ss lets you parametrize a state-space model of a given order
for parameter studies or for automatic tuning with Robust Control
Toolbox tuning commands such as systune or looptune.

=
=
=
=

ltiblock.ss(name,Nx,Ny,Nu)
ltiblock.ss(name,Nx,Ny,Nu,Ts)
ltiblock.ss(name,sys)
ltiblock.ss(...,Astruct)

ltiblock.ss is part of the Control Design Block family of parametric

models. Other Control Design Blocks includeltiblock.pid,
ltiblock.gain, and ltiblock.tf.

Construction

blk = ltiblock.ss(name,Nx,Ny,Nu) creates the continuous-time

parametric state-space model named name. The state-space model blk

has Nx states,Ny outputs, and Nu inputs. The tunable parameters are
the entries in the A, B, C, and D matrices of the state-space model.
blk = ltiblock.ss(name,Nx,Ny,Nu,Ts) creates a discrete-time

parametric state-space model with sampling time Ts.

blk = ltiblock.ss(name,sys) uses the dynamic system sys to
dimension the parametric state-space model, set its sampling time, and
initialize the tunable parameters.
blk = ltiblock.ss(...,Astruct) creates a parametric state-space
model whose A matrix is restricted to the structure specified in Astruct.

Input Arguments
name

String specifying the Name of the parametric state-space model blk.

(See Properties on page 1-405.)
Nx

1-403

ltiblock.ss

Nonnegative integer specifying the number of states (order) of the

parametric state-space model blk.
Ny

Nonnegative integer specifying the number of outputs of the parametric

state-space model blk.
Nu

Nonnegative integer specifying the number of inputs of the parametric

state-space model blk.
Ts

Scalar sampling time.

Astruct

String specifying constraints on the form of the A matrix of the

parametric state-space model blk. Astruct can take the following
values:
String

Structure of A matrix

'tridiag'

A is tridiagonal. In tridiagonal
form, A has free elements only

in the main diagonal, the first

diagonal below the main diagonal,
and the first diagonal above the
main diagonal. The remaining
elements of A are fixed to zero.
'full'

A is full (every entry in A is a free

parameter).
'companion'

A is in companion form.

In companion form, the

characteristic polynomial of
the system appears explicitly

1-404

ltiblock.ss

String

Structure of A matrix
in the rightmost column of the
A matrix. See canon for more
information.

If you do not specify Astruct, blk defaults to 'tridiag' form.

sys

Dynamic system model providing number of states, number of inputs

and outputs, sampling time, and initial values of the parameters of blk.
To obtain the dimensions and initial parameter values, ltiblock.ss
converts sys to a state-space model with the structure specified in
Astruct. If you omit Astruct, ltiblock.ss converts sys into
tridiagonal state-space form.

Tips

Use the Astruct input argument to constrain the structure of the

A matrix of the parametric state-space model. To impose additional
structure constrains on the state-space matrices, use the fields
blk.a.Free, blk.b.Free, blk.c.Free, and blk.d.Free to fix the
values of specific entries in the parameter matrices.
For example, to fix the value of blk.b(i,j), set
blk.b.Free(i,j) = 0. To allow hinfstruct to tune
blk.b(i,j), set blk.b.Free(i,j) = 1.
To convert an ltiblock.ss parametric model to a numeric
(non-tunable) model object, use model commands such as ss, tf,
or zpk.

Properties

a, b, c, d

Parametrization of the state-space matrices A, B, C, and D of the

tunable state-space model blk.
blk.a, blk.b, blk.c, and blk.d are param.Continuous objects. For
general information about the properties of these param.Continuous
objects, see the param.Continuous object reference page.

1-405

ltiblock.ss

The following fields of blk.a, blk.b, blk.c, and blk.d are used when
you tune blk using hinfstruct:
Field

Description

Value

Current values of the entries in

the parametrized state-space
matrix. For example,
blk.a.Value contains the
values of the A matrix of blk.
hinfstruct tunes all entries
in blk.a.Value, blk.b.Value,
blk.c.Value, and blk.d.Value
except those whose values are
fixed by blk.Gain.Free.

Free

2-D array of logical values

determining whether the
corresponding state-space matrix
parameters are fixed or free
parameters. For example:
If blk.a.Free(i,j) = 1, then
blk.a.Value(i,j) is a tunable
parameter.
If blk.a.Free(i,j) = 0, then
blk.a.Value(i,j) is fixed.
Defaults: By default, all entries
in b, c, and c are tunable. The
default free entries in a depend
upon the value of Astruct:

1-406

ltiblock.ss

Field

Description

'tridiag' entries on the

three diagonals of blk.a.Free
are 1; the rest are 0.
'full' all entries in
blk.a.Free are 0.
'companion'
blk.a.Free(1,:) = 1
and blk.a.Free(j,j-1) = 1;
all other entries are 0.
Minimum

Minimum value of the parameter.

This property places a lower
bound on the tuned value of
the parameter. For example,
setting blk.a.Minimum(1,1) =
0 ensures that the first entry in
the A matrix remains positive.
Default: -Inf.

Maximum

Maximum value of the parameter.

This property places an upper
bound on the tuned value of
the parameter. For example,
setting blk.a.Maximum(1,1) =
0 ensures that the first entry in
the A matrix remains negative.
Default: Inf.

StateName

State names. For first-order models, set StateName to a string. For

models with two or more states, set StateName to a cell array of strings
. Use an empty string '' for unnamed states.
Default: Empty string '' for all states

1-407

ltiblock.ss

StateUnit

State units. Use StateUnit to keep track of the units each state is
expressed in. For first-order models, set StateUnit to a string. For
models with two or more states, set StateUnit to a cell array of strings.
StateUnit has no effect on system behavior.
Default: Empty string '' for all states
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'

1-408

ltiblock.ss

'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

1-409

ltiblock.ss

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.

1-410

ltiblock.ss

You can use the shorthand notation y to refer to the OutputName

property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

1-411

ltiblock.ss

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

Examples

Create a parametrized 5th-order SISO model with zero D matrix.

blk = ltiblock.ss('ssblock',5,1,1);
blk.d.Value = 0;
% set D = 0
blk.d.Free = false;
% fix D to zero

By default, the A matrix is in tridiagonal form. To parametrize the

model in companion form, use the 'companion' input argument:
blk = ltiblock.ss('ssblock',5,1,1,'companion');
blk.d.Value = 0;
% set D = 0
blk.d.Free = false;
% fix D to zero

Create a parametric state-space model, and assign names to the inputs.

blk = ltiblock.ss('ssblock',5,2,2) % 5 states, 2 outputs, 2 inputs
blk.InputName = {'Xerror','Yerror'} % assign input names

1-412

ltiblock.ss

See Also

ltiblock.pid | ltiblock.pid2 | ltiblock.ss | ltiblock.tf | genss

| systune | looptune | hinfstruct

How To

Control Design Blocks

Models with Tunable Coefficients

1-413

ltiblock.tf

Purpose

Tunable transfer function with fixed number of poles and zeros

Syntax

blk = ltiblock.tf(name,Nz,Np)
blk = ltiblock.tf(name,Nz,Np,Ts)
blk = ltiblock.tf(name,sys)

Description

Model object for creating tunable SISO transfer function models of fixed
order. ltiblock.tf lets you parametrize a transfer function of a given
orderfor parameter studies or for automatic tuning with Robust Control
Toolbox tuning commands such as systune or looptune.
ltiblock.tf is part of the Control Design Block family of parametric
models. Other Control Design Blocks includeltiblock.pid,
ltiblock.ss, and ltiblock.gain.

Construction

blk = ltiblock.tf(name,Nz,Np) creates the parametric SISO

transfer function:

blk =

am sm + am1 sm1 + + a1 s + a0
sn + bn1 sn1 + + b1 s + b0

n = Np is the maximum number of poles of blk, and m = Nz is the

maximum number of zeros. The tunable parameters are the numerator

and denominator coefficients a0, ..., am and b0, ..., bn1. The leading
coefficient of the denominator is fixed to 1.
blk = ltiblock.tf(name,Nz,Np,Ts) creates a discrete-time

parametric transfer function with sampling time Ts.

blk = ltiblock.tf(name,sys) uses the tf model sys to set the
number of poles, number of zeros, sampling time, and initial parameter
values.

Input Arguments
name

1-414

ltiblock.tf

String specifying the Name of the parametric transfer function blk.

(See Properties on page 1-415.)
Nz

Nonnegative integer specifying the number of zeros of the parametric

transfer function blk.
Np

Nonnegative integer specifying the number of poles of the parametric

transfer function blk.
Ts

Scalar sampling time.

sys
tf model providing number of poles, number of zeros, sampling time,
and initial values of the parameters of blk.

Tips

To convert an ltiblock.tf parametric model to a numeric

(non-tunable) model object, use model commands such as tf, zpk,
or ss.

Properties

num, den

Parametrization of the numerator coefficients am, ..., a0 and the

denominator coefficients 1,bn1, ..., b0 of the tunable transfer function
blk.
blk.num and blk.den are param.Continuous objects. For general
information about the properties of these param.Continuous objects,

see the param.Continuous object reference page.

The following fields of blk.num and blk.den are used when you tune
blk using hinfstruct:

1-415

ltiblock.tf

Field

Description

Value

Array of current values of

the numerator am, ..., a0 or
the denominator coefficients
1,bn1, ..., b0. blk.num.Value has
length Nz + 1. blk.den.Value
has length Np + 1. The leading
coefficient of the denominator
(blk.den.Value(1)) is always
fixed to 1.
By default, the coefficients
initialize to values that yield a
stable, strictly proper transfer
function. Use the input sys
to initialize the coefficients to
different values.
hinfstruct tunes all values
except those whose Free field is
zero.

Free

Array of logical values

determining whether the
coefficients are fixed or tunable.
For example,
If blk.num.Free(j) = 1, then
blk.num.Value(j) is tunable.
If blk.num.Free(j) = 0, then
blk.num.Value(j) is fixed.
Default: blk.den.Free(1) = 0;
all other entries are 1.

1-416

ltiblock.tf

Field

Description

Minimum

Minimum value of the parameter.

This property places a lower
bound on the tuned value of
the parameter. For example,
setting blk.num.Minimum(1)
= 0 ensures that the leading
coefficient of the numerator
remains positive.
Default: -Inf.

Maximum

Maximum value of the parameter.

This property places an upper
bound on the tuned value of
the parameter. For example,
setting blk.num.Maximum(1)
= 1 ensures that the leading
coefficient of the numerator does
not exceed 1.
Default: Inf.

Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

1-417

ltiblock.tf

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.

1-418

ltiblock.tf

You can use the shorthand notation u to refer to the InputName

property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

1-419

ltiblock.tf

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field

1-420

ltiblock.tf

names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []

Examples

Create a parametric SISO transfer function with two zeros, four poles,
and at least one integrator.
A transfer function with an integrator includes a factor of 1/s.
Therefore, to ensure that a parametrized transfer function has at least

1-421

ltiblock.tf

one integrator regardless of the parameter values, fix the lowest-order

coeffiecient of the denominator to zero.
blk = ltiblock.tf('tfblock',2,4); % two zeros, four poles
blk.den.Value(end) = 0;
% set last denominator entry to zero
blk.den.Free(end) = 0;
% fix it to zero

Create a parametric transfer function, and assign names to the input

and output.
blk = ltiblock.tf('tfblock',2,3);
blk.InputName = {'error'};
% assign input name
blk.OutputName = {'control'};
% assign output name

See Also

ltiblock.pid | ltiblock.pid2 | ltiblock.ss | ltiblock.tf | genss

| systune | looptune | hinfstruct

How To

Control Design Blocks

Models with Tunable Coefficients

1-422

ltiview

Purpose

LTI Viewer for LTI system response analysis

Syntax

ltiview
ltiview(sys1,sys2,...,sysn)
ltiview(plottype,sys)
ltiview(plottype,sys,extras)
ltiview('clear',viewers)
ltiview('current',sys1,sys2,...,sysn,viewers)
ltiview(plottype,sys1,sys2,...sysN)
ltiview(plottype,sys1,PlotStyle1,sys2,PlotStyle2,...)
ltiview(plottype,sys1,sys2,...sysN,extras)

Description

ltiview when invoked without input arguments, initializes a new LTI

Viewer for LTI system response analysis.
ltiview(sys1,sys2,...,sysn) opens an LTI Viewer containing the
step response of the LTI models sys1,sys2,...,sysn. You can specify

a distinctive color, line style, and marker for each system, as in

sys1 = rss(3,2,2);
sys2 = rss(4,2,2);
ltiview(sys1,'r-*',sys2,'m--');
ltiview(plottype,sys) initializes an LTI Viewer containing the LTI

response type indicated by plottype for the LTI model sys. The string
plottype can be any one of the following:
'step'
'impulse'
'initial'
'lsim'
'pzmap'
'bode'
'nyquist'
'nichols'
'sigma'

1-423

ltiview

or,
plottype can be a cell vector containing up to six of these plot types.

For example,
ltiview({'step';'nyquist'},sys)

displays the plots of both of these response types for a given system sys.
ltiview(plottype,sys,extras) allows the additional input
arguments supported by the various LTI model response functions to be
passed to the ltiview command.
extras is one or more input arguments as specified by the function
named in plottype. These arguments may be required or optional,
depending on the type of LTI response. For example, if plottype is
'step' then extras may be the desired final time, Tfinal, as shown

below.
ltiview('step',sys,Tfinal)

However, if plottype is 'initial', the extras arguments must

contain the initial conditions x0 and may contain other arguments,
such as Tfinal.
ltiview('initial',sys,x0,Tfinal)

See the individual references pages of each possible plottype

commands for a list of appropriate arguments for extras.
ltiview('clear',viewers) clears the plots and data from the LTI
Viewers with handles viewers.
ltiview('current',sys1,sys2,...,sysn,viewers) adds the
responses of the systems sys1,sys2,...,sysn to the LTI Viewers
with handles viewers. If these new systems do not have the same I/O
dimensions as those currently in the LTI Viewer, the LTI Viewer is first
cleared and only the new responses are shown.

1-424

ltiview

ltiview(plottype,sys1,sys2,...sysN) initializes an LTI Viewer

containing the responses of multiple LTI models.

ltiview(plottype,sys1,PlotStyle1,sys2,PlotStyle2,...)

initializes the viewer with specified plot styles. See the individual
reference pages of the LTI response functions for more information
on specifying plot styles.
ltiview(plottype,sys1,sys2,...sysN,extras) initializes the viewer
for multiple models using the extras input arguments.

See Also

bode | impulse | initial | lsim | nichols | nyquist | pzmap |

sigma | step

Related
Examples

Linear Analysis Using the LTI Viewer

1-425

lyap

Purpose

Continuous Lyapunov equation solution

Syntax

lyap
X = lyap(A,Q)
X = lyap(A,B,C)
X = lyap(A,Q,[],E)

Description

lyap solves the special and general forms of the Lyapunov equation.

Lyapunov equations arise in several areas of control, including stability

theory and the study of the RMS behavior of systems.
X = lyap(A,Q) solves the Lyapunov equation

AX + XAT + Q = 0
where A and Q represent square matrices of identical sizes. If Q is a
symmetric matrix, the solution X is also a symmetric matrix.
X = lyap(A,B,C) solves the Sylvester equation

AX + XB + C = 0
The matrices A, B, and C must have compatible dimensions but need
not be square.
X = lyap(A,Q,[],E) solves the generalized Lyapunov equation

AXET + EXAT + Q = 0
where Q is a symmetric matrix. You must use empty square brackets
[] for this function. If you place any values inside the brackets, the
function errors out.

Algorithms

1-426

lyap uses SLICOT routines SB03MD and SG03AD for Lyapunov

equations and SB04MD (SLICOT) and ZTRSYL (LAPACK) for Sylvester
equations.

lyap

Limitations

The continuous Lyapunov equation has a unique solution if the

eigenvalues 1 , 2 ,..., n of A and 1 , 2 ,..., n of B satisfy

i + j 0

for all pairs (i, j)

If this condition is violated, lyap produces the error message:

Solution does not exist or is not unique.

Examples

Example 1
Solve Lyapunov Equation
Solve the Lyapunov equation

AX + XAT + Q = 0
where

2
1
A=

3 4

3 1
Q=

1 1

The A matrix is stable, and the Q matrix is positive definite.

A = [1 2; -3 -4];
Q = [3 1; 1 1];
X = lyap(A,Q)

These commands return the following X matrix:

X =
6.1667
-3.8333

-3.8333
3.0000

You can compute the eigenvalues to see that X is positive definite.

eig(X)

1-427

lyap

The command returns the following result:

ans =
0.4359
8.7308

Example 2
Solve Sylvester Equation
Solve the Sylvester equation

AX + XB + C = 0
where

A=5
A
B
C
X

=
=
=
=

4 3
B=

4 3

C = [ 2 1]

5;
[4 3; 4 3];
[2 1];
lyap(A,B,C)

These commands return the following X matrix:

X =
-0.2000

References

-0.0500

[1] Bartels, R.H. and G.W. Stewart, "Solution of the Matrix Equation
AX + XB = C," Comm. of the ACM, Vol. 15, No. 9, 1972.
[2] Barraud, A.Y., A numerical algorithm to solve A XA - X = Q, IEEE
Trans. Auto. Contr., AC-22, pp. 883885, 1977.

1-428

lyap

[3] Hammarling, S.J., Numerical solution of the stable, non-negative

definite Lyapunov equation, IMA J. Num. Anal., Vol. 2, pp. 303325,
1982.
[4] Penzl, T., Numerical solution of generalized Lyapunov equations,
Advances in Comp. Math., Vol. 8, pp. 3348, 1998.
[5] Golub, G.H., Nash, S. and Van Loan, C.F., A Hessenberg-Schur
method for the problem AX + XB = C, IEEE Trans. Auto. Contr.,
AC-24, pp. 909913, 1979.

See Also

covar | dlyap

1-429

lyapchol

Purpose

Square-root solver for continuous-time Lyapunov equation

Syntax

R = lyapchol(A,B)
X = lyapchol(A,B,E)

Description

R = lyapchol(A,B) computes a Cholesky factorization X = R'*R of the

solution X to the Lyapunov matrix equation:
A*X + X*A' + B*B' = 0

All eigenvalues of matrix A must lie in the open left half-plane for R
to exist.
X = lyapchol(A,B,E) computes a Cholesky factorization X = R'*R of
X solving the generalized Lyapunov equation:
A*X*E' + E*X*A' + B*B' = 0

All generalized eigenvalues of (A,E) must lie in the open left half-plane
for R to exist.

Algorithms

lyapchol uses SLICOT routines SB03OD and SG03BD.

References

[1] Bartels, R.H. and G.W. Stewart, "Solution of the Matrix Equation
AX + XB = C," Comm. of the ACM, Vol. 15, No. 9, 1972.
[2] Hammarling, S.J., Numerical solution of the stable, non-negative
definite Lyapunov equation, IMA J. Num. Anal., Vol. 2, pp. 303-325,
1982.
[3] Penzl, T., Numerical solution of generalized Lyapunov equations,
Advances in Comp. Math., Vol. 8, pp. 33-48, 1998.

See Also

1-430

lyap | dlyapchol

mag2db

Purpose

Convert magnitude to decibels (dB)

Syntax

ydb = mag2db(y)

Description

ydb = mag2db(y) returns the corresponding decibel (dB) value ydb for a

See Also

db2mag

given magnitude y. The relationship between magnitude and decibels

is ydb = 20 log10(y).

1-431

margin

Purpose

Gain margin, phase margin, and crossover frequencies

Syntax

[Gm,Pm,Wgm,Wpm] = margin(sys)
[Gm,Pm,Wgm,Wpm] = margin(mag,phase,w)
margin(sys)

Description

margin calculates the minimum gain margin, Gm, phase margin, Pm,
and associated frequencies Wgm and Wpm of SISO open-loop models. The
gain and phase margin of a system sys indicates the relative stability
of the closed-loop system formed by applying unit negative feedback to
sys, as in the following illustration.

+
-

sys

The gain margin is the amount of gain increase or decrease required to

make the loop gain unity at the frequency Wgm where the phase angle is
180 (modulo 360). In other words, the gain margin is 1/g if g is the
gain at the 180 phase frequency. Similarly, the phase margin is the
difference between the phase of the response and 180 when the loop
gain is 1.0. The frequency Wpm at which the magnitude is 1.0 is called
the unity-gain frequency or gain crossover frequency. It is generally
found that gain margins of three or more combined with phase margins
between 30 and 60 degrees result in reasonable trade-offs between
bandwidth and stability.
[Gm,Pm,Wgm,Wpm] = margin(sys) computes the gain margin Gm, the
phase margin Pm, and the corresponding frequencies Wgm and Wpm, given
the SISO open-loop dynamic system model sys. Wgm is the frequency

where the gain margin is measured, which is a 180 degree phase

crossing frequency. Wpm is the frequency where the phase margin is
measured, which is a 0dB gain crossing frequency. These frequencies
are expressed in radians/TimeUnit, where TimeUnit is the unit specified
in the TimeUnit property of sys. When sys has several crossovers,

1-432

margin

margin returns the smallest gain and phase margins and corresponding

frequencies.
The phase margin Pm is in degrees. The gain margin Gm is an absolute
magnitude. You can compute the gain margin in dB by
Gm_dB = 20*log10(Gm)
[Gm,Pm,Wgm,Wpm] = margin(mag,phase,w) derives the gain and

phase margins from Bode frequency response data (magnitude, phase,

and frequency vector). margin interpolates between the frequency
points to estimate the margin values. Provide the gain data mag in
absolute units, and phase data phase in degrees. You can provide the
frequency vector w in any units; margin returns Wgm and Wpm in the
same units.
Note When you use margin(mag,phase,w), margin relies on
interpolation to approximate the margins, which generally produces
less accurate results. For example, if there is no 0 dB crossing within
the w range, margin returns a phase margin of Inf. Therefore, if you
have an analytical model sys, using [Gm,Pm,Wgm,Wpm] = margin(sys)
is the most robust way to obtain the margins.
margin(sys), without output arguments, plots the Bode response of
sys on the screen and indicates the gain and phase margins on the plot.

By default, gain margins are expressed in dB on the plot.

Examples

Gain and Phase Margins of Open-Loop Transfer Function

Create an open-loop discrete-time transfer function.
hd = tf([0.04798 0.0464],[1 -1.81 0.9048],0.1)
hd =
0.04798 z + 0.0464

1-433

margin

--------------------z^2 - 1.81 z + 0.9048

Sample time: 0.1 seconds
Discrete-time transfer function.

Compute the gain and phase margins.

[Gm,Pm,Wgm,Wpm] = margin(hd)
Gm =
2.0517

Pm =
13.5711

Wgm =
5.4374

Wpm =
4.3544

Display the gain and phase margins graphically.

margin(hd)

1-434

margin

Solid vertical lines mark the gain margin and phase margin. The
dashed vertical lines indicate the locations of Wpm, the frequency where
the phase margin is measured, and Wgm, the frequency where the gain
margin is measured.

Algorithms

The phase margin is computed using H theory, and the gain margin
by solving H ( j ) = H ( j ) for the frequency .

See Also

bode | ltiview

1-435

minreal

Purpose

Minimal realization or pole-zero cancelation

Syntax

sysr = minreal(sys)
sysr = minreal(sys,tol)
[sysr,u] = minreal(sys,tol)
... = minreal(sys,tol,false)
... = minreal(sys,[],false)

Description

sysr = minreal(sys) eliminates uncontrollable or unobservable state

in state-space models, or cancels pole-zero pairs in transfer functions
or zero-pole-gain models. The output sysr has minimal order and the
same response characteristics as the original model sys.
sysr = minreal(sys,tol) specifies the tolerance used for state
elimination or pole-zero cancellation. The default value is tol =
sqrt(eps) and increasing this tolerance forces additional cancellations.
[sysr,u] = minreal(sys,tol) returns, for state-space model sys,
an orthogonal matrix U such that (U*A*U',U*B,C*U') is a Kalman
decomposition of (A,B,C)
... = minreal(sys,tol,false) and ... =
minreal(sys,[],false) disable the verbose output of the function. By
default, minreal displays a message indicating the number of states
removed from a state-space model sys.

Examples

The commands
g = zpk([],1,1);
h = tf([2 1],[1 0]);
cloop = inv(1+g*h) * g

produce the nonminimal zero-pole-gain model cloop.

cloop =
s (s-1)
-------------------

1-436

minreal

(s-1) (s^2 + s + 1)
Continuous-time zero/pole/gain model.

To cancel the pole-zero pair at s = 1, type

cloopmin = minreal(cloop)

This command produces the following result.

cloopmin =
s
------------(s^2 + s + 1)
Continuous-time zero/pole/gain model.

Algorithms

Pole-zero cancellation is a straightforward search through the poles and

zeros looking for matches that are within tolerance. Transfer functions
are first converted to zero-pole-gain form.

See Also

balreal | modred | sminreal

1-437

modred

Purpose

Model order reduction

Syntax

rsys = modred(sys,elim)
rsys = modred(sys,elim,'method')

Description

rsys = modred(sys,elim) reduces the order of a continuous or discrete

state-space model sys by eliminating the states found in the vector
elim. The full state vector X is partitioned as X = [X1;X2] where X1 is
the reduced state vector and X2 is discarded.
elim can be a vector of indices or a logical vector commensurate with
X where true values mark states to be discarded. This function is
usually used in conjunction with balreal. Use balreal to first isolate
states with negligible contribution to the I/O response. If sys has been
balanced with balreal and the vector g of Hankel singular values has
M small entries, you can use modred to eliminate the corresponding M
states. For example:
[sys,g] = balreal(sys)

% Compute balanced realization

elim = (g<1e-8)

% Small entries of g are negligible states

rsys = modred(sys,elim) % Remove negligible states

rsys = modred(sys,elim,'method') also specifies the state

elimination method. Choices for 'method' include

'MatchDC' (default): Enforce matching DC gains. The state-space

matrices are recomputed as described in Algorithms on page 1-441.
'Truncate': Simply delete X2.
The 'Truncate' option tends to produces a better approximation in the
frequency domain, but the DC gains are not guaranteed to match.
If the state-space model sys has been balanced with balreal and the
grammians have m small diagonal entries, you can reduce the model
order by eliminating the last m states with modred.

1-438

modred

Examples

Consider the continuous fourth-order model

h(s) =

s3 + 11s2 + 36 s + 26
s4 + 14.6 s3 + 74.96 s2 + 153.7s + 99.65

To reduce its order, first compute a balanced state-space realization

with balreal.
h = tf([1 11 36 26],[1 14.6 74.96 153.7 99.65]);
[hb,g] = balreal(h);

Examine the gramians.

g'
ans =
0.1394

0.0095

0.0006

0.0000

The last three diagonal entries of the balanced gramians are relatively
small. Eliminate these three least-contributing states with modred
using both matched DC gain and direct deletion methods.
hmdc = modred(hb,2:4,'MatchDC');
hdel = modred(hb,2:4,'Truncate');

Both hmdc and hdel are first-order models. Compare their Bode
responses against that of the original model h(s).
bodeplot(h,'-',hmdc,'x',hdel,'*')

1-439

modred

The reduced-order model hdel is clearly a better frequency-domain

approximation of h(s). Now compare the step responses.
stepplot(h,'-',hmdc,'-.',hdel,'--')

1-440

modred

While hdel accurately reflects the transient behavior, only hmdc gives
the true steady-state response.

Algorithms

The algorithm for the matched DC gain method is as follows. For

continuous-time models

x = Ax + By
y = Cx + Du
the state vector is partitioned into x1, to be kept, and x2, to be eliminated.

1-441

modred

x1 A11 A12 x1 B1
x = A
+ u
2 21 A22 x2 B2
y = [C1 C2 ] x + Du
Next, the derivative of x2 is set to zero and the resulting equation is
solved for x1. The reduced-order model is given by

x1 = A11 A12 A221 A21 x1 + B1 A12 A221 B2 u

y = C1 C2 A221 A21 x + D C2 A221 B2 u
The discrete-time case is treated similarly by setting

x2[ n + 1] = x2[ n]

Limitations

With the matched DC gain method, A22 must be invertible in continuous

time, and I A22 must be invertible in discrete time.

See Also

balreal | minreal

1-442

modsep

Purpose

Region-based modal decomposition

Syntax

[H,H0] = modsep(G,N,REGIONFCN)
MODSEP(G,N,REGIONFCN,PARAM1,...)

Description

[H,H0] = modsep(G,N,REGIONFCN) decomposes the LTI model G into a

sum of n simpler models Hj with their poles in disjoint regions Rj of

the complex plane:

G(s) = H 0 +

N
Hj(s)
j =1

G can be any LTI model created with ss, tf, or zpk, and N is the number
of regions used in the decomposition. modsep packs the submodels Hj
into an LTI array H and returns the static gain H0 separately. Use
H(:,:,j) to retrieve the submodel Hj(s).

To specify the regions of interest, use a function of the form

IR = REGIONFCN(p)

that assigns a region index IR between 1 and N to a given pole p. You can
specify this function as a string or a function handle, and use the syntax
MODSEP(G,N,REGIONFCN,PARAM1,...) to pass extra input arguments:
IR = REGIONFCN(p,PARAM1,...)

Examples

To decompose G into G(z) = H0 + H1(z) + H2(z) where H1 and H2

have their poles inside and outside the unit disk respectively, use
[H,H0]

= modsep(G,2,@udsep)

where the function udsep is defined by

function r = udsep(p)
if abs(p)<1, r = 1; % assign r=1 to poles inside unit disk
else
r = 2; % assign r=2 to poles outside unit disk
end

1-443

modsep

To extract H1(z) and H2(z) from the LTI array H, use

H1 = H(:,:,1);

See Also

1-444

stabsep

H2 = H(:,:,2);

nblocks

Purpose

Number of blocks in Generalized matrix or Generalized LTI model

Syntax

N = nblocks(M)

Description

N = nblocks(M) returns the number of Control Design Blocks in the

Input
Arguments

Output
Arguments

Generalized LTI model or Generalized matrix M.

AGeneralized LTI model (genss or genfrd model), a Generalized matrix

(genmat), or an array of such models.

The number of Control Design Blocks in M. If a block appears multiple

times in M, N reflects the total number of occurrences.
If M is a model array, N is an array with the same dimensions as M. Each
entry of N is the number of Control Design Blocks in the corresponding
entry of M.

Examples

Number of Control Design Blocks in a Second-Order Filter

Model
This example shows how to use nblocks to examine two different ways
of parametrizing a model of a second-order filter.
1 Create a tunable (parametric) model of the second-order filter:

F s

n2
s2 2n n2

where the damping and the natural frequency n are tunable

parameters.
wn = realp('wn',3);
zeta = realp('zeta',0.8);

1-445

nblocks

F = tf(wn^2,[1 2*zeta*wn wn^2]);

F is a genss model with two tunable Control Design Blocks, the
realp blocks wn and zeta. The blocks wn and zeta have initial values

of 3 and 0.8, respectively.

2 Examine the number of tunable blocks in the model using nblocks.

nblocks(F)

This command returns the result:

ans =
6
F has two tunable parameters, but the parameter wn appears five
timestwice in the numerator and three times in the denominator.
3 Rewrite F for fewer occurrences of wn.

The second-order filter transfer function can be expressed as follows:

F s

1
2

2
n

1
n

Use this expression to create the tunable filter:

F = tf(1,[(1/wn)^2 2*zeta*(1/wn) 1])
4 Examine the number of tunable blocks in the new filter model.

nblocks(F)

This command returns the result:

ans =

1-446

nblocks

In the new formulation, there are only three occurrences of the

tunable parameter wn. Reducing the number of occurrences of a block
in a model can improve performance time of calculations involving
the model. However, the number of occurrences does not affect the
results of tuning the model or sampling the model for parameter
studies.

See Also

genss | genfrd | genmat | getValue

How To

Control Design Blocks

Generalized Matrices
Generalized and Uncertain LTI Models

1-447

ndims

Purpose

Query number of dimensions of dynamic system model or model array

Syntax

n = ndims(sys)

Description

n = ndims(sys) is the number of dimensions of a dynamic system

model or a model array sys. A single model has two dimensions (one for

outputs, and one for inputs). A model array has 2 + p dimensions, where
p 2 is the number of array dimensions. For example, a 2-by-3-by-4
array of models has 2 + 3 = 5 dimensions.
ndims(sys) = length(size(sys))

Examples

sys = rss(3,1,1,3);
ndims(sys)
ans =
4
ndims returns 4 for this 3-by-1 array of SISO models.

See Also

1-448

size

ngrid

Purpose

Superimpose Nichols chart on Nichols plot

Syntax

ngrid

Description

ngrid superimposes Nichols chart grid lines over the Nichols frequency
response of a SISO LTI system. The range of the Nichols grid lines is
set to encompass the entire Nichols frequency response.

The chart relates the complex number H/(1 + H) to H, where H is any

complex number. For SISO systems, when H is a point on the open-loop
frequency response, then

H
1+ H
is the corresponding value of the closed-loop frequency response
assuming unit negative feedback.
If the current axis is empty, ngrid generates a new Nichols chart grid
in the region 40 dB to 40 dB in magnitude and 360 degrees to 0
degrees in phase. If the current axis does not contain a SISO Nichols
frequency response, ngrid returns a warning.

Examples

Plot the Nichols response with Nichols grid lines for the system.

H (s) =

4 s4 + 48 s3 18 s2 + 250 s + 600
s4 + 30 s3 + 282s2 + 525s + 60

Type
H = tf([-4 48 -18 250 600],[1 30 282 525 60])

These commands produce the following result.

Transfer function:
- 4 s^4 + 48 s^3 - 18 s^2 + 250 s + 600
--------------------------------------s^4 + 30 s^3 + 282 s^2 + 525 s + 60

1-449

ngrid

Type
nichols(H)
ngrid

See Also

1-450

nichols

nichols

Purpose

Nichols chart of frequency response

Syntax

nichols(sys)
nichols(sys)
nichols(sys,w)
nichols(sys1,sys2,...,sysN)
nichols(sys1,sys2,...,sysN,w)
nichols(sys1,'PlotStyle1',...,sysN,'PlotStyleN')
[mag,phase,w] = nichols(sys)
[mag,phase] = nichols(sys,w)
[mag,phase,w] = nichols(sys)
[mag,phase] = nichols(sys,w)

Description

nichols creates a Nichols chart of the frequency response. A Nichols

chart displays the magnitude (in dB) plotted against the phase (in
degrees) of the system response. Nichols charts are useful to analyze
open- and closed-loop properties of SISO systems, but offer little insight
into MIMO control loops. Use ngrid to superimpose a Nichols chart on
an existing SISO Nichols chart.
nichols(sys) creates a Nichols chart of the dynamic system sys. This

model can be continuous or discrete, SISO or MIMO. In the MIMO

case, nichols produces an array of Nichols charts, each plot showing
the response of one particular I/O channel. The frequency range and
gridding are determined automatically based on the system poles and
zeros.
nichols(sys,w) specifies the frequency range or frequency points
to be used for the chart. To focus on a particular frequency interval
[wmin,wmax], set w = {wmin,wmax}. To use particular frequency
points, set w to the vector of desired frequencies. Use logspace to
generate logarithmically spaced frequency vectors. Frequencies must
be in rad/TimeUnit, where TimeUnit is the time units of the input
dynamic system, specified in the TimeUnit property of sys.
nichols(sys1,sys2,...,sysN) or nichols(sys1,sys2,...,sysN,w)

superimposes the Nichols charts of several models on a single

figure. All systems must have the same number of inputs

1-451

nichols

and outputs, but may otherwise be a mix of continuous- and

discrete-time systems. You can also specify a distinctive color,
linestyle, and/or marker for each system plot with the syntax
nichols(sys1,'PlotStyle1',...,sysN,'PlotStyleN').
See bode for an example.
[mag,phase,w] = nichols(sys) or [mag,phase] = nichols(sys,w)

returns the magnitude and phase (in degrees) of the frequency response
at the frequencies w (in rad/TimeUnit). The outputs mag and phase are
3-D arrays similar to those produced by bode (see the bode reference
page). They have dimensions
(number of outputs) (number of inputs) (length of w)

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Nichols Chart of Dynamic System

Display a Nichols chart of the dynamic system:

H (s) =

4 s4 + 48 s3 18 s2 + 250 s + 600
s4 + 30 s3 + 282s2 + 525s + 60

num = [-4 48 -18 250 600];

den = [1 30 282 525 60];
H = tf(num,den)
nichols(H); ngrid

1-452

nichols

The right-click menu for Nichols charts includes the Tight option under
Zoom. You can use this to clip unbounded branches of the Nichols chart.

Algorithms

See bode.

See Also

bode | evalfr | freqresp | ltiview | ngrid | nyquist | sigma

1-453

nicholsoptions

Purpose

Create list of Nichols plot options

Syntax

P = nicholsoptions
P = nicholsoptions('cstprefs')

Description

P = nicholsoptions returns a list of available options for Nichols plots

with default values set. You can use these options to customize the
Nichols plot appearance from the command line.
P = nicholsoptions('cstprefs') initializes the plot options with the

options you selected in the Control System Toolbox Preferences Editor.

For more information about the editor, see Toolbox Preferences Editor
in the Users Guide documentation.
This table summarizes the Nichols plot options.

1-454

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid

Show or hide the grid

Specified as one of the following
strings: 'off' | 'on'
Default: 'off'

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

IOGrouping

Grouping of input-output pairs

Specified as one of the
following strings: 'none'
|'inputs'|'output'|'all'
Default: 'none'

InputLabels, OutputLabels

Input and output label styles.

InputVisible, OutputVisible

Visibility of input and output

channels

nicholsoptions

Option

Description

FreqUnits

Frequency units, specified as one

of the following strings:
'Hz'
'rad/second'
'rpm'
'kHz'
'MHz'
'GHz'
'rad/nanosecond'
'rad/microsecond'
'rad/millisecond'
'rad/minute'
'rad/hour'
'rad/day'
'rad/week'
'rad/month'
'rad/year'
'cycles/nanosecond'
'cycles/microsecond'
'cycles/millisecond'
'cycles/hour'
'cycles/day'
'cycles/week'
'cycles/month'

1-455

nicholsoptions

Option

Description
'cycles/year'
Default: 'rad/s'
You can also specify 'auto'
which uses frequency units
rad/TimeUnit relative to system
time units specified in the
TimeUnit property. For multiple
systems with different time units,
the units of the first system are
used.

1-456

MagLowerLimMode

Enables a lower magnitude limit

Specified as one of the following
strings: 'auto' | 'manual'
Default: 'auto'

MagLowerLim

Specifies the lower magnitude

limit

PhaseUnits

Phase units
Specified as one of the following
strings: 'deg' | 'rad'
Default: 'deg'

PhaseWrapping

Enables phase wrapping

Specified as one of the following
strings: 'on' | 'off'
Default: 'off'

PhaseMatching

Enables phase matching

Specified as one of the following
strings: 'on' | 'off'
Default: 'off'

nicholsoptions

Examples

Option

Description

PhaseMatchingFreq

Frequency for matching phase

PhaseMatchingValue

The value to make the phase

responses close to

In this example, you set the phase units and enable the grid option
for the Nichols plot.
P = nicholsoptions; % Set phase units to radians and grid to on in options
P.PhaseUnits = 'rad';
P.Grid = 'on'; % Create plot with the options specified by P
h = nicholsplot(tf(1,[1,.2,1,0]),P);

The following Nichols plot is created, with the phase units in radians
and the grid enabled.

1-457

nicholsoptions

See Also

1-458

getoptions | nicholsplot | setoptions

nicholsplot

Purpose

Plot Nichols frequency responses and return plot handle

Syntax

h = nicholsplot(sys)
nicholsplot(sys,{wmin,wmax})
nicholsplot(sys,w)
nicholsplot(sys1,sys2,...,w)
nicholsplot(AX,...)
nicholsplot(..., plotoptions)

Description

h = nicholsplot(sys) draws the Nichols plot of the dynamic system

sys. It also returns the plot handle h. You can use this handle to
customize the plot with the getoptions and setoptions commands.

Type
help nicholsoptions

for a list of available plot options.

The frequency range and number of points are chosen automatically.
See bode for details on the notion of frequency in discrete time.
nicholsplot(sys,{wmin,wmax}) draws the Nichols plot for frequencies
between wmin and wmax (in rad/TimeUnit, where TimeUnit is the time
units of the input dynamic system, specified in the TimeUnit property
of sys).
nicholsplot(sys,w) uses the user-supplied vector w of frequencies, in
rad/TimeUnit, at which the Nichols response is to be evaluated. See
logspace to generate logarithmically spaced frequency vectors.
nicholsplot(sys1,sys2,...,w) draws the Nichols plots of multiple
models sys1,sys2,... on a single plot. The frequency vector w is optional.
You can also specify a color, line style, and marker for each system, as in
nicholsplot(sys1,'r',sys2,'y--',sys3,'gx').
nicholsplot(AX,...) plots into the axes with handle AX.

1-459

nicholsplot

nicholsplot(..., plotoptions) plots the Nichols plot with the

options specified in plotoptions. Type
help nicholsoptions

for more details.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Generate Nichols plot and use plot handle to change frequency units
to Hz
sys = rss(5);
h = nicholsplot(sys);
% Change units to Hz
setoptions(h,'FreqUnits','Hz');

See Also

1-460

getoptions | nichols | nicholsoptions | setoptions

nmodels

Purpose

Number of models in model array

Syntax

N = nmodels(sysarray)

Description

N = nmodels(sysarray) returns the number of models in an array of

Input
Arguments

sysarray - Input model array

model array

dynamic system models or static models.

Input model array, specified as an array of input-output models such as

numeric LTI models, generalized models, or identified LTI models.

Output
Arguments

N - Number of models in array

positive integer

Number of models in the input model array, returned as a positive

integer.

Examples

Number of Models in Array

Create a 2-by-3-by-5 array of state-space models and confirm the
number of models in the array.
sysarr = rss(2,2,2,2,3,4);
N = nmodels(sysarr)
N =
24

See Also

ndims | size

1-461

norm

Purpose

Norm of linear model

Syntax

n = norm(sys)
n = norm(sys,2)
n = norm(sys,inf)
[n,fpeak] = norm(sys,inf)
[...] = norm(sys,inf,tol)

Description

n = norm(sys) or n = norm(sys,2) return the H2 norm of the linear

dynamic system model sys.
n = norm(sys,inf) returns the H norm of sys.
[n,fpeak] = norm(sys,inf) also returns the frequency fpeak at
which the gain reaches its peak value.
[...]

= norm(sys,inf,tol) sets the relative accuracy of the H

norm to tol.

Input
Arguments

sys

Continuous- or discrete-time linear dynamic system model. sys can

also be an array of linear models.
tol

Positive real value setting the relative accuracy of the H norm.

Default: 0.01

Output
Arguments

H2 norm or H norm of the linear model sys.

If sys is an array of linear models, n is an array of the same size as sys.
In that case each entry of n is the norm of each entry of sys.
fpeak

Frequency at which the peak gain of sys occurs.

1-462

norm

Definitions

H2 norm
The H2 norm of a stable continuous-time system with transfer function
H(s), is given by:

1
2

Trace H ( j)

H ( j ) d .

For a discrete-time system with transfer function H(z), the H2 norm

is given by:

1
Trace H (e j ) H H (e j ) d .

The H2 norm is equal to the root-mean-square of the impulse response

of the system. The H2 norm measures the steady-state covariance (or
power) of the output response y = Hw to unit white noise inputs w:

2
2

= lim E { y(t)T y(t)} ,

t

E ( w(t)w( )T ) = ( t ) I .

The H2 norm is infinite in the following cases:

sys is unstable.
sys is continuous and has a nonzero feedthrough (that is, nonzero
gain at the frequency = ).
norm(sys) produces the same result as
sqrt(trace(covar(sys,1)))

H-infinity norm
The H norm (also called the L norm) of a SISO linear system is the
peak gain of the frequency response. For a MIMO system, the H
norm is the peak gain across all input/output channels. Thus, for a
continuous-time system H(s), the H norm is given by:

1-463

norm

H ( s)

= max H ( j )

(SISO)

H ( s)

= max max ( H ( j ) )

(MIMO)

where max( ) denotes the largest singular value of a matrix.

For a discrete-time system H(z):

( )

H ( z)

= max H e j
[0, ]

H ( z)

= max max H e j
[0, ]

( ( ))

(SISO)
(MIMO)

The H norm is infinite if sys has poles on the imaginary axis (in
continuous time), or on the unit circle (in discrete time).

Examples

This example uses norm to compute the H2 and H norms of a

discrete-time linear system.
Consider the discrete-time transfer function

H ( z) =

z3 2.841 z2 + 2.875 z 1.004

z3 2.417 z2 + 2.003 z 0.5488

with sample time 0.1 second.

To compute the H2 norm of this transfer function, enter:
H = tf([1 -2.841 2.875 -1.004],[1 -2.417 2.003 -0.5488],0.1)
norm(H)

These commands return the result:

ans =
1.2438

To compute the H infinity norm, enter:

1-464

norm

[ninf,fpeak] = norm(H,inf)

This command returns the result:

ninf =
2.5488
fpeak =
3.0844

You can use a Bode plot of H(z) to confirm these values.

bode(H)
grid on;

1-465

norm

The gain indeed peaks at approximately 3 rad/sec. To find the peak

gain in dB, enter:
20*log10(ninf)

This command produces the following result:

ans =
8.1268

1-466

norm

Algorithms

norm first converts sys to a state space model.

norm uses the same algorithm as covar for the H2 norm. For the H
norm, norm uses the algorithm of [1]. norm computes the H norm

(peak gain) using the SLICOT library. For more information about the
SLICOT library, see http://slicot.org.

References

[1] Bruisma, N.A. and M. Steinbuch, "A Fast Algorithm to Compute the
H-Norm of a Transfer Function Matrix," System Control Letters, 14
(1990), pp. 287-293.

See Also

freqresp | sigma

1-467

nyquist

Purpose

Nyquist plot of frequency response

Syntax

nyquist(sys)
nyquist(sys,w)
nyquist(sys1,sys2,...,sysN)
nyquist(sys1,sys2,...,sysN,w)
nyquist(sys1,'PlotStyle1',...,sysN,'PlotStyleN')
[re,im,w] = nyquist(sys)
[re,im] = nyquist(sys,w)
[re,im,w,sdre,sdim] = nyquist(sys)

Description

nyquist creates a Nyquist plot of the frequency response of a dynamic

system model. When invoked without left-hand arguments, nyquist

produces a Nyquist plot on the screen. Nyquist plots are used to analyze
system properties including gain margin, phase margin, and stability.
nyquist(sys) creates a Nyquist plot of a dynamic system sys. This

model can be continuous or discrete, and SISO or MIMO. In the MIMO

case, nyquist produces an array of Nyquist plots, each plot showing the
response of one particular I/O channel. The frequency points are chosen
automatically based on the system poles and zeros.
nyquist(sys,w) explicitly specifies the frequency range or frequency
points to be used for the plot. To focus on a particular frequency
interval, set w = {wmin,wmax}. To use particular frequency points,
set w to the vector of desired frequencies. Use logspace to generate
logarithmically spaced frequency vectors. Frequencies must be in
rad/TimeUnit, where TimeUnit is the time units of the input dynamic
system, specified in the TimeUnit property of sys.
nyquist(sys1,sys2,...,sysN) or nyquist(sys1,sys2,...,sysN,w)

superimposes the Nyquist plots of several LTI models on a

single figure. All systems must have the same number of inputs
and outputs, but may otherwise be a mix of continuous- and
discrete-time systems. You can also specify a distinctive color,
linestyle, and/or marker for each system plot with the syntax
nyquist(sys1,'PlotStyle1',...,sysN,'PlotStyleN').

1-468

nyquist

[re,im,w] = nyquist(sys) and [re,im] = nyquist(sys,w)

return the real and imaginary parts of the frequency response at

the frequencies w (in rad/TimeUnit). re and im are 3-D arrays (see
"Arguments" below for details).
[re,im,w,sdre,sdim] = nyquist(sys) also returns the standard
deviations of re and im for the identified system sys.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Arguments

The output arguments re and im are 3-D arrays with dimensions

(number of outputs) (number of inputs) (length of w)

For SISO systems, the scalars re(1,1,k) and im(1,1,k) are the real
and imaginary parts of the response at the frequency k = w(k).

re(1, 1, k) = Re ( h( jk ) )

im(1, 1, k) = Im ( h( jwk ) )
For MIMO systems with transfer function H(s), re(:,:,k) and
im(:,:,k) give the real and imaginary parts of H(jk) (both arrays with
as many rows as outputs and as many columns as inputs). Thus,

re (i, j, k) = Re ( hij ( jk ) )

im (i, j, k) = Im ( hij ( jk ) )
where hij is the transfer function from input j to output i.

Examples

Example 1
Nyquist Plot of Dynamic System
Plot the Nyquist response of the system

1-469

nyquist

H (s) =

2s2 + 5s + 1
s2 + 2s + 3

H = tf([2 5 1],[1 2 3])

nyquist(H)

The nyquist function has support for M-circles, which are the contours
of the constant closed-loop magnitude. M-circles are defined as the
locus of complex numbers where

T ( j ) =

G( j )
1 + G( j )

is a constant value. In this equation, is the frequency in

radians/TimeUnit, where TimeUnit is the system time units, and G is

1-470

nyquist

the collection of complex numbers that satisfy the constant magnitude

requirement.
To activate the grid, select Grid from the right-click menu or type
grid

at the MATLAB prompt. This figure shows the M circles for transfer
function H.

You have two zoom options available from the right-click menu that
apply specifically to Nyquist plots:
Tight Clips unbounded branches of the Nyquist plot, but still
includes the critical point (-1, 0)
On (-1,0) Zooms around the critical point (-1,0)

1-471

nyquist

Also, click anywhere on the curve to activate data markers that display
the real and imaginary values at a given frequency. This figure shows
the nyquist plot with a data marker.

Example 2
Compute the standard deviation of the real and imaginary parts of
frequency response of an identified model. Use this data to create a 3
plot of the response uncertainty.
Identify a transfer function model based on data. Obtain the standard
deviation data for the real and imaginary parts of the frequency
response.
load iddata2 z2;
sys_p = tfest(z2,2);
w = linspace(-10*pi,10*pi,512);
[re, im, ~, sdre, sdim] = nyquist(sys_p,w);

1-472

nyquist

sys_p is an identified transfer function model. sdre and sdim contain

1-std standard deviation uncertainty values in re and im respectively.

Create a Nyquist plot showing the response and its 3 uncertainty:

re = squeeze(re);
im = squeeze(im);
sdre = squeeze(sdre);
sdim = squeeze(sdim);
plot(re,im,'b', re+3*sdre, im+3*sdim, 'k:', re-3*sdre, im-3*sdim, 'k:')

Algorithms

See bode.

See Also

bode | evalfr | freqresp | ltiview | nichols | sigma

1-473

nyquistoptions

Purpose

List of Nyquist plot options

Syntax

P = nyquistoptions
P = nyquistoptions('cstprefs')

Description

P = nyquistoptions returns the default options for Nyquist plots. You

can use these options to customize the Nyquist plot appearance using
the command line.
P = nyquistoptions('cstprefs') initializes the plot options with the

options you selected in the Control System Toolbox Preferences Editor.

For more information about the editor, see Toolbox Preferences Editor
in the Users Guide documentation.
The following table summarizes the Nyquist plot options.

1-474

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid

Show or hide the grid

Specified as one of the following strings: 'off' | 'on'
Default: 'off'

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

IOGrouping

Grouping of input-output pairs

Specified as one of the following strings: 'none'
|'inputs'|'output'|'all'
Default: 'none'

InputLabels,
OutputLabels

Input and output label styles

InputVisible,
OutputVisible

Visibility of input and output channels

nyquistoptions

Option

Description

FreqUnits

Frequency units, specified as one of the following strings:

'Hz'
'rad/second'
'rpm'
'kHz'
'MHz'
'GHz'
'rad/nanosecond'
'rad/microsecond'
'rad/millisecond'
'rad/minute'
'rad/hour'
'rad/day'
'rad/week'
'rad/month'
'rad/year'
'cycles/nanosecond'
'cycles/microsecond'
'cycles/millisecond'
'cycles/hour'
'cycles/day'
'cycles/week'
'cycles/month'

1-475

nyquistoptions

Option

Description
'cycles/year'
Default: 'rad/s'
You can also specify 'auto' which uses frequency units
rad/TimeUnit relative to system time units specified in the
TimeUnit property. For multiple systems with different time
units, the units of the first system are used.

MagUnits

Magnitude units
Specified as one of the following strings: 'dB' | 'abs'
Default: 'dB'

PhaseUnits

Phase units
Specified as one of the following strings: 'deg' | 'rad'
Default: 'deg'

ShowFullContour

Show response for negative frequencies

Specified as one of the following strings: 'on' | 'off'
Default: 'on'

ConfidenceRegionNumberSD
Number of standard deviations to use to plotting the response
confidence region (identified models only).
Default: 1.
ConfidenceRegionDisplaySpacing
The frequency spacing of confidence ellipses. For identified models
only.
Default: 5, which means the confidence ellipses are shown at
every 5th frequency sample.

Examples

This example shows how to create a Nyquist plot displaying the full
contour (the response for both positive and negative frequencies).
P = nyquistoptions;
P.ShowFullContour = 'on';
h = nyquistplot(tf(1,[1,.2,1]),P);

See Also

1-476

nyquist | nyquistplot | getoptions | setoptions

nyquistplot

Purpose

Nyquist plot with additional plot customization options

Syntax

h = nyquistplot(sys)
nyquistplot(sys,{wmin,wmax})
nyquistplot(sys,w)
nyquistplot(sys1,sys2,...,w)
nyquistplot(AX,...)
nyquistplot(..., plotoptions)

Description

h = nyquistplot(sys) draws the Nyquist plot of the dynamic system

model sys. It also returns the plot handle h. You can use this handle to
customize the plot with the getoptions and setoptions commands.
Type
help nyquistoptions

for a list of available plot options.

The frequency range and number of points are chosen automatically.
See bode for details on the notion of frequency in discrete time.
nyquistplot(sys,{wmin,wmax}) draws the Nyquist plot for frequencies
between wmin and wmax (in rad/TimeUnit, where TimeUnit is the time

units of the input dynamic system, specified in the TimeUnit property

of sys).
nyquistplot(sys,w) uses the user-supplied vector w of frequencies
(in rad/TimeUnit, where TimeUnit is the time units of the input
dynamic system, specified in the TimeUnit property of sys) at which
the Nyquist response is to be evaluated. See logspace to generate
logarithmically spaced frequency vectors.
nyquistplot(sys1,sys2,...,w) draws the Nyquist plots of multiple
models sys1,sys2,... on a single plot. The frequency vector w is optional.
You can also specify a color, line style, and marker for each system, as in
nyquistplot(sys1,'r',sys2,'y--',sys3,'gx')
nyquistplot(AX,...) plots into the axes with handle AX.

1-477

nyquistplot

nyquistplot(..., plotoptions) plots the Nyquist response with the

options specified in plotoptions. Type
help nyquistoptions

for more details.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Customize Nyquist Plot Frequency Units
Plot the Nyquist frequency response and change the units to rad/s.
sys = rss(5);
h = nyquistplot(sys);
% Change units to radians per second.
setoptions(h,'FreqUnits','rad/s');

Example 2
Compare the frequency responses of identified state-space models of
order 2 and 6 along with their 1-std confidence regions rendered at
every 50th frequency sample.
load iddata1
sys1 = n4sid(z1, 2) % discrete-time IDSS model of order 2
sys2 = n4sid(z1, 6) % discrete-time IDSS model of order 6

Both models produce about 76% fit to data. However, sys2 shows
higher uncertainty in its frequency response, especially close to Nyquist
frequency as shown by the plot:
w = linspace(10,10*pi,256);
h = nyquistplot(sys1,sys2,w);
setoptions(h,'ConfidenceRegionDisplaySpacing',50,'ShowFullContour','off');

1-478

nyquistplot

Right-click to turn on the confidence region characteristic by using the

Characteristics-> Confidence Region.

See Also

getoptions | nyquist | setoptions

1-479

obsv

Purpose

Observability matrix

Syntax

obsv(A,C)
Ob = obsv(sys)

Description

obsv computes the observability matrix for state-space systems. For

an n-by-n matrix A and a p-by-n matrix C, obsv(A,C) returns the
observability matrix

C
CA

Ob = CA

:
n1
CA

with n columns and np rows.

Ob = obsv(sys) calculates the observability matrix of the state-space
model sys. This syntax is equivalent to executing
Ob = obsv(sys.A,sys.C)

The model is observable if Ob has full rank n.

Examples

Determine if the pair

A =
1
4

1
-2

1
0

0
1

C =

is observable. Type

1-480

obsv

Ob = obsv(A,C);
% Number of unobservable states
unob = length(A)-rank(Ob)

These commands produce the following result.

unob =
0

Tips

obsv is here for educational purposes and is not recommended for

See Also

obsvf

serious control design. Computing the rank of the observability

matrix is not recommended for observability testing. Ob will
be numerically singular for most systems with more
than a handful of states. This fact is well documented in
the control literature. For example, see section III in
http://lawww.epfl.ch/webdav/site/la/users/105941/public/NumCompCtrl.pdf

1-481

obsvf

Purpose

Compute observability staircase form

Syntax

[Abar,Bbar,Cbar,T,k] = obsvf(A,B,C)
obsvf(A,B,C,tol)

Description

If the observability matrix of (A,C) has rank r n, where n is the size of

A, then there exists a similarity transformation such that

A = TAT T , B = TB, C = CT T
where T is unitary and the transformed system has a staircase form
with the unobservable modes, if any, in the upper left corner.

A12
B
, B = no , C = [0 Co ]
Ao
Bo

A
A = no
0

where (Co, Ao) is observable, and the eigenvalues of Ano are the
unobservable modes.
[Abar,Bbar,Cbar,T,k] = obsvf(A,B,C) decomposes the state-space
system with matrices A, B, and C into the observability staircase
form Abar, Bbar, and Cbar, as described above. T is the similarity
transformation matrix and k is a vector of length n, where n is the
number of states in A. Each entry of k represents the number of

observable states factored out during each step of the transformation

matrix calculation [1]. The number of nonzero elements in k indicates
how many iterations were necessary to calculate T, and sum(k) is the
number of states in Ao, the observable portion of Abar.
obsvf(A,B,C,tol) uses the tolerance tol when calculating the
observable/unobservable subspaces. When the tolerance is not specified,
it defaults to 10*n*norm(a,1)*eps.

Examples

Form the observability staircase form of

A =
1

1-482

obsvf

-2

1
1

-1
-1

1
0

0
1

B =

C =

by typing
[Abar,Bbar,Cbar,T,k] = obsvf(A,B,C)
Abar =
1
1
4
-2
Bbar =
1
1
1
-1
Cbar =
1
0
0
1
T =
1
0
0
1
k =
2
0

Algorithms

obsvf implements the Staircase Algorithm of [1] by calling ctrbf and

using duality.

References

[1] Rosenbrock, M.M., State-Space and Multivariable Theory, John

Wiley, 1970.

See Also

ctrbf | obsv

1-483

ord2

Purpose

Generate continuous second-order systems

Syntax

[A,B,C,D] = ord2(wn,z)
[num,den] = ord2(wn,z)

Description

[A,B,C,D] = ord2(wn,z) generates the state-space description

(A,B,C,D) of the second-order system

h(s) =

1
2

s + 2n s + n2

given the natural frequency wn (n) and damping factor z (). Use ss to
turn this description into a state-space object.
[num,den] = ord2(wn,z) returns the numerator and denominator of
the second-order transfer function. Use tf to form the corresponding
transfer function object.

Examples

To generate an LTI model of the second-order transfer function with

damping factor = 0.4 and natural frequency n = 2.4 rad/sec., type
[num,den] = ord2(2.4,0.4)
num =
1
den =
1.0000
1.9200
5.7600
sys = tf(num,den)
Transfer function:
1
------------------s^2 + 1.92 s + 5.76

See Also

1-484

rss | ss | tf

order

Purpose

Query model order

Syntax

NS = order(sys)

Description

NS = order(sys) returns the model order NS. The order of a dynamic

system model is the number of poles (for proper transfer functions) or

the number of states (for state-space models). For improper transfer
functions, the order is defined as the minimum number of states
needed to build an equivalent state-space model (ignoring pole/zero
cancellations).
order(sys) is an overloaded method that accepts SS, TF, and ZPK
models. For LTI arrays, NS is an array of the same size listing the
orders of each model in sys.

Caveat

order does not attempt to find minimal realizations of MIMO systems.

For example, consider this 2-by-2 MIMO system:

s=tf('s');
h = [1, 1/(s*(s+1)); 1/(s+2), 1/(s*(s+1)*(s+2))];
order(h)
ans =
6

Although h has a 3rd order realization, order returns 6. Use

order(ss(h,'min'))

to find the minimal realization order.

See Also

pole | balred

1-485

pade

Purpose

Pad approximation of model with time delays

Syntax

[num,den] = pade(T,N)
sysx = pade(sys,N)
sysx = pade(sys,NU,NY,NINT)

Description

pade approximates time delays by rational models. Such approximations

are useful to model time delay effects such as transport and computation
delays within the context of continuous-time systems. The Laplace
transform of a time delay of T seconds is exp(sT). This exponential
transfer function is approximated by a rational transfer function using
Pad approximation formulas [1].
[num,den] = pade(T,N) returns the Pad approximation of order N

of the continuous-time I/O delay exp(sT) in transfer function form.

The row vectors num and den contain the numerator and denominator
coefficients in descending powers of s. Both are Nth-order polynomials.
When invoked without output arguments,
pade(T,N)

plots the step and phase responses of the Nth-order Pad approximation
and compares them with the exact responses of the model with I/O delay
T. Note that the Pad approximation has unit gain at all frequencies.
sysx = pade(sys,N) produces a delay-free approximation sysx of
the continuous delay system sys. All delays are replaced by their
Nth-order Pad approximation. See Models with Time Delays for more

information about models with time delays.

sysx = pade(sys,NU,NY,NINT) specifies independent approximation
orders for each input, output, and I/O or internal delay. Here NU, NY,
and NINT are integer arrays such that

NU is the vector of approximation orders for the input channel

NY is the vector of approximation orders for the output channel

1-486

pade

NINT is the approximation order for I/O delays (TF or ZPK models) or
internal delays (state-space models)
You can use scalar values for NU, NY, or NINT to specify a uniform
approximation order. You can also set some entries of NU, NY, or NINT to
Inf to prevent approximation of the corresponding delays.

Examples

Third-Order Pad Approximation

Compute a third-order Pad approximation of a 0.1 second I/O delay
and compare the time and frequency responses of the true delay and its
approximation. To do this, type
pade(0.1,3)

1-487

pade

Limitations

High-order Pad approximations produce transfer functions with

clustered poles. Because such pole configurations tend to be very
sensitive to perturbations, Pad approximations with order N>10 should
be avoided.

References

[1] Golub, G. H. and C. F. Van Loan, Matrix Computations, Johns

Hopkins University Press, Baltimore, 1989, pp. 557-558.

See Also

c2d | absorbDelay | thiran

1-488

pade

How To

Time-Delay Approximation

1-489

parallel

Purpose

Parallel connection of two models

Syntax

parallel
sys = parallel(sys1,sys2)
sys = parallel(sys1,sys2,inp1,inp2,out1,out2)
sys = parallel(sys1,sys2,'name')

Description

parallel connects two model objects in parallel. This function accepts

any type of model. The two systems must be either both continuous or
both discrete with identical sample time. Static gains are neutral and
can be specified as regular matrices.
sys = parallel(sys1,sys2) forms the basic parallel connection

shown in the following figure.

This command equals the direct addition

sys = sys1 + sys2
sys = parallel(sys1,sys2,inp1,inp2,out1,out2) forms the more
general parallel connection shown in the following figure.

1-490

parallel

The vectors inp1 and inp2 contain indexes into the input channels of
sys1 and sys2, respectively, and define the input channels u1 and u2
in the diagram. Similarly, the vectors out1 and out2 contain indexes
into the outputs of these two systems and define the output channels
y1 and y2 in the diagram. The resulting model sys has [v1 ; u ; v2] as
inputs and [z1 ; y ; z2] as outputs.
sys = parallel(sys1,sys2,'name') connects sys1 and sys2 by
matching I/O names. You must specify all I/O names of sys1 and sys2.
The matching names appear in sys in the same order as in sys1. For
example, the following specification:
sys1 = ss(eye(3),'InputName',{'C','B','A'},'OutputName',{'Z','Y','X'});
sys2 = ss(eye(3),'InputName',{'A','C','B'},'OutputName',{'X','Y','Z'});
parallel(sys1,sys2,'name')

returns this result:

d =
Z
Y
X

C
1
1
0

B
1
1
0

A
0
0
2

1-491

parallel

Static gain.

Note If sys1 and sys2 are model arrays, parallel

returns model array sys of the same size, where
sys(:,:,k)=parallel(sys1(:,:,k),sys2(:,:,k),inp1,...).

Examples

See Kalman Filtering for an example.

See Also

append | feedback | series

1-492

permute

Purpose

Permute array dimensions in model arrays

Syntax

newarray = permute(sysarray,order)

Description

newarray = permute(sysarray,order) rearranges the array

dimensions of a model array so that the dimensions are in the specified
order. The input and output dimensions of the model array are not
counted as array dimensions for this operation.

Input
Arguments

sysarray - Model array to rearrange

model array

Model array to rearrange, specified as an array of input-output models

such as numeric LTI models, generalized models, or identified LTI
models.
order - Dimensions of rearranged model array

vector

Dimensions of rearranged model array, specified as a vector of positive

integers. For example, to rearrange a model array into a 3-by-2 array,
order is [3 2].
Data Types
double

Output
Arguments

newarray - Rearranged model array

model array

Rearranged model array, returned as an array of input-output models

with the new dimensions as specified in order.

Examples

Permute Model Array Dimensions

Create a 1-by-2-by-3 array of state-space models and rearrange it so
that its dimensions are 3-by-2-by-1.
sysarr = rss(2,2,2,1,2,3);
newarr = permute(sysarr,[3 2 1]);

1-493

permute

size(newarr)
3x2 array of state-space models.
Each model has 2 outputs, 2 inputs, and 2 states.

The input and output dimensions of the model array remain unchanged.

See Also

1-494

ndims | size | reshape

pid

Purpose

Create PID controller in parallel form, convert to parallel-form PID

controller

Syntax

C
C
C
C
C
C
C
C

Description

C = pid(Kp,Ki,Kd,Tf) creates a continuous-time PID controller

with proportional, integral, and derivative gains Kp, Ki, and Kd and
first-order derivative filter time constant Tf:

=
=
=
=
=
=
=
=

pid(Kp,Ki,Kd,Tf)
pid(Kp,Ki,Kd,Tf,Ts)
pid(sys)
pid(Kp)
pid(Kp,Ki)
pid(Kp,Ki,Kd)
pid(...,Name,Value)
pid

C = Kp +

Ki
Kds
+
.
s Tf s + 1

This representation is in parallel form. If all of Kp, Ki, Kd, and Tf are
real, then the resulting C is a pid controller object. If one or more
of these coefficients is tunable (realp or genmat), then C is a tunable
generalized state-space (genss) model object.
C = pid(Kp,Ki,Kd,Tf,Ts) creates a discrete-time PID controller with

sampling time Ts. The controller is:

C = K p + K i IF ( z ) +

Kd
.
Tf + DF ( z )

IF(z) and DF(z) are the discrete integrator formulas for the integrator
and derivative filter. By default, IF(z) = DF(z) = Tsz/(z 1). To choose
different discrete integrator formulas, use the IFormula and DFormula
properties. (See Properties on page 1-500 for more information about
IFormula and DFormula). If DFormula = 'ForwardEuler' (the default
value) and Tf 0, then Ts and Tf must satisfy Tf > Ts/2. This
requirement ensures a stable derivative filter pole.

1-495

pid

C = pid(sys) converts the dynamic system sys to a parallel form pid

controller object.
C = pid(Kp) creates a continuous-time proportional (P) controller with
Ki = 0, Kd = 0, and Tf = 0.
C = pid(Kp,Ki) creates a proportional and integral (PI) controller with

Kd = 0 and Tf = 0.
C = pid(Kp,Ki,Kd) creates a proportional, integral, and derivative
(PID) controller with Tf = 0.
C = pid(...,Name,Value) creates a controller or converts a dynamic
system to a pid controller object with additional options specified by one
or more Name,Value pair arguments.
C = pid creates a P controller with Kp = 1.

Tips

Use pid either to create a pid controller object from known PID
gains and filter time constant, or to convert a dynamic system model
to a pid object.
To deisgn a PID controller for a particular plant, use pidtune or
pidtool.
Create arrays of pid controller objects by:

Specifying array values for Kp,Ki,Kd, and Tf

Using stack to build arrays from individual controllers or smaller

arrays

Specifying an array of dynamic systems sys to convert to pid

controller objects

In an array of pid controllers, each controller must have the same

sampling time Ts and discrete integrator formulas IFormula and
DFormula.
To create or convert to a standard-form controller, use pidstd.
Standard form expresses the controller actions in terms of an overall
proportional gain Kp, integral and derivative times Ti and Td, and
filter divisor N:

1-496

pid

Td s
1 1
C = K p 1 +
+
.
Ti s Td

s + 1
N

There are two ways to discretize a continuous-time pid controller:

Use the c2d command. c2d computes new parameter values for
the discretized controller. The discrete integrator formulas of the
discretized controller depend upon the c2d discretization method
you use, as shown in the following table.
c2d Discretization

IFormula

DFormula

'zoh'

ForwardEuler

ForwardEuler

'foh'

Trapezoidal

Trapezoidal

'tustin'

Trapezoidal

Trapezoidal

'impulse'

ForwardEuler

ForwardEuler

'matched'

ForwardEuler

ForwardEuler

Method

For more information about c2d discretization methods, See the

c2d reference page. For more information about IFormula and
DFormula, see Properties on page 1-500 .

Input
Arguments

If you require different discrete integrator formulas, you can

discretize the controller by directly setting Ts, IFormula, and
DFormula to the desired values. (See this example.) However, this
method does not compute new gain and filter-constant values for
the discretized controller. Therefore, this method might yield
a poorer match between the continuous- and discrete-time pid
controllers than using c2d.

Kp

Proportional gain.
Kp can be:

1-497

pid

A real and finite value.

An array of real and finite values.
A tunable parameter (realp).
A tunable generalized matrix (genmat), such as a gain surface for
gain-scheduled tuning, created using gainsurf (requires Robust
Control Toolbox software).
When Kp = 0, the controller has no proportional action.
Default: 1
Ki

Integral gain.
Ki can be:
A real and finite value.
An array of real and finite values.
A tunable parameter (realp).
A tunable generalized matrix (genmat), such as a gain surface for
gain-scheduled tuning, created using gainsurf (requires Robust
Control Toolbox software).
When Ki = 0, the controller has no integral action.
Default: 0
Kd

Derivative gain.
Kd can be:
A real and finite value.
An array of real and finite values.
A tunable parameter (realp).

1-498

pid

A tunable generalized matrix (genmat), such as a gain surface for

gain-scheduled tuning, created using gainsurf (requires Robust
Control Toolbox software).
When Kd = 0, the controller has no derivative action.
Default: 0
Tf

Time constant of the first-order derivative filter.

Tf can be:
A real, finite, and nonnegative value.
An array of real, finite, and nonnegative values.
A tunable parameter (realp).
A tunable generalized matrix (genmat), such as a gain surface for
gain-scheduled tuning, created using gainsurf (requires Robust
Control Toolbox software).
When Tf = 0, the controller has no filter on the derivative action.
Default: 0
Ts

Sampling time.
To create a discrete-time pid controller, provide a positive real
value (Ts > 0). pid does not support discrete-time controller with
undetermined sample time (Ts = -1).
Ts must be a scalar value. In an array of pid controllers, each controller
must have the same Ts.
sys

SISO dynamic system to convert to parallel pid form.

1-499

pid

sys must represent a valid PID controller that can be written in

parallel form with Tf 0.
sys can also be an array of SISO dynamic systems.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments.
Name is the argument name and Value is the corresponding
value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
Use Name,Value syntax to set the numerical integration formulas
IFormula and DFormula of a discrete-time pid controller, or to set other
object properties such as InputName and OutputName. For information
about available properties of pid controller objects, see Properties
on page 1-500.

Output
Arguments

PID controller, represented as a pid controller object, an array of pid

controller objects, a genss object, or a genss array.
If all the gains Kp, Ki, Kd, and Tf have numeric values, then C is a
pid controller object. When the gains are numeric arrays, C is an
array of pid controller objects. The controller type (P, I, PI, PD, PDF,
PID, PIDF) depends upon the values of the gains. For example, when
Kd = 0, but Kp and Ki are nonzero, C is a PI controller.
If one or more gains is a tunable parameter (realp) or generalized
matrix (genmat), then C is a generalized state-space model (genss).

Properties

pid controller objects have the following properties:

Kp, Ki, Kd

PID controller gains.

The Kp, Ki, and Kd properties store the proportional, integral, and
derivative gains, respectively. Kp, Ki, and Kd values are real and finite.

1-500

pid

Tf

Derivative filter time constant.

The Tf property stores the derivative filter time constant of the pid
controller object. Tf are real, finite, and greater than or equal to zero.
IFormula

Discrete integrator formula IF(z) for the integrator of the discrete-time

pid controller C:

C = K p + K i IF ( z ) +

Kd
.
Tf + DF ( z )

IFormula can take the following values:

Ts
.
z 1
This formula is best for small sampling time, where the Nyquist limit
is large compared to the bandwidth of the controller. For larger
sampling time, the ForwardEuler formula can result in instability,
even when discretizing a system that is stable in continuous time.

'ForwardEuler' IF(z) =

'BackwardEuler' IF(z) =

Ts z
.
z 1

An advantage of the BackwardEuler formula is that discretizing a

stable continuous-time system using this formula always yields a
stable discrete-time result.

Ts z + 1
.
2 z 1
An advantage of the Trapezoidal formula is that discretizing a
stable continuous-time system using this formula always yields a
stable discrete-time result. Of all available integration formulas,
the Trapezoidal formula yields the closest match between

'Trapezoidal' IF(z) =

1-501

pid

frequency-domain properties of the discretized system and the

corresponding continuous-time system.
When C is a continuous-time controller, IFormula is ''.
Default: 'ForwardEuler'
DFormula

Discrete integrator formula DF(z) for the derivative filter of the

discrete-time pid controller C:

C = K p + K i IF ( z ) +

Kd
.
Tf + DF ( z )

DFormula can take the following values:

Ts
.
z 1
This formula is best for small sampling time, where the Nyquist limit
is large compared to the bandwidth of the controller. For larger
sampling time, the ForwardEuler formula can result in instability,
even when discretizing a system that is stable in continuous time.

'ForwardEuler' DF(z) =

'BackwardEuler' DF(z) =

Ts z
.
z 1

An advantage of the BackwardEuler formula is that discretizing a

stable continuous-time system using this formula always yields a
stable discrete-time result.

Ts z + 1
.
2 z 1
An advantage of the Trapezoidal formula is that discretizing a
stable continuous-time system using this formula always yields a
stable discrete-time result. Of all available integration formulas,
the Trapezoidal formula yields the closest match between

'Trapezoidal' DF(z) =

1-502

pid

frequency-domain properties of the discretized system and the

corresponding continuous-time system.
The Trapezoidal value for DFormula is not available for a pid
controller with no derivative filter (Tf = 0).
When C is a continuous-time controller, DFormula is ''.
Default: 'ForwardEuler'
InputDelay

Time delay on the system input. InputDelay is always 0 for a pid

controller object.
OutputDelay

Time delay on the system Output. OutputDelay is always 0 for a pid

controller object.
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For

1-503

pid

discrete-time models, it represents the sampling time Ts. Use any of

the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.

1-504

pid

Input channel names have several uses, including:

Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

1-505

pid

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field

1-506

pid

names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with

1-507

pid

each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25

1-508

pid

---------------s^2 + 3.5 s + 25
...

Default: []

Examples

PID Controller with Proportional and Derivative Gains, and

Filter Time Constant (PDF Controller)
Create a continuous-time controller with proportional and derivative
gains, and filter time constant (PDF controller).
Kp=1;
Ki=0;
Kd=3;
Tf=0.5;
C = pid(Kp,Ki,Kd,Tf)

C =
s
Kp + Kd * -------Tf*s+1
with Kp = 1, Kd = 3, Tf = 0.5
Continuous-time PDF controller in parallel form.

The display hows the controller type, formula, and parameter values.
Discrete-Time PI Controller
Create a discrete-time PI controller with trapezoidal discretization
formula.

1-509

pid

To create a discrete-time controller, set the value of Ts using

Name,Value syntax.
C = pid(5,2.4,'Ts',0.1,'IFormula','Trapezoidal') % Ts = 0.1s

This command produces the result:

Discrete-time PI controller in parallel form:
Ts*(z+1)
Kp + Ki * -------2*(z-1)
with Kp = 5, Ki = 2.4, Ts = 0.1

Alternatively, you can create the same discrete-time controller by

supplying Ts as the fifth argument after all four PID parameters Kp,
Ki, Kd, and Tf.
C = pid(5,2.4,0,0,0.1,'IFormula','Trapezoidal');

PID Controller with Custom Input and Output Names

Create a PID controller, and set dynamic system properties InputName
and OutputName.
C = pid(1,2,3,'InputName','e','OutputName','u');

Array of PID Controllers

Create a 2-by-3 grid of PI controllers with proportional gain ranging
from 12 and integral gain ranging from 59.
Create a grid of PI controllers with proportional gain varying row to
row and integral gain varying column to column. To do so, start with
arrays representing the gains.

1-510

pid

Kp = [1 1 1;2 2 2];
Ki = [5:2:9;5:2:9];
pi_array = pid(Kp,Ki,'Ts',0.1,'IFormula','BackwardEuler');

These commands produce a 2-by-3 array of discrete-time pid objects.

All pid objects in an array must have the same sample time, discrete
integrator formulas, and dynamic system properties (such as InputName
and OutputName).
Alternatively, you can use stack to build arrays of pid objects.
C = pid(1,5,0.1)
% PID controller
Cf = pid(1,5,0.1,0.5)
% PID controller with filter
pid_array = stack(2,C,Cf); % stack along 2nd array dimension

These commands produce a 1-by-2 array of controllers. Enter the

command:
size(pid_array)

to see the result

1x2 array of PID controller.
Each PID has 1 output and 1 input.

Convert PID Controller from Standard to Parallel Form

Convert a standard form pidstd controller to parallel form.
Standard PID form expresses the controller actions in terms of an
overall proportional gain Kp, integral and derivative times Ti and Td,
and filter divisor N. You can convert any standard form controller to
parallel form using pid.
stdsys = pidstd(2,3,4,5);
parsys = pid(stdsys)

% Standard-form controller

These commands produce a parallel-form controller:

1-511

pid

Continuous-time PIDF controller in parallel form:

1
s
Kp + Ki * --- + Kd * -------s
Tf*s+1
with Kp = 2, Ki = 0.66667, Kd = 8, Tf = 0.8

Convert Dynamic System to Parallel-Form PID Controller

Convert a continuous-time dynamic system that represents a PID
controller to parallel pid form.
The dynamic system

H ( s) =

3 ( s + 1) ( s + 2 )
s

represents a PID controller. Use pid to obtain H(s) to in terms of the

PID gains Kp, Ki, and Kd.
H = zpk([-1,-2],0,3);
C = pid(H)

These commands produce the result:

Continuous-time PID controller in parallel form:
1
Kp + Ki * --- + Kd * s
s
with Kp = 9, Ki = 6, Kd = 3

Convert Discrete-Time Zero-Pole-Gain Model to Parallel-Form

PID Controller

1-512

pid

Convert a discrete-time dynamic system that represents a PID

controller with derivative filter to parallel pid form.
% PIDF controller expressed in zpk form
sys = zpk([-0.5,-0.6],[1 -0.2],3,'Ts',0.1)

The resulting pid object depends upon the discrete integrator formula
you specify for IFormula and DFormula. For example, if you use the
default ForwardEuler for both formulas:
C = pid(sys)

returns the result

Discrete-time PIDF controller in parallel form:
Ts
1
Kp + Ki * ------ + Kd * ----------z-1
Tf+Ts/(z-1)
with Kp = 2.75, Ki = 60, Kd = 0.020833, Tf = 0.083333, Ts = 0.1

Converting using the Trapezoidal formula returns different parameter

values:
C = pid(sys,'IFormula','Trapezoidal','DFormula','Trapezoidal')

This command returns the result:

Discrete-time PIDF controller in parallel form:
Ts*(z+1)
1
Kp + Ki * -------- + Kd * ------------------2*(z-1)
Tf+Ts/2*(z+1)/(z-1)
with Kp = -0.25, Ki = 60, Kd = 0.020833, Tf = 0.033333, Ts = 0.1

1-513

pid

For this particular sys, you cannot write sys in parallel PID form using
the BackwardEuler formula for DFormula. Doing so would result in
Tf < 0, which is not permitted. In that case, pid returns an error.
Discretize a Continuous-time PID Controller
First, discretize the controller using the 'zoh' method of c2d.
Cc = pid(1,2,3,4) % continuous-time pidf controller
Cd1 = c2d(Cc,0.1,'zoh')
c2d computes new parameters for the discrete-time controller:
Discrete-time PIDF controller in parallel form:
Ts
1
Kp + Ki * ------ + Kd * ----------z-1
Tf+Ts/(z-1)
with Kp = 1, Ki = 2, Kd = 3.0377, Tf = 4.0502, Ts = 0.1

The resulting discrete-time controller uses ForwardEuler (Ts/(z1))

for both IFormula and DFormula.
The discrete integrator formulas of the discretized controller depend
upon the c2d discretization method, as described in Tips on page
1-496. To use a different IFormula and DFormula, directly set Ts,
IFormula, and DFormula to the desired values:
Cd2 = Cc;
Cd2.Ts = 0.1;
Cd2.IFormula = 'BackwardEuler';
Cd2.DFormula = 'BackwardEuler';

These commands do not compute new parameter values for the

discretized controller. To see this, enter:
Cd2

1-514

pid

to obtain the result:

Discrete-time PIDF controller in parallel form:
Ts*z
1
Kp + Ki * ------ + Kd * ------------z-1
Tf+Ts*z/(z-1)
with Kp = 1, Ki = 2, Kd = 3, Tf = 4, Ts = 0.1

See Also

pidstd | piddata | pidtune | pidtool | ltiblock.pid | genss |

realp

Tutorials

Proportional-Integral-Derivative (PID) Controller

Discrete-Time Proportional-Integral-Derivative (PID) Controller

How To

What Are Model Objects?

PID Controllers

1-515

piddata

Purpose

Access PID data

Syntax

[Kp,Ki,Kd,Tf] = piddata(sys)
[Kp,Ki,Kd,Tf,Ts] = piddata(sys)
[Kp,Ki,Kd,Tf,Ts] = piddata(sys, J1,...,JN)

Description

[Kp,Ki,Kd,Tf] = piddata(sys) returns the PID gains Kp,Ki, Kd and

the filter time constant Tf of the parallel-form controller represented by
the dynamic system sys.
[Kp,Ki,Kd,Tf,Ts] = piddata(sys) also returns the sample time Ts.
[Kp,Ki,Kd,Tf,Ts] = piddata(sys, J1,...,JN) extracts the data for
a subset of entries in the array of sys dynamic systems. The indices J
specify the array entries to extract.

Tips

If sys is not a pid controller object, piddata returns the PID gains
Kp, Ki, Kd and the filter time constant Tf of a parallel-form controller
equivalent to sys.
For discrete-time sys, piddata returns the parameters of an equivalent
parallel-form controller. This controller has discrete integrator formulas
Iformula and Dformula set to ForwardEuler. See the pid reference
page for more information about discrete integrator formulas.

Input
Arguments

sys

SISO dynamic system or array of SISO dynamic systems. If sys is

not a pid object, it must represent a valid PID controller that can be
written in parallel PID form.
J

Integer indices of N entries in the array sys of dynamic systems.

Output
Arguments

1-516

Kp

Proportional gain of the parallel-form PID controller represented by

dynamic system sys.

piddata

If sys is a pid controller object, the output Kp is equal to the Kp value

of sys.
If sys is not a pid object, Kp is the proportional gain of a parallel PID
controller equivalent to sys.
If sys is an array of dynamic systems, Kp is an array of the same
dimensions as sys.
Ki

Integral gain of the parallel-form PID controller represented by dynamic

system sys.
If sys is a pid controller object, the output Ki is equal to the Ki value
of sys.
If sys is not a pid object, Ki is the integral gain of a parallel PID
controller equivalent to sys.
If sys is an array of dynamic systems, Ki is an array of the same
dimensions as sys.
Kd

Derivative gain of the parallel-form PID controller represented by

dynamic system sys.
If sys is a pid controller object, the output Kd is equal to the Kd value
of sys.
If sys is not a pid object, Kd is the derivative gain of a parallel PID
controller equivalent to sys.
If sys is an array of dynamic systems, Kd is an array of the same
dimensions as sys.
Tf

Filter time constant of the parallel-form PID controller represented by

dynamic system sys.

1-517

piddata

If sys is a pid controller object, the output Tf is equal to the Tf value

of sys.
If sys is not a pid object, Tf is the filter time constant of a parallel
PID controller equivalent to sys.
If sys is an array of dynamic systems, Tf is an array of the same
dimensions as sys.
Ts

Sampling time of the dynamic system sys. Ts is always a scalar value.

Examples

Extract the proportional, integral, and derivative gains and the filter
time constant from a parallel-form pid controller.
For the following pid object:
sys = pid(1,4,0.3,10);

you can extract the parameter values from sys by entering:

[Kp Ki Kd Tf] = piddata(sys);

Extract the parallel form proportional and integral gains from an

equivalent standard-form PI controller.
For a standard-form PI controller, such as:
sys = pidstd(2,3);

you can extract the gains of an equivalent parallel-form PI controller

by entering:
[Kp Ki] = piddata(sys)

These commands return the result:

Kp =

1-518

piddata

Ki =
0.6667

Extract parameters from a dynamic system that represents a PID

controller.
The dynamic system

H ( z) =

( z 0 .5 ) ( z 0 .6 )
( z 1 ) ( z + 0 .8 )

represents a discrete-time PID controller with a derivative filter. Use

piddata to extract the parallel-form PID parameters.
H = zpk([0.5 0.6],[1,-0.8],1,0.1);
[Kp Ki Kd Tf Ts] = piddata(H);

% sampling time Ts = 0.1s

the piddata function uses the default ForwardEuler discrete integrator

formula for Iformula and Dformula to compute the parameter values.
Extract the gains from an array of PI controllers.
sys = pid(rand(2,3),rand(2,3)); % 2-by-3 array of PI controllers
[Kp Ki Kd Tf] = piddata(sys);

The parameters Kp, Ki, Kd, and Tf are also 2-by-3 arrays.
Use the index input J to extract the parameters of a subset of sys.
[Kp Ki Kd Tf] = piddata(sys,5);

See Also

pid | pidstd | get

1-519

pidstd

Purpose

Create a PID controller in standard form, convert to standard-form

PID controller

Syntax

C
C
C
C
C
C
C
C

Description

C = pidstd(Kp,Ti,Td,N) creates a continuous-time PIDF (PID with

first-order derivative filter) controller object in standard form. The
controller has proportional gain Kp, integral and derivative times Ti
and Td, and first-order derivative filter divisor N:

=
=
=
=
=
=
=
=

pidstd(Kp,Ti,Td,N)
pidstd(Kp,Ti,Td,N,Ts)
pidstd(sys)
pidstd(Kp)
pidstd(Kp,Ti)
pidstd(Kp,Ti,Td)
pidstd(...,Name,Value)
pidstd

Td s
1 1
C = K p 1 +
+
.
Ti s Td

s + 1
N

C = pidstd(Kp,Ti,Td,N,Ts) creates a discrete-time controller with

sampling time Ts. The discrete-time controller is:

Td
1
C = K p 1 + IF ( z ) +
.
Td
Ti

+ DF ( z )
N

IF(z) and DF(z) are the discrete integrator formulas for the integrator
and derivative filter. By default, IF(z) = DF(z) = Tsz/(z 1). To choose
different discrete integrator formulas, use the IFormula and DFormula
inputs. (See Properties on page 1-525 for more information about
IFormula and DFormula). If DFormula = 'ForwardEuler' (the default

1-520

pidstd

value) and N Inf, then Ts, Td, and N must satisfy Td/N > Ts/2. This
requirement ensures a stable derivative filter pole.
C = pidstd(sys) converts the dynamic system sys to a standard form
pidstd controller object.
C = pidstd(Kp) creates a continuous-time proportional (P) controller
with Ti = Inf, Td = 0, and N = Inf.
C = pidstd(Kp,Ti) creates a proportional and integral (PI) controller
with Td = 0 and N = Inf.
C = pidstd(Kp,Ti,Td) creates a proportional, integral, and derivative
(PID) controller with N = Inf.
C = pidstd(...,Name,Value) creates a controller or converts a
dynamic system to a pidstd controller object with additional options

specified by one or more Name,Value pair arguments.

C = pidstd creates a P controller with Kp = 1.

Tips

Use pidstd either to create a pidstd controller object from known

PID gain, integral and derivative times, and filter divisor, or to
convert a dynamic system model to a pidstd object.
To tune a PID controller for a particular plant, use pidtune or
pidtool.
Create arrays of pidstd controllers by:

Specifying array values for Kp,Ti,Td, and N

Using stack to build arrays from individual controllers or smaller

arrays

Specifying an array of dynamic systems sys to convert to standard

PID form

In an array of pidstd controllers, each controller must have the

same sampling time Ts and discrete integrator formulas IFormula
and DFormula.

1-521

pidstd

To create or convert to a parallel-form controller, use pid. Parallel

form expresses the controller actions in terms of proportional,
integral, and derivative gains Kp, Ki and Kd, and a filter time constant
Tf:

C = Kp +

Ki
Kds
+
.
s Tf s + 1

There are two ways to discretize a continuous-time pidstd controller:

Use the c2d command. c2d computes new parameter values for
the discretized controller. The discrete integrator formulas of the
discretized controller depend upon the c2d discretization method
you use, as shown in the following table.
c2d Discretization

IFormula

DFormula

'zoh'

ForwardEuler

ForwardEuler

'foh'

Trapezoidal

Trapezoidal

'tustin'

Trapezoidal

Trapezoidal

'impulse'

ForwardEuler

ForwardEuler

'matched'

ForwardEuler

ForwardEuler

Method

For more information about c2d discretization methods, See the

c2d reference page. For more information about IFormula and
DFormula, see Properties on page 1-525 .

1-522

If you require different discrete integrator formulas, you can

discretize the controller by directly setting Ts, IFormula, and
DFormula to the desired values. (See this example.) However, this
method does not compute new gain and filter-constant values for
the discretized controller. Therefore, this method might yield a
poorer match between the continuous- and discrete-time pidstd
controllers than using c2d.

pidstd

Input
Arguments

Kp

Proportional gain.
Kp must be a real and finite value.
For an array of pidstd controllers, Kp must be an array of real and
finite values.
Default: 1
Ti

Integral time.
Ti must be a real and positive value. When Ti = Inf, the controller
has no integral action.
For an array of pidstd controllers, Ti must be an array of real and
positive values.
Default: Inf
Td

Derivative time.
Td must be a real, finite, and nonnegative value. When Td = 0, the
controller has no derivative action.
For an array of pidstd controllers, Td must be an array of real, finite,
and nonnegative values.
Default: 0
N

Time constant of the first-order derivative filter.

N must be a real and positive value. When N = Inf, the controller has
no derivative filter.

1-523

pidstd

For an array of pidstd controllers, N must be an array of real and

positive values.
Default: Inf
Ts

Sampling time.
To create a discrete-time pidstd controller, provide a positive real
value (Ts > 0).pidstd does not support discrete-time controller with
undetermined sample time (Ts = -1).
Ts must be a scalar value. In an array of pidstd controllers, each
controller must have the same Ts.
sys

SISO dynamic system to convert to standard pidstd form.

sys must represent a valid controller that can be written in standard
form with Ti > 0, Td 0, and N > 0.
sys can also be an array of SISO dynamic systems.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments.
Name is the argument name and Value is the corresponding
value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
Use Name,Value syntax to set the numerical integration formulas
IFormula and DFormula of a discrete-time pidstd controller, or to
set other object properties such as InputName and OutputName. For
information about available properties of pidstd controller objects, see
Properties on page 1-525.

1-524

pidstd

Output
Arguments

pidstd object representing a single-input, single-output PID controller

in standard form.
The controller type (P, PI, PD, PDF, PID, PIDF) depends upon the
values of Kp, Ti, Td, and N. For example, when Td = Inf and Kp and
Ti are finite and nonzero, C is a PI controller. Enter getType(C) to
obtain the controller type.
When the inputs Kp,Ti, Td, and N or the input sys are arrays, C is an
array of pidstd objects.

Properties

pidstd controller objects have the following properties:

Kp

Proportional gain. Kp must be real and finite.

Ti

Integral time. Ti must be real, finite, and greater than or equal to zero.
Td

Derivative time. Td must be real, finite, and greater than or equal to

zero.
N

Derivative time. N must be real, and greater than or equal to zero.

IFormula

Discrete integrator formula IF(z) for the integrator of the discrete-time

pidstd controller C:

1-525

pidstd

Td
1
C = K p 1 + IF ( z ) +
.
T
Ti
d + DF z

( )
N

IFormula can take the following values:

Ts
.
z 1
This formula is best for small sampling time, where the Nyquist limit
is large compared to the bandwidth of the controller. For larger
sampling time, the ForwardEuler formula can result in instability,
even when discretizing a system that is stable in continuous time.

'ForwardEuler' IF(z) =

'BackwardEuler' IF(z) =

Ts z
.
z 1

An advantage of the BackwardEuler formula is that discretizing a

stable continuous-time system using this formula always yields a
stable discrete-time result.

Ts z + 1
.
2 z 1
An advantage of the Trapezoidal formula is that discretizing a
stable continuous-time system using this formula always yields a
stable discrete-time result. Of all available integration formulas,
the Trapezoidal formula yields the closest match between
frequency-domain properties of the discretized system and the
corresponding continuous-time system.

'Trapezoidal' IF(z) =

When C is a continuous-time controller, IFormula is ''.

Default: 'ForwardEuler'
DFormula

1-526

pidstd

Discrete integrator formula DF(z) for the derivative filter of the

discrete-time pidstd controller C:

Td
1
C = K p 1 + IF ( z ) +
.
T
Ti
d + DF z

( )
N

DFormula can take the following values:

Ts
.
z 1
This formula is best for small sampling time, where the Nyquist limit
is large compared to the bandwidth of the controller. For larger
sampling time, the ForwardEuler formula can result in instability,
even when discretizing a system that is stable in continuous time.

'ForwardEuler' DF(z) =

'BackwardEuler' DF(z) =

Ts z
.
z 1

An advantage of the BackwardEuler formula is that discretizing a

stable continuous-time system using this formula always yields a
stable discrete-time result.

Ts z + 1
.
2 z 1
An advantage of the Trapezoidal formula is that discretizing a
stable continuous-time system using this formula always yields a
stable discrete-time result. Of all available integration formulas,
the Trapezoidal formula yields the closest match between
frequency-domain properties of the discretized system and the
corresponding continuous-time system.

'Trapezoidal' DF(z) =

The Trapezoidal value for DFormula is not available for a pidstd

controller with no derivative filter (N = Inf).
When C is a continuous-time controller, DFormula is ''.

1-527

pidstd

Default: 'ForwardEuler'
InputDelay

Time delay on the system input. InputDelay is always 0 for a pidstd

controller object.
OutputDelay

Time delay on the system Output. OutputDelay is always 0 for a

pidstd controller object.
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'

1-528

pidstd

'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels

1-529

pidstd

InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

1-530

pidstd

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

1-531

pidstd

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times

1-532

pidstd

t = 0:10. The following code stores the time samples with the linear

models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Examples

Create a continuous-time standard-form PDF controller with

proportional gain 1, derivative time 3, and a filter divisor of 6.
C = pidstd(1,Inf,3,6);

1-533

pidstd

C =
s
Kp * (1 + Td * ------------)
(Td/N)*s+1
with Kp = 1, Td = 3, N = 6
Continuous-time PDF controller in standard form

The display shows the controller type, formula, and coefficient values.
Create a discrete-time PI controller with trapezoidal discretization
formula.
To create a discrete-time controller, set the value of Ts using
Name,Value syntax.
C = pidstd(1,0.5,'Ts',0.1,'IFormula','Trapezoidal') % Ts = 0.1s

This command produces the result:

Discrete-time PI controller in standard form:
1
Ts*(z+1)
Kp * (1 + ---- * --------)
Ti
2*(z-1)
with Kp = 1, Ti = 0.5, Ts = 0.1

Alternatively, you can create the same discrete-time controller by

supplying Ts as the fifth argument after all four PID parameters Kp,
Ti, Td, and N.
C = pidstd(5,2.4,0,Inf,0.1,'IFormula','Trapezoidal');

1-534

pidstd

Create a PID controller and set dynamic system properties InputName

and OutputName.
C = pidstd(1,0.5,3,'InputName','e','OutputName','u')

Create a 2-by-3 grid of PI controllers with proportional gain ranging

from 12 and integral time ranging from 59.
Create a grid of PI controllers with proportional gain varying row to
row and integral time varying column to column. To do so, start with
arrays representing the gains.
Kp = [1 1 1;2 2 2];
Ti = [5:2:9;5:2:9];
pi_array = pidstd(Kp,Ti,'Ts',0.1,'IFormula','BackwardEuler');

These commands produce a 2-by-3 array of discrete-time pidstd

objects. All pidstd objects in an array must have the same sample
time, discrete integrator formulas, and dynamic system properties (such
as InputName and OutputName).
Alternatively, you can use the stack command to build arrays of pidstd
objects.
C = pidstd(1,5,0.1)
% PID controller
Cf = pidstd(1,5,0.1,0.5)
% PID controller with filter
pid_array = stack(2,C,Cf); % stack along 2nd array dimension

These commands produce a 1-by-2 array of controllers. Enter the

command:
size(pid_array)

to see the result

1x2 array of PID controller.
Each PID has 1 output and 1 input.

1-535

pidstd

Convert a standard form pid controller to parallel form.

Parallel PID form expresses the controller actions in terms of an
proportional, integral, and derivative gains Kp, Ki, and Kd, and a filter
time constant Tf. You can convert a parallel form controller parsys to
standard form using pidstd, provided that:
parsys is not a pure integrator (I) controller.
The gains Kp, Ki, and Kd of parsys all have the same sign.
parsys = pid(2,3,4,5); % Standard-form controller
stdsys = pidstd(parsys)

These commands produce a parallel-form controller:

Continuous-time PIDF controller in standard form:
1
1
s
Kp * (1 + ---- * --- + Td * ------------)
Ti
s
(Td/N)*s+1
with Kp = 2, Ti = 0.66667, Td = 2, N = 0.4

Convert a continuous-time dynamic system that represents a PID

controller to parallel pid form.
The dynamic system

H ( s) =

3 ( s + 1) ( s + 2 )
s

represents a PID controller. Use pidstd to obtain H(s) to in terms of

the standard-form PID parameters Kp, Ti, and Td.
H = zpk([-1,-2],0,3);
C = pidstd(H)

1-536

pidstd

These commands produce the result:

Continuous-time PID controller in standard form:
1
1
Kp * (1 + ---- * --- + Td * s)
Ti
s
with Kp = 9, Ti = 1.5, Td = 0.33333

Convert a discrete-time dynamic system that represents a PID

controller with derivative filter to standard pidstd form.
% PIDF controller expressed in zpk form
sys = zpk([-0.5,-0.6],[1 -0.2],3,'Ts',0.1)

The resulting pidstd object depends upon the discrete integrator

formula you specify for IFormula and DFormula.
For example, if you use the default ForwardEuler for both formulas:
C = pidstd(sys)

you obtain the result:

Discrete-time PIDF controller in standard form:
1
Ts
1
Kp * (1 + ---- * ------ + Td * ---------------)
Ti
z-1
(Td/N)+Ts/(z-1)
with Kp = 2.75, Ti = 0.045833, Td = 0.0075758, N = 0.090909, Ts = 0.1

For this particular sys, you cannot write sys in standard PID form
using the BackwardEuler formula for the DFormula. Doing so would
result in N < 0, which is not permitted. In that case, pidstd returns
an error.

1-537

pidstd

Similarly, you cannot write sys in standard form using the Trapezoidal
formula for both integrators. Doing so would result in negative Ti and
Td, which also returns an error.
Discretize a continuous-time pidstd controller.
First, discretize the controller using the 'zoh' method of c2d.
Cc = pidstd(1,2,3,4) % continuous-time pidf controller
Cd1 = c2d(Cc,0.1,'zoh')
c2d computes new parameters for the discrete-time controller:
Discrete-time PIDF controller in standard form:
1
Ts
1
Kp * (1 + ---- * ------ + Td * ---------------)
Ti
z-1
(Td/N)+Ts/(z-1)
with Kp = 1, Ti = 2, Td = 3.2044, N = 4, Ts = 0.1

The resulting discrete-time controller uses ForwardEuler (Ts/(z1))

for both IFormula and DFormula.
The discrete integrator formulas of the discretized controller depend
upon the c2d discretization method, as described in Tips on page
1-521. To use a different IFormula and DFormula, directly set Ts,
IFormula, and DFormula to the desired values:
Cd2 = Cc;
Cd2.Ts = 0.1;
Cd2.IFormula = 'BackwardEuler';
Cd2.DFormula = 'BackwardEuler';

These commands do not compute new parameter values for the

discretized controller. To see this, enter:
Cd2

1-538

pidstd

to obtain the result:

Discrete-time PIDF controller in standard form:
1
Ts*z
1
Kp * (1 + ---- * ------ + Td * -----------------)
Ti
z-1
(Td/N)+Ts*z/(z-1)
with Kp = 1, Ti = 2, Td = 3, N = 4, Ts = 0.1

See Also

pid | piddata | pidtune | pidtool

Tutorials

Proportional-Integral-Derivative (PID) Controller

Discrete-Time Proportional-Integral-Derivative (PID) Controller

How To

What Are Model Objects?

PID Controllers

1-539

pidstddata

Purpose

Access PIDSTD data

Syntax

[Kp,Ti,Td,N] = pidstddata(sys)
[Kp,Ti,Td,N,Ts] = pidstddata(sys)
[Kp,Ti,Td,N,Ts] = pidstddata(sys, J1,...,JN)

Description

[Kp,Ti,Td,N] = pidstddata(sys) returns the proportional gain

Kp, integral time Ti, derivative time Td, and filter divisor N of the
standard-form controller represented by the dynamic system sys.
[Kp,Ti,Td,N,Ts] = pidstddata(sys) also returns the sample time

Ts.
[Kp,Ti,Td,N,Ts] = pidstddata(sys, J1,...,JN) extracts the data
for a subset of entries in the array of sys dynamic systems. The indices
J specify the array entries to extract.

Tips

If sys is not a pidstd controller object, pidstddata returns Kp, Ti, Td

and N values of a standard-form controller equivalent to sys.
For discrete-time sys, piddata returns parameters of an equivalent
pidstd controller. This controller has discrete integrator formulas
Iformula and Dformula set to ForwardEuler. See the pidstd reference
page for more information about discrete integrator formulas.

Input
Arguments

sys

SISO dynamic system or array of SISO dynamic systems. If sys is

not a pidstd object, it must represent a valid PID controller that can
be written in standard PID form.
J

Integer indices of N entries in the array sys of dynamic systems.

Output
Arguments

1-540

Kp

Proportional gain of the standard-form PID controller represented by

dynamic system sys.

pidstddata

If sys is a pidstd controller object, the output Kp is equal to the Kp

value of sys.
If sys is not a pidstd object, Kp is the proportional gain of a
standard-form PID controller equivalent to sys.
If sys is an array of dynamic systems, Kp is an array of the same
dimensions as sys.
Ti

Integral time constant of the standard-form PID controller represented

by dynamic system sys.
If sys is a pidstd controller object, the output Ti is equal to the Ti
value of sys.
If sys is not a pidstd object, Ti is the integral time constant of a
standard-form PID controller equivalent to sys.
If sys is an array of dynamic systems, Ti is an array of the same
dimensions as sys.
Td

Derivative time constant of the standard-form PID controller

represented by dynamic system sys.
If sys is a pidstd controller object, the output Td is equal to the Td
value of sys.
If sys is not a pidstd object, Td is the derivative time constant of a
standard-form PID controller equivalent to sys.
If sys is an array of dynamic systems, Td is an array of the same
dimensions as sys.
N

Filter divisor of the standard-form PID controller represented by

dynamic system sys.

1-541

pidstddata

If sys is a pidstd controller object, the output N is equal to the N value

of sys.
If sys is not a pidstd object, N is the filter time constant of a
standard-form PID controller equivalent to sys.
If sys is an array of dynamic systems, N is an array of the same
dimensions as sys.
Ts

Sampling time of the dynamic system sys. Ts is always a scalar value.

Examples

Extract the proportional, integral, and derivative gains and the filter
time constant from a standard-form pidstd controller.
For the following pidstd object:
sys = pidstd(1,4,0.3,10);

you can extract the parameter values from sys by entering:

[Kp Ti Td N] = pidstddata(sys);

Extract the standard-form proportional and integral gains from an

equivalent parallel-form PI controller.
For a standard-form PI controller, such as:
sys = pid(2,3);

you can extract the gains of an equivalent parallel-form PI controller

by entering:
[Kp Ti] = pidstddata(sys)

These commands return the result:

Kp =

1-542

pidstddata

Ti =
0.6667

Extract parameters from a dynamic system that represents a PID

controller.
The dynamic system

H ( z) =

( z 0 .5 ) ( z 0 .6 )
( z 1 ) ( z + 0 .8 )

represents a discrete-time PID controller with a derivative filter. Use

pidstddata to extract the standard-form PID parameters.
H = zpk([0.5 0.6],[1,-0.8],1,0.1);
[Kp Ti Td N Ts] = pidstddata(H);

% sampling time Ts = 0.1s

the pidstddata function uses the default ForwardEuler discrete

integrator formula for Iformula and Dformula to compute the
parameter values.
Extract the gains from an array of PI controllers.
sys = pidstd(rand(2,3),rand(2,3)); % 2-by-3 array of PI controllers
[Kp Ti Td N] = pidstddata(sys);

The parameters Kp, Ti, Td, and N are also 2-by-3 arrays.
Use the index input J to extract the parameters of a subset of sys.
[Kp Ti Td N] = pidstddata(sys,5);

See Also

pidstd | pid | get

1-543

pidtool

Purpose

Open PID Tuner for PID tuning

Syntax

pidtool(sys,type)
pidtool(sys,Cbase)
pidtool(sys)
pidtool

Description

pidtool(sys,type) launches the PID Tuner GUI and designs a

controller of type type for plant sys.

pidtool(sys,Cbase) launches the GUI with a baseline controller
Cbase so that you can compare performance between the designed
controller and the baseline controller. If Cbase is a pid or pidstd
controller object, the PID Tuner designs a controller of the same form,
type, and discrete integrator formulas as Cbase.
pidtool(sys) designs a parallel-form PI controller.
pidtool launches the GUI with default plant of 1 and proportional (P)
controller of 1.

Tips

The PID Tuner designs a controller in the feedforward path of a

single control loop with unit feedback:

+
-

sys

The PID Tuner has a default target phase margin of 60 degrees and
automatically tunes the PID gains to balance performance (response
time) and robustness (stability margins). Use the Response time
or Bandwidth and Phase Margin sliders to tune the controllers
performance to your requirements. Increasing performance typically
decreases robustness, and vice versa.
Select response plots from the Response menu to analyze the
controllers performance.

1-544

pidtool

If you provide Cbase, check Show baseline to display the response

of the baseline controller.
For more detailed information about using the PID Tuner, see
Designing PID Controllers with the PID Tuner.

Input
Arguments

sys

Plant model for controller design. sys can be:

Any SISO LTI system (such as ss, tf, zpk, or frd).
Any System Identification Toolbox SISO linear model (idarx, idfrd,
idgrey, idpoly, idproc, or idss).
A continuous- or discrete-time model.
Stable, unstable, or integrating. However, you might not be able to
stabilize a plant with unstable poles under PID control.
A model that includes any type of time delay. A plant with long time
delays, however, might not achieve adequate performance under
PID control.
If the plant has unstable poles, and sys is either:
A frd model
A ss model with internal time delays that cannot be converted to
I/O delays
then you must specify the number of unstable poles in the plant. To do
button to open
this, After launching the PID Tuner GUI, click the
the Import Linear System dialog box. In that dialog box, you can
reimport sys, specifying the number of unstable poles where prompted.
type

Controller type (actions) of the controller you are designing, specified as

one of the following strings:

1-545

pidtool

String Type

Continuous-Time
Controller
Formula
(parallel form)

Discrete-Time
Controller Formula
(parallel form,
ForwardEuler

integration
method)
'p'

proportional only

'i'

integral only

Kp

Kp

Ki
s
'pi'

'pd'

proportional and
integral

proportional and
derivative

Kp +

Ki

Ki
s

K p + Kds

Ts
z 1

K p + Ki

Ts
z 1

K p + Kd

z 1
Ts

'pdf' proportional and

derivative with
first-order filter
on derivative
term

Kp +

Kds
Tf s + 1

K p + Kd

Kp +

Ki
+ Kds
s

K p + Ki

Ts
z 1
+ Kd
z 1
Ts

Kp +

Ki
Kds
+
s Tf s + 1

K p + Ki

Ts
+ Kd
z 1

Tf +

Ts
z 1

'pid' proportional,

integral, and
derivative
'pidf' proportional,

integral, and
derivative with
first-order filter
on derivative
term

1-546

1
Tf +

Ts
z 1

pidtool

When you use the type input, the PID Tuner designs a controller in
parallel form. If you want to design a controller in standard form, Use
the input Cbase instead of type, or select Standard from the Form
menu. For more information about parallel and standard forms, see the
pid and pidstd reference pages.
If sys is a discrete-time model with sampling time Ts, the PID Tuner
designs a discrete-time pid controller using the ForwardEuler discrete
integrator formula. If you want to design a controller having a different
discrete integrator formula, use the input Cbase instead of type or
the Preferences dialog box. For more information about discrete
integrator formulas, see the pid and pidstd reference pages.
Cbase

A dynamic system representing a baseline controller, permitting

comparison of the performance of the designed controller to the
performance of Cbase.
If Cbase is a pid or pidstd object, the PID Tuner also uses it to
configure the type, form, and discrete integrator formulas of the
designed controller. The designed controller:
Is the type represented by Cbase.
Is a parallel-form controller, if Cbase is a pid controller object.
Is a standard-form controller, if Cbase is a pidstd controller object.
Has the same Iformula and Dformula values as Cbase. For more
information about Iformula and Dformula, see the pid and pidstd
reference pages .
If Cbase is any other dynamic system, the PID Tuner designs a
parallel-form PI controller. You can change the controller form and type
using the Form and Type menus after launching the PID Tuner.

Examples

Interactive PID Tuning of Parallel-Form Controller

Launch the PID Tuner to design a parallel-form PIDF controller for a
discrete-time plant:

1-547

pidtool

Gc = zpk([],[-1 -1 -1],1);
Gd = c2d(Gc,0.1);

% Create discrete-time plant

pidtool(Gd,'pidf')

% Launch PID Tuner

Interactive PID Tuning of Standard-Form Controller Using

Integrator Discretization Method
Design a standard-form PIDF controller using BackwardEuler discrete
integrator formula:
Gc = zpk([],[-1 -1 -1],1);
Gd = c2d(Gc,0.1);

% Create discrete-time plant

% Create baseline controller.

Cbase = pidstd(1,2,3,4,'Ts',0.1,...
'IFormula','BackwardEuler','DFormula','BackwardEuler')
pidtool(Gd,Cbase)

% Launch PID Tuner

The PID Tuner designs a controller for Gd having the same form, type,
and discrete integrator formulas as Cbase. For comparison, you can
display the response plots of Cbase with the response plots of the
designed controller by clicking the Show baseline checkbox on the
PID Tuner GUI.

Algorithms

Typical PID tuning objectives include:

Closed-loop stability The closed-loop system output remains
bounded for bounded input.
Adequate performance The closed-loop system tracks reference
changes and suppresses disturbances as rapidly as possible. The
larger the loop bandwidth (the first frequency at which the open-loop
gain is unity), the faster the controller responds to changes in the
reference or disturbances in the loop.

1-548

pidtool

Adequate robustness The loop design has enough phase margin

and gain margin to allow for modeling errors or variations in system
dynamics.
The MathWorks algorithm for tuning PID controllers helps you meet
these objectives by automatically tuning the PID gains to balance
performance (response time) and robustness (stability margins).
By default, the algorithm chooses a crossover frequency (loop
bandwidth) based upon the plant dynamics, and designs for a target
phase margin of 60. If you change the bandwidth or phase margin
using the sliders in the PID Tuner GUI, the algorithm computes PID
gains that best meet those targets.

References

strm, K. J. and Hgglund, T. Advanced PID Control, Research

Triangle Park, NC: Instrumentation, Systems, and Automation Society,
2006.

Alternatives

For PID tuning at the command line, use pidtune. pidtune can design
controllers for multiple plants at once.

See Also

pid | pidstd | pidtune

Tutorials

Designing PID for Disturbance Rejection with PID Tuner

How To

Designing PID Controllers with the PID Tuner

1-549

pidtune

Purpose

PID tuning algorithm for linear plant model

Syntax

C = pidtune(sys,type)
C = pidtune(sys,C0)
C = pidtune(sys,type,wc)
C = pidtune(sys,C0,wc)
C = pidtune(sys,...,opts)
[C,info] = pidtune(...)

Description

C = pidtune(sys,type) designs a PID controller of type type for the

plant sys in the unit feedback loop

+
-

sys

pidtune tunes the parameters of the PID controller C to balance

performance (response time) and robustness (stability margins).
C = pidtune(sys,C0) designs a controller of the same type and form

as the controller C0. If sys and C0 are discrete-time models, C has the
same discrete integrator formulas as C0.
C = pidtune(sys,type,wc) and C = pidtune(sys,C0,wc) specify

a target value wc for the first 0 dB gain crossover frequency of the

open-loop response L = sys*C.
C = pidtune(sys,...,opts) uses additional tuning options, such as
the target phase margin. Use pidtuneOptions to specify the option
set opts.
[C,info] = pidtune(...) returns the data structure info, which

contains information about closed-loop stability, the selected open-loop

gain crossover frequency, and the actual phase margin.

Tips

1-550

By default, pidtune with the type input returns a pid controller in

parallel form. To design a controller in standard form, use a pidstd

pidtune

controller as input argument C0. For more information about parallel

and standard controller forms, see the pid and pidstd reference pages.

Input
Arguments

sys

Single-input, single-output dynamic system model of the plant for

controller design. sys can be:
Any type of SISO dynamic system model, including Numeric LTI
models and identified models. If sys is a tunable or uncertain model,
pidtune designs a controller for the current or nominal value of sys.
A continuous- or discrete-time model.
Stable, unstable, or integrating. A plant with unstable poles,
however, might not be stabilizable under PID control.
A model that includes any type of time delay. A plant with long time
delays, however, might not achieve adequate performance under
PID control.
An array of plant models. If sys is an array, pidtune designs a
separate controller for each plant in the array.
If the plant has unstable poles, and sys is one of the following:
A frd model
A ss model with internal time delays that cannot be converted to
I/O delays
you must use pidtuneOptions to specify the number of unstable poles
in the plant, if any.
type

Controller type (actions) of the controller to design, specified as one of

the following strings.

1-551

pidtune

StringType

'p'

Proportional only

'i'

Integral only

Continuous-Time
Controller
Formula (parallel
form)

Discrete-Time
Controller
Formula
(parallel form,
ForwardEuler
integration
method)

Kp

Kp

Ki
s

Ki

Ts
z 1

'pi' Proportional and

integral

Kp +

Ki
s

K p + Ki

Ts
z 1

K p + Kd

z 1
Ts

'pd' Proportional and

derivative

K p + Kds

'pdf' Proportional and

derivative with
first-order filter on
derivative term

Kp +

Kds
Tf s + 1

K p + Kd

Kp +

Ki
+ Kds
s

K p + Ki

Ts
z 1
+ Kd
z 1
Ts

Kp +

Ki
Kds
+
s Tf s + 1

K p + Ki

Ts
+ Kd
z 1

Tf +

Ts
z 1

'pid' Proportional,

integral, and
derivative
'pidf'Proportional,

integral, and
derivative with
first-order filter on
derivative term

1-552

1
Tf +

Ts
z 1

pidtune

When you use the type input, pidtune designs a controller in parallel
(pid) form. Use the input C0 instead of type if you want to design a
controller in standard (pidstd) form.
If sys is a discrete-time model with sampling time Ts, pidtune
designs a discrete-time controller with the same Ts. The controller has
the ForwardEuler discrete integrator formula for both integral and
derivative actions. Use the input C0 instead of type if you want to
design a controller having a different discrete integrator formula.
C0
pid or pidstd controller specifying properties of the designed controller.
If you provide C0, pidtune:

Designs a controller of the type represented by C0.

Returns a pid controller, if C0 is a pid controller.
Returns a pidstd controller, if C0 is a pidstd controller.
Returns a controller with the same Iformula and Dformula values
as C0, if sys is a discrete-time system. See the pid and pidstd
reference pages for more information about Iformula and Dformula.
wc

Target value for the 0 dB gain crossover frequency of the tuned

open-loop response L = sys*C. Specify wc in units of radians/TimeUnit,
where TimeUnit is the time unit of sys. The crossover frequency wc
roughly sets the control bandwidth. The closed-loop response time is
approximately 1/wc.
Increase wc to speed up the response. Decrease wc to improve stability.
When you omit wc, pidtune automatically chooses a value, based on the
plant dynamics, that achieves a balance between response and stability.
opts

1-553

pidtune

Option set specifying additional tuning options for the pidtune design
algorithm, such as target phase margin. Use pidtuneOptions to create
opts.

Output
Arguments

Controller designed for sys. If sys is an array of linear models,

pidtune designs a controller for each linear model and returns an
array of PID controllers.
Controller form:
If the second argument to pidtune is type, C is a pid controller.
If the second argument to pidtune is C0:

C is a pid controller, if C0 is a pid object.

C is a pidstd controller, if C0 is a pidstd object.

Controller type:
If the second argument to pidtune is type, C generally has the
specified type.
If the second argument to pidtune is C0, C generally has the same
type as C0.
In either case, however, where the algorithm can achieve adequate
performance and robustness using a lower-order controller than
specified with type or C0, pidtune returns a C having fewer actions
than specified. For example, C can be a PI controller even though type
is 'pidf'.
Time domain:
C has the same time domain as sys.
If sys is a discrete-time model, C has the same sampling time as sys.
If you specify C0, C has the same Iformula and Dformula as C0. If
no C0 is specified, both Iformula and Dformula are Forward Euler.
See the pid and pidstd reference pages for more information about
Iformula and Dformula.

1-554

pidtune

If you specify C0, C also obtains model properties such as InputName

and OutputName from C0. For more information about model properties,
see the reference pages for each type of dynamic system model.
info

Data structure containing information about performance and

robustness of the tuned PID loop. The fields of info are:
Stable Boolean value indicating closed-loop stability. Stable is 1
if the closed loop is stable, and 0 otherwise.
CrossoverFrequency First 0 dB crossover frequency of the
open-loop system C*sys, in rad/TimeUnit, where TimeUnit is the
time units specified in the TimeUnit property of sys.
PhaseMargin Phase margin of the tuned PID loop, in degrees.
If sys is an array of plant models, info is an array of data structures
containing information about each tuned PID loop.

Examples

Tune Parallel-Form PID Controller

This example shows how to design a PID controller for the plant

sys

s 1 3

As a first pass, design a simple PI controller:

sys = zpk([],[-1 -1 -1],1); % define the plant
[C_pi,info] = pidtune(sys,'pi')
C_pi =
1
Kp + Ki * --s
with Kp = 1.14, Ki = 0.454

1-555

pidtune

Continuous-time PI controller in parallel form.

info =
Stable: 1
CrossoverFrequency: 0.5205
PhaseMargin: 60.0000
C_pi is a pid controller object that represents a PI controller. The fields
of info show that the tuning algorithm chooses an open-loop crossover

frequency of about 0.52 rad/s.

Examine the closed-loop step response (reference tracking) of the
controlled system.
T_pi = feedback(C_pi*sys, 1);
step(T_pi)

1-556

pidtune

To improve the response time, you can set a higher target crossover
frequency than the result that pidtune automatically selects, 0.52.
Increase the crossover frequency to 1.0.
[C_pi_fast,info] = pidtune(sys,'pi',1.0)
C_pi_fast =
1
Kp + Ki * --s
with Kp = 2.83, Ki = 0.0495
Continuous-time PI controller in parallel form.

info =
Stable: 1
CrossoverFrequency: 1
PhaseMargin: 43.9973

The new controller achieves the higher crossover frequency, but at the
cost of a reduced phase margin.
Compare the closed-loop step response with the two controllers.
T_pi_fast = feedback(C_pi_fast*sys,1);
step(T_pi,T_pi_fast)
axis([0 30 0 1.4])
legend('C\_pi','C\_pi\_fast')

1-557

pidtune

This reduction in performance results because the PI controller does not

have enough degrees of freedom to achieve a good phase margin at a
crossover frequency of 1.0 rad/s. Adding a derivative action improves
the response.
Design a PIDF controller for Gc with the target crossover frequency
of 1.0 rad/s.
[C_pidf_fast,info] = pidtune(sys,'pidf',1.0)
C_pidf_fast =
1
s
Kp + Ki * --- + Kd * -------s
Tf*s+1
with Kp = 2.72, Ki = 1.03, Kd = 1.76, Tf = 0.00875
Continuous-time PIDF controller in parallel form.

1-558

pidtune

info =
Stable: 1
CrossoverFrequency: 1
PhaseMargin: 60.0000

The fields of info show that the derivative action in the controller
allows the tuning algorithm to design a more aggressive controller that
achieves the target crossover frequency with a good phase margin.
Compare the closed-loop step response and disturbance rejection for
the fast PI and PIDF controllers.
T_pidf_fast = feedback(C_pidf_fast*sys,1);
step(T_pi_fast, T_pidf_fast);
axis([0 30 0 1.4]);
legend('C\_pi\_fast','C\_pidf\_fast');

1-559

pidtune

You can compare the input (load) disturbance rejection of the controlled
system with the fast PI and PIDF controllers. To do so, plot the
response of the closed-loop transfer function from the plant input to
the plant output.
S_pi_fast = feedback(sys,C_pi_fast);
S_pidf_fast = feedback(sys,C_pidf_fast);
step(S_pi_fast,S_pidf_fast);
axis([0 50 0 0.4]);
legend('C\_pi\_fast','C\_pidf\_fast');

This plot shows that the PIDF controller also provides faster
disturbance rejection.

Tune Standard-Form PID Controller

This example shows how to design a PID controller in standard form for
the plant defined by

1-560

pidtune

sys

s 1 3

To design a controller in standard form, use a standard-form controller

as the C0 argument to pidtune.
sys = zpk([],[-1 -1 -1],1);
C0 = pidstd(1,1,1);
C = pidtune(sys,C0)
C =
1
1
Kp * (1 + ---- * --- + Td * s)
Ti
s
with Kp = 2.18, Ti = 2.36, Td = 0.591
Continuous-time PID controller in standard form

Specify Integrator Discretization Method

This example shows how to design a discrete-time PI controller using a
specified method to discretize the integrator.
If your plant is in discrete time, pidtune automatically returns a
discrete-time controller using the default Forward Euler integration
method. To specify a different integration method, use pid or pidstd to
create a discrete-time controller having the desired integration method.
sys = c2d(tf([1 1],[1 5 6]),0.1);
C0 = pid(1,1,'Ts',0.1,'IFormula','BackwardEuler');
C = pidtune(sys,C0)

C =
Ts*z

1-561

pidtune

Kp + Ki * -----z-1
with Kp = -0.518, Ki = 10.4, Ts = 0.1
Sample time: 0.1 seconds
Discrete-time PI controller in parallel form.

Using C0 as an input causes pidtune to design a controller C of the same

form, type, and discretization method as C0. The display shows that the
integral term of C uses the Backward Euler integration method.
Specify a Trapezoidal integrator and compare the resulting controller.
C0_tr = pid(1,1,'Ts',0.1,'IFormula','Trapezoidal');
Ctr = pidtune(sys,C_tr)
Ctr =
Ts*(z+1)
Ki * -------2*(z-1)
with Ki = 10.4, Ts = 0.1
Sample time: 0.1 seconds
Discrete-time I-only controller.

Algorithms

Typical PID tuning objectives include:

Closed-loop stability The closed-loop system output remains
bounded for bounded input.
Adequate performance The closed-loop system tracks reference
changes and suppresses disturbances as rapidly as possible. The
larger the loop bandwidth (the first frequency at which the open-loop
gain is unity), the faster the controller responds to changes in the
reference or disturbances in the loop.

1-562

pidtune

Adequate robustness The loop design has enough phase margin

and gain margin to allow for modeling errors or variations in system
dynamics.
The MathWorks algorithm for tuning PID controllers helps you meet
these objectives by automatically tuning the PID gains to balance
performance (response time) and robustness (stability margins).
By default, the algorithm chooses a crossover frequency (loop
bandwidth) based upon the plant dynamics, and designs for a target
phase margin of 60. If you specify the crossover frequency using wc or
the phase margin using pidtuneOptions, the algorithm computes PID
gains that best meet those targets.

References

strm, K. J. and Hgglund, T. Advanced PID Control, Research

Triangle Park, NC: Instrumentation, Systems, and Automation Society,
2006.

Alternatives

For interactive PID tuning, use the PID Tuner GUI (pidtool). See
PID Controller Design for Fast Reference Tracking for an example of
designing a controller using the PID Tuner GUI.
The PID Tuner GUI cannot design controllers for multiple plants at
once.

See Also

pidtuneOptions | pid | pidstd | pidtool

Tutorials

Designing Cascade Control System with PI Controllers

1-563

pidtuneOptions

Purpose

Define options for the pidtune command

Syntax

opt = pidtuneOptions
opt = pidtuneOptions(Name,Value)

Description

opt = pidtuneOptions returns the default option set for the pidtune

command.
opt = pidtuneOptions(Name,Value) creates an option set with the

options specified by one or more Name,Value pair arguments.

Tips

Use pidtuneOptions with the pidtune command to design a PID

controller for a specified phase margin.
When using the pidtune command to design a PID controller for a
plant with unstable poles, if your plant model is one of the following:

A frd model
A ss model with internal delays that cannot be converted to I/O
delays

then use pidtuneOptions to specify the number of unstable poles

in the plant.

Input
Arguments

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments.
Name is the argument name and Value is the corresponding
value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
PhaseMargin

Target phase margin in degrees. pidtune attempts to design a

controller such that the phase margin is at least the value specified
for PhaseMargin. The selected crossover frequency could restrict the
achievable phase margin. Typically, higher phase margin improves
stability and overshoot, but limits bandwidth and response speed.

1-564

pidtuneOptions

Default: 60
NumUnstablePoles

Number of unstable poles in the plant. When your plant is a frd model
or a state-space model with internal delays, you must specify the
number of open-loop unstable poles (if any). Incorrect values might
result in PID controllers that fail to stabilize the real plant. (pidtune
ignores this option for other model types.)
Unstable poles are poles located at:
Re(s) > 0, for continuous-time plants
|z| > 1, for discrete-time plants
A pure integrator in the plant (s = 0) or (|z| > 1) does not count as
an unstable pole for NumUnstablePoles. If your plant is a frd model
of a plant with a pure integrator, for best results, ensure that your
frequency response data covers a low enough frequency to capture the
integrator slope.
Default: 0

Output
Arguments

opt

Examples

Tune a PI controller with a target phase margin of 45 degrees. Use

pidtuneOptions to specify the phase margin:

Object containing the specified options for pidtune.

sys = tf(1,[1 3 3 1]);

opts = pidtuneOptions('PhaseMargin',45);
[C,info] = pidtune(sys,'pid',opts);

See Also

pidtune

1-565

place

Purpose

Pole placement design

Syntax

K = place(A,B,p)
[K,prec,message] = place(A,B,p)

Description

Given the single- or multi-input system

x = Ax + Bu
and a vector p of desired self-conjugate closed-loop pole locations, place
computes a gain matrix K such that the state feedback u = Kx places
the closed-loop poles at the locations p. In other words, the eigenvalues
of A BK match the entries of p (up to the ordering).
K = place(A,B,p) places the desired closed-loop poles p by computing
a state-feedback gain matrix K. All the inputs of the plant are assumed
to be control inputs. The length of p must match the row size of A. place
works for multi-input systems and is based on the algorithm from [1].
This algorithm uses the extra degrees of freedom to find a solution that
minimizes the sensitivity of the closed-loop poles to perturbations in
A or B.
[K,prec,message] = place(A,B,p) returns prec, an estimate of
how closely the eigenvalues of A BK match the specified locations p
(prec measures the number of accurate decimal digits in the actual
closed-loop poles). If some nonzero closed-loop pole is more than 10% off
from the desired location, message contains a warning message.

You can also use place for estimator gain selection by transposing the A
matrix and substituting C' for B.
l = place(A',C',p).'

Examples

Pole Placement Design

Consider a state-space system (a,b,c,d) with two inputs, three
outputs, and three states. You can compute the feedback gain matrix
needed to place the closed-loop poles at p = [-1 -1.23 -5.0] by

1-566

place

p = [-1 -1.23 -5.0];

K = place(a,b,p)

Algorithms

place uses the algorithm of [1] which, for multi-input systems,

optimizes the choice of eigenvectors for a robust solution.

In high-order problems, some choices of pole locations result in very

large gains. The sensitivity problems attached with large gains suggest
caution in the use of pole placement techniques. See [2] for results from
numerical testing.

References

[1] Kautsky, J., N.K. Nichols, and P. Van Dooren, "Robust Pole
Assignment in Linear State Feedback," International Journal of
Control, 41 (1985), pp. 1129-1155.
[2] Laub, A.J. and M. Wette, Algorithms and Software for Pole
Assignment and Observers, UCRL-15646 Rev. 1, EE Dept., Univ. of
Calif., Santa Barbara, CA, Sept. 1984.

See Also

lqr | rlocus

1-567

pole

Purpose

Compute poles of dynamic system

Syntax

pole(sys)

Description

pole(sys) computes the poles p of the SISO or MIMO dynamic system

model sys.

If sys has internal delays, poles are obtained by first setting all internal
delays to zero (creating a zero-order Pad approximation) so that the
system has a finite number of zeros. For some systems, setting delays
to 0 creates singular algebraic loops, which result in either improper or
ill-defined, zero-delay approximations. For these systems, pole returns
an error. This error does not imply a problem with the model sys itself.

Algorithms

For state-space models, the poles are the eigenvalues of the A matrix, or
the generalized eigenvalues of A E in the descriptor case.
For SISO transfer functions or zero-pole-gain models, the poles are
simply the denominator roots (see roots).
For MIMO transfer functions (or zero-pole-gain models), the poles are
computed as the union of the poles for each SISO entry. If some columns
or rows have a common denominator, the roots of this denominator are
counted only once.

Limitations

Multiple poles are numerically sensitive and cannot be computed to high

accuracy. A pole with multiplicity m typically gives rise to a cluster of
computed poles distributed on a circle with center and radius of order

1/ m
where is the relative machine precision (eps).

See Also

1-568

damp | esort | dsort | pzmap | zero

prescale

Purpose

Optimal scaling of state-space models

Syntax

scaledsys = prescale(sys)
scaledsys = prescale(sys,focus)
[scaledsys,info] = prescale(...)
prescale(sys)

Description

scaledsys = prescale(sys) scales the entries of the state vector

of a state-space model sys to maximize the accuracy of subsequent
frequency-domain analysis. The scaled model scaledsys is equivalent
to sys.
scaledsys = prescale(sys,focus) specifies a frequency interval
focus = {fmin,fmax} (in rad/TimeUnit, where TimeUnit is the systems
time units specified in the TimeUnit property of sys) over which to
maximize accuracy. This is useful when sys has a combination of slow

and fast dynamics and scaling cannot achieve high accuracy over the
entire dynamic range. By default, prescale attempts to maximize
accuracy in the frequency band with dominant dynamics.
[scaledsys,info] = prescale(...) also returns a structure info

with the fields shown in the following table.

SL

Left scaling factors

SR

Right scaling factors

Freqs

Frequencies used to test accuracy

RelAcc

Guaranteed relative accuracy at

these frequencies

The test frequencies lie in the frequency interval focus when specified.
The scaled state-space matrices are

As = TL ATR
Bs = TL B
Cs = CTR
Es = TL ETR

1-569

prescale

where TL = diag(SL) and TR = diag(SR). TL and TR are inverse of each

other for explicit models (E = [ ]).
prescale(sys) opens an interactive GUI for:

Visualizing accuracy trade-offs for sys.

Adjusting the frequency interval where the accuracy of sys is
maximized.

For more information on scaling and using the Scaling Tool GUI, see
Scaling State-Space Models.

1-570

prescale

Tips

Most frequency-domain analysis commands perform automatic scaling

equivalent to scaledsys = prescale(sys).
You do not need to scale for time-domain simulations and doing so
may invalidate the initial condition x0 used in initial and lsim
simulations.

See Also

ss

1-571

pzmap

Purpose

Pole-zero plot of dynamic system

Syntax

pzmap(sys)
pzmap(sys1,sys2,...,sysN)

[p,z] = pzmap(sys)

Description

pzmap(sys) creates a pole-zero plot of the continuous- or discrete-time

dynamic system model sys. For SISO systems, pzmap plots the transfer

function poles and zeros. For MIMO systems, it plots the system poles
and transmission zeros. The poles are plotted as xs and the zeros are
plotted as os.
pzmap(sys1,sys2,...,sysN) creates the pole-zero plot of multiple models
on a single figure. The models can have different numbers of inputs and
outputs and can be a mix of continuous and discrete systems.

[p,z] = pzmap(sys) returns the system poles and (transmission) zeros

in the column vectors p and z. No plot is drawn on the screen.

You can use the functions sgrid or zgrid to plot lines of constant
damping ratio and natural frequency in the s- or z-plane.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Pole-Zero Plot of Dynamic System
Plot the poles and zeros of the continuous-time system

H ( s) =

2s2 + 5s + 1
s2 + 2s + 3

H = tf([2 5 1],[1 2 3]); sgrid

pzmap(H)
grid on

1-572

pzmap

Example 2
Plot the pzmap for a 2-input-output discrete-time IDSS model.
A = [0.1 0; 0.2 0.9]; B = [.1 .2; 0.1 .02]; C = [10 20; 2 -5]; D = [1 2; 0 1];
sys = idss(A,B,C,D, 'Ts', 0.1);

Algorithms

pzmap uses a combination of pole and zero.

See Also

damp | esort | dsort | pole | rlocus | sgrid | zgrid | zero |

iopzmap

1-573

pzplot

Purpose

Pole-zero map of dynamic system model with plot customization options

Syntax

h = pzplot(sys)
pzplot(sys1,sys2,...)
pzplot(AX,...)
pzplot(..., plotoptions)

Description

h = pzplot(sys) computes the poles and (transmission) zeros of the

dynamic system model sys and plots them in the complex plane. The

poles are plotted as xs and the zeros are plotted as os. It also returns
the plot handle h. You can use this handle to customize the plot with
the getoptions and setoptions commands. Type
help pzoptions

for a list of available plot options.

pzplot(sys1,sys2,...) shows the poles and zeros of multiple models
sys1,sys2,... on a single plot. You can specify distinctive colors for each

model, as in
pzplot(sys1,'r',sys2,'y',sys3,'g')
pzplot(AX,...) plots into the axes with handle AX.
pzplot(..., plotoptions) plots the poles and zeros with the options
specified in plotoptions. Type
help pzoptions

for more detail.

The function sgrid or zgrid can be used to plot lines of constant
damping ratio and natural frequency in the s- or z-plane.
For arrays sys of dynamic system models, pzmap plots the poles and
zeros of each model in the array on the same diagram.

1-574

pzplot

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Use the plot handle to change the color of the plots title.
sys = rss(3,2,2);
h = pzplot(sys);
p = getoptions(h); % Get options for plot.
p.Title.Color = [1,0,0]; % Change title color in options.
setoptions(h,p); % Apply options to plot.

See Also

getoptions | pzmap | setoptions | iopzplot

1-575

pzoptions

Purpose

Create list of pole/zero plot options

Syntax

P = pzoptions
P = pzoption('cstprefs')

Description

P = pzoptions returns a list of available options for pole/zero plots

(pole/zero, input-output pole/zero and root locus) with default values

set.. You can use these options to customize the pole/zero plot
appearance from the command line.
P = pzoption('cstprefs') initializes the plot options with the options
you selected in the Control System Toolbox Preferences Editor. For
more information about the editor, see Toolbox Preferences Editor in
the Users Guide documentation.

This table summarizes the available pole/zero plot options.

1-576

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid

Show or hide the grid

Specified as one of the following
strings: 'off' | 'on'
Default: 'off'

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

IOGrouping

Grouping of input-output pairs

Specified as one of the
following strings: 'none'
|'inputs'|'output'|'all'
Default: 'none'

InputLabels, OutputLabels

Input and output label styles

pzoptions

Option

Description

InputVisible, OutputVisible

Visibility of input and output

channels

FreqUnits

Frequency units, specified as one

of the following strings:
'Hz'
'rad/second'
'rpm'
'kHz'
'MHz'
'GHz'
'rad/nanosecond'
'rad/microsecond'
'rad/millisecond'
'rad/minute'
'rad/hour'
'rad/day'
'rad/week'
'rad/month'
'rad/year'
'cycles/nanosecond'
'cycles/microsecond'
'cycles/millisecond'
'cycles/hour'
'cycles/day'

1-577

pzoptions

Option

Description
'cycles/week'
'cycles/month'
'cycles/year'
Default: 'rad/s'
You can also specify 'auto'
which uses frequency units
rad/TimeUnit relative to system
time units specified in the
TimeUnit property. For multiple
systems with different time units,
the units of the first system are
used.

TimeUnits

Time units, specified as one of the

following strings:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Default: 'seconds'

1-578

pzoptions

Option

Description
You can also specify 'auto' which
uses time units specified in the
TimeUnit property of the input
system. For multiple systems
with different time units, the
units of the first system is used.

ConfidenceRegionNumberSD

Examples

Number of standard deviations

to use when displaying the
confidence region characteristic
for identified models (valid only
iopzplot).

In this example, you enable the grid option before creating a plot.
P = pzoptions; % Create set of plot options P
P.Grid = 'on'; % Set the grid to on in options
h = rlocusplot(tf(1,[1,.2,1,0]),P);

The following root locus plot is created with the grid enabled.

1-579

pzoptions

See Also

1-580

getoptions | iopzplot | pzplot | setoptions

realp

Purpose

Real tunable parameter

Syntax

p = realp(paramname,initvalue)

Description

p = realp(paramname,initvalue) creates a tunable real-valued

Tips

Use arithmetic operators (+, -, *, /, \, and ^) to combine realp

objects into rational expressions or matrix expressions. You can use
the resulting expressions in model-creation functions such as tf, zpk,
and ss to create tunable models. For more information about tunable
models, see Models with Tunable Coefficients in the Control System
Toolbox Users Guide.

Input
Arguments

paramname

parameter with name specified by the string paramname and initial

value initvalue. Tunable real parameters can be scalar- or matrixvalued.

String specifying the name of the realp parameter p. This input

argument sets the value of the Name property of p.
initvalue

Initial numeric value of the parameter p. initvalue can be a real

scalar value or a 2-dimensional matrix.

Output
Arguments

Properties

Name

realp parameter object.

String containing the name of the realp parameter object. The value
of Name is set by the paramname input argument to realp and cannot
be changed.
Value

1-581

realp

Value of the tunable parameter.

Value can be a real scalar value or a 2-dimensional matrix. The initial

value is set by the initvalue input argument. The dimensions of

Value are fixed on creation of the realp object.
Minimum

Lower bound for the parameter value. The dimension of the Minimum
property matches the dimension of the Value property.
For matrix-valued parameters, use indexing to specify lower bounds on
individual elements:
p = realp('K',eye(2));
p.Minimum([1 4]) = -5;

Use scalar expansion to set the same lower bound for all matrix
elements:
p.Minimum = -5;

Default: -Inf for all entries

Maximum

Upper bound for the parameter value. The dimension of the Maximum
property matches the dimension of the Value property.
For matrix-valued parameters, use indexing to specify upper bounds on
individual elements:
p = realp('K',eye(2));
p.Maximum([1 4]) = 5;

Use scalar expansion to set the same upper bound for all matrix
elements:
p.Maximum = 5;

Default: Inf for all entries

1-582

realp

Free

Boolean value specifying whether the parameter is free to be tuned. Set

the Free property to 1 (true) for tunable parameters, and 0 (false)
for fixed parameters.
The dimension of the Free property matches the dimension of the Value
property.
Default: 1 (true) for all entries

Examples

Tunable Low-Pass Filter

This example shows how to create the low-pass filter F = a/(s + a) with
one tunable parameter a.
You cannot use ltiblock.tf to represent F, because the numerator
and denominator coefficients of an ltiblock.tf block are independent.
Instead, construct F using the tunable real parameter object realp.
1 Create a tunable real parameter.

a = realp('a',10);

The realp object a is a tunable parameter with initial value 10.

2 Use tf to create the tunable filter F:

F = tf(a,[1 a]);
F is a genss object which has the tunable parameter a in its Blocks
property. You can connect F with other tunable or numeric models to

create more complex models of control systems. For an example, see

Control System with Tunable Components.
Parametric Diagonal Matrix

1-583

realp

This example shows how to create a parametric matrix whose

off-diagonal terms are fixed to zero, and whose diagonal terms are
tunable parameters.
1 Create a parametric matrix whose initial value is the identity matrix.

p = realp('P',eye(2));
p is a 2-by-2 parametric matrix. Because the initial value is the

identity matrix, the off-diagonal initial values are zero.

2 Fix the values of the off-diagonal elements by setting the Free

property to false.
p.Free(1,2) = false;
p.Free(2,1) = false;

See Also

genss | genmat | tf | ss

How To

Models with Tunable Coefficients

1-584

reg

Purpose

Form regulator given state-feedback and estimator gains

Syntax

rsys = reg(sys,K,L)
rsys = reg(sys,K,L,sensors,known,controls)

Description

rsys = reg(sys,K,L) forms a dynamic regulator or compensator rsys

given a state-space model sys of the plant, a state-feedback gain matrix
K, and an estimator gain matrix L. The gains K and L are typically
designed using pole placement or LQG techniques. The function reg

handles both continuous- and discrete-time cases.

This syntax assumes that all inputs of sys are controls, and all outputs
are measured. The regulator rsys is obtained by connecting the
state-feedback law u = Kx and the state estimator with gain matrix L
(see estim). For a plant with equations

x = Ax + Bu
y = Cx + Du
this yields the regulator

x = [ A LC ( B LD) K ] x + Ly
u = Kx
This regulator should be connected to the plant using positive feedback.

1-585

reg

rsys = reg(sys,K,L,sensors,known,controls) handles more

general regulation problems where:

The plant inputs consist of controls u, known inputs ud, and
stochastic inputs w.
Only a subset y of the plant outputs is measured.
The index vectors sensors, known, and controls specify y, ud, and u as
subsets of the outputs and inputs of sys. The resulting regulator uses
[ud ; y] as inputs to generate the commands u (see next figure).

1-586

reg

Examples

Given a continuous-time state-space model

sys = ss(A,B,C,D)

with seven outputs and four inputs, suppose you have designed:
A state-feedback controller gain K using inputs 1, 2, and 4 of the
plant as control inputs
A state estimator with gain L using outputs 4, 7, and 1 of the plant as
sensors, and input 3 of the plant as an additional known input
You can then connect the controller and estimator and form the
complete regulation system by
controls = [1,2,4];
sensors = [4,7,1];
known = [3];
regulator = reg(sys,K,L,sensors,known,controls)

See Also

estim | kalman | lqgreg | lqr | dlqr | place

1-587

replaceBlock

Purpose

Replace or update Control Design Blocks in Generalized LTI model

Syntax

Mnew = replaceBlock(M,Block1,Value1,...,BlockN,ValueN)
Mnew = replaceBlock(M,blockvalues)
Mnew = replaceBlock(...,mode)

Description

Mnew = replaceBlock(M,Block1,Value1,...,BlockN,ValueN)

replaces the Control Design Blocks Block1,...,BlockN of M with the

specified values Value1,...,ValueN. M is a Generalized LTI model
or a Generalized matrix.
Mnew = replaceBlock(M,blockvalues) specifies the block names

and replacement values as field names and values of the structure

blockvalues.
Mnew = replaceBlock(...,mode) performs block replacement on an
array of models M using the substitution mode specified by the string
mode.

Tips

Use replaceBlock to perform parameter studies by sampling

Generalized LTI models across a grid of parameters, or to evaluate
tunable models for specific values of the tunable blocks. See
Examples on page 1-590.

Input
Arguments

Generalized LTI model, Generalized matrix, or array of such models.

Block1,...,BlockN

Names of Control Design Blocks in M. The replaceBlock command

replaces each listed block of M with the corresponding values
Value1,...,ValueN that you supply.
If a specified Block is not a block of M, replaceBlock that block and
the corresponding value.
Value1,...,ValueN

1-588

replaceBlock

Replacement values for the corresponding blocks Block1,...,BlockN.

The replacement value for a block can be any value compatible with the
size of the block, including a different Control Design Block, a numeric
matrix, or an LTI model. If any value is [], the corresponding block is
replaced by its nominal (current) value.
blockvalues

Structure specifying blocks of M to replace and the values with which to

replace those blocks.
The field names of blockvalues match names of Control Design
Blocks of M. Use the field values to specify the replacement values for
the corresponding blocks of M. The replacement values may be numeric
values, Numeric LTI models, Control Design Blocks, or Generalized
LTI models.
mode

String specifying the block replacement mode for an input array M of

Generalized matrices or LTI models.
mode can take the following values:
'-once' (default) Vectorized block replacement across the model
array M. Each block is replaced by a single value, but the value may
change from model to model across the array.
For vectorized block replacement, use a structure array for the input
blockvalues, or cell arrays for the Value1,...,ValueN inputs.
For example, if M is a 2-by-3 array of models:

Mnew = replaceBlock(M,blockvalues,'-once'), where

Mnew = replaceBlock(M,Block,Value,'-once'), where Value

is a 2-by-3 cell array, replaces Block by Value{k} in the model
M(:,:,k) in the array.

blockvalues is a 2-by-3 structure array, specifies one set of block

values blockvalues(k) for each model M(:,:,k) in the array.

1-589

replaceBlock

'-batch' Batch block replacement. Each block is replaced by an

array of values, and the same array of values is used for each model
in M. The resulting array of model Mnew is of size [size(M) Asize],
where Asize is the size of the replacement value.
When the input M is a single model, '-once' and '-batch' return
identical results.
Default: '-once'

Output
Arguments

Mnew

Matrix or linear model or matrix where the specified blocks are replaced
by the specified replacement values.
Mnew is a numeric array or numeric LTI model when all the specified
replacement values are numeric values or numeric LTI models.

Examples

Replace Control Design Block with Numeric Values

This example shows how to replace a tunable PID controller
(ltiblock.pid) in a Generalized LTI model by a pure gain, a numeric
PI controller, or the current value of the tunable controller.
1 Create a Generalized LTI model of the following system:

+
-

C(s)

where the plant G s

G(s)

s 1
, and C is a tunable PID controller.
s 1 3

G = zpk(1,[-1,-1,-1],1);
C = ltiblock.pid('C','pid');
Try = feedback(G*C,1)

1-590

replaceBlock

2 Replace C by a pure gain of 5.

T1 = replaceBlock(Try,'C',5);
T1 is a ss model that equals feedback(G*5,1).
3 Replace C by a PI controller with proportional gain of 5 and integral

gain of 0.1.
C2 = pid(5,0.1);
T2 = replaceBlock(Try,'C',C2);
T2 is a ss model that equals feedback(G*C2,1).
4 Replace C by its current (nominal) value.

T3 = replaceBlock(Try,'C',[]);
T3 is a ss model where C has been replaced by getValue(C).

Sample a Parametric Model over a Matrix of Parameter Values.

This example shows how to sample a parametric model of a second-order
filter across a grid of parameter values using replaceBlock.
1 Create a tunable (parametric) model of the second-order filter:

F s

n2
s2 2n s n2

where the damping and the natural frequency n are the

parameters.
wn = realp('wn',3);
zeta = realp('zeta',0.8);
F = tf(wn^2,[1 2*zeta*wn wn^2])
F =

1-591

replaceBlock

Generalized continuous-time state-space model with 1 outputs, 1 input

wn: Scalar parameter, 5 occurrences.
zeta: Scalar parameter, 1 occurrences.
Type "ss(F)" to see the current value, "get(F)" to see all properties,
F is a genss model with two tunable Control Design Blocks, the
realp blocks wn and zeta. The blocks wn and zeta have initial values

of 3 and 0.8, respectively.

2 Sample F over a 2-by-3 grid of (wn,zeta) values.

wnvals = [3;5];
zetavals = [0.6 0.8 1.0];
Fsample = replaceBlock(F,'wn',wnvals,'zeta',zetavals);
Fsample is 2-by-3 array of state-space models. Each entry in the
array is the transfer function for the corresponding (wn,zeta) pair.
3 Plot the step response of Fsample.

step(Fsample)

1-592

replaceBlock

The step response plots show the variation in the natural frequency
and damping constant across the six models in the array Fsample.
4 You can set the SamplingGrid property of the model array to help

keep track of which set of parameter values corresponds to which

entry in the array. To do so, create a grid of parameter values that
matches the dimensions of the array. Then, assign these values to
Fsample.SamplingGrid with the parameter names.
[wngrid,zetagrid] = ndgrid(wnvals,zetavals);
Fsample.SamplingGrid = struct('wn',wngrid,'zeta',zetagrid);

1-593

replaceBlock

When you display H, the parameter values in Fsample.SamplingGrid

are displayed along with the each transfer function in the array.

See Also

getValue | genss | genmat | nblocks

How To

Generalized Matrices
Generalized and Uncertain LTI Models
Models with Tunable Coefficients

1-594

repsys

Purpose

Replicate and tile models

Syntax

rsys = repsys(sys,[M N])

rsys = repsys(sys,N)
rsys = repsys(sys,[M N S1,...,Sk])

Description

rsys = repsys(sys,[M N]) replicates the model sys into an M-by-N

tiling pattern. The resulting model rsys has size(sys,1)*M outputs
and size(sys,2)*N inputs.
rsys = repsys(sys,N) creates an N-by-N tiling.
rsys = repsys(sys,[M N S1,...,Sk]) replicates and tiles sys along

both I/O and array dimensions to produce a model array. The indices S
specify the array dimensions. The size of the array is [size(sys,1)*M,
size(sys,2)*N, size(sys,3)*S1, ...].

Tips

rsys = repsys(sys,N) produces the same result as rsys =

repsys(sys,[N N]). To produce a diagonal tiling, use rsys =
sys*eye(N).

Input
Arguments

sys

Model to replicate.
M

Number of replications of sys along the output dimension.

N

Number of replications of sys along the input dimension.

S

Numbers of replications of sys along array dimensions.

Output
Arguments

rsys

Model having size(sys,1)*M outputs and size(sys,2)*N inputs.

1-595

repsys

If you provide array dimensions S1,...,Sk, rsys is an array of dynamic

systems which each have size(sys,1)*M outputs and size(sys,2)*N
inputs. The size of rsys is [size(sys,1)*M, size(sys,2)*N,
size(sys,3)*S1, ...].

Examples

Replicate a SISO transfer function to create a MIMO transfer function

that has three inputs and two outputs.
sys = tf(2,[1 3]);
rsys = repsys(sys,[2 3]);

The preceding commands produce the same result as:

sys = tf(2,[1 3]);
rsys = [sys sys sys; sys sys sys];

Replicate a SISO transfer function into a 3-by-4 array of two-input,

one-output transfer functions.
sys = tf(2,[1 3]);
rsys = repsys(sys, [1 2 3 4]);

To check the size of rsys, enter:

size(rsys)

This command produces the result:

3x4 array of transfer functions.
Each model has 1 outputs and 2 inputs.

See Also

1-596

append

reshape

Purpose

Change shape of model array

Syntax

sys = reshape(sys,s1,s2,...,sk)
sys = reshape(sys,[s1 s2 ... sk])

Description

sys = reshape(sys,s1,s2,...,sk) (or, equivalently, sys =

reshape(sys,[s1 s2 ... sk])) reshapes the LTI array sys into an
s1-by-s2-by-...-by-sk model array. With either syntax, there must be
s1*s2*...*sk models in sys to begin with.

Examples

Change the shape of a model array from 2x3 to 6x1.

% Create a 2x3 model array.
sys = rss(4,1,1,2,3);
% Confirm the size of the array.
size(sys)

This input produces the following output:

2x3 array of state-space models
Each model has 1 output, 1 input, and 4 states.

Change the shape of the array.

sys1 = reshape(sys,6,1);
size(sys1)

This input produces the following output:

6x1 array of state-space models
Each model has 1 output, 1 input, and 4 states.

See Also

ndims | size

1-597

rlocus

Purpose

Root locus plot of dynamic system

Syntax

rlocus(sys)
rlocus(sys1,sys2,...)
[r,k] = rlocus(sys)
r = rlocus(sys,k)

Description

rlocus computes the root locus of a SISO open-loop model. The root
locus gives the closed-loop pole trajectories as a function of the feedback
gain k (assuming negative feedback). Root loci are used to study the
effects of varying feedback gains on closed-loop pole locations. In turn,
these locations provide indirect information on the time and frequency
responses.
rlocus(sys) calculates and plots the root locus of the open-loop SISO
model sys. This function can be applied to any of the following negative
feedback loops by setting sys appropriately.

If sys has transfer function

1-598

rlocus

h ( s) =

n ( s)

d ( s)

the closed-loop poles are the roots of

d(s) + kn(s) = 0
rlocus adaptively selects a set of positive gains k to produce a smooth
plot. Alternatively,
rlocus(sys,k)

uses the user-specified vector k of gains to plot the root locus.

rlocus(sys1,sys2,...) draws the root loci of multiple LTI models
sys1, sys2,... on a single plot. You can specify a color, line style,

and marker for each model, as in

rlocus(sys1,'r',sys2,'y:',sys3,'gx').
[r,k] = rlocus(sys) and r = rlocus(sys,k) return the vector k of
selected gains and the complex root locations r for these gains. The
matrix r has length(k) columns and its jth column lists the closed-loop
roots for the gain k(j).

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Root Locus Plot of Dynamic System

Plot the root-locus of the following system.

h(s) =

2s2 + 5s + 1
s2 + 2s + 3

h = tf([2 5 1],[1 2 3]);

1-599

rlocus

rlocus(h)

You can use the right-click menu for rlocus to add grid lines, zoom in or
out, and invoke the Property Editor to customize the plot. Also, click
anywhere on the curve to activate a data marker that displays the gain
value, pole, damping, overshoot, and frequency at the selected point.

See Also

1-600

pole | pzmap

rlocusplot

Purpose

Plot root locus and return plot handle

Syntax

h = rlocusplot(sys)
rlocusplot(sys,k)
rlocusplot(sys1,sys2,...)
rlocusplot(AX,...)
rlocusplot(..., plotoptions)

Description

h = rlocusplot(sys) computes and plots the root locus of the

single-input, single-output LTI model sys. It also returns the plot
handle h. You can use this handle to customize the plot with the
getoptions and setoptions commands. Type
help pzoptions

for a list of available plot options.

See rlocus for a discussion of the feedback structure and algorithms
used to calculate the root locus.
rlocusplot(sys,k) uses a user-specified vector k of gain values.
rlocusplot(sys1,sys2,...) draws the root loci of multiple LTI
models sys1, sys2,... on a single plot. You can specify a color, line style,

and marker for each model, as in

rlocusplot(sys1,'r',sys2,'y:',sys3,'gx')
rlocusplot(AX,...) plots into the axes with handle AX.
rlocusplot(..., plotoptions) plots the root locus with the options
specified in plotoptions. Type
help pzoptions

for more details.

1-601

rlocusplot

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Use the plot handle to change the title of the plot.

sys = rss(3);
h = rlocusplot(sys);
p = getoptions(h); % Get options for plot.
p.Title.String = 'My Title'; % Change title in options.
setoptions(h,p); % Apply options to plot.

See Also

1-602

getoptions | rlocus | pzoptions | setoptions

rss

Purpose

Generate random continuous test model

Syntax

rss(n)
rss(n,p)
rss(n,p,m,s1,...,sn)

Description

rss(n) generates an n-th order model with one input and one output
and returns the model in the state-space object sys. The poles of sys
are random and stable with the possible exception of poles at s = 0
(integrators).
rss(n,p) generates an nth order model with one input and p outputs,
and rss(n,p,m) generates an n-th order model with m inputs and p
outputs. The output sys is always a state-space model.
rss(n,p,m,s1,...,sn) generates an s1-by-...-by-sn array of n-th order
state-space models with m inputs and p outputs.

Use tf, frd, or zpk to convert the state-space object sys to transfer
function, frequency response, or zero-pole-gain form.

Examples

Obtain a random continuous LTI model with three states, two inputs,
and two outputs by typing
sys = rss(3,2,2)
a =
x1
x2
x3

x1
-0.54175
0.09729
0.08304

x2
0.09729
-0.89491
0.58707

x1
x2
x3

u1
-0.88844
0
-0.07162

u2
-2.41459
-0.69435
-1.39139

x3
0.08304
0.58707
-1.95271

b =

c =

1-603

rss

y1
y2

x1
0.32965
0.59854

x2
0.14718
-0.10144

y1
y2

u1
-0.87631
0

u2
-0.32758
0

d =

Continuous-time system.

See Also

1-604

drss | frd | tf | zpk

x3
0
0.02805

series

Purpose

Series connection of two models

Syntax

series

sys = series(sys1,sys2)
sys = series(sys1,sys2,outputs1,inputs2)

Description

series connects two model objects in series. This function accepts any

type of model. The two systems must be either both continuous or both
discrete with identical sample time. Static gains are neutral and can
be specified as regular matrices.
sys = series(sys1,sys2) forms the basic series connection shown

below.

This command is equivalent to the direct multiplication

sys = sys2 * sys1
sys = series(sys1,sys2,outputs1,inputs2) forms the more

general series connection.

1-605

series

The index vectors outputs1 and inputs2 indicate which outputs y1 of

sys1 and which inputs u2 of sys2 should be connected. The resulting
model sys has u as input and y as output.

Examples

Consider a state-space system sys1 with five inputs and four outputs
and another system sys2 with two inputs and three outputs. Connect
the two systems in series by connecting outputs 2 and 4 of sys1 with
inputs 1 and 2 of sys2.
outputs1 = [2 4];
inputs2 = [1 2];
sys = series(sys1,sys2,outputs1,inputs2)

See Also

1-606

append | feedback | parallel

set

Purpose

Set or modify model properties

Syntax

set(sys,'Property',Value)
set(sys,'Property1',Value1,'Property2',Value2,...)
sysnew = set( ___ )
set(sys,'Property')

Description

set is used to set or modify the properties of a dynamic system

model. Like its Handle Graphics counterpart, set uses property
name/property value pairs to update property values.
set(sys,'Property',Value) assigns the value Value to the property
of the model sys specified by the string 'Property'. This string can be
the full property name (for example, 'UserData') or any unambiguous
case-insensitive abbreviation (for example, 'user'). The specified
property must be compatible with the model type. For example, if sys
is a transfer function, Variable is a valid property but StateName is

not. For a complete list of available system properties for any linear
model type, see the reference page for that model type. This syntax is
equivalent to sys.Property = Value.
set(sys,'Property1',Value1,'Property2',Value2,...) sets
multiple property values with a single statement. Each property
name/property value pair updates one particular property.
sysnew = set( ___ ) returns the modified dynamic system model, and

can be used with any of the previous syntaxes.

set(sys,'Property') displays help for the property specified by
'Property'.

Examples

Consider the SISO state-space model created by

sys = ss(1,2,3,4);

You can add an input delay of 0.1 second, label the input as torque,
reset the D matrix to zero, and store its DC gain in the 'Userdata'
property by

1-607

set

set(sys,'inputd',0.1,'inputn','torque','d',0,'user',dcgain(sys))

Note that set does not require any output argument. Check the result
with get by typing
get(sys)
a:
b:
c:
d:
e:
StateName:
InternalDelay:
Ts:
InputDelay:
OutputDelay:
InputName:
OutputName:
InputGroup:
OutputGroup:
Name:
Notes:
UserData:

Tips

1
2
3
0
[]
{''}
[0x1 double]
0
0.1
0
{'torque'}
{''}
[1x1 struct]
[1x1 struct]
''
{}
-2

For discrete-time transfer functions, the convention used to represent

the numerator and denominator depends on the choice of variable (see
tf for details). Like tf, the syntax for set changes to remain consistent
with the choice of variable. For example, if the Variable property is set
to 'z' (the default),
set(h,'num',[1 2],'den',[1 3 4])

produces the transfer function

h ( z) =

1-608

z+2
2

z + 3z + 4

set

However, if you change the Variable to 'z^-1' by

set(h,'Variable','z^-1'),

the same command

set(h,'num',[1 2],'den',[1 3 4])

now interprets the row vectors [1 2] and [1 3 4] as the polynomials

1 + 2z1 and 1 + 3z1 + 4z2 and produces:

( )

h z1 =

1 + 2 z1
1 + 3 z1 + 4 z2

= zh ( z )

Note Because the resulting transfer functions are different, make sure
to use the convention consistent with your choice of variable.

See Also

get | frd | ss | tf | zpk

Tutorials

Model Properties

How To

What Are Model Objects?

1-609

setDelayModel

Purpose

Construct state-space model with internal delays

Syntax

sys = setDelayModel(H,tau)
sys = setDelayModel(A,B1,B2,C1,C2,D11,D12,D21,D22,tau)

Description

sys = setDelayModel(H,tau) constructs the state-space model sys

obtained by LFT interconnection of the state-space model H with the

vector of internal delays tau, as shown:

sys
u

H
w

z
exp(-tau*s)

sys = setDelayModel(A,B1,B2,C1,C2,D11,D12,D21,D22,tau)

constructs the state-space model sys described by the following

equations:

dx t

Ax t B1u t B2 w t
dt
y t C1 x t D11u t D12 w t

z t C2 x t D21u t D22 w t

wt z t .

tau () is the vector of internal delays in sys.

1-610

setDelayModel

Tips

setDelayModel is an advanced operation and is not the natural way

to construct models with internal delays. See Models with Time
Delays for recommended ways of creating internal delays.
The syntax sys =

setDelayModel(A,B1,B2,C1,C2,D11,D12,D21,D22,tau) constructs
a continuous-time model. You can construct the discrete-time model
described by the state-space equations

x k 1 Ax k B1u k B2 w k

y k C1 x k D11u k D12 w k

z k C2 x k D21u k D22 w k

w k z k .

To do so, first construct sys using sys =

setDelayModel(A,B1,B2,C1,C2,D11,D12,D21,D22,tau). Then, use
sys.Ts to set the sampling time.

Input
Arguments

State-space (ss) model to interconnect with internal delays tau.

tau

Vector of internal delays of sys.

For continuous-time models, express tau in seconds.
For discrete-time models, express tau as integer values that represent
multiples of the sampling time.
A,B1,B2,C1,C2,D11,D12,D21,D22

Set of state-space matrices that, with the internal delay vector tau,
explicitly describe the state-space model sys.

Output
Arguments

sys

State-space (ss) model with internal delays tau.

1-611

setDelayModel

See Also

getDelayModel | ss | lft

Concepts

Internal Delays
Models with Time Delays

1-612

setoptions

Purpose

Set plot options for response plot

Syntax

setoptions(h, PlotOpts)
setoptions(h, 'Property1', 'value1', ...)
setoptions(h, PlotOpts, 'Property1', 'value1', ...)

Description

setoptions(h, PlotOpts) sets preferences for response plot using the

plot handle. h is the plot handle, PlotOpts is a plot options handle
containing information about plot options.

There are two ways to create a plot options handle:

Use getoptions, which accepts a plot handle and returns a plot
options handle.
p = getoptions(h)

Create a default plot options handle using one of the following

commands:

bodeoptions Bode plots

hsvoptions Hankel singular values plots
nicholsoptions Nichols plots
nyquistoptions Nyquist plots
pzoptions Pole/zero plots
sigmaoptions Sigma plots
timeoptions Time plots (step, initial, impulse, etc.)

For example,
p = bodeoptions

returns a plot options handle for Bode plots.

setoptions(h, 'Property1', 'value1', ...) assigns values
to property pairs instead of using PlotOpts. To find out what

1-613

setoptions

properties and values are available for a particular plot, type help
<function>options. For example, for Bode plots type
help bodeoptions

For a list of the properties and values available for each plot type, see
Properties and Values Reference.
setoptions(h, PlotOpts, 'Property1', 'value1', ...) first
assigns plot properties as defined in @PlotOptions, and then overrides

any properties governed by the specified property/value pairs.

Examples

To change frequency units, first create a Bode plot.

sys=tf(1,[1 1]);
h=bodeplot(sys)

1-614

% Create a Bode plot with plot handle h.

setoptions

Now, change the frequency units from rad/s to Hz.

p=getoptions(h);
% Create a plot options handle p.
p.FreqUnits = 'Hz'; % Modify frequency units.
setoptions(h,p);
% Apply plot options to the Bode plot and
% render.

To change the frequency units using property/value pairs, use this code.
sys=tf(1,[1 1]);
h=bodeplot(sys);
setoptions(h,'FreqUnits','Hz');

The result is the same as the first example.

See Also

getoptions

1-615

setBlockValue

Purpose

Modify value of Control Design Block in Generalized Model

Syntax

M = setBlockValue(M0,blockname,val)
M = setBlockValue(M0,blockvalues)
M = setBlockValue(M0,Mref)

Description

M = setBlockValue(M0,blockname,val) modifies the current

or nominal value of the Control Design Block blockname in the

Generalized Model M0 to the value specified by val.
M = setBlockValue(M0,blockvalues) modifies the value of several
Control Design Blocks at once. The structure blockvalues specifies
the blocks and replacement values. Blocks of M0 not listed in
blockvalues are unchanged.
M = setBlockValue(M0,Mref) takes replacement values from Control

Design blocks in the Generalized Model Mref. This syntax modifies

the Control Design Blocks in M0 to match the current values of all
corresponding blocks in Mref.
Use this syntax to propagate block values, such as tuned parameter
values, from one parametric model to other models that depend on the
same parameters.

Input
Arguments

M0

Generalized Model containing the blocks whose current or nominal

value is modified to val. For the syntax M = setBlockValue(M0,Mref)
M0 can be a single Control Design Block whose value is modified to
match the value of the corresponding block in Mref.
blockname

Name of the Control Design Block in the model M0 whose current or

nominal value is modified.
To get a list of the Control Design Blocks in M0, enter M0.Blocks.
val

1-616

setBlockValue

Replacement value for the current or nominal value of the Control

Design Block, blockname. The value val can be any value that
is compatible with blockname without changing the size, type, or
sampling time of blockname.
For example, you can set the value of a tunable PID block
(ltiblock.pid) to a pid controller model , or to a transfer function (tf)
model that represents a PID controller.
blockvalues

Structure specifying Control Design Blocks of M0 to modify, and the

corresponding replacement values. The fields of the structure are the
names of the blocks to modify. The value of each field specifies the
replacement current or nominal value for the corresponding block.
Mref

Generalized Model that shares some Control Design Blocks with M0.
The values of these blocks in Mref are used to update their counterparts
in M0.

Output
Arguments

Examples

Update Controller Model with Tuned Values

Generalized Model obtained from M0 by updating the values of the

specified blocks.

Propagate the values of tuned parameters to other Control Design

Blocks.
You can use the Robust Control Toolbox tuning commands such as
systune, looptune, or hinfstruct to tune blocks in a closed-loop model
of a control system. If you do so, the tuned controller parameters are
embedded in a Generalized LTI Model. You can use setBlockValue to
propagate those parameters to a controller model.
Create a tunable model of the closed-loop response of a control system,
and tune the parameters using hinfstruct.

1-617

setBlockValue

G = tf([1,0.0007],[1,0.00034,0.00086]);
Cpi = ltiblock.pid('Cpi','pi');
a = realp('a',10);
F0 = tf(a,[1 a]);
C0 = Cpi*F0;
T0 = feedback(G*C0,1);
T = hinfstruct(T0);

The controller model C0 is a Generalized LTI model with two tunable

blocks, Cpi and a. The closed-loop model T0 is also a Generalized LTI
model with the same blocks. The model T contains the tuned values
of these blocks.
Propagate the tuned values of the controller in T to the controller model
C0.
C = setBlockValue(C0,T)
C =
Generalized continuous-time state-space model with 1 outputs,
1 inputs, 2 states, and the following blocks:
Cpi: Parametric PID controller, 1 occurrences.
a: Scalar parameter, 2 occurrences.
Type "ss(C)" to see the current value, "get(C)" to see all properties,
and "C.Blocks" to interact with the blocks.
C is still a Generalized model. The current value of the Control Design
Blocks in C are set to the values the corresponding blocks of T.

Obtain a Numeric LTI model of the controller with the tuned values
using getValue.
CVal = getValue(C0,T);

1-618

setBlockValue

This command returns a numerical state-space model of the tuned

controller.

See Also

getValue | getBlockValue | showBlockValue | genss | systune

| looptune | hinfstruct

1-619

setValue

Purpose

Modify current value of Control Design Block

Syntax

blk = setValue(blk0,val)

Description

blk = setValue(blk0,val) modifies the parameter values in the

tunable Control Design Block, blk0, to best match the values specified
by val. An exact match can only occur when val is compatible with
the structure of blk0.

Input
Arguments

blk0

Control Design Block whose value is modified.

val

Specifies the replacement parameters values for blk0. The value

val can be any value that is compatible with blk0 without changing
the size, type, or sampling time of blk0. For example, if blk0 is a
ltiblock.pid block, valid types for val include ltiblock.pid, a
numeric pid controller model, or a numeric tf model that represents
a PID controller. setValue uses the parameter values of val to set
the current value of blockname.

Output
Arguments

blk

See Also

getValue | setBlockValue | getBlockValue

1-620

Control Design Block of the same type as blk0, whose parameters are
updated to best match the parameters of val.

sgrid

Purpose

Generate s-plane grid of constant damping factors and natural

frequencies

Syntax

sgrid
sgrid(z,wn)

Description

sgrid generates, for pole-zero and root locus plots, a grid of constant
damping factors from zero to one in steps of 0.1 and natural frequencies
from zero to 10 rad/sec in steps of one rad/sec, and plots the grid over
the current axis. If the current axis contains a continuous s-plane root
locus diagram or pole-zero map, sgrid draws the grid over the plot.
sgrid(z,wn) plots a grid of constant damping factor and natural
frequency lines for the damping factors and natural frequencies in the
vectors z and wn, respectively. If the current axis contains a continuous
s-plane root locus diagram or pole-zero map, sgrid(z,wn) draws the
grid over the plot.

Alternatively, you can select Grid from the right-click menu to generate
the same s-plane grid.

Examples

Plot s-plane grid lines on the root locus for the following system.

H (s) =

2s2 + 5s + 1
s2 + 2s + 3

You can do this by typing

H = tf([2 5 1],[1 2 3])
Transfer function:
2 s^2 + 5 s + 1
--------------s^2 + 2 s + 3
rlocus(H)
sgrid

1-621

sgrid

See Also

1-622

pzmap | rlocus | zgrid

showBlockValue

Purpose

Display current value of Control Design Blocks in Generalized Model

Syntax

showBlockValue(M)

Description

showBlockValue(M) displays the current values of all Control Design

Blocks in the Generalized Model, M. (For uncertain blocks, the current
value is the nominal value of the block.)

Input
Arguments

Examples

Create a tunable genss model, and display the current value of its
tunable elements.

Generalized Model.

G
C
a
F
T

=
=
=
=
=

zpk([],[-1,-1],1);
ltiblock.pid('C','PID');
realp('a',10);
tf(a,[1 a]);
feedback(G*C,1)*F;

showBlockValue(T)
C =
Continuous-time I-only controller:
1
Ki * --s
With Ki = 0.001
----------------------------------a = 10

1-623

showBlockValue

Tips

Displaying the current values of a model is useful, for example, after

you have tuned the free parameters of the model using a Robust
Control Toolbox tuning command such as looptune.
showBlockValue displays the current values of all Control Design
Blocks in a model, including tunable, uncertain, and switch blocks.
To display the current values of only the tunable blocks, use
showTunable.

See Also

1-624

genss | getBlockValue | setBlockValue | showTunable

showTunable

Purpose

Display current value of tunable Control Design Blocks in Generalized

Model

Syntax

showTunable(M)

Description

showTunable(M) displays the current values of all tunable Control

Input
Arguments

M - Input model

Design Blocks in a generalized LTI model. Tunable control design blocks

are parametric blocks such as realp, ltiblock.tf, and ltiblock.pid.

generalized LTI model

Input model of which to display tunable block values, specified as a
generalized LTI model such as a genss model.

Examples

Display Block Values of Tuned Control System Model

Tune the following control system using systune, and display the
values of the tunable blocks.

+
-

F
The control structure includes a PI controller C and a tunable low-pass
filter in the feedback path. The plant G is a third-order system.
Create models of the system components and connect them together to
create a tunable closed-loop model of the control system.
s = tf('s');

1-625

showTunable

num = 33000*(s^2 - 200*s + 90000);

den = (s + 12.5)*(s^2 + 25*s + 63000);
G = num/den;
C0 = ltiblock.pid('C','pi');
a = realp('a',1);
F0 = tf(a,[1 a]);
X = loopswitch('X');
T0 = feedback(G*X*C0,F0);
T0.InputName = 'r';
T0.OutputName = 'y';
T0 is a genss model that has two tunable blocks, the PI controller, C,
and the parameter, a. T0 also contains the switch block X.

Create a tuning requirement that forces the output y to track the input
r, and tune the system to meet that requirement.
Req = TuningGoal.Tracking('r','y',0.05);
[T,fSoft,~] = systune(T0,Req);
systune finds values for the tunable parameters that optimally meet
the tracking requirement. The output T is a genss model with the
same Control Design Blocks as T0. The current values of those blocks

are the tuned values.

Examine the tuned values of the tunable blocks of the control system.
showTunable(T)
C =
1
Kp + Ki * --s
with Kp = 0.000433, Ki = 0.00527

1-626

showTunable

Name: C
Continuous-time PI controller in parallel form.
----------------------------------a = 68.6
showTunable displays the values of the tunable blocks only. If you use
showBlockValue instead, the display also includes the switch block X.

Tips

Displaying the current values of tunable blocks is useful, for example,

after you have tuned the free parameters of the model using a Robust
Control Toolbox tuning command such as systune.
showTunable displays the current values of the tunable blocks
only. To display the current values of all Control Design Blocks
in a model, including tunable, uncertain, and switch blocks, use
showBlockValue.

See Also

genss | getBlockValue | setBlockValue | showBlockValue | systune

Concepts

Generalized Models
Control Design Blocks

1-627

sigma

Purpose

Singular values plot of dynamic system

Syntax

sigma(sys)
sigma(sys,w)
sigma(sys,[],type)
sigma(sys,w,type)
sigma(sys1,sys2,...,sysN,w,type)
sigma(sys1,'PlotStyle1',...,sysN,'PlotStyleN',w,type)
sv = sigma(sys,w)
[sv,w] = sigma(sys)

Description

sigma calculates the singular values of the frequency response of

a dynamic system sys. For an FRD model, sigma computes the
singular values of sys.Response at the frequencies, sys.frequency.
For continuous-time TF, SS, or ZPK models with transfer function
H(s), sigma computes the singular values of H(j) as a function of the
frequency . For discrete-time TF, SS, or ZPK models with transfer
function H(z) and sample time Ts, sigma computes the singular values of

H ( e jTs )
for frequencies between 0 and the Nyquist frequency N = /Ts.
The singular values of the frequency response extend the Bode
magnitude response for MIMO systems and are useful in robustness
analysis. The singular value response of a SISO system is identical to
its Bode magnitude response. When invoked without output arguments,
sigma produces a singular value plot on the screen.
sigma(sys) plots the singular values of the frequency response of a
model sys. This model can be continuous or discrete, and SISO or

MIMO. The frequency points are chosen automatically based on the

system poles and zeros, or from sys.frequency if sys is an FRD.
sigma(sys,w) explicitly specifies the frequency range or frequency

points to be used for the plot. To focus on a particular frequency interval

[wmin,wmax], set w = {wmin,wmax}. To use particular frequency
points, set w to the corresponding vector of frequencies. Use logspace

1-628

sigma

to generate logarithmically spaced frequency vectors. Frequencies must

be in rad/TimeUnit, where TimeUnit is the time units of the input
dynamic system, specified in the TimeUnit property of sys.
sigma(sys,[],type) or sigma(sys,w,type) plots the following

modified singular value responses:

type = 1

Singular values of the frequency response H1, where H is

the frequency response of sys.

type = 2

Singular values of the frequency response I + H.

type = 3

Singular values of the frequency response I + H1.

These options are available only for square systems, that is, with the
same number of inputs and outputs.
sigma(sys1,sys2,...,sysN,w,type) plots the singular value plots of
several LTI models on a single figure. The arguments w and type are
optional. The models sys1,sys2,...,sysN need not have the same
number of inputs and outputs. Each model can be either continuousor discrete-time.
sigma(sys1,'PlotStyle1',...,sysN,'PlotStyleN',w,type)

specifies a distinctive color, linestyle, and/or marker for each system

plot. See bode for an example.
sv = sigma(sys,w) and [sv,w] = sigma(sys) return the singular
values sv of the frequency response at the frequencies w. For a system
with Nu input and Ny outputs, the array sv has min(Nu,Ny) rows and as
many columns as frequency points (length of w). The singular values
at the frequency w(k) are given by sv(:,k).

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Singular Values Plot of Dynamic System

Plot the singular value responses of

1-629

sigma

0
H (s) =
s+1
s + 5

s + s + 10
2

s + 6
3s

and I + H(s).
You can do this by typing
H = [0 tf([3 0],[1 1 10]) ; tf([1 1],[1 5]) tf(2,[1 6])]
subplot(211)
sigma(H)
subplot(212)
sigma(H,[],2)

1-630

sigma

Algorithms

sigma uses the MATLAB function svd to compute the singular values
of a complex matrix.

For TF, ZPK, and SS models, sigma computes the frequency response
using the freqresp algorithms. As a result, small discrepancies may
exist between the sigma responses for equivalent TF, ZPK, and SS
representations of a given model.

See Also

bode | evalfr | freqresp | ltiview | nichols | nyquist

1-631

sigmaoptions

Purpose

Create list of singular-value plot options

Syntax

P = sigmaoptions
P = sigmaoptions('cstprefs')

Description

P = sigmaoptions returns a list of available options for singular value

plots with default values set. You can use these options to customize
the singular value plot appearance from the command line.
P = sigmaoptions('cstprefs') initializes the plot options with the
options you selected in the Control System Toolbox Preferences Editor.
For more information about the editor, see Toolbox Preferences Editor
in the Users Guide documentation.

This table summarizes the sigma plot options.

1-632

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid

Show or hide the grid

Specified as one of the following
strings: 'off' | 'on'
Default: 'off'

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

IOGrouping

Grouping of input-output pairs

Specified as one of the
following strings: 'none'
|'inputs'|'output'|'all'
Default: 'none'

InputLabels, OutputLabels

Input and output label styles

InputVisible, OutputVisible

Visibility of input and output

channels

sigmaoptions

Option

Description

FreqUnits

Frequency units, specified as one

of the following strings:
'Hz'
'rad/second'
'rpm'
'kHz'
'MHz'
'GHz'
'rad/nanosecond'
'rad/microsecond'
'rad/millisecond'
'rad/minute'
'rad/hour'
'rad/day'
'rad/week'
'rad/month'
'rad/year'
'cycles/nanosecond'
'cycles/microsecond'
'cycles/millisecond'
'cycles/hour'
'cycles/day'
'cycles/week'
'cycles/month'

1-633

sigmaoptions

Option

Description
'cycles/year'
Default: 'rad/s'
You can also specify 'auto'
which uses frequency units
rad/TimeUnit relative to system
time units specified in the
TimeUnit property. For multiple
systems with different time units,
the units of the first system are
used.

Examples

FreqScale

Frequency scale
Specified as one of the following
strings: 'linear' | 'log'
Default: 'log'

MagUnits

Magnitude units
Specified as one of the following
strings: 'dB' | 'abs'
Default: 'dB'

MagScale

Magnitude scale
Specified as one of the following
strings: 'linear' | 'log'
Default: 'linear'

In this example, set the frequency units to Hz before creating a plot.

P = sigmaoptions; % Set the frequency units to Hz in options
P.FreqUnits = 'Hz'; % Create plot with the options specified by P
h = sigmaplot(rss(2,2,3),P);

The following singular value plot is created with the frequency units in
Hz.

1-634

sigmaoptions

See Also

getoptions | setoptions | sigmaplot

1-635

sigmaplot

Purpose

Plot singular values of frequency response and return plot handle

Syntax

h = sigmaplot(sys)
sigmaplot(sys,{wmin,wmax})
sigmaplot(sys,w)
sigmaplot(sys,w,TYPE)
sigmaplot(AX,...)
sigmaplot(..., plotoptions)

Description

h = sigmaplot(sys) produces a singular value (SV) plot of the

frequency response of the dynamic system sys. It also returns the
plot handle h. You can use this handle to customize the plot with the
getoptions and setoptions commands. Type
help sigmaoptions

for a list of available plot options.

The frequency range and number of points are chosen automatically.
See bode for details on the notion of frequency in discrete time.
sigmaplot(sys,{wmin,wmax}) draws the SV plot for frequencies
ranging between wmin and wmax (in rad/TimeUnit, where TimeUnit is
the time units of the input dynamic system, specified in the TimeUnit
property of sys).
sigmaplot(sys,w) uses the user-supplied vector w of frequencies, in
rad/TimeUnit, at which the frequency response is to be evaluated. See
logspace to generate logarithmically spaced frequency vectors.
sigmaplot(sys,w,TYPE) or sigmaplot(sys,[],TYPE) draws the
following modified SV plots depending on the value of TYPE:

1-636

TYPE = 1

-->

SV of inv(SYS)

TYPE = 2

-->

SV of I + SYS

TYPE = 3

-->

SV of I + inv(SYS)

sigmaplot

sys should be a square system when using this syntax.

sigmaplot(AX,...) plots into the axes with handle AX.
sigmaplot(..., plotoptions) plots the singular values with the
options specified in plotoptions. Type
help sigmaoptions

for more details.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Use the plot handle to change the units to Hz.

sys = rss(5);
h = sigmaplot(sys);
% Change units to Hz.
setoptions(h,'FreqUnits','Hz');

See Also

getoptions | setoptions | sigma | sigmaoptions

1-637

sisoinit

Purpose

Configure SISO Design Tool at startup

Syntax

init_config = sisoinit(config)

Description

init_config = sisoinit(config) returns a template init_config

for initializing Graphical Tuning window of the SISO Design Tool with
the one of the following control system configurations:

config corresponds to the control system configuration. Available

configurations include:

config = 1 (default) C in forward path, F in series

config = 2 C in feedback path, F in series
config = 3 C in forward path, feedforward F
config = 4 Nested loop configuration

1-638

sisoinit

config = 5 Internal model control (IMC) structure

config = 6 Cascade loop configuration
For each configuration, you can specify the plant models G and H,
initialize the compensator C and prefilter F, and configure the openand closed-loop views by specifying the corresponding fields of the
structure init_config. Then use sisotool(init_config) to start the
SISO Design Tool in the specified configuration.
Output argument init_config is an object with properties. The
following tables list the block and loop properties.
Block Properties
Block

Properties

Values

Name

String

Description

String

Value

LTI object

Name

String

Value

LTI object

Row or column array of LTI objects. If

the sensor H is also an array of LTI
objects, the lengths of G and H must
match.
H

Name

String

Value

LTI object
Row or column array of LTI objects.
If the plant G is also an array of LTI
objects, the lengths of H and G must
match.

1-639

sisoinit

Block Properties (Continued)

Block

Properties

Values

Name

String

Description

String

Value

LTI object

Loop Properties
Loops

Properties

Values

OL1

Name
Description
View

String
String

Name
Description
View

String
String

CL1

Examples

'rlocus' 'bode'

'bode'

Initialize SISO Design Tool with C in feedback path using an LTI model:
% Single-loop configuration with C in the feedback path.
T = sisoinit(2);
% Model for plant G.
T.G.Value = tf(1, [1 1]);
% Initial compensator value.
T.C.Value = tf(1,[1 2]);
% Views for tuning Open-Loop OL1.
T.OL1.View = {'rlocus','nichols'};
% Launch SISO Design Tool using configuration T
sisotool(T)

1-640

sisoinit

Initialize SISO Design Tool with C in feedback path using an array

of LTI models:
% Specify an initial configuration.
initconfig = sisoinit(2);
% Specify model parameters.
m = 3;
b = 0.5;
k = 8:1:10;
T = 0.1:.05:.2;
% Create an LTI array to model variations in plant G.
for ct = 1:length(k);
G(:,:,ct) = tf(1,[m,b,k(ct)]);
end
% Assign G to the initial configuration.
initconfig.G.Value = G;
% Create an LTI array to model variations in sensor H.
for ct = 1:length(T);
H(:,:,ct) = tf(1,[1/T(ct), 1]);
end
% Assign H to the initial configuration.
initconfig.H.Value = H;
% Specify initial controller.
initconfig.C.Value = tf(1,[1 2]);
% Views for tuning Open-Loop (OL1)
initconfig.OL1.View = {'rlocus','bode'};
% Launch SISO Design Tool using initconfig.
sisotool(initconfig)

See Also

sisotool

How To

SISO Design Tool

Control Design Analysis of Multiple Models

1-641

sisotool

Purpose

Interactively design and tune SISO feedback loops

Syntax

sisotool
sisotool(plant)
sisotool(plant,comp)

sisotool(plant,comp,sensor,prefilt)
sisotool(views)
sisotool(views,plant,comp)
sisotool(initdata)
sisotool(sessiondata)

Description

sisotool opens a SISO Design GUI for interactive compensator design.

This GUI allows you to design a single-input/single-output (SISO)
compensator using root locus, Bode diagram, Nichols and Nyquist
techniques. You can also automatically design a compensator using
this GUI.

By default, the SISO Design Tool:

Opens the Control and Estimation Tools Manager with a default
SISO Design Task node.
Opens the Graphical Tuning editor with root locus and open-loop
Bode diagrams.
Places the compensator, C, in the forward path in series with the
plant, G.
Assumes the prefilter, F, and the sensor, H, are unity gains. Once
you specify G and H, they are fixed in the feedback structure.
The default control architecture is shown in this figure.

1-642

sisotool

There are six control architectures available. See sisoinit for more
information.
This picture shows the SISO Design Graphical editor.

1-643

sisotool

sisotool(plant) opens the SISO Design Tool, imports plant, and

initializes the plant model G to plant. plant can be any SISO LTI
model created with ss, tf, zpk or frd, or a row or column array of LTI

models.
sisotool(plant,comp) initializes the plant model G to plant, the

compensator C to comp. comp is an LTI object.

sisotool(plant,comp,sensor,prefilt) initializes the plant G to
plant, compensator C to comp, sensor H to sensor, and the prefilter F
to prefilt. sensor is an LTI object or a row or column array of LTI
objects. If plant is also an array of LTI objects, the lengths of sensor
and plant must match. prefilt is an LTI object.
sisotool(views) or sisotool(views,plant,comp) specifies the initial
configuration of the SISO Design Tool. views can be any of the following

strings (or combination thereof):

'rlocus' Root Locus plot
'bode' Bode diagrams of the open-loop response
'nichols' Nichols plot
'filter' Bode diagrams of the prefilter F and the closed-loop
response from the command into F to the output of the plant G .
For example
sisotool('bode')

opens a SISO Design Tool with only the Bode Diagrams. If there is
more than one view, the views are specified in a cell array.
sisotool(initdata) initializes the SISO Design Tool with more
general control system configurations. Use sisoinit to create the
initialization data structure initdata.
sisotool(sessiondata) opens the SISO Design Tool with a previously
saved session where sessiondata is the MAT-file for the saved session.

1-644

sisotool

Examples

Launch SISO Design Tool GUI in default configuration using LTI

models:
% Create plant G.
G = tf(1, [1 1]);
% Create controller C.
C = tf(1,[1 2]);
% Launch the GUI.
sisotool(G,C)

Launch SISO Design Tool GUI in default configuration using an array

of LTI models:
% Specify model parameters.
m = 3;
b = 0.5;
k = 8:1:10;
T = 0.1:.05:.2;
% Create an LTI array to model variations in plant G.
for ct = 1:length(k);
G(:,:,ct) = tf(1,[m,b,k(ct)]);
end
% Create an LTI array to model variations in sensor H.
for ct = 1:length(T);
H(:,:,ct) = tf(1,[1/T(ct), 1]);
end
% Create a controller C.
C = tf(1,[1 2]);
% Launch the GUI.
sisotool(G,C,H)

See Also

bode | ltiview | rlocus | nichols |

Tutorials

How to Analyze the Controller Design for Multiple Models

Bode Diagram Design

1-645

sisotool

Root Locus Design

Nichols Plot Design
Position Control of a DC Motor

How To

1-646

SISO Design Tool

size

Purpose

Query output/input/array dimensions of inputoutput model and

number of frequencies of FRD model

Syntax

size(sys)
d = size(sys)
Ny = size(sys,1)
Nu = size(sys,2)
Sk = size(sys,2+k)
Nf = size(sys,'frequency')

Description

When invoked without output arguments, size(sys) returns a

description of type and the input-output dimensions of sys. If sys is a
model array, the array size is also described. For identified models,
the number of free parameters is also displayed. The lengths of the
array dimensions are also included in the response to size when sys is
a model array.
d = size(sys) returns:

The row vector d = [Ny Nu] for a single dynamic model sys with
Ny outputs and Nu inputs
The row vector d = [Ny Nu S1 S2 ... Sp] for an
S1-by-S2-by-...-by-Sp array of dynamic models with Ny outputs and Nu
inputs
Ny = size(sys,1) returns the number of outputs of sys.
Nu = size(sys,2) returns the number of inputs of sys.
Sk = size(sys,2+k) returns the length of the k-th array dimension
when sys is a model array.
Nf = size(sys,'frequency') returns the number of frequencies
when sys is a frequency response data model. This is the same as the
length of sys.frequency.

Examples

Example 1
Consider the model array of random state-space models

1-647

size

sys = rss(5,3,2,3);

Its dimensions are obtained by typing

size(sys)
3x1 array of state-space models
Each model has 3 outputs, 2 inputs, and 5 states.

Example 2
Consider the process model:
sys = idproc({'p1d', 'p2'; 'p3uz', 'p0'});

Its input-output dimensions and number of free parameters are

obtained by typing:
size(sys)

Process model with 2 outputs, 2 inputs and 12 free parameters.

See Also

1-648

isempty | issiso | ndims

sminreal

Purpose

Structural pole/zero cancellations

Syntax

msys = sminreal(sys)

Description

msys = sminreal(sys) eliminates the states of the state-space model

sys that dont affect the input/output response. All of the states of
the resulting state-space model msys are also states of sys and the
input/output response of msys is equivalent to that of sys.

sminreal eliminates only structurally non minimal states, i.e., states

that can be discarded by looking only at hard zero entries in the A,
B, and C matrices. Such structurally nonminimal states arise, for
example, when linearizing a Simulink model that includes some
unconnected state-space or transfer function blocks.

Tips

The model resulting from sminreal(sys) is not necessarily minimal,

and may have a higher order than one resulting from minreal(sys).
However, sminreal(sys) retains the state structure of sys, while, in
general, minreal(sys) does not.

Examples

Suppose you concatenate two SS models, sys1 and sys2.

sys = [sys1,sys2];

This operation is depicted in the diagram below.

If you extract the subsystem sys1 from sys, with

sys(1,1)

1-649

sminreal

all of the states of sys, including those of sys2 are retained. To

eliminate the unobservable states from sys2, while retaining the states
of sys1, type
sminreal(sys(1,1))

See Also

1-650

minreal

ss

Purpose

Create state-space model, convert to state-space model

Syntax

sys = ss(a,b,c,d)
sys = ss(a,b,c,d,Ts)
sys = ss(d)
sys = ss(a,b,c,d,ltisys)
sys_ss = ss(sys)
sys_ss = ss(sys,'minimal')
sys_ss = ss(sys,'explicit')
sys_ss = ss(sys, 'measured')
sys_ss = ss(sys, 'noise')
sys_ss = ss(sys, 'augmented')

Description

Use ss to create state-space models (ss model objects) with real- or

complex-valued matrices or to convert dynamic system models to
state-space model form. You can also use ss to create Generalized
state-space (genss) models.

Creation of State-Space Models

sys = ss(a,b,c,d) creates a state-space model object representing
the continuous-time state-space model

x = Ax + Bu
y = Cx + Du
For a model with Nx states, Ny outputs, and Nu inputs:
a is an Nx-by-Nx real- or complex-valued matrix.
b is an Nx-by-Nu real- or complex-valued matrix.
c is an Ny-by-Nx real- or complex-valued matrix.
d is an Ny-by-Nu real- or complex-valued matrix.
To set D = 0 , set d to the scalar 0 (zero), regardless of the dimension.
sys = ss(a,b,c,d,Ts) creates the discrete-time model

1-651

ss

x[ n + 1] = Ax[ n] + Bu[ n]
y[ n] = Cx[ n] + Du[ n]
with sample time Ts (in seconds). Set Ts = -1 or Ts = [] to leave the
sample time unspecified.
sys = ss(d) specifies a static gain matrix D and is equivalent to
sys = ss([],[],[],d)
sys = ss(a,b,c,d,ltisys) creates a state-space model with
properties inherited from the model ltisys (including the sample time).

Any of the previous syntaxes can be followed by property name/property

value pairs.
'PropertyName',PropertyValue

Each pair specifies a particular property of the model, for example,

the input names or some notes on the model history. See Properties
on page 1-654 for more information about available ss model object
properties.
The following expression:
sys = ss(a,b,c,d,'Property1',Value1,...,'PropertyN',ValueN)

is equivalent to the sequence of commands:

sys = ss(a,b,c,d)
set(sys,'Property1',Value1,...,'PropertyN',ValueN)

Conversion to State Space

sys_ss = ss(sys) converts a dynamic system model sys to state-space
form. The output sys_ss is an equivalent state-space model (ss model
object). This operation is known as state-space realization.

1-652

ss

sys_ss = ss(sys,'minimal') produces a state-space realization with

no uncontrollable or unobservable states. This state-space realization is

equivalent to sys_ss = minreal(ss(sys)).
sys_ss = ss(sys,'explicit') computes an explicit realization (E =
I) of the dynamic system model sys. If sys is improper, ss returns
an error.

Note Conversions to state space are not uniquely defined in the SISO
case. They are also not guaranteed to produce a minimal realization
in the MIMO case. For more information, see Recommended Working
Representation.

Conversion of Identified Models

An identified model is represented by an input-output equation of the
form y(t) = Gu(t) + He(t) , where u(t) is the set of measured input
channels and e(t) represents the noise channels. If = LL represents
the covariance of noise e(t), this equation can also be written as

y(t) = Gu(t) + HLv(t) , where cov(v(t)) = I .

sys_ss = ss(sys) or sys_ss = ss(sys, 'measured') converts the
measured component of an identified linear model into the state-space
form. sys is a model of type idss, idproc, idtf, idpoly, or idgrey.
sys_ss represents the relationship between u and y.
sys_ss = ss(sys, 'noise') converts the noise component of an
identified linear model into the state space form. It represents the
relationship between the noise input v(t) and output y_noise = HL
v(t). The noise input channels belong to the InputGroup Noise. The
names of the noise input channels are v@yname, where yname is the
name of the corresponding output channel. sys_ss has as many inputs
as outputs.
sys_ss = ss(sys, 'augmented') converts both the measured
and noise dynamics into a state-space model. sys_ss has ny+nu

inputs such that the first nu inputs represent the channels u(t)

1-653

ss

while the remaining by channels represent the noise channels

v(t). sys_ss.InputGroup contains 2 input groups- 'measured'
and 'noise'. sys_ss.InputGroup.Measured is set to 1:nu while
sys_ss.InputGroup.Noise is set to nu+1:nu+ny. sys_ss represents
the equation y(t) = [G HL] [u; v]
Tip An identified nonlinear model cannot be converted into a
state-space form. Use linear approximation functions such as
linearize and linapp.

Creation of Generalized State-Space Models

You can use the syntax:
gensys = ss(A,B,C,D)

to create a Generalized state-space (genss) model when one or more of

the matrices A, B, C, D is a tunable realp or genmat model. For more
information about Generalized state-space models, see Models with
Tunable Coefficients.

Properties

ss objects have the following properties:

a,b,c,d,e

State-space matrices.
a State matrix A. Square real- or complex-valued matrix with
as many rows as states.
b Input-to-state matrix B. Real- or complex-valued matrix with as
many rows as states and as many columns as inputs.
c State-to-output matrix C. Real- or complex-valued matrix with
as many rows as outputs and as many columns as states.
d Feedthrough matrix D. Real- or complex-valued matrix with as
many rows as outputs and as many columns as inputs.

1-654

ss

e E matrix for implicit (descriptor) state-space models. By default

e = [], meaning that the state equation is explicit. To specify an
implicit state equation E dx/dt = Ax + Bu, set this property to a
square matrix of the same size as a. See dss for more information
about creating descriptor state-space models.
Scaled

Logical value indicating whether scaling is enabled or disabled.

When Scaled = 0 (false), most numerical algorithms acting on the
state-space model automatically rescale the state vector to improve
numerical accuracy. You can disable such auto-scaling by setting
Scaled = 1 (true). For more information about scaling, see prescale.
Default: 0 (false)
StateName

State names. For first-order models, set StateName to a string. For

models with two or more states, set StateName to a cell array of strings
. Use an empty string '' for unnamed states.
Default: Empty string '' for all states
StateUnit

State units. Use StateUnit to keep track of the units each state is
expressed in. For first-order models, set StateUnit to a string. For
models with two or more states, set StateUnit to a cell array of strings.
StateUnit has no effect on system behavior.
Default: Empty string '' for all states
InternalDelay

Vector storing internal delays.

Internal delays arise, for example, when closing feedback loops on
systems with delays, or when connecting delayed systems in series or

1-655

ss

parallel. For more information about internal delays, see Closing

Feedback Loops with Time Delays in the Control System Toolbox Users
Guide.
For continuous-time models, internal delays are expressed in the time
unit specified by the TimeUnit property of the model. For discrete-time
models, internal delays are expressed as integer multiples of the
sampling period Ts. For example, InternalDelay = 3 means a delay
of three sampling periods.
You can modify the values of internal delays. However, the number of
entries in sys.InternalDelay cannot change, because it is a structural
property of the model.
InputDelay - Input delays
0 (default) | scalar | vector

Input delay for each input channel, specified as a numeric vector. For
continuous-time systems, specify input delays in the time unit stored
in the TimeUnit property. For discrete-time systems, specify input
delays in integer multiples of the sampling period Ts. For example,
InputDelay = 3 means a delay of three sampling periods.
For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each
entry of this vector is a numerical value that represents the input delay
for the corresponding input channel.
You can also set InputDelay to a scalar value to apply the same delay
to all channels.
OutputDelay

Output delays. OutputDelay is a numeric vector specifying a time

delay for each output channel. For continuous-time systems, specify
output delays in the time unit stored in the TimeUnit property. For
discrete-time systems, specify output delays in integer multiples of the
sampling period Ts. For example, OutputDelay = 3 means a delay
of three sampling periods.

1-656

ss

For a system with Ny outputs, set OutputDelay to an Ny-by-1 vector,

where each entry is a numerical value representing the output delay for
the corresponding output channel. You can also set OutputDelay to a
scalar value to apply the same delay to all channels.
Default: 0 for all output channels
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'

1-657

ss

'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input

1-658

ss

model, set InputUnit to a cell array of strings. InputUnit has no effect

on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.

1-659

ss

You can use the shorthand notation y to refer to the OutputName

property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

1-660

ss

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.

1-661

ss

sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Algorithms

1-662

For TF to SS model conversion, ss(sys_tf) returns a modified version

of the controllable canonical form. It uses an algorithm similar to tf2ss,
but further rescales the state vector to compress the numerical range in
state matrix A and to improve numerics in subsequent computations.

ss

For ZPK to SS conversion, ss(sys_zpk) uses direct form II structures,

as defined in signal processing texts. See Discrete-Time Signal
Processing by Oppenheim and Schafer for details.
For example, in the following code, A and sys.a differ by a diagonal
state transformation:
n=[1 1];
d=[1 1 10];
[A,B,C,D]=tf2ss(n,d);
sys=ss(tf(n,d));
A
A =
-1
1

-10
0

sys.a
ans =
-1
2

-5
0

For details, see balance.

Examples

Example 1
Discrete-Time State-Space Model
Create a state-space model with a sampling time of 0.25 s and the
following state-space matrices:

0 1
A=

5 2

0
B=
3

C = [ 0 1]

D = [0]

To do this, enter the following commands:

1-663

ss

A =
B =
C =
D =
sys

[0 1;-5 -2];
[0;3];
[0 1];
0;
= ss(A,B,C,D,0.25);

The last argument sets the sampling time.

Example 2
Discrete-Time State-Space Model with Custom State and Input
Names
Create a discrete-time model with matrices A,B,C,D and sample time
0.05 second.
sys = ss(A,B,C,D,0.05,'statename',{'position' 'velocity'},...
'inputname','force',...
'notes','Created 01/16/11');

This model has two states labeled position and velocity, and one
input labeled force (the dimensions of A,B,C,D should be consistent
with these numbers of states and inputs). Finally, a note is attached
with the date of creation of the model.

Example 3
Convert Transfer Function Model to State-Space Model
Convert a transfer function model to a state-space model.

s+1

2
s + 3s + 3s + 2
H ( s) =

s2 + 3

2
s + s+1

by typing
H = [tf([1 1],[1 3 3 2]) ; tf([1 0 3],[1 1 1])];
sys = ss(H);

1-664

ss

size(sys)
State-space model with 2 outputs, 1 input, and 5 states.

The number of states is equal to the cumulative order of the SISO

entries of H(s).
To obtain a minimal realization of H(s), type
sys = ss(H,'min');
size(sys)
State-space model with 2 outputs, 1 input, and 3 states.

The resulting state-space model has order of three, which is the

minimum number of states needed to represent H(s). You can see this
number of states by factoring H(s) as the product of a first-order system
with a second-order system.

s+1
1
2

0 s + s + 1
H (s) = s + 2

1 s + 3
0
2
s + s + 1

Example 4
Descriptor State-Space Model
Create a descriptor state-space model.
a = [2 -4; 4 2];
b = [-1; 0.5];
c = [-0.5, -2];
d = [-1];
e = [1 0; -3 0.5];
% Create a descriptor state-space model.
sys1 = dss(a,b,c,d,e);
% Compute an explicit realization.
sys2 = ss(sys1,'explicit')

1-665

ss

These commands produce the result:

a =
x1
x2

x1
2
20

x2
-4
-20

b =
x1
x2

u1
-1
-5

y1

x1
-0.5

y1

u1
-1

c =
x2
-2

d =

Continuous-time model.

The result is an explicit state-space model (E = I). A Bode plot shows

that sys1 and sys2 are equivalent.
bode(sys1,sys2)

1-666

ss

Example 5
Generalized State-Space Model
This example shows how to create a state-space (genss) model having
both fixed and tunable parameters.
Create a state-space model having the following state-space matrices:

1 a b
A
,
0 ab

3.0
B
,
1 .5

C 0 .3 0 ,

D 0,

where a and b are tunable parameters, whose initial values are 1 and
3, respectively.
1 Create the tunable parameters using realp.

a = realp('a',-1);

1-667

ss

b = realp('b',3);
2 Define a generalized matrix using algebraic expressions of a and b.

A = [1 a+b;0 a*b]
A is a generalized matrix whose Blocks property contains a and b.
The initial value of A is M = [1 2;0 -3], from the initial values of
a and b.
3 Create the fixed-value state-space matrices.

B = [-3.0;1.5];
C = [0.3 0];
D = 0;
4 Use ss to create the state-space model.

sys = ss(A,B,C,D)
sys is a generalized LTI model (genss) with tunable parameters a and b.

Example 6
Extract the measured and noise components of an identified polynomial
model into two separate state-space models. The former (measured
component) can serve as a plant model while the latter can serve as a
disturbance model for control system design.
load icEngine
z = iddata(y,u,0.04);
sys = ssest(z, 3);
sysMeas = ss(sys, 'measured')
sysNoise = ss(sys, 'noise')

Alternatively, use can simply use ss(sys) to extract the measured

component.

1-668

ss

See Also

dss | frd | get | set | ssdata | tf | zpk

Tutorials

State-Space Model
MIMO State-Space Model

How To

What Are Model Objects?

State-Space Models

1-669

ss2ss

Purpose

State coordinate transformation for state-space model

Syntax

sysT = ss2ss(sys,T)

Description

Given a state-space model sys with equations

x Ax Bu
y Cx Du
or the innovations form used by the identified state-space (IDSS)
models:

dx
Ax Bu Ke
dt
y Cx Du e
(or their discrete-time counterpart), ss2ss performs the similarity
transformation x = Tx on the state vector x and produces the equivalent
state-space model sysT with equations.

x = TAT 1 x + TBu
y = CT 1 x + Du
or, in the case of an IDSS model:

x TAT 1 x TBu TKe

y CT 1 x Du e
(IDSS models require System Identification Toolbox software.)
sysT = ss2ss(sys,T) returns the transformed state-space model sysT
given sys and the state coordinate transformation T. The model sys
must be in state-space form and the matrix T must be invertible. ss2ss

is applicable to both continuous- and discrete-time models.

1-670

ss2ss

Examples

Perform a similarity transform to improve the conditioning of the A

matrix.
T = balance(sys.a)
sysb = ss2ss(sys,inv(T))

See Also

balreal | canon

1-671

ssdata

Purpose

Access state-space model data

Syntax

[a,b,c,d] = ssdata(sys)

[a,b,c,d,Ts] = ssdata(sys)

Description

[a,b,c,d] = ssdata(sys) extracts the matrix (or multidimensional

array) data A, B, C, D from the state-space model (LTI array) sys. If sys
is a transfer function or zero-pole-gain model (LTI array), it is first
converted to state space. See ss for more information on the format
of state-space model data.

If sys appears in descriptor form (nonempty E matrix), an equivalent

explicit form is first derived.
If sys has internal delays, A, B, C, D are obtained by first setting all
internal delays to zero (creating a zero-order Pad approximation).
For some systems, setting delays to zero creates singular algebraic
loops, which result in either improper or ill-defined, zero-delay
approximations. For these systems, ssdata cannot display the matrices
and returns an error. This error does not imply a problem with the
model sys itself.
[a,b,c,d,Ts] = ssdata(sys) also returns the sample time Ts.

You can access the remaining LTI properties of sys with get or by
direct referencing. For example:
sys.statename

For arrays of state-space models with variable numbers of states, use

the syntax:
[a,b,c,d] = ssdata(sys,'cell')

to extract the state-space matrices of each model as separate cells in the

cell arrays a, b, c, and d.

See Also

1-672

dssdata | get | getdelaymodel | set | ss | tfdata | zpkdata

stabsep

Purpose

Stable-unstable decomposition

Syntax

[GS,GNS]=stabsep(G)
[G1,GNS] = stabsep(G,'abstol',ATOL,'reltol',RTOL)
[G1,G2]=stabsep(G, ...,'Mode', MODE,'Offset', ALPHA)
[G1,G2] = stabsep(G, opts)

Description

[GS,GNS]=stabsep(G) decomposes the LTI model G into its stable and

unstable parts
G = GS + GNS

where GS contains all stable modes that can be separated from the
unstable modes in a numerically stable way, and GNS contains the
remaining modes. GNS is always strictly proper.
[G1,GNS] = stabsep(G,'abstol',ATOL,'reltol',RTOL) specifies
absolute and relative error tolerances for the stable/unstable
decomposition. The frequency responses of G and GS + GNS should differ
by no more than ATOL+RTOL*abs(G). Increasing these tolerances helps
separate nearby stable and unstable modes at the expense of accuracy.
The default values are ATOL=0 and RTOL=1e-8.
[G1,G2]=stabsep(G, ...,'Mode', MODE,'Offset', ALPHA) produces
a more general stable/unstable decomposition where G1 includes all
separable poles lying in the regions defined using offset ALPHA. This can
be useful when there are numerical accuracy issues. For example, if you
have a pair of poles close to, but slightly to the left of the j-axis, you
can decide not to include them in the stable part of the decomposition
if numerical considerations lead you to believe that the poles may be
in fact unstable

This table lists the stable/unstable boundaries as defined by the offset

ALPHA.

1-673

stabsep

Mode Continuous Time Region

Discrete Time Region

Re(s)<-ALPHA*max(1,|Im(s)|)

1 |z| < 1-ALPHA

Re(s)> ALPHA*max(1,|Im(s)|)

2 |z| > 1+ALPHA

The default values are MODE=1 and ALPHA=0.

[G1,G2] = stabsep(G, opts) computes the stable/unstable
decomposition of G using the options specified in the stabsepOptions
object opts.

Examples

Compute a stable/unstable decomposition with absolute error no larger

than 1e-5 and an offset of 0.1:
h = zpk(1,[-2 -1 1 -0.001],0.1)
[hs,hns] = stabsep(h,stabsepOptions('AbsTol',1e-5,'Offset',0.1));

The stable part of the decomposition has poles at -1 and -2.

hs
Zero/pole/gain:
-0.050075 (s+2.999)
------------------(s+1) (s+2)

The unstable part of the decomposition has poles at +1 and -.001 (which
is nominally stable).
hns
Zero/pole/gain:
0.050075 (s-1)
--------------(s+0.001) (s-1)

See Also

1-674

stabsepOptions | modsep

stabsepOptions

Purpose

Options for stable-unstable decomposition

Syntax

opts = stabsepOptions
opts = stabsepOptions('OptionName', OptionValue)

Description

opts = stabsepOptions returns the default options for the stabsep

command.
opts = stabsepOptions('OptionName', OptionValue) accepts one
or more comma-separated name/value pairs. Specify OptionName inside
single quotes.

Input
Arguments

Name-Value Pair Arguments

Focus

Focus of decomposition. Specified as one of the following values:

'stable'

First output of stabsep contains only stable

dynamics.

'unstable'

First output of stabsep contains only unstable

dynamics.

Default: 'stable'
AbsTol, RelTol

Absolute and relative error tolerance for stable/unstable decomposition.

Positive scalar values. When decomposing a model G, stabsep ensures
that the frequency responses of G and GS + GU differ by no more than
AbsTol + RelTol*abs(G). Increasing these tolerances helps separate
nearby stable and unstable modes at the expense of accuracy. See
stabsep for more information.
Default: AbsTol = 0; RelTol = 1e-8
Offset

1-675

stabsepOptions

Offset for the stable/unstable boundary. Positive scalar value. The first
output of stabsepincludes only poles satisfying:
Continuous time:
Re(s) < -Offset * max(1,|Im(s)|) (Focus = 'stable')
Re(s) > Offset * max(1,|Im(s)|) (Focus = 'unstable')
Discrete time:
|z| < 1 - Offset (Focus = 'stable')
|z| >1 + Offset (Focus = 'unstable')
Increase the value of Offset to treat poles close to the stability
boundary as unstable.
Default: 0
For additional information on the options and how to use them, see
the stabsep reference page.

Examples

Compute the stable/unstable decomposition of the system given by:

G ( s) =

10 ( s + 0.5 )

( s + 10 ) ( s + 2 5i) ( s + 2 + 5i)
6

Use the Offset option to force stabsep to exclude the pole at s = 106
from the stable term of the stable/unstable decomposition.
G = zpk(-.5,[-1e-6 -2+5i -2-5i],10);
opts = stabsepOptions('Offset',.001); % Create option set
[G1,G2] = stabsep(G,opts)
% treats -1e-6 as unstable

These commands return the result:

Zero/pole/gain:
-0.17241 (s-54)
---------------

1-676

stabsepOptions

(s^2 + 4s + 29)

Zero/pole/gain:
0.17241
---------(s+1e-006)

The pole at s = 106 is in the second (unstable) output.

See Also

stabsep

1-677

stack

Purpose

Build model array by stacking models or model arrays along array

dimensions

Syntax

sys = stack(arraydim,sys1,sys2,...)

Description

sys = stack(arraydim,sys1,sys2,...) produces an array of

dynamic system models sys by stacking (concatenating) the models
(or arrays) sys1,sys2,... along the array dimension arraydim. All

models must have the same number of inputs and outputs (the same
I/O dimensions), but the number of states can vary. The I/O dimensions
are not counted in the array dimensions. For more information about
model arrays and array dimensions, see Model Arrays.
For arrays of state-space models with variable order, you cannot use the
dot operator (e.g., sys.a) to access arrays. Use the syntax
[a,b,c,d] = ssdata(sys,'cell')

to extract the state-space matrices of each model as separate cells in the

cell arrays a, b, c, and d.

Examples

Example 1
If sys1 and sys2 are two models:
stack(1,sys1,sys2) produces a 2-by-1 model array.
stack(2,sys1,sys2) produces a 1-by-2 model array.
stack(3,sys1,sys2) produces a 1-by-1-by-2 model array.

Example 2
Stack identified state-space models derived from the same estimation
data and compare their bode responses.
load iddata1 z1
sysc = cell(1,5);
opt = ssestOptions('Focus','simulation');
for i = 1:5

1-678

stack

sysc{i} = ssest(z1,i-1,opt);
end
sysArray = stack(1, sysc{:});
bode(sysArray);

1-679

step

Purpose

Step response plot of dynamic system

Syntax

step(sys)
step(sys,Tfinal)
step(sys,t)
step(sys1,sys2,...,sysN)
step(sys1,sys2,...,sysN,Tfinal)
step(sys1,sys2,...,sysN,t)
y = step(sys,t)
[y,t] = step(sys)
[y,t] = step(sys,Tfinal)
[y,t,x] = step(sys)
[y,t,x,ysd] = step(sys)
[y,...] = step(sys,...,options)

Description

step calculates the step response of a dynamic system. For the state
space case, zero initial state is assumed. When it is invoked with no
output arguments, this function plots the step response on the screen.
step(sys) plots the step response of an arbitrary dynamic system
model sys. This model can be continuous or discrete, and SISO or

MIMO. The step response of multi-input systems is the collection of

step responses for each input channel. The duration of simulation is
determined automatically, based on the system poles and zeros.
step(sys,Tfinal) simulates the step response from t = 0 to the
final time t = Tfinal. Express Tfinal in the system time units,
specified in the TimeUnit property of sys. For discrete-time systems
with unspecified sampling time (Ts = -1), step interprets Tfinal as
the number of sampling periods to simulate.
step(sys,t) uses the user-supplied time vector t for simulation.
Express t in the system time units, specified in the TimeUnit property
of sys. For discrete-time models, t should be of the form Ti:Ts:Tf,
where Ts is the sample time. For continuous-time models, t should
be of the form Ti:dt:Tf, where dt becomes the sample time of a

discrete approximation to the continuous system (see Algorithms on

1-680

step

page 1-687). The step command always applies the step input at t=0,
regardless of Ti.
To plot the step response of several modelssys1,..., sysN on a single
figure, use
step(sys1,sys2,...,sysN)
step(sys1,sys2,...,sysN,Tfinal)
step(sys1,sys2,...,sysN,t)

All of the systems plotted on a single plot must have the same number
of inputs and outputs. You can, however, plot a mix of continuous- and
discrete-time systems on a single plot. This syntax is useful to compare
the step responses of multiple systems.
You can also specify a distinctive color, linestyle, marker, or all three
for each system. For example,
step(sys1,'y:',sys2,'g--')

plots the step response of sys1 with a dotted yellow line and the step
response of sys2 with a green dashed line.
When invoked with output arguments:
y = step(sys,t)
[y,t] = step(sys)
[y,t] = step(sys,Tfinal)
[y,t,x] = step(sys)
step returns the output response y, the time vector t used for
simulation (if not supplied as an input argument), and the state
trajectories x (for state-space models only). No plot generates on the
screen. For single-input systems, y has as many rows as time samples
(length of t), and as many columns as outputs. In the multi-input case,
the step responses of each input channel are stacked up along the third
dimension of y. The dimensions of y are then

1-681

step

(length of t) (number of outputs) (number of inputs)

and y(:,:,j) gives the response to a unit step command injected in the
jth input channel. Similarly, the dimensions of x are

(length of t) (number of states) (number of inputs)

For identified models (see idlti and idnlmodlel) [y,t,x,ysd] =
step(sys) also computes the standard deviation ysd of the response y
(ysd is empty if sys does not contain parameter covariance information).
= step(sys,...,options) specifies additional options for
computing the step response, such as the step amplitude or input offset.
Use stepDataOptions to create the option set options.

[y,...]

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Step Response Plot of Dynamic System
Plot the step response of the following second-order state-space model.

x1 0.5572 0.7814 x1 1 1 u1
x = 0.7814
x + 0 2 u
0
2
2
2
x1
y = [1.9691 6.4493]
x2
a = [-0.5572
-0.7814;0.7814
b = [1 -1;0 2];
c = [1.9691 6.4493];
sys = ss(a,b,c,0);
step(sys)

1-682

0];

step

The left plot shows the step response of the first input channel, and the
right plot shows the step response of the second input channel.

Step Response Plot of Feedback Loop with Delay

Create a feedback loop with delay and plot its step response.
s = tf('s');
G = exp(-s) * (0.8*s^2+s+2)/(s^2+s);
T = feedback(ss(G),1);
step(T)

1-683

step

The system step response displayed is chaotic. The step response

of systems with internal delays may exhibit odd behavior, such as
recurring jumps. Such behavior is a feature of the system and not
software anomalies.

Example 3
Compare the step response of a parametric identified model to a
non-parametric (empirical) model/ Also view their 3- confidence
regions.

1-684

step

load iddata1 z1
sys1 = ssest(z1,4);

parametric model
sys2 = impulseest(z1);

non-parametric model
[y1, ~, ~, ysd1] = step(sys1,t);
[y2, ~, ~, ysd2] = step(sys2,t);
plot(t, y1, 'b', t, y1+3*ysd1, 'b:', t, y1-3*ysd1, 'b:')
hold on
plot(t, y2, 'g', t, y2+3*ysd2, 'g:', t, y2-3*ysd2, 'g:')

Example 4
Validation the linearization of a nonlinear ARX model by comparing
their small amplitude step responses.
nlsys = nlarx(z2,[4 3 10],'tree','custom',...
{'sin(y1(t-2)*u1(t))+y1(t-2)*u1(t)+u1(t).*u1(t-13)',...
'y1(t-5)*y1(t-5)*y1(t-1)'},'nlr',[1:5, 7 9]);

Determine an equilibrium operating point for nlsys corresponding to a

steady-state input value of 1:
u0 = 1;
[X,~,r] = findop(nlsys, 'steady', 1);
y0 = r.SignalLevels.Output;

Obtain a linear approximation of nlsys at this operating point.

sys = linearize(nlsys,u0,X)

Now validate the usefulness of sys by comparing its small-amplitude

step response to that of nlsys. The nonlinear system nlsys is operating
an equilibrium level dictated by (u0, y0). About this steady-state, we

1-685

step

introduce a step perturbation of size 0.1. The corresponding response is

computed as follows:
opt = stepDataOptions;
opt.InputOffset = u0;
opt.StepAmplitude = 0.1;
t = (0:0.1:10)';
ynl = step(nlsys, t, opt);

The linear system sys expresses the relationship between the

perturbations in input to the corresponding perturbation in output. It is
unaware of nonlinear systems equilibrium values. The step response of
the linear system is:
opt = stepDataOptions;
opt.StepAmplitude = 0.1;
yl = step(sys, t, opt);

To compare, add the steady-state offset, y0, to the response of the linear
system:
plot(t, ynl, t, yl+y0)
legend('Nonlinear', 'Linear with offset')

Example 5
Compute the step response of an identified time series model.
A time series model, also called a signal model, is one without measured
input signals. The step plot of this model uses its (unmeasured) noise
channel as the input channel to which the step signal is applied.
load iddata9
sys = ar(z9, 4);
ys is a model of the form A y(t) = e(t), where e(t) represents the
noise channel. For computation of step response, e(t) is treated as an
input channel, and is named "e@y1".

1-686

step

step(sys)

Algorithms

Continuous-time models without internal delays are converted to

state space and discretized using zero-order hold on the inputs. The
sampling period, dt, is chosen automatically based on the system
dynamics, except when a time vector t = 0:dt:Tf is supplied (dt is
then used as sampling period). The resulting simulation time steps t
are equisampled with spacing dt.
For systems with internal delays, Control System Toolbox software uses
variable step solvers. As a result, the time steps t are not equisampled.

References

[1] L.F. Shampine and P. Gahinet, "Delay-differential-algebraic

equations in control theory," Applied Numerical Mathematics, Vol. 56,
Issues 34, pp. 574588.

See Also

impulse | stepDataOptions | initial | lsim | ltiview

1-687

stepDataOptions

Purpose

Options set for step

Syntax

opt = stepDataOptions
opt = stepDataOptions(Name,Value)

Description

opt = stepDataOptions creates the default options for step.

opt = stepDataOptions(Name,Value) creates an options set with the
options specified by one or more Name,Value pair arguments.

Input
Arguments

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments.
Name is the argument name and Value is the corresponding
value. Name must appear inside single quotes (' '). You can
specify several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN.
InputOffset

Input signal level for all time t < 0, as shown in the next figure.

Default: 0

1-688

stepDataOptions

StepAmplitude

Change of input signal level which occurs at time t = 0, as shown in

the previous figure.
Default: 1

Output
Arguments

opt

Examples

Specify Input Offset and Step Amplitude Level

Option set containing the specified options for step.

Specify the input offset and amplitude level for step response.
sys = tf(1,[1,1]);
opt = stepDataOptions('InputOffset',-1,'StepAmplitude',2);
[y,t] = step(sys,opt)

See Also

step

1-689

stepinfo

Purpose

Rise time, settling time, and other step response characteristics

Syntax

S
S
S
S
S
S

Description

S = stepinfo(y,t,yfinal) takes step response data (t,y) and a

steady-state value yfinal and returns a structure S containing the

=
=
=
=
=
=

stepinfo(y,t,yfinal)
stepinfo(y,t)
stepinfo(y)
stepinfo(sys)
stepinfo(...,'SettlingTimeThreshold',ST)
stepinfo(...,'RiseTimeLimits',RT)

following performance indicators:

RiseTime Rise time
SettlingTime Settling time
SettlingMin Minimum value of y once the response has risen
SettlingMax Maximum value of y once the response has risen
Overshoot Percentage overshoot (relative to yfinal)
Undershoot Percentage undershoot
Peak Peak absolute value of y
PeakTime Time at which this peak is reached
For SISO responses, t and y are vectors with the same length NS.
For systems with NU inputs and NY outputs, you can specify y as an
NS-by-NY-by-NU array (see step) and yfinal as an NY-by-NU array.
stepinfo then returns a NY-by-NU structure array S of performance
metrics for each I/O pair.
S = stepinfo(y,t) uses the last sample value of y as steady-state
value yfinal. S = stepinfo(y) assumes t = 1:ns.
S = stepinfo(sys)computes the step response characteristics for an
LTI model sys (see tf, zpk, or ss for details).
S = stepinfo(...,'SettlingTimeThreshold',ST) lets you specify
the threshold ST used in the settling time calculation. The response

1-690

stepinfo

has settled when the error |y(t) - yfinal| becomes smaller than a
fraction ST of its peak value. The default value is ST=0.02 (2%).
S = stepinfo(...,'RiseTimeLimits',RT) lets you specify the lower
and upper thresholds used in the rise time calculation. By default,
the rise time is the time the response takes to rise from 10 to 90% of
the steady-state value (RT=[0.1 0.9]). Note that RT(2) is also used
to calculate SettlingMin and SettlingMax.

Examples

Step Response Characteristics of Fifth-Order System

Create a fifth order system and ascertain the response characteristics.
sys = tf([1 5],[1 2 5 7 2]);
S = stepinfo(sys,'RiseTimeLimits',[0.05,0.95])

These commands return the following result:

S =
RiseTime:
SettlingTime:
SettlingMin:
SettlingMax:
Overshoot:
Undershoot:
Peak:
PeakTime:

See Also

7.4454
13.9378
2.3737
2.5201
0.8032
0
2.5201
15.1869

step | lsiminfo

1-691

stepplot

Purpose

Plot step response and return plot handle

Syntax

h = stepplot(sys)
stepplot(sys,Tfinal)
stepplot(sys,t)
stepplot(sys1,sys2,...,sysN)
stepplot(sys1,sys2,...,sysN,Tfinal)
stepplot(sys1,sys2,...,sysN,t)
stepplot(AX,...)
stepplot(..., plotoptions)
stepplot(..., dataoptions)

Description

h = stepplot(sys) plots the step response of the dynamic system

model sys. It also returns the plot handle h. You can use this handle to
customize the plot with the getoptions and setoptions commands.

Type
help timeoptions

for a list of available plot options.

For multiinput models, independent step commands are applied to
each input channel. The time range and number of points are chosen
automatically.
stepplot(sys,Tfinal) simulates the step response from t = 0 to
the final time t = Tfinal. Express Tfinal in the system time units,
specified in the TimeUnit property of sys. For discrete-time systems
with unspecified sampling time (Ts = -1), stepplot interprets Tfinal

as the number of sampling intervals to simulate.

stepplot(sys,t) uses the user-supplied time vector t for simulation.
Express t in the system time units, specified in the TimeUnit property
of sys. For discrete-time models, t should be of the form Ti:Ts:Tf,
where Ts is the sample time. For continuous-time models, t should be
of the form Ti:dt:Tf, where dt becomes the sample time of a discrete
approximation to the continuous system (see step). The stepplot
command always applies the step input at t=0, regardless of Ti.

1-692

stepplot

To plot the step responses of multiple models sys1,sys2,... on a single

plot, use:
stepplot(sys1,sys2,...,sysN)
stepplot(sys1,sys2,...,sysN,Tfinal)
stepplot(sys1,sys2,...,sysN,t)

You can also specify a color, line style, and marker for each system, as in
stepplot(sys1,'r',sys2,'y--',sys3,'gx')
stepplot(AX,...) plots into the axes with handle AX.
stepplot(..., plotoptions) customizes the plot appearance using
the options set, plotoptions. Use timeOptions to create the options

set.
stepplot(..., dataoptions) specifies options such as the step
amplitude and input offset using the options set, dataoptions. Use
stepDataOptions to create the options set.

Tips

You can change the properties of your plot, for example the units. For
information on the ways to change properties of your plots, see Ways
to Customize Plots.

Examples

Example 1
Use the plot handle to normalize the responses on a step plot.
sys = rss(3);
h = stepplot(sys);
% Normalize responses.
setoptions(h,'Normalize','on');

Example 2
Compare the step response of a parametric identified model to a
non-parametric (empirical) model, and view their 3- confidence

1-693

stepplot

regions. (Identified models require System Identification Toolbox

software.)
load iddata1 z1

for parametric model

sys1 = ssest(z1,4);

non-parametric model
sys2 = impulseest(z1);
t = -1:0.1:5;
h = stepplot(sys1,sys2,t);
showConfidence(h,3)

The non-parametric model sys2 shows higher uncertainty.

Example 3
Plot the step response of a nonlinear (Hammerstein-Wiener) model using
a starting offset of 2 and step amplitude of 0.5. (Hammerstein-Weiner
models require System Identification Toolbox software.)
load twotankdata
z = iddata(y, u, 0.2, 'Name', 'Two tank system');
sys = nlhw(z, [1 5 3], pwlinear, poly1d);
dataoptions = stepDataOptions('InputOffset', 2, 'StepAmplitude', 0.5);
stepplot(sys,60,dataoptions);

See Also

1-694

getoptions | setoptions | step

strseq

Purpose

Create sequence of indexed strings

Syntax

strvec = strseq(STR,INDICES)

Description

strvec = strseq(STR,INDICES) creates a sequence of indexed strings

in the string vector strvec by appending the integer values INDICES to
the string STR.

Note You can use strvec to aid in system interconnection. For an

example, see the sumblk reference page.

Examples

Create a string vector by indexing the string 'e' at 1, 2, and 4.

strseq('e',[1 2 4])

This command returns the following result:

ans =
'e1'
'e2'
'e4'

See Also

strcat | connect

1-695

sumblk

Purpose

Summing junction for name-based interconnections

Syntax

S = sumblk(formula)
S = sumblk(formula,signalsize)
S = sumblk(formula,signames1,signames2,...)

Description

S = sumblk(formula) creates the transfer function, S, of the summing

junction described by the string formula. The string formula specifies

an equation that relates the scalar input and output signals of S.
S = sumblk(formula,signalsize) returns a vector-valued summing

junction. The input and output signals are vectors with signalsize
elements.
S = sumblk(formula,signames1,signames2,...) replaces aliases
(signal names beginning with %) in formula by the signal names

signames. The number of signames arguments must match the

number of aliases in formula. The first alias in formula is replaced by
signames1, the second by signames2, and so on.

Tips

Use sumblk in conjunction with connect to interconnect dynamic

system models and derive aggregate models for block diagrams.

Input
Arguments

formula

String specifying the equation that relates the input and output signals
of the summing junction transfer function S. For example, the following
command:
S = sumblk('e = r - y + d')

creates a summing junction with input names 'r', 'y', and 'd', output
name 'e' and equation e = r-y+d.
If you specify a signalsize greater than 1, the inputs and outputs
of S are vector-valued signals. sumblk automatically performs vector
expansion of the signal names of S. For example, the following command:
S = sumblk('v = u + d',2)

1-696

sumblk

specifies a summing junction with input names

{'u(1)';'u(2)';'d(1)';'d(2)'} and output names
{'v(1)';'v(2)'}. The formulas of this summing junction are v(1) =
u(1) + d(1); v(2) = u(2) + d(2).
You can use one or more aliases in formula to refer to signal names
defined in a variable. An alias is a signal name that begins with %.
When formula contains aliases, sumblk replaces each alias with the
corresponding signames argument.
Aliases are useful when you want to name individual entries in a
vector-valued signal. Aliases also allow you to use input or output names
of existing models. For example, if C and G are dynamic system models
with nonempty InputName and OutputName properties, respectively, you
can create a summing junction using the following expression.
S = sumblk('%e = r - %y',C.InputName,G.OutputName)
sumblk uses the values of C.InputName and G.OutputName in place
of %e and %y, respectively. The vector dimension of C.InputName and
G.OutputName must match. sumblk assigns the signal r the same

dimension.
signalsize

Number of elements in each input and output signal of S. Setting

signalsize greater than 1 lets you specify a summing junction that
operates on vector-valued signals.
Default: 1
signames

Signal names to replace one alias (signal name beginning with %) in the
formula string. You must provide one signames argument for each
alias in formula.
Specify signames as:
A cell array of name strings.

1-697

sumblk

The InputName or OutputName property of a model in the MATLAB

workspace. For example:
S = sumblk('%e = r - y',C.InputName)

This command creates a summing junction whose outputs have the

same name as the inputs of the model C in the MATLAB workspace.

Output
Arguments

Examples

Summing Junction with Scalar-Valued Signals

Transfer function for the summing junction, represented as a MIMO

tf model object.

Create the summing junction of the following illustration. All signals

are scalar-valued.

u1
u2
u3

This summing junction has the formula u = u1 + u2 + u3.

S = sumblk('u = u1+u2+u3');
S is the transfer function (tf) representation of the sum u = u1 + u2
+ u3. The transfer function S gets its input and output names from

the formula string.

S.OutputName,S.Inputname
ans =
'u'

ans =

1-698

sumblk

'u1'
'u2'
'u3'

Summing Junction with Vector-Valued Signals

Create the summing junction v = u - d where u,d,v are vector-valued
signals of length 2.
S = sumblk('v = u-d',2);
sumblk automatically performs vector expansion of the signal names
of S.
S.OutputName,S.Inputname
ans =
'v(1)'
'v(2)'

ans =
'u(1)'
'u(2)'
'd(1)'
'd(2)'

Summing Junction with Vector-Valued Signals That Have

Specified Signal Names
Create the summing junction

1-699

sumblk

e 1 setpoint 1 alpha d 1
e 2 setpoint 2 q d 2
The signals alpha and q have custom names that are not merely the
vector expansion of a single signal name. Therefore, use an alias in the
formula specifying the summing junction.
S = sumblk('e = setpoint - %y + d', {'alpha';'q'});
sumblk replaces the alias %y with the cell array {'alpha';'q'}.
S.OutputName,S.Inputname
ans =
'e(1)'
'e(2)'

ans =
'setpoint(1)'
'setpoint(2)'
'alpha'
'q'
'd(1)'
'd(2)'

See Also

connect | series | parallel | strseq

How To

Multi-Loop Control System

MIMO Control System

1-700

tf

Purpose

Create transfer function model, convert to transfer function model

Syntax

sys =
sys =
sys =
sys =
tfsys
tfsys
tfsys
tfsys

Description

Use tf to create real- or complex-valued transfer function models (TF

objects) or to convert state-space or zero-pole-gain models to transfer
function form. You can also use tf to create generalized state-space
(genss) models or uncertain state-space (uss) models.

tf(num,den)
tf(num,den,Ts)
tf(M)
tf(num,den,ltisys)
= tf(sys)
= tf(sys, 'measured')
= tf(sys, 'noise')
= tf(sys, 'augmented')

Creation of Transfer Functions

sys = tf(num,den) creates a continuous-time transfer function with
numerator(s) and denominator(s) specified by num and den. The output
sys is:

A tf model object, when num and den are numeric arrays.

A generalized state-space model (genss) when num or den include
tunable parameters, such as realp parameters or generalized
matrices (genmat).
An uncertain state-space model (uss) when num or den are uncertain
(requires Robust Control Toolbox software).
In the SISO case, num and den are the real- or complex-valued
row vectors of numerator and denominator coefficients ordered in
descending powers of s. These two vectors need not have equal length
and the transfer function need not be proper. For example, h = tf([1
0],1) specifies the pure derivative h(s) = s.
To create MIMO transfer functions, using one of the following
approaches:
Concatenate SISO tf models.

1-701

tf

Use the tf command with cell array arguments. In this case, num and
den are cell arrays of row vectors with as many rows as outputs and
as many columns as inputs. The row vectors num{i,j} and den{i,j}
specify the numerator and denominator of the transfer function from
input j to output i.
For examples of creating MIMO transfer functions, see Examples on
page 1-704 and MIMO Transfer Function Model in the Control System
Toolbox User Guide.
If all SISO entries of a MIMO transfer function have the same
denominator, you can set den to the row vector representation of this
common denominator. See "Examples" for more details.
sys = tf(num,den,Ts) creates a discrete-time transfer function
with sample time Ts (in seconds). Set Ts = -1 to leave the sample
time unspecified. The input arguments num and den are as in the
continuous-time case and must list the numerator and denominator
coefficients in descending powers of z.
sys = tf(M) creates a static gain M (scalar or matrix).
sys = tf(num,den,ltisys) creates a transfer function with
properties inherited from the dynamic system model ltisys (including

the sample time).

There are several ways to create arrays of transfer functions. To create
arrays of SISO or MIMO TF models, either specify the numerator and
denominator of each SISO entry using multidimensional cell arrays, or
use a for loop to successively assign each TF model in the array. See
Model Arrays in the Control System Toolbox User Guide for more
information.
Any of the previous syntaxes can be followed by property name/property
value pairs
'Property',Value

Each pair specifies a particular property of the model, for example, the
input names or the transfer function variable. For information about
the properties of tf objects, see Properties on page 1-710. Note that

1-702

tf

sys = tf(num,den,'Property1',Value1,...,'PropertyN',ValueN)

is a shortcut for
sys = tf(num,den)
set(sys,'Property1',Value1,...,'PropertyN',ValueN)

Transfer Functions as Rational Expressions in s or z

You can also use real- or complex-valued rational expressions to create
a TF model. To do so, first type either:
s = tf('s') to specify a TF model using a rational function in the
Laplace variable, s.
z = tf('z',Ts) to specify a TF model with sample time Ts using a
rational function in the discrete-time variable, z.
Once you specify either of these variables, you can specify TF models
directly as rational expressions in the variable s or z by entering your
transfer function as a rational expression in either s or z.

Conversion to Transfer Function

tfsys = tf(sys) converts the dynamic system model sys to transfer
function form. The output tfsys is a tf model object representing sys

expressed as a transfer function.

If sys is a model with tunable components, such as a genss, genmat,
ltiblock.tf, or ltiblock.ss model, the resulting transfer function
tfsys takes the current values of the tunable components.

Conversion of Identified Models

An identified model is represented by an input-output equation of the
form y(t) = Gu(t) + He(t), where u(t) is the set of measured input
channels and e(t) represents the noise channels. If = LL represents
the covariance of noise e(t), this equation can also be written as: y(t)
= Gu(t) + HLv(t), where cov(v(t)) = I.
tfsys = tf(sys), or tfsys = tf(sys, 'measured') converts the
measured component of an identified linear model into the transfer

1-703

tf

function form. sys is a model of type idss, idproc, idtf, idpoly, or

idgrey. tfsys represents the relationship between u and y.
tfsys = tf(sys, 'noise') converts the noise component of an
identified linear model into the transfer function form. It represents
the relationship between the noise input, v(t) and output, y_noise =
HL v(t). The noise input channels belong to the InputGroup 'Noise'.
The names of the noise input channels are v@yname, where yname is the
name of the corresponding output channel. tfsys has as many inputs
as outputs.
tfsys = tf(sys, 'augmented') converts both the measured
and noise dynamics into a transfer function. tfsys has ny+nu
inputs such that the first nu inputs represent the channels u(t)

while the remaining by channels represent the noise channels

v(t). tfsys.InputGroup contains 2 input groups- 'measured'
and 'noise'. tfsys.InputGroup.Measured is set to 1:nu while
tfsys.InputGroup.Noise is set to nu+1:nu+ny. tfsys represents the
equation y(t) = [G HL] [u; v].
Tip An identified nonlinear model cannot be converted into a transfer
function. Use linear approximation functions such as linearize and
linapp.

Creation of Generalized State-Space Models

You can use the syntax:
gensys = tf(num,den)

to create a Generalized state-space (genss) model when one or more

of the entries num and den depends on a tunable realp or genmat
model. For more information about Generalized state-space models, see
Models with Tunable Coefficients.

Examples

Example 1
Transfer Function Model with One-Input Two-Outputs

1-704

tf

Create the one-input, two-output transfer function

p+1

p + 2p + 2
H ( p) =

with input current and outputs torque and ang velocity.

To do this, enter
num = {[1 1] ; 1};
den = {[1 2 2] ; [1 0]};
H = tf(num,den,'inputn','current',...
'outputn',{'torque' 'ang. velocity'},...
'variable','p')

These commands produce the result:

Transfer function from input "current" to output...
p + 1
torque: ------------p^2 + 2 p + 2

ang. velocity:

1
p

Setting the 'variable' property to 'p' causes the result to be displayed

as a transfer function of the variable p.

Example 2
Transfer Function Model Using Rational Expression
To use a rational expression to create a SISO TF model, type
s = tf('s');
H = s/(s^2 + 2*s +10);

1-705

tf

This produces the same transfer function as

h = tf([1 0],[1 2 10]);

Example 3
Multiple-Input Multiple-Output Transfer Function Model
Specify the discrete MIMO transfer function

1
z + 0 .3
H ( z) =
z + 2
z + 0.3

z
z + 0 .3

3
z + 0.3

with common denominator d (z) = z + 0.3 and sample time of 0.2 seconds.
nums = {1 [1 0];[-1 2] 3};
Ts = 0.2;
H = tf(nums,[1 0.3],Ts)

% Note: row vector for common den. d(z)

Example 4
Convert State-Space Model to Transfer Function
Compute the transfer function of the state-space model with the
following data.

2 1
A=
,
1 2

1 1
B=
,
2 1

C = [1 0] ,

D = [ 0 1].

To do this, type
sys = ss([-2 -1;1 -2],[1 1;2 -1],[1 0],[0 1]);
tf(sys)

These commands produce the result:

1-706

tf

Transfer function from input 1 to output:

s - 4.441e-016
-------------s^2 + 4 s + 5
Transfer function from input 2 to output:
s^2 + 5 s + 8
------------s^2 + 4 s + 5

Example 5
Array of Transfer Function Models
You can use a for loop to specify a 10-by-1 array of SISO TF models.
H = tf(zeros(1,1,10));
s = tf('s')
for k=1:10,
H(:,:,k) = k/(s^2+s+k);
end

The first statement pre-allocates the TF array and fills it with zero
transfer functions.

Example 6
Tunable Low-Pass Filter
This example shows how to create the low-pass filter F = a/(s + a) with
one tunable parameter a.
You cannot use ltiblock.tf to represent F, because the numerator
and denominator coefficients of an ltiblock.tf block are independent.
Instead, construct F using the tunable real parameter object realp.
1 Create a tunable real parameter.

a = realp('a',10);

The realp object a is a tunable parameter with initial value 10.

1-707

tf

2 Use tf to create the tunable filter F:

F = tf(a,[1 a]);
F is a genss object which has the tunable parameter a in its Blocks
property. You can connect F with other tunable or numeric models to

create more complex models of control systems. For an example, see

Control System with Tunable Components.

Example 7
Extract the measured and noise components of an identified polynomial
model into two separate transfer functions. The former (measured
component) can serve as a plant model while the latter can serve as a
disturbance model for control system design.
load icEngine;
z = iddata(y,u,0.04);
nb = 2; nf = 2; nc = 1; nd = 3; nk = 3;
sys = bj(z, [nb nc nd nf nk]);
sys is a model of the form: y(t) = B/F u(t) + C/D e(t), where B/F
represents the measured component and C/D the noise component.
sysMeas = tf(sys, 'measured')
sysNoise = tf(sys, 'noise')

Alternatively, use can simply use tf(sys) to extract the measured

component.

Discrete-Time
Conventions

The control and digital signal processing (DSP) communities tend to use
different conventions to specify discrete transfer functions. Most control
engineers use the z variable and order the numerator and denominator
terms in descending powers of z, for example,

h ( z) =

1-708

z2
z2 + 2 z + 3

tf

The polynomials z2 and z2 + 2z + 3 are then specified by the row vectors

[1 0 0] and [1 2 3], respectively. By contrast, DSP engineers prefer
to write this transfer function as

( )

h z1 =

1
1 + 2z

+ 3 z2

and specify its numerator as 1 (instead of [1 0 0]) and its denominator

as [1 2 3].
tf switches convention based on your choice of variable (value of the
'Variable' property).

Variable

Convention

'z' (default), 'q'

Use the row vector [ak ...

a1 a0] to specify

the polynomial ak zk + ... + a1 z + a0 (coefficients

ordered in descending powers of z or q).
Use the row vector [b0 b1 ...

'z^-1'

bk] to specify

the polynomial b0 + b1 z1 + ... + bk z k (coefficients

in ascending powers of z-1).
For example,
g = tf([1 1],[1 2 3],0.1);

specifies the discrete transfer function

g ( z) =

z+1
2

z + 2z + 3

because z is the default variable. In contrast,

h = tf([1 1],[1 2 3],0.1,'variable','z^-1');

uses the DSP convention and creates

1-709

tf

( )

h z1 =

1 + z1
1 + 2 z1 + 3 z2

= zg ( z ) .

See also filt for direct specification of discrete transfer functions using
the DSP convention.
Note that tf stores data so that the numerator and denominator lengths
are made equal. Specifically, tf stores the values
num = [0 1 1]; den = [1 2 3];

for g (the numerator is padded with zeros on the left) and the values
num = [1 1 0]; den = [1 2 3];

for h (the numerator is padded with zeros on the right).

Properties

tf objects have the following properties:

num

Transfer function numerator coefficients.

For SISO transfer functions, num is a row vector of polynomial
coefficients in order of descending power (for Variable values s, z, p, or
q) or in order of ascending power (for Variable values z^-1 or q^-1).
For MIMO transfer functions with Ny outputs and Nu inputs, num is a
Ny-by-Nu cell array of the numerator coefficients for each input/output
pair.
den

Transfer function denominator coefficients.

For SISO transfer functions, den is a row vector of polynomial
coefficients in order of descending power (for Variable values s, z, p, or
q) or in order of ascending power (for Variable values z^-1 or q^-1).

1-710

tf

For MIMO transfer functions with Ny outputs and Nu inputs, den is a

Ny-by-Nu cell array of the denominator coefficients for each input/output
pair.
Variable

String specifying the transfer function display variable. Variable can

take the following values:
's' Default for continuous-time models
'z' Default for discrete-time models
'p' Equivalent to 's'
'q' Equivalent to 'z'
'z^-1' Inverse of 'z'
'q^-1' Equivalent to 'z^-1'
The value of Variable is reflected in the display, and also affects the
interpretation of the num and den coefficient vectors for discrete-time
models. For Variable = 'z' or 'q', the coefficient vectors are ordered
in descending powers of the variable. For Variable = 'z^-1' or
'q^-1', the coefficient vectors are ordered as ascending powers of the
variable.
Default: 's'
ioDelay

Transport delays. ioDelay is a numeric array specifying a separate

transport delay for each input/output pair.
For continuous-time systems, specify transport delays in the time unit
stored in the TimeUnit property. For discrete-time systems, specify
transport delays in integer multiples of the sampling period, Ts.
For a MIMO system with Ny outputs and Nu inputs, set ioDelay to
a Ny-by-Nu array. Each entry of this array is a numerical value that
represents the transport delay for the corresponding input/output pair.

1-711

tf

You can also set ioDelay to a scalar value to apply the same delay to all
input/output pairs.
Default: 0 for all input/output pairs
InputDelay - Input delays
0 (default) | scalar | vector

Input delay for each input channel, specified as a numeric vector. For
continuous-time systems, specify input delays in the time unit stored
in the TimeUnit property. For discrete-time systems, specify input
delays in integer multiples of the sampling period Ts. For example,
InputDelay = 3 means a delay of three sampling periods.
For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each
entry of this vector is a numerical value that represents the input delay
for the corresponding input channel.
You can also set InputDelay to a scalar value to apply the same delay
to all channels.
OutputDelay

Output delays. OutputDelay is a numeric vector specifying a time

delay for each output channel. For continuous-time systems, specify
output delays in the time unit stored in the TimeUnit property. For
discrete-time systems, specify output delays in integer multiples of the
sampling period Ts. For example, OutputDelay = 3 means a delay
of three sampling periods.
For a system with Ny outputs, set OutputDelay to an Ny-by-1 vector,
where each entry is a numerical value representing the output delay for
the corresponding output channel. You can also set OutputDelay to a
scalar value to apply the same delay to all channels.
Default: 0 for all output channels
Ts

1-712

tf

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.

1-713

tf

Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field

1-714

tf

names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:
sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels

1-715

tf

OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:
sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}

1-716

tf

UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.
For example, suppose you create a 11-by-1 array of linear models,
sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.

1-717

tf

M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Algorithms

tf uses the MATLAB function poly to convert zero-pole-gain models,

and the functions zero and pole to convert state-space models.

See Also

filt | frd | get | set | ss | tfdata | zpk | genss | realp | genmat

| ltiblock.tf

Tutorials

Transfer Function Model Using Numerator and Denominator

Coefficients
Discrete-Time Transfer Function Model
MIMO Transfer Function Model

How To

What Are Model Objects?

Transfer Functions

1-718

tfdata

Purpose

Access transfer function data

Syntax

[num,den] = tfdata(sys)
[num,den,Ts] = tfdata(sys)
[num,den,Ts,sdnum,sdden]=tfdata(sys)
[num,den,Ts,...]=tfdata(sys,J1,...,Jn)

Description

[num,den] = tfdata(sys) returns the numerator(s) and

denominator(s) of the transfer function for the TF, SS or ZPK model

(or LTI array of TF, SS or ZPK models) sys. For single LTI models,
the outputs num and den of tfdata are cell arrays with the following
characteristics:
num and den have as many rows as outputs and as many columns as
inputs.
The (i,j) entries num{i,j} and den{i,j} are row vectors specifying
the numerator and denominator coefficients of the transfer function
from input j to output i. These coefficients are ordered in descending
powers of s or z.
For arrays sys of LTI models, num and den are multidimensional cell
arrays with the same sizes as sys.
If sys is a state-space or zero-pole-gain model, it is first converted to
transfer function form using tf. For more information on the format of
transfer function model data, see the tf reference page.
For SISO transfer functions, the syntax
[num,den] = tfdata(sys,'v')

forces tfdata to return the numerator and denominator directly as row

vectors rather than as cell arrays (see example below).
[num,den,Ts] = tfdata(sys) also returns the sample time Ts.
[num,den,Ts,sdnum,sdden]=tfdata(sys) also returns the

uncertainties in the numerator and denominator coefficients of

identified system sys. sdnum{i,j}(k) is the 1 standard uncertainty

1-719

tfdata

in the value num{i,j}(k) and sdden{i,j}(k) is the 1 standard

uncertainty in the value den{i,j}(k). If sys does not contain
uncertainty information, sdnum and sdden are empty ([]).
[num,den,Ts,...]=tfdata(sys,J1,...,Jn) extracts the data for the
(J1,...,JN)entry in the model array sys.

You can access the remaining LTI properties of sys with get or by
direct referencing, for example,
sys.Ts
sys.variable

Examples

Example 1
Given the SISO transfer function
h = tf([1 1],[1 2 5])

you can extract the numerator and denominator coefficients by typing

[num,den] = tfdata(h,'v')
num =
0
1
1
den =
1

This syntax returns two row vectors.

If you turn h into a MIMO transfer function by typing
H = [h ; tf(1,[1 1])]

the command
[num,den] = tfdata(H)

now returns two cell arrays with the numerator/denominator data for
each SISO entry. Use celldisp to visualize this data. Type

1-720

tfdata

celldisp(num)

This command returns the numerator vectors of the entries of H.

num{1} =
0

num{2} =
0

Similarly, for the denominators, type

celldisp(den)
den{1} =
1
2
den{2} =
1

Example 2
Extract the numerator, denominator and their standard deviations for
a 2-input, 1 output identified transfer function.
load iddata7

transfer function model

sys1 = tfest(z7, 2, 1, 'InputDelay',[1 0]);

an equivalent process model

sys2 = procest(z7, {'P2UZ', 'P2UZ'}, 'InputDelay',[1 0]);
[num1, den1, ~, dnum1, dden1] = tfdata(sys1);
[num2, den2, ~, dnum2, dden2] = tfdata(sys2);

See Also

get | ssdata | tf | zpkdata

1-721

thiran

Purpose

Generate fractional delay filter based on Thiran approximation

Syntax

sys = thiran(tau, Ts)

Description

sys = thiran(tau, Ts) discretizes the continuous-time delay tau

Tips

If tau is an integer multiple of Ts, then sys represents the pure

discrete delay zN, with N = tau/Ts. Otherwise, sys is a discrete-time,
all-pass, infinite impulse response (IIR) filter of order ceil(tau/Ts).

using a Thiran filter to approximate the fractional part of the delay. Ts

specifies the sampling time.

thiran approximates and discretizes a pure time delay. To

approximate a pure continuous-time time delay without discretizing,
use pade. To discretize continuous-time models having time delays,
use c2d.

Input
Arguments

tau

Time delay to discretize.

Ts

Sampling time.

Output
Arguments

sys

Examples

Approximate and discretize a time delay that is a noninteger multiple

of the target sample time.

Discrete-time tf object.

sys1 = thiran(2.4, 1)
Transfer function:
0.004159 z^3 - 0.04813 z^2 + 0.5294 z + 1
----------------------------------------z^3 + 0.5294 z^2 - 0.04813 z + 0.004159

1-722

thiran

Sampling time: 1

The time delay is 2.4 s, and the sample time is 1 s. Therefore, sys1 is a
discrete-time transfer function of order 3.
Discretize a time delay that is an integer multiple of the target sample
time.
sys2 = thiran(10, 1)
Transfer function:
1
---z^10
Sampling time: 1

Algorithms

The Thiran fractional delay filter has the following form:

H ( z) =

aN z N + aN 1 z N 1 + + a1
a0 z N + a1 z N 1 + + aN

The coefficients a0, ..., aN are given by:

N
D N +i
kN
ak = ( 1)
,
k
D
i =0 N + k + i
a0 = 1

k : 1, 2, , N

where D = /Ts and N = ceil(D) is the filter order. See [1].

References

[1] T. Laakso, V. Valimaki, Splitting the Unit Delay, IEEE Signal

Processing Magazine, Vol. 13, No. 1, p.30-60, 1996.

See Also

c2d | pade | tf

1-723

timeoptions

Purpose

Create list of time plot options

Syntax

P = timeoptions
P = timeoptions('cstprefs')

Description

P = timeoptions returns a list of available options for time plots with

default values set. You can use these options to customize the time
value plot appearance from the command line.
P = timeoptions('cstprefs') initializes the plot options you selected

in the Control System Toolbox Preferences Editor. For more information

about the editor, see Toolbox Preferences Editor in the Users Guide
documentation.
This table summarizes the available time plot options.

1-724

Option

Description

Title, XLabel, YLabel

Label text and style

TickLabel

Tick label style

Grid

Show or hide the grid

Specified as one of the following
strings: 'off' | 'on'
Default: 'off'

XlimMode, YlimMode

Limit modes

Xlim, Ylim

Axes limits

IOGrouping

Grouping of input-output pairs

Specified as one of the
following strings: 'none'
|'inputs'|'output'|'all'
Default: 'none'

InputLabels, OutputLabels

Input and output label styles

InputVisible, OutputVisible

Visibility of input and output

channels

timeoptions

Option

Description

Normalize

Normalize responses
Specified as one of the following
strings: 'on' |'off'
Default: 'off'

SettleTimeThreshold

Settling time threshold

RiseTimeLimits

Rise time limits

TimeUnits

Time units, specified as one of the

following strings:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Default: 'seconds'
You can also specify 'auto' which
uses time units specified in the
TimeUnit property of the input
system. For multiple systems with
different time units, the units of
the first system is used.

1-725

timeoptions

Examples

In this example, enable the normalized response option before creating

a plot.
P = timeoptions;
% Set normalize response to on in options
P.Normalize = 'on';
% Create plot with the options specified by P
h = stepplot(tf(10,[1,1]),tf(5,[1,5]),P);

The following step plot is created with the responses normalized.

See Also

1-726

getoptions | impulseplot | initialplot | lsimplot | setoptions

| stepplot

totaldelay

Purpose

Total combined I/O delays for LTI model

Syntax

td = totaldelay(sys)

Description

td = totaldelay(sys) returns the total combined I/O delays for

an LTI model sys. The matrix td combines contributions from the
InputDelay, OutputDelay, and ioDelayMatrix properties.

Delays are expressed in seconds for continuous-time models, and as

integer multiples of the sample period for discrete-time models. To
obtain the delay times in seconds, multiply td by the sample time
sys.Ts.

Examples

sys = tf(1,[1 0]);

% TF of 1/s
sys.inputd = 2;
% 2 sec input delay
sys.outputd = 1.5;
% 1.5 sec output delay
td = totaldelay(sys)
td =
3.5000

The resulting I/O map is

1
1
e2 s e1.5 s = e3.5 s
s
s
This is equivalent to assigning an I/O delay of 3.5 seconds to the original
model sys.

See Also

absorbDelay | hasdelay

1-727

tzero

Purpose

Invariant zeros of linear system

Syntax

z = tzero(sys)
z = tzero(A,B,C,D,E)
z = tzero( ___ ,tol)
[z,nrank] = tzero( ___ )

Description

z = tzero(sys) returns the invariant zeros of the multi-input,

multi-output (MIMO) dynamic system, sys. If sys is a minimal
realization, the invariant zeros coincide with the transmission zeros
of sys.
z = tzero(A,B,C,D,E) returns the invariant zeros of the state-space

model

dx
Ax Bu
dt
y Cx Du.

Omit E for an explicit state-space model (E = I).

z = tzero( ___ ,tol) specifies the relative tolerance, tol, controlling
rank decisions.
[z,nrank] = tzero( ___ ) also returns the normal rank of the transfer

function of sys or of the transfer function H(s) = D + C(sE A)1B.

Tips

You can use the syntax z = tzero(A,B,C,D,E) to find the

uncontrollable or unobservable modes of a state-space model. When
C and D are empty or zero, tzero returns the uncontrollable modes
of (A-sE,B). Similarly, when B and D are empty or zero, tzero
returns the unobservable modes of (C,A-sE). See Unobservable and
Uncontrollable Modes of MIMO Model on page 1-731 for an example.

Input
Arguments

sys

1-728

MIMO dynamic system model. If sys is not a state-space model, then

tzero computes tzero(ss(sys)).

tzero

A,B,C,D,E

State-space matrices describing the linear system

dx
Ax Bu
dt
y Cx Du.

tzero does not scale the state-space matrices when you use the syntax z
= tzero(A,B,C,D,E). Use prescale if you want to scale the matrices
before using tzero.

Omit E to use E = I.
tol

Relative tolerance controlling rank decisions. Increasing tolerance

helps detect nonminimal modes and eliminate very large zeros (near
infinity). However, increased tolerance might artificially inflate the
number of transmission zeros.
Default: eps^(3/4)

Output
Arguments

Column vector containing the invariant zeros of sys or the state-space

model described by A,B,C,D,E.
nrank

Normal rank of the transfer function of sys or of the transfer function

H(s) = D + C(sE A)1B. The normal rank is the rank for values of s
other than the transmission zeros.
To obtain a meaningful result for nrank, the matrix s*E-A must be
regular (invertible for most values of s). In other words, sys or the
system described by A,B,C,D,E must have a finite number of poles.

1-729

tzero

Definitions

Invariant zeros
For a MIMO state-space model

dx
Ax Bu
dt
y Cx Du,

the invariant zeros are the complex values of s for which the rank of the
system matrix

A sE
C

B
D

drops from its normal value. (For explicit state-space models, E = I).

Transmission zeros
For a MIMO state-space model

dx
Ax Bu
dt
y Cx Du,

the transmission zeros are the complex values of s for which the rank of
the equivalent transfer function H(s) = D + C(sE A)1B drops from its
normal value. (For explicit state-space models, E = I.)
Transmission zeros are a subset of the invariant zeros. For minimal
realizations, the transmission zeros and invariant zeros are identical.

Examples

Transmission Zeros of MIMO Transfer Function

Find the invariant zeros of a MIMO transfer function and confirm that
they coincide with the transmission zeros.
Create a MIMO transfer function, and locate its invariant zeros.
s = tf('s');

1-730

tzero

H = [1/(s+1) 1/(s+2);1/(s+3) 2/(s+4)];

z = tzero(H)
z =
-2.5000 + 1.3229i
-2.5000 - 1.3229i

The output is a column vector listing the locations of the invariant zeros
of H. This output shows that H a has complex pair of invariant zeros.
Check whether the first invariant zero is a transmission zero of H.
If z(1) is a transmission zero of H, then H drops rank at s = z(1).
H1 = evalfr(H,z(1));
svd(H1)
ans =
1.5000
0.0000
H1 is the transfer function, H, evaluated at s = z(1). H1 has a zero
singular value, indicating that H drops rank at that value of s.
Therefore, z(1) is a transmission zero of H. A similar analysis shows
that z(2) is also a transmission zero.

Unobservable and Uncontrollable Modes of MIMO Model

Identify the unobservable and uncontrollable modes of a MIMO model
using the state-space matrix syntax of tzero.
Obtain a MIMO model.
load ltiexamples gasf
size(gasf)
State-space model with 4 outputs, 6 inputs, and 25 states.

1-731

tzero

gasf is a MIMO model that might contain uncontrollable or

unobservable states.
Scale the state-space matrices of gasf.
[A,B,C,D] = ssdata(prescale(gasf));

To identify the unobservable and uncontrollable modes of gasf, you

need access to the state-space matrices A, B, C, and D of the model. tzero
does not scale state-space matrices when you use the syntax. Therefore,
use prescale with ssdata to extract scaled values of these matrices.
Use tzero to identify the uncontrollable states of gasf.
uncon = tzero(A,B,[],[])
uncon =
-0.0568
-0.0568
-0.0568
-0.0568
-0.0568
-0.0568

When you provide A and B matrices to tzero, but no C and D matrices,

the command returns the eigenvalues of the uncontrollable modes of
gasf. The output shows that there are six degenerate uncontrollable
modes.
Identify the unobservable states of gasf.
unobs = tzero(A,[],C,[])
unobs =
Empty matrix: 0-by-1

1-732

tzero

When you provide A and C matrices, but no B and D matrices, the

command returns the eigenvalues of the unobservable modes. The
empty result shows that gasf contains no unobservable states.

Algorithms

tzero is based on SLICOT routines AB08ND, AG08BD, and AB8NXZ.

tzero implements the algorithms in [1] and [2].

References

[1] Emami-Naeini, A. and P. Van Dooren, "Computation of Zeros of

Linear Multivariable Systems," Automatica, 18 (1982), pp. 415430.
[2] Misra, P, P. Van Dooren, and A. Varga, Computation of Structural
Invariants of Generalized State-Space Systems, Automatica, 30 (1994),
pp. 1921-1936.

Alternatives

To calculate the zeros and gain of a single-input, single-output (SISO)

system, use zero.

See Also

pole | pzmap | zero

1-733

updateSystem

Purpose

Update dynamic system data in a response plot

Syntax

updateSystem(h,sys)
updateSystem(h,sys,N)

Description

updateSystem(h,sys) replaces the dynamic system used to compute

a response plot with the dynamic system model or model array sys,
and updates the plot. If the plot with handle h contains more than one
system response, this syntax replaces the first response in the plot.
updateSystem is useful, for example, to cause a plot in a GUI to update
in response to interactive input. See Build GUI With Interactive Plot
Updates.
updateSystem(h,sys,N) replaces the data used to compute the Nth

response in the plot.

Input
Arguments

h - Plot to update
plot handle

Plot to update with new system data, specified as a plot handle.

Typically, you obtain the plot handle as an output argument of a
response plotting command such as stepplot or bodeplot. For
example, the command h = bodeplot(G) returns a handle to a plot
containing the Bode response of a dynamic system, G.
sys - System for new response data
dynamic system model | model array

System from which to compute new response data for the response plot,
specified as a dynamic system model or model array.
sys must match the plotted system that it replaces in both I/O
dimensions and array dimensions. For example, suppose h refers to a
plot that displays the step responses of a 5-element vector of 2-input,
2-output systems. In this case, sys must also be a 5-element vector of
2-input, 2-output systems. The number of states in the elements of sys
need not match the number of states in the plotted systems.

1-734

updateSystem

N - Index of system to replace

positive integer | 1 (default)

Index of system to replace in the plot, specified as a positive integer.

For example, suppose you create a plot using the following command.
h = impulseplot(G1,G2,G3,G4);

To replace the impulse data of G3 with data from a new system, sys,
use the following command.
updateSystem(h,sys,3);

Examples

Update System Data in Plot

Replace plotted step response data with data computed from a different
dynamic system model.
Suppose you have a plant model and pure integrator controller that you
designed for that plant. Plot the step responses of the plant and the
closed-loop system.
w = 2;
zeta = 0.5;
G = tf(w^2,[1,2*zeta*w,w^2]);
C1 = pid(0,0.621);
CL1 = feedback(G*C1,1);
h = stepplot(G,CL1);

1-735

updateSystem

h is the plot handle that identifies the plot created by stepplot. In

this figure, G is used to compute the first response, and CL1 is used to

compute the second response. This ordering corresponds to the order of

inputs to stepplot.
Suppose you also have a PID controller design that you want to analyze.
Create a model of the closed-loop system using this alternate controller.
C2 = pid(2,2.6,0.4,0.002);
CL2 = feedback(G*C2,1);

Update the step plot to display the second closed-loop system instead of
the first. The closed-loop system is the second response in the plot, so
specify the index value 2.

1-736

updateSystem

updateSystem(h,CL2,2);

The updateSystem command replaces the system used to compute the

second response displayed in the plot. Instead of displaying response
data derived from CL1, the plot now shows data derived from CL2.

Related
Examples

Build GUI With Interactive Plot Updates

1-737

upsample

Purpose

Upsample discrete-time models

Syntax

sysl = upsample(sys,L)

Description

sysl = upsample(sys,L) resamples the discrete-time dynamic system

model sys at a sampling rate that is L-times faster than the sampling
time of sys (Ts0). L must be a positive integer. When sys is a TF model,
H(z), upsample returns sysl as H(zL) with the sampling time Ts0 / L.

The responses of models sys and sysl have the following similarities:
The time responses of sys and sysl match at multiples of Ts0.
The frequency responses of sys and sysl match up to the Nyquist
frequency / Ts0.
Note sysl has L times as many states as sys.

Examples

Create a transfer function with a sampling time that is 14 times faster

than that of the following transfer function:
sys = tf(0.75,[1 10 2],2.25)
Transfer function:
0.75
-------------z^2 + 10 z + 2
Sampling time: 2.25

To create the upsampled transfer function sys1, type the following

commands:
L=14;
sys1 = upsample(sys,L)

1-738

upsample

These commands return the result:

Transfer function:
0.75
-----------------z^28 + 10 z^14 + 2
Sampling time: 0.16071

The sampling time of sys1 is 0.16071 seconds, which is 14 times faster

than the 2.25 second sampling time of sys.

See Also

d2d | d2c | c2d

1-739

view (genmat)

Purpose

Visualize gain surface as a function of scheduling variables

Syntax

view(M)
view(M,xvar)
view(M,xvar,yvar)
view(M,xvar,xdata)
view(M,xvar,xdata,yvar,ydata)

Description

view(M) plots the values of a 1-D or 2-D array of generalized matrices

on a 1-D or 2-D plot. Typically, M is a tunable gain surface that you

create with gainsurf. The plot uses the independent variable values
specified in M.SamplingGrid if available. Otherwise, The plot uses the
indices along each array dimension for the X and Y values.
view(M,xvar) plots a 1-D plot of values in the generalized matrix
array against a specified independent variable, xvar. For a 2-D
array, the plot contains multiple traces corresponding to the other
dimension in the array. xvar must refer to a sampling variable listed
in M.SamplingGrid.
view(M,xvar,yvar) plots the values in the generalized matrix array

against the specified independent variables, placing xvar on the X

axis and yvar on the Y axis. xvar and yvar must refer to sampling
variables listed in M.SamplingGrid. Use this syntax:
To specify the order of independent variables plotted along the X
and Y axes.
To select the independent variable values when M.SamplingGrid
lists more than two independent variables.
view(M,xvar,xdata) plots a 1-D plot of values in the generalized

matrix array, using xvar to name the X axis. This plot also uses the
values in xdata as the values along the X axis. Use this syntax when
M.SamplingGrid is empty.

1-740

view (genmat)

view(M,xvar,xdata,yvar,ydata) plots a 2-D plot of values in the

generalized matrix array, using xvar and yvar to name the X and Y
axes, respectively. This plot also uses the values in xdata and ydata
as values along the X and Y axes, respectively. Use this syntax when
M.SamplingGrid is empty.

Input
Arguments

M - Array of generalized matrices

genmat array

Array of generalized matrices to plot, specified as a genmat array.

Typically, M represents a variable gain surface that you create using
the gainsurfcommand. Optionally, you can set the SamplingGrid
property of M to list the independent variable names and values
corresponding to entries in the array. See the genmat reference page
for more information.
xvar - X-axis variable

string

X-axis variable in the plot, specified as a string.

If the SamplingGrid property of M specifies independent variable names
and values, xvar must match one of those variable names. In this case,
view uses the values stored in M.SamplingGrid for the X axis of the plot.
If the SamplingGrid property of M is empty, view uses xvar to label the
X axis of the plot. In this case, you must also specify values for the X
axis using the xvar input argument.
yvar - Y-axis variable

string

Y-axis variable in the plot, specified as a string.

If the SamplingGrid property of M specifies independent variable names
and values, yvar must match one of those variable names. In this case,
view uses the values stored in M.SamplingGrid for the Y axis of the plot.

1-741

view (genmat)

If the SamplingGrid property of M is empty, view uses yvar to label the

Y axis of the plot. In this case, you must also specify values for the Y
axis using the yvar input argument.
xdata - X-axis values
numeric vector

X-axis values in the plots, specified as a numeric vector. If the

SamplingGrid property of M is empty, use xdata to specify values for
view to display along the X axis of the plot. The length of xdata must
match the first array dimension of M.
ydata - Y-axis values

numeric vector

Y-axis values in the plots, specified as a numeric vector. If the

SamplingGrid property of M is empty, use ydata to specify values for
view to display along the Y axis of the plot. The length of ydata must

match the first array dimension of M.

Examples

View Gain Surface

Display a tunable gain surface that depends on two independent
variables.
Create a scalar gain, K, that is a bilinear function of two independent
variables, and :

K , K 0 K1 K 2 K 3 .
[alpha,beta] = ndgrid(0:1:15,300:50:600);
F1 = alpha;
F2 = beta;
F3 = alpha.*beta;
K = gainsurf('K',1,F1,F2,F3);
K.SamplingGrid = struct('alpha',alpha,'beta',beta);

1-742

view (genmat)

gainsurf initializes all gain surface coefficients to zero. For this

example, manually set the coefficients to nonzero values.
K.Blocks.K_1.Value = -0.015;
K.Blocks.K_2.Value = 0.02;
K.Blocks.K_3.Value = 0.01;

Typically, you would tune the coefficients as part of a control system.

You would then use setBlockValue to write the tuned coefficients back
to K, and view the tuned gain surface.
Plot the gain surface.
view(K);

1-743

view (genmat)

view automatically applies the axis labels and scaling stored in the
SamplingGrid property of the gain surface (see the genmat reference
page). If the SamplingGrid property is empty, the independent variable

axes are unlabeled and the values are index values.

By default, view puts alpha on the X-axis. This ordering arises because
SamplingGrid associates alpha with the first dimension of the gain
matrix. Reverse the ordering of the independent variables on the Xand Y-axes.

1-744

view (genmat)

view(K,'beta','alpha')

View 1-Dimensional Projections of Gain Surface

Plot gain surface values as a function of one independent variable, for a
gain surface that depends on two independent variables.
Create a gain surface that is a bilinear function of two independent
variables, and .

1-745

view (genmat)

[alpha,beta] = ndgrid(0:1:15,300:50:600);
F1 = alpha;
F2 = beta;
F3 = alpha.*beta;
K = gainsurf('K',1,F1,F2,F3);
SG = struct('alpha',alpha,'beta',beta);
K.SamplingGrid = SG;
gainsurf initializes all gain surface coefficients to zero. For this
example, manually set the coefficients to nonzero values.
K.Blocks.K_1.Value = -0.015;
K.Blocks.K_2.Value = 0.02;
K.Blocks.K_3.Value = 0.01;

Typically, you would tune the coefficients as part of a control system.

You would then use setBlockValue to write the tuned coefficients back
to K, and view the tuned gain surface.
Plot the gain as a function of for all values of in the grid of the gain
surface.
view(K,'beta')

1-746

view (genmat)

view scales the X-axis using the beta values stored in the SamplingGrid

property of the gain surface. This plot is useful to visualize the full
range of gain variation due to one independent variable.

View Gain Surface With Specified Independent Variable

Names and Values
Plot a gain surface for which you provide variable names and values.
When plotting a gain surface for which you have not specified a
SamplingGrid property value, view cannot label the independent

1-747

view (genmat)

variable axes. In addition, the independent variable values are just the
index values of the gain matrix. (For information about SamplingGrid,
see the genmat reference page). In this case, you can specify variable
names and values for the purpose of the plot.
Create a gain surface that is a bilinear function of two independent
variables, and .
[alpha,beta] = ndgrid(0:1:15,300:50:600);
F1 = alpha;
F2 = beta;
F3 = alpha.*beta;
K = gainsurf('K',1,F1,F2,F3);
gainsurf initializes all gain surface coefficients to zero. For this
example, manually set the coefficients to nonzero values.
K.Blocks.K_1.Value = -0.015;
K.Blocks.K_2.Value = 0.02;
K.Blocks.K_3.Value = 0.01;

Typically, you would tune the coefficients as part of a control system.

You would then use setBlockValue to write the tuned coefficients back
to K, and view the tuned gain surface.
View the gain surface, specifying variable names and values.
view(K,'A',0:0.1:1.5,'B',15:2.5:30)

1-748

view (genmat)

You can use any variable name and values that you like. The name and
value only label the axes and do not affect the gain values themselves,
which are stored in K. However, the vectors you supply for the variable
values must match the sampling dimensions of the gain surface. For
example, K is created using an 16-element vector for its first dimension.
Therefore, the vector you provide of values for that dimension must
also have 16 elements.

1-749

view (genmat)

See Also
Functions

1-750

genmatgainsurfgetValuesetBlockValue

xperm

Purpose

Reorder states in state-space models

Syntax

sys = xperm(sys,P)

Description

sys = xperm(sys,P) reorders the states of the state-space model

sys according to the permutation P. The vector P is a permutation of
1:NX, where NX is the number of states in sys. For information about
creating state-space models, see ss and dss.

Examples

Order the states in the ssF8 model in alphabetical order.

1 Load the ssF8 model by typing the following commands:

load ltiexamples
ssF8

These commands return:

a =
PitchRate

Velocity

AOA

-0.7

-0.0458

-12.2

-0.014

-0.2904

-0.562

AOA

-0.0057

-1.4

PitchAngle

PitchRate
Velocity

PitchAngle

b =
Elevator
PitchRate
Velocity
AOA
PitchAngle

Flaperon

-19.1

-3.1

-0.0119

-0.0096

-0.14

-0.72

c =
PitchRate

Velocity

AOA

FlightPath

-1

PitchAngle
1

Acceleration

0.733

1-751

xperm

d =
Elevator
FlightPath
Acceleration

Flaperon

0.0768

0.1134

Continuous-time model.

2 Order the states in alphabetical order by typing the following

commands:
[y,P]=sort(ssF8.StateName);
sys=xperm(ssF8,P)

These commands return:

a =
AOA

AOA

PitchAngle

PitchRate

Velocity

-1.4

-0.0057

-12.2

-0.7

-0.0458

-0.2904

-0.562

-0.014

PitchAngle
PitchRate
Velocity
b =
AOA
PitchAngle
PitchRate
Velocity

Elevator

Flaperon

-0.14

-0.72

-19.1

-3.1

-0.0119

-0.0096

c =
AOA

PitchAngle

PitchRate

-1

0.733

FlightPath
Acceleration
d =
Elevator
FlightPath
Acceleration

1-752

Flaperon

0.0768

0.1134

Velocity

xperm

Continuous-time model.

The states in ssF8 now appear in alphabetical order.

See Also

ss | dss

1-753

zero

Purpose

Zeros and gain of SISO dynamic system

Syntax

z = zero(sys)
[z,gain] = zero(sys)
[z,gain] = zero(sysarr,J1,...,JN)

Description

z = zero(sys) returns the zeros of the single-input, single-output

(SISO) dynamic system model, sys.
[z,gain] = zero(sys) also returns the overall gain of sys.
[z,gain] = zero(sysarr,J1,...,JN) returns the zeros and gain of
the model with subscripts J1,...,JN in the model array sysarr.

Input
Arguments

sys

SISO dynamic system model.

If sys has internal delays, zero sets all internal delays to zero, creating
a zero-order Pad approximation. This approximation ensures that the
system has a finite number of zeros. zero returns an error if setting
internal delays to zero creates singular algebraic loops.
sysarr

Array of dynamic system models.

J1,...,JN

Indices identifying the model sysarr(J1,...,JN) in the array sysarr.

Output
Arguments

Column vector containing the locations of zeros in sys. The zero

locations are expressed in the reciprocal of the time units of sys. For
example, the zeros are in units of 1/minutes if the TimeUnit property of
sys is minutes.
gain

1-754

zero

Gain of sys (in the zero-pole-gain sense).

Examples

Zero Locations and Gain of Transfer Function

Calculate the zero locations and overall gain of the transfer function

H s

4.2s2 0.25s 0.004

s2 9.6 s 17

H = tf([4.2,0.25,-0.004],[1,9.6,17]);
[z,gain] = zero(H)
z =
-0.0726
0.0131

gain =
4.2000

The zero locations are expressed in radians per second, because the time
unit of the transfer function (H.TimeUnit) is seconds. Change the model
time units, and zero returns pole locations relative to the new unit.
H = chgTimeUnit(H,'minutes');
[z,gain] = zero(H)
z =
-4.3581
0.7867

gain =
4.2000

1-755

zero

Alternatives

To calculate the transmission zeros of a multi-input, multi-output

system, use tzero.

See Also

pole | pzmap | tzero

1-756

zgrid

Purpose

Generate z-plane grid of constant damping factors and natural

frequencies

Syntax

zgrid
zgrid(z,wn)
zgrid([],[])

Description

zgrid generates, for root locus and pole-zero maps, a grid of constant
damping factors from zero to one in steps of 0.1 and natural frequencies
from zero to in steps of /10, and plots the grid over the current axis.
If the current axis contains a discrete z-plane root locus diagram or
pole-zero map, zgrid draws the grid over the plot without altering the
current axis limits.
zgrid(z,wn) plots a grid of constant damping factor and natural
frequency lines for the damping factors and normalized natural
frequencies in the vectors z and wn, respectively. If the current axis
contains a discrete z-plane root locus diagram or pole-zero map,
zgrid(z,wn) draws the grid over the plot. The frequency lines for
unnormalized (true) frequencies can be plotted using
zgrid(z,wn/Ts)

where Ts is the sample time.

zgrid([],[]) draws the unit circle.

Alternatively, you can select Grid from the right-click menu to generate
the same z-plane grid.

Examples

Plot z-plane grid lines on the root locus for the system

H ( z) =

2 z2 3.4 z + 1.5
z2 1.6 z + 0.8

by typing
H = tf([2 -3.4 1.5],[1 -1.6 0.8],-1)

1-757

zgrid

Transfer function:
2 z^2 - 3.4 z + 1.5
------------------z^2 - 1.6 z + 0.8
Sampling time: unspecified

To see the z-plane grid on the root locus plot, type

rlocus(H)
zgrid
axis('square')

See Also

1-758

pzmap | rlocus | sgrid

zpk

Purpose

Create zero-pole-gain model; convert to zero-pole-gain model

Syntax

sys = zpk(z,p,k)

sys = zpk(z,p,k,Ts)
sys = zpk(M)
sys = zpk(z,p,k,ltisys)
s = zpk('s')
z = zpk('z',Ts)
zsys = zpk(sys)
zsys = zpk(sys, 'measured')
zsys = zpk(sys, 'noise')
zsys = zpk(sys, 'augmented')

Description

Used zpk to create zero-pole-gain models (zpk model objects), or to

convert dynamic systems to zero-pole-gain form.

Creation of Zero-Pole-Gain Models

sys = zpk(z,p,k) creates a continuous-time zero-pole-gain model with
zeros z, poles p, and gain(s) k. The output sys is a zpk model object
storing the model data.

In the SISO case, z and p are the vectors of real- or complex-valued

zeros and poles, and k is the real- or complex-valued scalar gain:

h ( s) = k

( s z (1 ) ) ( s z ( 2 ) ) ( s z ( m ) )
( s p (1 ) ) ( s p ( 2 ) ) ( s p ( n ) )

Set z or p to [] for systems without zeros or poles. These two vectors

need not have equal length and the model need not be proper (that is,
have an excess of poles).
To create a MIMO zero-pole-gain model, specify the zeros, poles, and
gain of each SISO entry of this model. In this case:
z and p are cell arrays of vectors with as many rows as outputs and
as many columns as inputs, and k is a matrix with as many rows as
outputs and as many columns as inputs.

1-759

zpk

The vectors z{i,j} and p{i,j} specify the zeros and poles of the
transfer function from input j to output i.
k(i,j) specifies the (scalar) gain of the transfer function from input
j to output i.
See below for a MIMO example.
sys = zpk(z,p,k,Ts) creates a discrete-time zero-pole-gain model
with sample time Ts (in seconds). Set Ts = -1 or Ts = [] to leave the
sample time unspecified. The input arguments z, p, k are as in the
continuous-time case.
sys = zpk(M) specifies a static gain M.
sys = zpk(z,p,k,ltisys) creates a zero-pole-gain model with
properties inherited from the LTI model ltisys (including the sample

time).
To create an array of zpk model objects, use a for loop, or use
multidimensional cell arrays for z and p, and a multidimensional array
for k.
Any of the previous syntaxes can be followed by property name/property
value pairs.
'PropertyName',PropertyValue

Each pair specifies a particular property of the model, for example, the
input names or the input delay time. For more information about the
properties of zpk model objects, see Properties on page 1-762. Note
that
sys = zpk(z,p,k,'Property1',Value1,...,'PropertyN',ValueN)

is a shortcut for the following sequence of commands.

sys = zpk(z,p,k)
set(sys,'Property1',Value1,...,'PropertyN',ValueN)

1-760

zpk

Zero-Pole-Gain Models as Rational Expressions in s or z

You can also use rational expressions to create a ZPK model. To do
so, first type either:
s = zpk('s') to specify a ZPK model using a rational function in
the Laplace variable, s.
z = zpk('z',Ts) to specify a ZPK model with sample time Ts using
a rational function in the discrete-time variable, z.
Once you specify either of these variables, you can specify ZPK models
directly as rational expressions in the variable s or z by entering your
transfer function as a rational expression in either s or z.

Conversion to Zero-Pole-Gain Form

zsys = zpk(sys) converts an arbitrary LTI model sys to
zero-pole-gain form. The output zsys is a ZPK object. By default, zpk
uses zero to compute the zeros when converting from state-space to
zero-pole-gain. Alternatively,
zsys = zpk(sys,'inv')

uses inversion formulas for state-space models to compute the zeros.

This algorithm is faster but less accurate for high-order models with
low gain at s = 0.

Conversion of Identified Models

An identified model is represented by an input-output equation of the
form y(t) = Gu(t) + He(t), where u(t) is the set of measured input
channels and e(t) represents the noise channels. If = LL represents
the covariance of noise e(t), this equation can also be written as y(t)
= Gu(t) + HLv(t), where cov(v(t)) = I.
zsys = zpk(sys), or zsys = zpk(sys, 'measured') converts the
measured component of an identified linear model into the ZPK form.
sys is a model of type idss, idproc, idtf, idpoly, or idgrey. zsys
represents the relationship between u and y.

1-761

zpk

zsys = zpk(sys, 'noise') converts the noise component of an

identified linear model into the ZPK form. It represents the relationship
between the noise input, v(t) and output, y_noise = HL v(t). The
noise input channels belong to the InputGroup 'Noise'. The names of
the noise input channels are v@yname, where yname is the name of the
corresponding output channel. zsys has as many inputs as outputs.
zsys = zpk(sys, 'augmented') converts both the measured and noise
dynamics into a ZPK model. zsys has ny+nu inputs such that the first
nu inputs represent the channels u(t) while the remaining by channels
represent the noise channels v(t). zsys.InputGroup contains 2 input
groups, 'measured' and 'noise'. zsys.InputGroup.Measured is set
to 1:nu while zsys.InputGroup.Noise is set to nu+1:nu+ny. zsys
represents the equation y(t) = [G HL] [u; v].

Tip An identified nonlinear model cannot be converted into a ZPK

system. Use linear approximation functions such as linearize and
linapp.

Variable
Selection

As for transfer functions, you can specify which variable to use in the
display of zero-pole-gain models. Available choices include s (default)
and p for continuous-time models, and z (default), z-1, q-1 (equivalent
to z-1), or q (equivalent to z) for discrete-time models. Reassign the
'Variable' property to override the defaults. Changing the variable
affects only the display of zero-pole-gain models.

Properties

zpk objects have the following properties:

z

System zeros.
The z property stores the transfer function zeros (the numerator roots).
For SISO models, z is a vector containing the zeros. For MIMO models
with Ny outputs and Nu inputs, z is a Ny-by-Nu cell array of vectors of the
zeros for each input/output pair.

1-762

zpk

System poles.
The p property stores the transfer function poles (the denominator
roots). For SISO models, p is a vector containing the poles. For MIMO
models with Ny outputs and Nu inputs, p is a Ny-by-Nu cell array of
vectors of the poles for each input/output pair.
k

System gains.
The k property stores the transfer function gains. For SISO models, k is
a scalar value. For MIMO models with Ny outputs and Nu inputs, k is a
Ny-by-Nu matrix storing the gains for each input/output pair.
DisplayFormat

String specifying the way the numerator and denominator polynomials

are factorized for display purposes.
The numerator and denominator polynomials are each displayed as a
product of first- and second-order factors. DisplayFormat controls the
display of those factors. DisplayFormat can take the following values:
'roots' (default) Display factors in terms of the location of the
polynomial roots.
'frequency' Display factors in terms of root natural frequencies
0 and damping ratios .
The 'frequency' display format is not available for discrete-time
models with Variable value 'z^-1' or 'q^-1'.
'time constant' Display factors in terms of root time constants
and damping ratios .
The 'time constant' display format is not available for
discrete-time models with Variable value 'z^-1' or 'q^-1'.
For continuous-time models, the following table shows how the
polynomial factors are written in each display format.

1-763

zpk

DisplayName Value

First-Order Factor (Real

Root R)

Second-Order Factor
(Complex Root pair
R = ajb)

'roots'

(s R)

(s2 s + ), where = 2a,

= a 2 + b2

'frequency'

(1 s/0), where 0 = R

1 2(s/0) + (s/0)2, where

02 = a2 + b2, = a/0

'time constant'

(1 s), where = 1/R

1 2(s) + (s)2, where

= 1/0, = a

For discrete-time models, the polynomial factors are written as in

continuous time, with the following variable substitutions:

sw

z 1
;
Ts

R 1
,
Ts

where Ts is the sampling time. In discrete time, and 0 closely

match the time constant and natural frequency of the equivalent
continuous-time root, provided |z1| Ts (0 /Ts = Nyquist frequency).
Default: 'roots'
Variable

String specifying the transfer function display variable. Variable can

take the following values:
's' Default for continuous-time models
'z' Default for discrete-time models
'p' Equivalent to 's'
'q' Equivalent to 'z'
'z^-1' Inverse of 'z'
'q^-1' Equivalent to 'z^-1'

1-764

zpk

The value of Variable only affects the display of zpk models.

Default: 's'
ioDelay

Transport delays. ioDelay is a numeric array specifying a separate

transport delay for each input/output pair.
For continuous-time systems, specify transport delays in the time unit
stored in the TimeUnit property. For discrete-time systems, specify
transport delays in integer multiples of the sampling period, Ts.
For a MIMO system with Ny outputs and Nu inputs, set ioDelay to
a Ny-by-Nu array. Each entry of this array is a numerical value that
represents the transport delay for the corresponding input/output pair.
You can also set ioDelay to a scalar value to apply the same delay to all
input/output pairs.
Default: 0 for all input/output pairs
InputDelay - Input delays
0 (default) | scalar | vector

Input delay for each input channel, specified as a numeric vector. For
continuous-time systems, specify input delays in the time unit stored
in the TimeUnit property. For discrete-time systems, specify input
delays in integer multiples of the sampling period Ts. For example,
InputDelay = 3 means a delay of three sampling periods.
For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each
entry of this vector is a numerical value that represents the input delay
for the corresponding input channel.
You can also set InputDelay to a scalar value to apply the same delay
to all channels.
OutputDelay

1-765

zpk

Output delays. OutputDelay is a numeric vector specifying a time

delay for each output channel. For continuous-time systems, specify
output delays in the time unit stored in the TimeUnit property. For
discrete-time systems, specify output delays in integer multiples of the
sampling period Ts. For example, OutputDelay = 3 means a delay
of three sampling periods.
For a system with Ny outputs, set OutputDelay to an Ny-by-1 vector,
where each entry is a numerical value representing the output delay for
the corresponding output channel. You can also set OutputDelay to a
scalar value to apply the same delay to all channels.
Default: 0 for all output channels
Ts

Sampling time. For continuous-time models, Ts = 0. For discrete-time

models, Ts is a positive scalar representing the sampling period. This
value is expressed in the unit specified by the TimeUnit property of
the model. To denote a discrete-time model with unspecified sampling
time, set Ts = -1.
Changing this property does not discretize or resample the model.
Use c2d and d2c to convert between continuous- and discrete-time
representations. Use d2d to change the sampling time of a discrete-time
system.
Default: 0 (continuous time)
TimeUnit

String representing the unit of the time variable. For continuous-time

models, this property represents any time delays in the model. For
discrete-time models, it represents the sampling time Ts. Use any of
the following values:
'nanoseconds'
'microseconds'

1-766

zpk

'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
Changing this property changes the overall system behavior. Use
chgTimeUnit to convert between time units without modifying system
behavior.
Default: 'seconds'
InputName

Input channel names. Set InputName to a string for single-input model.

For a multi-input model, set InputName to a cell array of strings.
Alternatively, use automatic vector expansion to assign input names for
multi-input models. For example, if sys is a two-input model, enter:
sys.InputName = 'controls';

The input names automatically expand to

{'controls(1)';'controls(2)'}.
You can use the shorthand notation u to refer to the InputName
property. For example, sys.u is equivalent to sys.InputName.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models

1-767

zpk

Default: Empty string '' for all input channels

InputUnit

Input channel units. Use InputUnit to keep track of input signal units.
For a single-input model, set InputUnit to a string. For a multi-input
model, set InputUnit to a cell array of strings. InputUnit has no effect
on system behavior.
Default: Empty string '' for all input channels
InputGroup

Input channel groups. The InputGroup property lets you assign the
input channels of MIMO systems into groups and refer to each group
by name. Specify input groups as a structure. In this structure, field
names are the group names, and field values are the input channels
belonging to each group. For example:
sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

creates input groups named controls and noise that include input
channels 1, 2 and 3, 5, respectively. You can then extract the subsystem
from the controls inputs to all outputs using:
sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names. Set OutputName to a string for single-output

model. For a multi-output model, set OutputName to a cell array of
strings.
Alternatively, use automatic vector expansion to assign output names
for multi-output models. For example, if sys is a two-output model,
enter:

1-768

zpk

sys.OutputName = 'measurements';

The output names to automatically expand to

{'measurements(1)';'measurements(2)'}.
You can use the shorthand notation y to refer to the OutputName
property. For example, sys.y is equivalent to sys.OutputName.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
Default: Empty string '' for all input channels
OutputUnit

Output channel units. Use OutputUnit to keep track of output signal

units. For a single-output model, set OutputUnit to a string. For
a multi-output model, set OutputUnit to a cell array of strings.
OutputUnit has no effect on system behavior.
Default: Empty string '' for all input channels
OutputGroup

Output channel groups. The OutputGroup property lets you assign the
output channels of MIMO systems into groups and refer to each group
by name. Specify output groups as a structure. In this structure, field
names are the group names, and field values are the output channels
belonging to each group. For example:
sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that

include output channels 1, and 3, 5, respectively. You can then extract
the subsystem from all inputs to the measurement outputs using:

1-769

zpk

sys('measurement',:)

Default: Struct with no fields

Name

System name. Set Name to a string to label the system.

Default: ''
Notes

Any text that you want to associate with the system. Set Notes to a
string or a cell array of strings.
Default: {}
UserData

Any type of data you wish to associate with system. Set UserData to
any MATLAB data type.
Default: []
SamplingGrid

Sampling grid for model arrays, specified as a data structure.

For model arrays that are derived by sampling one or more independent
variables, this property tracks the variable values associated with
each model in the array. This information appears when you display
or plot the model array. Use this information to trace results back to
the independent variables.
Set the field names of the data structure to the names of the sampling
variables. Set the field values to the sampled variable values associated
with each model in the array. All sampling variables should be numeric
and scalar valued, and all arrays of sampled values should match the
dimensions of the model array.

1-770

zpk

For example, suppose you create a 11-by-1 array of linear models,

sysarr, by taking snapshots of a linear time-varying system at times
t = 0:10. The following code stores the time samples with the linear
models.
sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently

sampling two variables, zeta and w. The following code attaches the
(zeta,w) values to M.
[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding
zeta and w values.
M
M(:,:,1,1) [zeta=0.3, w=5] =
25
-------------s^2 + 3 s + 25

M(:,:,2,1) [zeta=0.35, w=5] =

25
---------------s^2 + 3.5 s + 25
...

Default: []

Examples

Example 1
Create the continuous-time SISO transfer function:

1-771

zpk

h ( s) =

2s
( s 1 + j ) ( s 1 j ) ( s 2)

Create h(s) as a zpk object using:

h = zpk(0, [1-i 1+i 2], -2);

Example 2
Specify the following one-input, two-output zero-pole-gain model:

z 0 .3
.
H ( z) =
2 ( z + 0 .5 )

( z 0 .1 + j ) ( z 0 .1 j )

To do this, enter:
z
p
k
H

=
=
=
=

{[] ; -0.5};
{0.3 ; [0.1+i 0.1-i]};
[1 ; 2];
zpk(z,p,k,-1);
% unspecified sample time

Example 3
Convert the transfer function
h = tf([-10 20 0],[1 7 20 28 19 5]);

to zero-pole-gain form, using:

zpk(h)

This command returns the result:

Zero/pole/gain:
-10 s (s-2)

1-772

zpk

---------------------(s+1)^3 (s^2 + 4s + 5)

Example 4
Create a discrete-time ZPK model from a rational expression in the
variable z.
z = zpk('z',0.1);
H = (z+.1)*(z+.2)/(z^2+.6*z+.09)

This command returns the following result:

Zero/pole/gain:
(z+0.1) (z+0.2)
--------------(z+0.3)^2
Sampling time: 0.1

Example 5
Create a MIMO zpk model using cell arrays of zeros and poles.
Create the two-input, two-output zero-pole-gain model

H ( s) =
2
2 s 2s + 2

( s 1) ( s 2 ) ( s 3 )

3 ( s + 5)

( s + 1 )2

by entering:
Z = {[],-5;[1-i 1+i] []};
P = {0,[-1 -1];[1 2 3],[]};

1-773

zpk

K = [-1 3;2 0];

H = zpk(Z,P,K);

Use [] as a place holder in Z or P when the corresponding entry of H(s)

has no zeros or poles.

Example 6
Extract the measured and noise components of an identified polynomial
model into two separate ZPK models. The former (measured component)
can serve as a plant model while the latter can serve as a disturbance
model for control system design.
load icEngine
z = iddata(y,u,0.04);
nb = 2; nf = 2; nc = 1; nd = 3; nk = 3;
sys = bj(z, [nb nc nd nf nk]);
sys is a model of the form, y(t) = B/F u(t) + C/D e(t), where B/F
represents the measured component and C/D the noise component.
sysMeas = zpk(sys, 'measured')

Alternatively, use can simply use zpk(sys) to extract the measured

component.
sysNoise = zpk(sys, 'noise')

Algorithms

zpk uses the MATLAB function roots to convert transfer functions and
the functions zero and pole to convert state-space models.

See Also

frd | get | set | ss | tf | zpkdata

1-774

zpkdata

Purpose

Access zero-pole-gain data

Syntax

[z,p,k] = zpkdata(sys)
[z,p,k,Ts] = zpkdata(sys)
[z,p,k,Ts,covz,covp,covk] = zpkdata(sys)

Description

[z,p,k] = zpkdata(sys) returns the zeros z, poles p, and gain(s) k

of the zero-pole-gain model sys. The outputs z and p are cell arrays

with the following characteristics:

z and p have as many rows as outputs and as many columns as
inputs.
The (i,j) entries z{i,j} and p{i,j} are the (column) vectors of
zeros and poles of the transfer function from input j to output i.
The output k is a matrix with as many rows as outputs and as many
columns as inputs such that k(i,j) is the gain of the transfer function
from input j to output i. If sys is a transfer function or state-space
model, it is first converted to zero-pole-gain form using zpk.
For SISO zero-pole-gain models, the syntax
[z,p,k] = zpkdata(sys,'v')

forces zpkdata to return the zeros and poles directly as column vectors
rather than as cell arrays (see example below).
[z,p,k,Ts] = zpkdata(sys) also returns the sample time Ts.
[z,p,k,Ts,covz,covp,covk] = zpkdata(sys) also returns the
covariances of the zeros, poles and gain of the identified model sys.
covz is a cell array such that covz{ky,ku} contains the covariance
information about the zeros in the vector z{ky,ku}. covz{ky,ku}
is a 3-D array of dimension 2-by-2-by-Nz, where Nz is the length of
z{ky,ku}, so that the (1,1) element is the variance of the real part, the
(2,2) element is the variance of the imaginary part, and the (1,2) and
(2,1) elements contain the covariance between the real and imaginary
parts. covp has a similar relationship to p.covk is a matrix containing
the variances of the elements of k.

1-775

zpkdata

You can access the remaining LTI properties of sys with get or by
direct referencing, for example,
sys.Ts
sys.inputname

Examples

Example 1
Given a zero-pole-gain model with two outputs and one input
H = zpk({[0];[-0.5]},{[0.3];[0.1+i 0.1-i]},[1;2],-1)
Zero/pole/gain from input to output...
z
#1: ------(z-0.3)

#2:

2 (z+0.5)
------------------(z^2 - 0.2z + 1.01)

Sampling time: unspecified

you can extract the zero/pole/gain data embedded in H with

[z,p,k] = zpkdata(H)
z =
[
0]
[-0.5000]
p =
[
0.3000]
[2x1 double]
k =
1
2

To access the zeros and poles of the second output channel of H, get the
content of the second cell in z and p by typing

1-776

zpkdata

z{2,1}
ans =
-0.5000
p{2,1}
ans =
0.1000+ 1.0000i
0.1000- 1.0000i

Example 2
Extract the ZPK matrices and their standard deviations for a 2-input, 1
output identified transfer function.
load iddata7

transfer function model

sys1 = tfest(z7, 2, 1, 'InputDelay',[1 0]);

an equivalent process model

sys2 = procest(z7, {'P2UZ', 'P2UZ'}, 'InputDelay',[1 0]);
1, p1, k1, ~, dz1, dp1, dk1] = zpkdata(sys1);
[z2, p2, k2, ~, dz2, dp2, dk2] = zpkdata(sys2);

Use iopzplot to visualize the pole-zero locations and their covariances

h = iopzplot(sys1, sys2);
showConfidence(h)

See Also

get | ssdata | tfdata | zpk

1-777

zpkdata

1-778

2
Block Reference

LTI System

Purpose

Use linear system model object in Simulink

Description

The LTI System block imports linear system model objects into the
Simulink environment.
The imported system must be proper. State-space models are always
proper. SISO transfer functions or zero-pole-gain models are proper if
the degree of their numerator is less than or equal to the degree of their
denominator. MIMO transfer functions are proper if all their SISO
entries are proper.

2-2

LTI System

Dialog
Box

LTI system variable

Enter your LTI model. This block supports state-space,
zero/pole/gain, and transfer function formats. Your model can
be discrete- or continuous-time.
Initial states (state-space only)
If your model is in state-space format, you can specify the initial
states in vector format. The default is zero for all states.

2-3