Sysquake Pro – 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

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))``s = jw`

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

The same plot, between `w=0``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

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

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

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

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

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)``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)``w``pi``scale('lindb')` or
`scale('linlog/lindb')` before `dnichols`.

The range of frequencies is selected automatically between 0 and
`pi``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)``w``pi``pi``2 pi`

The range of frequencies is selected automatically between 0 and
`pi``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)``Ts` is the sampling period.

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

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

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)``R^3`

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

#### See also

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

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

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

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

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

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:

Name | Default | Meaning |
---|---|---|

Delay | 0 | time delay |

NegFreq | false | negative frequencies |

Offset | 0 | offset |

Range | [] | time or frequency range |

tOnly | false | samples 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)`

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 `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
`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``conj(p)``s^2 + 2*w*d*s + w^2``w``d < 1``d``abs(imag(p)) = sqrt(1-d^2)/d real(p)``real(p) < 0``w``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)

`w`, a vector of frequencies.

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

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``w``sgrid` function, with the mapping
`z = exp(s)``d``z``conj(z)``z = exp((-1+j*sqrt(1-d^2)/d)*u)``0 <= u <= umax``umax``w``pi``exp(w*exp(j*v))``v`

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