en fr

Sysquake Pro – Table of Contents

Sysquake – Table of Contents

Sysquake for LaTeX – Table of Contents

Graphics for Dynamic Systems

Graphical commands described in this section are related to automatic control. They display the time responses and frequency responses of linear time-invariant systems defined by transfer functions or state-space models in continuous time (Laplace transform) or discrete time (z transform).

Some of these functions can return results in output arguments instead of displaying them. These values depend not only on the input arguments, but also on the current scale of the figure. For instance, the set of frequencies where the response of the system is evaluated for the Nyquist diagram is optimized in the visible area. Option Range of responseset can be used when this behavior is not suitable, such as for phase portraits using lsim. Output can be used for uncommon display purposes such as special styles, labels, or export. Evaluation or simulation functions not related to graphics, like polyval, ode45 or filter, are better suited to other usages.

bodemag

Magnitude Bode diagram of a continuous-time system.

Syntax

bodemag(numc, denc)
bodemag(numc, denc, w)
bodemag(numc, denc, opt)
bodemag(numc, denc, w, opt)
bodemag(Ac, Bc, Cc, Dc)
bodemag(Ac, Bc, Cc, Dc, w)
bodemag(Ac, Bc, Cc, Dc, opt)
bodemag(Ac, Bc, Cc, Dc, w, opt)
bodemag(..., style)
bodemag(..., style, id)
(mag, w) = bodemag(...)

Description

bodemag(numc,denc) plots the magnitude of the frequency response of the continuous-time transfer function numc/denc. The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

bodemag(Ac,Bc,Cc,Dc) plots the magnitude of the frequency response Y(jw)/U(jw) of the continuous-time state-space model (Ac,Bc,Cc,Dc) defined as

jw X(jw) = Ac X(jw) + Bc U(jw)
   Y(jw) = Cc X(jw) + Dc U(jw)

With output arguments, bodemag gives the magnitude and the frequency as column vectors. No display is produced.

Examples

Green plot for abs(1 / (s^3 + 2s^2 + 3s + 4)) with s = jw:

bodemag(1, [1, 2, 3, 4], 'g');

The same plot, between w=0 and w=10:

scale([0,10]);
bodemag(1, [1, 2, 3, 4], 'g');

See also

bodephase, dbodemag, sigma, responseset, plotset

bodephase

Phase Bode diagram for a continuous-time system.

Syntax

bodephase(numc, denc)
bodephase(numc, denc, w)
bodephase(numc, denc, opt)
bodephase(numc, denc, w, opt)
bodephase(Ac, Bc, Cc, Dc)
bodephase(Ac, Bc, Cc, Dc, w)
bodephase(Ac, Bc, Cc, Dc, opt)
bodephase(Ac, Bc, Cc, Dc, w, opt)
bodephase(..., style)
bodephase(..., style, id)
(phase, w) = bodephase(...)

Description

bodephase(numc,denc) plots the phase of the frequency response of the continuous-time transfer function numc/denc. The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options (such as time delay) can be provided in a structure opt created with responseset; fields Delay and Range are utilized. The optional arguments style and id have their usual meaning.

bodephase(Ac,Bc,Cc,Dc) plots the phase of the frequency response Y(jw)/U(jw) of the continuous-time state-space model (Ac,Bc,Cc,Dc) defined as

jw X(jw) = Ac X(jw) + Bc U(jw)
   Y(jw) = Cc X(jw) + Dc U(jw)

With output arguments, bodephase gives the phase and the frequency as column vectors. No display is produced.

Example

Green plot for angle(1 / (s^3 + 2s^2 + 3s + 4)), with s = jw:

bodephase(1, [1, 2, 3, 4], 'g');

See also

bodemag, dbodephase, responseset, plotset

dbodemag

Magnitude Bode diagram for a discrete-time system.

Syntax

dbodemag(numd, dend, Ts)
dbodemag(numd, dend, Ts, w)
dbodemag(numd, dend, Ts, opt)
dbodemag(numd, dend, Ts, w, opt)
dbodemag(Ad, Bd, Cd, Dd, Ts)
dbodemag(Ad, Bd, Cd, Dd, Ts, w)
dbodemag(Ad, Bd, Cd, Dd, Ts, opt)
dbodemag(Ad, Bd, Cd, Dd, Ts, w, opt)
dbodemag(..., style)
dbodemag(..., style, id)
(mag, w) = dbodemag(...)

Description

dbodemag(numd,dend,Ts) plots the magnitude of the frequency response of the discrete-time transfer function numd/dend with sampling period Ts. The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

dbodemag(Ad,Bd,Cd,Dd,Ts) plots the magnitude of the frequency response Y(jw)/U(jw) of the discrete-time state-space model (Ad,Bd,Cd,Dd) defined as

z X(z) = Ad X(z) + Bd U(z)
  Y(z) = Cd X(z) + Dd U(z)

where z=exp(j*w*Ts).

With output arguments, dbodemag gives the magnitude and the frequency as column vectors. No display is produced.

Example

dbodemag(1,poly([0.9,0.7+0.6j,0.7-0.6j]),1);

See also

bodemag, dbodephase, dsigma, responseset, plotset

dbodephase

Phase Bode diagram for a discrete-time system.

Syntax

dbodephase(numd, dend, Ts)
dbodephase(numd, dend, Ts, w)
dbodephase(numd, dend, Ts, opt)
dbodephase(numd, dend, Ts, w, opt)
dbodephase(Ad, Bd, Cd, Dd, Ts)
dbodephase(Ad, Bd, Cd, Dd, Ts, w)
dbodephase(Ad, Bd, Cd, Dd, Ts, opt)
dbodephase(Ad, Bd, Cd, Dd, Ts, w, opt)
dbodephase(..., style)
dbodephase(..., style, id)
(phase, w) = dbodephase(...)

Description

dbodemag(numd,dend,Ts) plots the phase of the frequency response of the discrete-time transfer function numd/dend with sampling period Ts. The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

dbodephase(Ad,Bd,Cd,Dd,Ts) plots the phase of the frequency response Y(jw)/U(jw) of the discrete-time state-space model (Ad,Bd,Cd,Dd) defined as

z X(z) = Ad X(z) + Bd U(z)
  Y(z) = Cd X(z) + Dd U(z)

where z=exp(j*w*Ts).

With output arguments, dbodephase gives the phase and the frequency as column vectors. No display is produced.

Example

dbodephase(1,poly([0.9,0.7+0.6j,0.7-0.6j]),1);

See also

bodephase, dbodemag, responseset, plotset

dimpulse

Impulse response plot of a discrete-time linear system.

Syntax

dimpulse(numd, dend, Ts)
dimpulse(numd, dend, Ts, opt)
dimpulse(Ad, Bd, Cd, Dd, Ts)
dimpulse(Ad, Bd, Cd, Dd, Ts, opt)
dimpulse(..., style)
dimpulse(..., style, id)
(y, t) = dimpulse(...)

Description

dimpulse(numd,dend,Ts) plots the impulse response of the discrete-time transfer function numd/dend with sampling period Ts.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

dimpulse(Ad,Bd,Cd,Dd,Ts) plots the impulse response of the discrete-time state-space model (Ad,Bd,Cd,Dd) defined as

x(k+1) = Ad x(k) + Bd u(k)
y(k)   = Cd x(k) + Dd u(k)

where u(k) is a unit discrete impulse. The state-space model must have a scalar input, and may have a scalar or vector output.

With output arguments, dimpulse gives the output and the time as column vectors. No display is produced.

Example

dimpulse(1, poly([0.9,0.7+0.6j,0.7-0.6j]), 1, 'r');

See also

impulse, dstep, dlsim, dinitial, responseset, plotset

dinitial

Time response plot of a discrete-time linear state-space model with initial conditions.

Syntax

dinitial(Ad, Bd, Cd, Dd, Ts, x0)
dinitial(Ad, Cd, Ts, x0)
dinitial(..., opt)
dinitial(..., style)
dinitial(..., style, id)
(y, t) = dinitial(...)

Description

dinitial(Ad,Bd,Cd,Dd,Ts,x0) plots the output(s) of the discrete-time state-space model (Ad,Bd,Cd,Dd) with null input and initial state x0. The model is defined as

x(k+1) = Ad x(k) + Bd u(k)
y(k)   = Cd x(k) + Dd u(k)

where u(k) is null. Sampling period is Ts. The state-space model may have a scalar or vector output.

Since there is no system input, matrices Bd and Dd are not used. They can be omitted.

The simulation time range can be provided in a structure opt created with responseset. It is a vector of two elements, the start time and the end time. Such an explicit time range is required when the response is not displayed in a plot where the x axis represents the time.

The optional arguments style and id have their usual meaning.

With output arguments, dinitial gives the output and the time as column vectors. No display is produced.

See also

initial, dimpulse, responseset, plotset

dlsim

Time response plot of a discrete-time linear system with arbitrary input.

Syntax

dlsim(numd, dend, u, Ts)
dlsim(Ad, Bd, Cd, Dd, u, Ts)
dlsim(Ad, Bd, Cd, Dd, u, Ts, x0)
dlsim(..., opt)
dlsim(..., style)
dlsim(..., style, id)
dlsim(..., opt, style)
dlsim(..., opt, style, id)
(y, t) = dlsim(...)

Description

dlsim(numd,dend,u,Ts) plots the time response of the discrete-time transfer function numd/dend with sampling period Ts. The input is given in real vector u, where the element i corresponds to time (i-1)*Ts. Input samples before 0 and after length(u)-1 are 0.

dlsim(Ad,Bd,Cd,Dd,u,Ts) plots the time response of the discrete-time state-space model (Ad,Bd,Cd,Dd) defined as

x(k+1) = Ad x(k) + Bd u(k,:)'
y(k)   = Cd x(k) + Dd u(k,:)'

where the system input at time sample k is u(k,:)'. For single-input systems, u can also be a row vector.

dlsim(Ad,Bd,Cd,Dd,u,Ts,x0) starts with initial state x0 at time t=0. The length of x0 must match the number of states. The default initial state is the zero vector.

The simulation time range can be provided in a structure opt created with responseset. It is a vector of two elements, the start time and the end time. Such an explicit time range is required when the response is not displayed in a plot where the x axis represents the time.

The optional arguments style and id have their usual meaning.

With output arguments, dlsim gives the output and the time as column vectors (or an array for the output of a multiple-output state-space model, where each row represents a sample). No display is produced.

Example

Simulation of a third-order system with a rectangular input:

u = repmat([ones(1,10), zeros(1,10)], 1, 3);
dlsim(1, poly([0.9,0.7+0.6j,0.7-0.6j]), u, 1, 'rs');

See also

dstep, dimpulse, dinitial, lsim, responseset, plotset

dnichols

Nichols diagram of a discrete-time system.

Syntax

dnichols(numd, dend)
dnichols(numd, dend, w)
dnichols(numd, dend, opt)
dnichols(numd, dend, w, opt)
dnichols(..., style)
dnichols(..., style, id)
w = dnichols(...)
(mag, phase) = dnichols(...)
(mag, phase, w) = dnichols(...)

Description

dnichols(numd,dend) displays the Nichols diagram of the discrete-time transfer function given by polynomials numd and dend. In discrete time, the Nichols diagram is the locus of the complex values of the transfer function evaluated at exp(j*w), where w is a real number between 0 and pi inclusive, displayed in the phase-magnitude plane. Usually, the magnitude is displayed with a logarithmic or dB scale; use scale('lindb') or scale('linlog/lindb') before dnichols.

The range of frequencies is selected automatically between 0 and pi or can be specified in an optional argument w, a vector of normalized frequencies.

Further options can be provided in a structure opt created with responseset; fields NegFreq and Range are utilized. The optional arguments style and id have their usual meaning.

With output arguments, dnichols gives the magnitude and phase of the frequency response and the frequency as column vectors. No display is produced.

In Sysquake, when the mouse is over a Nichols diagram, in addition to the magnitude and phase which can be retrieved with _y0 and _x0, the normalized frequency is obtained in _q.

Example

scale('lindb');
ngrid;
dnichols(3, poly([0.9,0.7+0.6j,0.7-0.6j]))

See also

nichols, ngrid, dnyquist, responseset, plotset

dnyquist

Nyquist diagram of a discrete-time system.

Syntax

dnyquist(numd, dend)
dnyquist(numd, dend, w)
dnyquist(numd, dend, opt)
dnyquist(numd, dend, w, opt)
dnyquist(..., style)
dnyquist(..., style, id)
w = dnyquist(...)
(re, im) = dnyquist(...)
(re, im, w) = dnyquist(...)

Description

The Nyquist diagram of the discrete-time transfer function given by polynomials numd and dend is displayed in the complex plane. In discrete time, the Nyquist diagram is the locus of the complex values of the transfer function evaluated at exp(j*w), where w is a real number between 0 and pi inclusive (other definitions include the range between pi and 2 pi, which gives a symmetric diagram with respect to the real axis).

The range of frequencies is selected automatically between 0 and pi or can be specified in an optional argument w, a vector of normalized frequencies.

Further options can be provided in a structure opt created with responseset; fields NegFreq and Range are utilized. The optional arguments style and id have their usual meaning.

With output arguments, dnichols gives the real and imaginary parts of the frequency response and the frequency as column vectors. No display is produced.

In Sysquake, when the mouse is over a Nyquist diagram, in addition to the complex value which can be retrieved with _z0 or _x0 and _y0, the normalized frequency is obtained in _q.

Example

Nyquist diagram with the same scale along both x and y axis and a Hall chart grid (reduced to a horizontal line)

scale equal;
hgrid;
dnyquist(3, poly([0.9,0.7+0.6j,0.7-0.6j]))

See also

nyquist, hgrid, dnichols, responseset, plotset

dsigma

Singular value plot for a discrete-time state-space model.

Syntax

dsigma(Ad, Bd, Cd, Dd, Ts)
dsigma(Ad, Bd, Cd, Dd, Ts, w)
dsigma(Ad, Bd, Cd, Dd, Ts, opt)
dsigma(Ad, Bd, Cd, Dd, Ts, w, opt)
dsigma(..., style)
dsigma(..., style, id)
(sv, w) = dsigma(...)

Description

dsigma(Ad,Bd,Cd,Dd,Ts) plots the singular values of the frequency response of the discrete-time state-space model (Ad,Bd,Cd,Dd) defined as

z X(z) = Ad X(z) + Bd U(z)
  Y(z) = Cd X(z) + Dd U(z)

where z=exp(j*w*Ts) and Ts is the sampling period.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

dsigma is the equivalent of dbodemag for multiple-input systems. For single-input systems, it produces the same plot.

The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

With output arguments, dsigma gives the singular values and the frequency as column vectors. No display is produced.

See also

dbodemag, dbodephase, sigma, responseset, plotset

dstep

Step response plot of a discrete-time linear system.

Syntax

dstep(numd, dend, Ts)
dstep(numd, dend, Ts, opt)
dstep(Ad, Bd, Cd, Dd, Ts)
dstep(Ad, Bd, Cd, Dd, Ts, opt)
dstep(..., style)
dstep(..., style, id)
(y, t) = dstep(...)

Description

dstep(numd,dend,Ts) plots the step response of the discrete-time transfer function numd/dend with sampling period Ts.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

dstep(Ad,Bd,Cd,Dd,Ts) plots the step response of the discrete-time state-space model (Ad,Bd,Cd,Dd) defined as

x(k+1) = Ad x(k) + Bd u(k)
y(k)   = Cd x(k) + Dd u(k)

where u(k) is a unit step. The state-space model must have a scalar input, and may have a scalar or vector output.

With output arguments, dstep gives the output and the time as column vectors. No display is produced.

Examples

Step response of a discrete-time third-order system:

dstep(1, poly([0.9,0.7+0.6j,0.7-0.6j]), 1, 'g');

Step response of a state-space model with two outputs, and a style argument which is a struct array of two elements to specify two different styles:

A = [-0.3,0.1;-0.8,-0.4];
B = [2;3];
C = [1,3;2,1];
D = [2;1];
style = {Color='navy',LineWidth=3; Color='red',LineStyle='-'};
step(A, B, C, D, style);

See also

dimpulse, dlsim, step, hstep, responseset, plotset

erlocus

Root locus of a polynomial with coefficients bounded by an ellipsoid.

Syntax

erlocus(C0, P)
erlocus(C0, P, sizes, colors)

Description

erlocus displays the set of the roots of all the polynomial whose coefficients are bounded by an ellipsoid defined by C0 and P. The polynomials are defined as C0 + [0,dC], where dC*inv(P)*dC' < 1.

If sizes and colors are provided, sizes must be a vector of n values and colors an n-by-3 matrix whose columns correspond respectively to the red, green, and blue components. The locus corresponding to dC*inv(P)*dC' < sizes(i)^2 is displayed with colors(i,:). The vector sizes must be sorted from the smallest to the largest ellipsoid. The default values are sizes = [0.1;0.5;1;2] and colors = [0,0,0;0,0,1;0.4,0.4,1;0.8,0.8,0.8] (i.e. black, dark blue, light blue, and light gray).

Warning: depending on the size of the figure (in pixels) and the speed of the computer, the computation may be slow (several seconds). The number of sizes does not have a big impact.

Example

Roots of the polynomial (z-0.8)(z-0.7-0.6j)(z-0.7+0.6j), where the coefficients, in R^3, have an uncertainty bounded by a unit sphere.

scale('equal', [-2,2,-2,2]);
erlocus(poly([0.8, 0.7+0.6j, 0.7-0.6j]), eye(3));
zgrid;

See also

plotroots, rlocus

hgrid

Hall chart grid.

Syntax

hgrid
hgrid(style)

Description

hgrid plots a Hall chart in the complex plane of the Nyquist diagram. The Hall chart represents circles which correspond to the same magnitude or phase of the closed-loop frequency response. The optional argument specifies the style.

The whole grid is displayed only if the user selects it in the Grid menu, or after the command plotoption fullgrid. By default, only the unit circle and the real axis are displayed. The whole grid is made of the circles corresponding to a closed-loop magnitude of plus or minus 0, 2, 4, 6, 10, and 20 dB; and to a closed-loop phase of plus or minus 0, 10, 20, 30, 45, 60, and 75 degrees.

Example

Hall chart grid with a Nyquist diagram:

scale('equal', [-1.5, 1.5, -1.5, 1.5]);
hgrid;
nyquist(20, poly([-1,-2+1j,-2-1j]))

See also

ngrid, nyquist, plotset, plotoption

hstep

Step response plot of a discrete-time transfer function followed by a continuous-time transfer function.

Syntax

hstep(numd, dend, Ts, numc, denc)
hstep(numd, dend, Ts, numc, denc, style)
hstep(numd, dend, Ts, numc, denc, style, id)

Description

A step is filtered first by numd/dend, a discrete-time transfer function with sampling period Ts; the resulting signal is converted to continuous-time with a zero-order hold, and filtered by the continuous-time transfer function numc/denc.

Most discrete-time controllers are used with a zero-order hold and a continuous-time system. hstep can display the simulated output of the system when a step is applied somewhere in the loop, e.g. as a reference signal or a disturbance. The transfer function numd/dend should correspond to the transfer function between the step and the system input; the transfer function numc/denc should be the model of the system.

Note that the simulation is performed in open loop. If an unstable system is stabilized with a discrete-time feedback controller, all closed-loop transfer functions are stable; however, the simulation with hstep, which uses the unstable model of the system, may diverge if it is run over a long enough time period, because of round-off errors. But in most cases, this is not a problem.

Example

Exact simulation of the output of a continuous-time system whose input comes from a zero-order hold converter:

% unstable system continuous-time transfer function
num = 1;
den = [1, -1];
% sampling at Ts = 1 (too slow, only for illustration)
Ts = 1;
[numd, dend] = c2dm(num, den, Ts);
% stabilizing proportional controller
kp = 1.5;
% transfer function between ref. signal and input
b = conv(kp, dend);
a = addpol(conv(kp, numd), dend);
% continuous-time output for a ref. signal step
scale([0,10]);
hstep(b, a, Ts, num, den);
% discrete-time output (exact)
dstep(conv(b, numd), conv(a, dend), Ts, 'o');

See also

step, dstep, plotset

impulse

Impulse response plot of a continuous-time linear system.

Syntax

impulse(numc, denc)
impulse(numc, denc, opt)
impulse(Ac, Bc, Cc, Dc)
impulse(Ac, Bc, Cc, Dc, opt)
impulse(..., style)
impulse(..., style, id)
(y, t) = impulse(...)

Description

impulse(numc,denc) plots the impulse response of the continuous-time transfer function numc/denc.

Further options can be provided in a structure opt created with responseset; fields Delay and Range are utilized. The optional arguments style and id have their usual meaning.

impulse(Ac,Bc,Cc,Dc) plots the impulse response of the continuous-time state-space model (Ac,Bc,Cc,Dc) defined as

dx/dt = Ac x + Bc u
y     = Cc x + Dc u

where u(t) is a Dirac impulse. The state-space model must have a scalar input, and may have a scalar or vector output.

With output arguments, impulse gives the output and the time as column vectors. No display is produced.

Example

impulse(1, 1:4, 'm');

See also

dimpulse, step, lsim, initial, responseset, plotset

initial

Time response plot for a continuous-time state-space model with initial conditions.

Syntax

initial(Ac, Bc, Cc, Dc, x0)
initial(Ac, Cc, x0)
initial(Ac, Bc, Cc, Dc, x0, opt)
initial(..., style)
initial(..., style, id)
(y, t) = initial(...)

Description

initial(Ac,Bc,Cc,Dc,x0) plots the output(s) of the continuous-time state-space model (Ac,Bc,Cc,Dc) with null input and initial state x0. The model is defined as

dx/dt = Ac x + Bc u
y     = Cc x + Dc u

where u(t) is null. The state-space model may have a scalar or vector output.

Since there is no system input, matrices Bd and Dd are not used. They can be omitted.

The simulation time range can be provided in a structure opt created with responseset. It is a vector of two elements, the start time and the end time. Such an explicit time range is required when the response is not displayed in a plot where the x axis represents the time.

The optional arguments style and id have their usual meaning.

With output arguments, initial gives the output and the time as column vectors. No display is produced.

Example

Response of a continuous-time system whose initial state is [5;3]:

initial([-0.3,0.1;-0.8,-0.4],[2;3],[1,3;2,1],[2;1],[5;3])

See also

dinitial, impulse, responseset, plotset

lsim

Time response plot of a continuous-time linear system with piece-wise linear input.

Syntax

lsim(numc, denc, u, t)
lsim(numc, denc, u, t, opt)
lsim(Ac, Bc, Cc, Dc, u, t)
lsim(Ac, Bc, Cc, Dc, u, t, opt)
lsim(Ac, Bc, Cc, Dc, u, t, x0)
lsim(Ac, Bc, Cc, Dc, u, t, x0, opt)
lsim(..., style)
lsim(..., style, id)
(y, t) = lsim(...)

Description

lsim(numc,denc,u,t) plots the time response of the continuous-time transfer function numd/dend. The input is piece-wise linear; it is defined by points in real vectors t and u, which must have the same length. Input before t(1) and after t(end) is 0. The input used for the simulation is interpolated to have a smooth response.

lsim(Ac,Bc,Cc,Dc,u,t) plots the time response of the continuous-time state-space model (Ac,Bc,Cc,Dc) defined as

dx/dt = Ac x + Bc u
y     = Cc x + Dc u

where the system input at time sample t(i) is u(i,:)'. For single-input systems, u can also be a row vector.

lsim(Ac,Bc,Cc,Dc,u,t,x0) starts with initial state x0 at time t=0. The length of x0 must match the number of states. The default initial state is the zero vector.

Options can be provided in a structure opt created with responseset:

'Range'
The range is a vector of two elements, the start time and the end time. Such an explicit time range is required when the response is not displayed in a plot where the x axis represents the time.
'tOnly'
When opt.tOnly is true, lsim produces output only at the time instants defined in t. The logical value false gives the default interpolated values.

The optional arguments style and id have their usual meaning.

With output arguments, lsim gives the output and the time as column vectors (or an array for the output of a multiple-output state-space model, where each row represents a sample). No display is produced.

Example

Response of continuous-time system given by its transfer function with an input defined by linear segments:

t = [0, 10, 20, 30, 50];
u = [1, 1, 0, 1, 1];
lsim(1, [1, 2, 3, 4], u, t, 'b');

See also

step, impulse, initial, dlsim, responseset, plotset

ngrid

Nichols chart grid.

Syntax

ngrid
ngrid(mag)
ngrid(..., style)

Description

ngrid plots a Nichols chart in the complex plane of the Nichols diagram. The Nichols chart is a set of lines which correspond to the same magnitude of the closed-loop frequency response. The style can be specified with an input argument.

The whole grid is displayed only if the user selects it in the Grid menu, or after the command plotoption fullgrid. By default, only the lines corresponding to unit magnitude and to a phase equal to -pi*(1+2*k), with integer k, are displayed. The whole grid is made of the lines corresponding to a closed-loop magnitude of -12, -6, -3, 0, 3, 6 and 12 dB.

The closed-loop magnitude can be specified with an input argument, a scalar or an array of positive real values. If the style is also specified, it must follow the magnitue.

Examples

Plain Nichols chart grid for a Nichols diagram:

ngrid;
nichols(7, 1:3);

Finer Nichols chart with dashed lines:

ngrid(logspace(-2, 1, 20), LineStyle='-');

See also

hgrid, nichols, plotset, plotoption

nichols

Nichols diagram of a continuous-time system.

Syntax

nichols(numc, denc)
nichols(numc, denc, w)
nichols(numc, denc, opt)
nichols(numc, denc, w, opt)
nichols(..., style)
nichols(..., style, id)
w = nichols(...)
(mag, phase) = nichols(...)
(mag, phase, w) = nichols(...)

Description

nichols(numc,denc) displays the Nichols diagram of the continuous-time transfer function given by polynomials numc and denc. In continuous time, the Nichols diagram is the locus of the complex values of the transfer function evaluated at jw, where w is real positive, displayed in the phase-magnitude plane. Usually, the magnitude is displayed with a logarithmic or dB scale; use scale('lindb') or scale('linlog/lindb') before nichols.

The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options can be provided in a structure opt created with responseset; fields Delay, NegFreq and Range are utilized. The optional arguments style and id have their usual meaning.

With output arguments, nichols gives the phase and magnitude of the frequency response and the frequency as column vectors. No display is produced.

In Sysquake, when the mouse is over a Nichols diagram, in addition to the magnitude and phase which can be retrieved with _y0 and _x0, the frequency is obtained in _q.

Examples

Nichols diagram of a third-order system:

scale('lindb');
ngrid;
nichols(20,poly([-1,-2+1j,-2-1j]));

Same plot with angles in degrees:

scale('lindb');
scalefactor([180/pi, 1]);
ngrid;
nichols(20,poly([-1,-2+1j,-2-1j]));

See also

dnichols, ngrid, nyquist, responseset, plotset, scalefactor

nyquist

Nyquist diagram of a continuous-time system.

Syntax

nyquist(numc, denc)
nyquist(numc, denc, w)
nyquist(numc, denc, opt)
nyquist(numc, denc, w, opt)
nyquist(..., style)
nyquist(..., style, id)
w = nyquist(...)
(re, im) = nyquist(...)
(re, im, w) = nyquist(...)

Description

The Nyquist diagram of the continuous-time transfer function given by polynomials numc and denc is displayed in the complex plane. In continuous time, the Nyquist diagram is the locus of the complex values of the transfer function evaluated at jw, where w is real positive (other definitions include the real negative values, which gives a symmetric diagram with respect to the real axis).

The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options can be provided in a structure opt created with responseset; fields Delay, NegFreq and Range are utilized. The optional arguments style and id have their usual meaning.

With output arguments, nyquist gives the real and imaginary parts of the frequency response and the frequency as column vectors. No display is produced.

In Sysquake, when the mouse is over a Nyquist diagram, in addition to the complex value which can be retrieved with _z0 or _x0 and _y0, the frequency is obtained in _q.

Example

Nyquist diagram of a third-order system:

scale equal;
hgrid;
nyquist(20, poly([-1,-2+1j,-2-1j]))

See also

dnyquist, hgrid, nichols, responseset, plotset

plotroots

Roots plot.

Syntax

plotroots(pol)
plotroots(pol, style)
plotroots(pol, style, id)

Description

plotroots(pol) displays the roots of the polynomial pol in the complex plane. If this argument is a matrix, each line corresponds to a different polynomial. The default style is crosses; it can be changed with a second argument, or with named arguments.

Example

den = [1, 2, 3, 4];
num = [1, 2];
scale equal;
plotroots(den, 'x');
plotroots(num, 'o');

See also

rlocus, erlocus, sgrid, zgrid, plotset, movezero

responseset

Options for frequency responses.

Syntax

options = responseset
options = responseset(name1, value1, ...)
options = responseset(options0, name1, value1, ...)

Description

responseset(name1,value1,...) creates the option argument used by functions which display frequency and time responses, such as nyquist and step. Options are specified with name/value pairs, where the name is a string which must match exactly the names in the table below. Case is significant. Options which are not specified have a default value. The result is a structure whose fields correspond to each option. Without any input argument, responseset creates a structure with all the default options. Note that functions such as nyquist and step also interpret the lack of an option argument as a request to use the default values. Contrary to other functions which accept options in structures, such as ode45, empty array [] cannot be used (it would be interpreted incorrectly as a numeric argument).

When its first input argument is a structure, responseset adds or changes fields which correspond to the name/value pairs which follow.

Here is the list of permissible options:

NameDefaultMeaning
Delay0time delay
NegFreqfalsenegative frequencies
Offset0offset
Range[]time or frequency range
tOnlyfalsesamples for specified time only (lsim)

Option Delay is used only by continuous-time frequency-response and time-response functions; for frequency responses, it subtracts a phase of delay*w, where w is the angular frequency. Option Offset adds a a value to the step or impulse response.

Option NegFreq is used in Nyquist and Nichols diagrams, continuous-time or discrete-time; when true, the response is computed for negative frequencies instead of positive frequencies. Option Range should take into account the sampling period for discrete-time commands where it is specified.

Examples

Default options:

responseset
  Delay: 0
  NegFreq: false

Nyquist diagram of exp(-s)/(s+1):

nyquist(1, [1,1], responseset('Delay', 1));

Complete Nyquist diagram of 1/(s^3+2s^2+2s+1) with dashed line for negative frequencies:

nyquist(2, [1,2,2,1]);
nyquist(2, [1,2,2,1], responseset('NegFreq',true), '-');

See also

bodemag, bodephase, dbodemag, dbodephase, dlsim, dnichols, dnyquist, dsigma, impulse, lsim, nichols, nyquist, sigma, step

rlocus

Root locus.

Syntax

rlocus(num, den)
rlocus(num, den, style)
rlocus(num, den, style, id)
branches = rlocus(num, den)

Description

The root locus is the locus of the roots of the denominator of the closed-loop transfer function (characteristic polynomial) of the system whose open-loop transfer function is num/den when the gain is between 0 and +inf inclusive. The characteristic polynomial is num+k*den, with k>=0. rlocus requires a system with real coefficients, causal or not. Note that the rlocus is defined the same way in the domain of the Laplace transform, the z transform, and the delta transform. The root locus is made of length(den)-1 branches which start from each pole and end to each zero or to a real or complex point at infinity. The locus is symmetric with respect to the real axis, because the coefficients of the characteristic polynomial are real. By definition, closed-loop poles for the current gain (i.e. the roots of num+den) are on the root locus, and move on it when the gain change. rlocus plots only the root locus, not the particular values of the roots for the current gain, a null gain or an infinite gain. If necessary, these values should be plotted with plotroots.

The part of the root locus which is calculated and drawn depends on the scale. If no scale has been set before explicitly with scale or implicitly with plotroots or plot, the default scale is set such that the zeros of num and den are visible.

With an output argument, rlocus gives the list of root locus branches, i.e. a list of row vectors which contain the roots. Different branches do not always have the same numbers of values, because rlocus adapts the gain steps for each branch. Parts of the root locus outside the visible area of the complex plane, as defined by the current scale, have enough points to avoid any interference in the visible area when they are displayed with plot. The gains corresponding to roots are not available directly; they can be computed as real(polyval(den,r)/polyval(num,r)) for root r.

As with other plots, the id is used for interactive manipulation. Manipulating a root locus means changing the gain of the controller, which keeps the locus at the same place but makes the closed-loop poles move on it. Other changes are done by dragging the open-loop poles and zeros, which are plotted by plotroots. To change the gain, you must also plot the current closed-loop poles with the plotroots function and use the same ID, so that the initial click identifies the nearest closed-loop pole and the mouse drag makes Sysquake use the root locus to calculate the change of gain, which can be retrieved in _q (see the example below).

Examples

Root locus of (s^2+3s+2)/(s^3+2s^2+3s+4) with open-loop poles and zeros added with plotroots:

num = [1, 3, 2];
den = [1, 2, 3, 4];
scale('equal', [-4,1,-2,2]);
sgrid;
rlocus(num, den);
plotroots(num, 'o');
plotroots(den, 'x');

The second example shows how rlocus can be used interactively in Sysquake.

figure "Root Locus"
  draw myPlotRLocus(num, den);
  mousedrag num = myDragRLocus(num, _q);

function
{@
function myPlotRLocus(num, den)
  scale('equal', [-3, 1, -2, 2]);
  rlocus(num, den, '', 1);
  plotroots(addpol(num, den), '^', 1);

function num = myDragRLocus(num, q)
  if isempty(q)
    cancel;
  else
    num = q * num;
  end
@}

Caveat

The Laguerre algorithm is used for fast evaluation (roots and plotroots are based on eig and have a better accuracy, but their evaluation for a single polynomial is typically 10 times slower). The price to pay is a suboptimal precision for multiple roots and/or high-order polynomials.

See also

plotroots, plotset, erlocus, sgrid, zgrid

sgrid

Relative damping and natural frequency grid for the poles of a continuous-time system.

Syntax

sgrid
sgrid(damping, freq)
sgrid(..., style)

Description

With no numeric argument, sgrid plots a grid of lines with constant relative damping and natural frequencies in the complex plane of s.

The whole grid is displayed only if the user selects it in the Grid menu, or after the command plotoption fullgrid. By default, only the imaginary axis (the stability limit for the poles of the Laplace transform) is displayed.

With one or two numeric arguments, sgrid plots only the lines for the specified values of damping and natural frequency. Let p and conj(p) be the complex conjugate roots of the polynomial s^2 + 2*w*d*s + w^2, where w is the natural frequency and d < 1 the damping. The locus of roots with a constant damping d is generated by abs(imag(p)) = sqrt(1-d^2)/d real(p) with real(p) < 0. The locus of roots with a constant natural frequency w is a circle of radius w.

The style argument has its usual meaning.

Example

Typical use for poles or zeros displayed in the s plane:

scale equal;
sgrid;
plotroots(pol);

See also

zgrid, plotroots, hgrid, ngrid, plotset, plotoption

sigma

Singular value plot for a continuous-time state-space model.

Syntax

sigma(Ac, Bc, Cc, Dc)
sigma(Ac, Bc, Cc, Dc, w)
sigma(Ac, Bc, Cc, Dc, opt)
sigma(Ac, Bc, Cc, Dc, w, opt)
sigma(..., style)
sigma(..., style, id)
(sv, w) = sigma(...)

Description

sigma(Ac,Bc,Cc,Dc) plots the singular values of the frequency response of the continuous-time state-space model (Ac,Bc,Cc,Dc) defined as

jw X(jw) = Ac X(jw) + Bc U(jw)
   Y(jw) = Cc X(jw) + Dc U(jw)

The range of frequencies is selected automatically or can be specified in an optional argument w, a vector of frequencies.

Further options can be provided in a structure opt created with responseset; field Range is utilized. The optional arguments style and id have their usual meaning.

sigma is the equivalent of bodemag for multiple-input systems. For single-input systems, it produces the same plot.

With output arguments, sigma gives the singular values and the frequency as column vectors. No display is produced.

See also

bodemag, bodephase, dsigma, responseset, plotset

step

Step response plot of a continuous-time linear system.

Syntax

step(numc, denc)
step(numc, denc, opt)
step(Ac, Bc, Cc, Dc)
step(Ac, Bc, Cc, Dc, opt)
step(..., style)
step(..., style, id)
(y, t) = step(...)

Description

step(numc,denc) plots the step response of the continuous-time transfer function numc/denc.

Further options can be provided in a structure opt created with responseset; fields Delay and Range are utilized. The optional arguments style and id have their usual meaning.

step(Ac,Bc,Cc,Dc) plots the step response of the continuous-time state-space model (Ac,Bc,Cc,Dc) defined as

dx/dt = Ac x + Bc u
y     = Cc x + Dc u

where u(t) is a unit step. The state-space model must have a scalar input, and may have a scalar or vector output.

With output arguments, step gives the output and the time as column vectors. No display is produced.

Example

Step response of the continuous-time system 1/(s^3+2s^2+3s+4):

step(1, 1:4, 'b');

See also

impulse, lsim, dstep, hstep, responseset, plotset

zgrid

Relative damping and natural frequency grid for the poles of a discrete-time system.

Syntax

zgrid
zgrid(damping, freq)
zgrid(..., style)

Description

With no numeric argument, zgrid plots a grid of lines with constant relative damping and natural frequencies in the complex plane of z.

The whole grid is displayed only if the user selects it in the Grid menu, or after the command plotoption fullgrid. By default, only the unit circle (the stability limit for the poles of the z transform) is displayed.

With one or two numeric arguments, zgrid plots only the lines for the specified values of damping and natural frequency. The damping d and the natural frequency w are defined the same way as for the sgrid function, with the mapping z = exp(s) (a normalized sampling frequency is assumed). With a damping d, the line z and its complex conjugate conj(z) are generated by z = exp((-1+j*sqrt(1-d^2)/d)*u), with 0 <= u <= umax and umax chosen such that the line has a positive imaginary part. With a natural frequency w (typically in the range 0 for a null frequency to pi for the Nyquist frequency), the line is generated by exp(w*exp(j*v)), where v is such that the curve is inside the unit circle.

The style argument has its usual meaning.

Example

Typical use for poles or zeros displayed in the z plane:

scale('equal',[-1.2,1.2,-1.2,1.2]);
zgrid;
plotroots(pol);

See also

sgrid, plotroots, hgrid, ngrid, plotset, plotoption