Graphic Functions

The main goal of SysQuake is the interactive manipulation of graphics. Hence, graphic functions play an important role in SQ files. There are low-level commands for basic shapes as well as high-level commands for more specialized plots:

Low-level commands
Low-level commands add simple shapes such as lines, marks, polygons, circles and images. With them, you can display virtually everything you want. Arguments of these commands are such that it is very easy to work globally with matrices without computing each value sequentially in a loop.
High-level commands
High-level commands perform some computation of their own to process their arguments before displaying the result. This has two benefits: first, the code is simpler, more compact, and faster to develop. Second, command execution is faster, because the additional processing is not interpreted by LME, but implemented as native machine code. The information related to interactive manipulation is often easier to use, too. Most of these functions are related to automatic control and signal processing.

Commands which display data in a figure can be used only in the draw functions or from the command line interface. Conversely, commands which change the number of subplots or the subplots themselves cannot be used in the draw functions.

Here is the list of these two groups of commands:

Reserved for draw functions

bar
bodemag
bodephase
button
circle
contour
dbodemag
dbodephase
dimpulse
dinitial
dnichols
dnyquist
dsigma
dstep
erlocus
freqrange
barh
hgrid
hstep
image
impulse
initial
label
line
ngrid
nyquist
nyquist
plot
plotoption
plotroots
rlocus
scale
settabs
sgrid
sigma
step
text
title
zgrid

Cannot be used in draw functions

clf
redraw
subplot
subplots
subplotpos
subplotprops
subplotparam
 
 

Commands from both groups can be typed in the command line interface. For example, to plot the step response of the continuous-time system whose Laplace transform is 1/(s^3 + 2 s^2 + 3 s + 4), type

> clf
> step(1, [1,2,3,4])

The first command, only valid from the command line interface (or indirectly in a function called from the command line interface), clears the figure window (necessary if there was already something displayed); the second command integrates the system over a suitable range with a unit entry and null initial conditions.

The commands which produce the display of graphical data accept two optional parameters. The first one is the style. It defines the color, the line dash pattern (for continuous traces) or the shape (for discrete points) of the data. The possible values are given below. Note that the color is ignored on some output devices (such as black and white printers) and the dash pattern is used only on high-resolution devices (such as printers or EPS output). The color code is lower-case for thin lines and upper-case for thicker lines on devices which support it.

ColorCharacter
blackk
blueb
greeng
cyanc
redr
magentam
yellowy
whitew
Dash PatternCharacter
solid_ (underscore)
dashed-
dotted:
dash-dot!
ShapeCharacter
point.
circleo
crossx
star*
triangle up^
triangle downv
square[
diamond<
stairss
MiscellaneousCharacter
fillf

The style 's' (stairs) is supported only by the plot and dstep functions. It is equivalent to a zero-order hold, i.e. two points are linked with an horizontal segment followed by a vertical segment. The style 'f' (fill) fills the shape instead of drawing its contour. Exactly how the shape is filled depends on the underlying graphic architecture; if the contour intersects itself, there may be holes.

Many graphical commands accept data for more than one line. If the style string contains several sequences of styles, the first line borrows its style from the first sequence, the second line, from the second sequence, and so on. If there are not enough styles, they are recycled. A sequence is one or two characters, one of them for the color and the other one for the dash pattern or the symbol shape, in any order. Sequences of two characters are used if possible. For example, with the command

plot([0,1;0,1;0,1],[1,1;2,2;3,3],'k-r!')

the first line (from (0,1) to (1,1)) is black and dashed, the second line (from (0,2) to (1,2)) is red and dash-dot, and the third line (from (0,3) to (1,3)) is black and dashed again. With the style string 'rbk', the first line is red, the second line is blue, and the third line is black. With '-br', the first and third lines are blue and dashed, and the second line is red and solid.

The second optional argument is the trace ID. It has two purposes. First, it specifies that the trace can be manipulated by the user. When the user clicks in a figure, SysQuake scans all the curves which have a non-negative trace ID (the default value of all commands is -1, making the graphical object impossible to grasp) and sets _z0, _x0, _y0, _id, and _ix such that they correspond to the nearest element if it is close enough to the mouse coordinates. Second, the argument _id is set to the ID value so that the mousedown, mousedrag, and mouseup handlers can identify the different objects the user can manipulate.

Scale

Before any figure can be drawn on the screen, the scale (or equivalently the portion of the plane which is represented on the screen) must be determined. The scale depends on the kind of graphics, and consequently is specified in the draw handler, but can be changed by the user with the zoom and shift commands. What the user specifies has always the priority. If he has not specified a new scale, the scale command found in the draw handler is used:

scale([xMin,xMax,yMin,yMax])

If scale is not used, or if some of the limits are NaN (not an number), a default scale is given by the plot commands themselves. If used, the scale command should always be executed before any plot command, because several of them use the scale to calculate traces only over the visible range or to adjust the density of the calculated points of the traces.

If you need to know the limits of the displayed area in your draw handler, use scale to get them right after setting the default scale, so that you take into account the zoom and shift specified by the user:

scale(optString, [defXMin, defXMax, defYMin, defYMax]);
sc = scale;
xMin = sc(1);
xMax = sc(2);
yMin = sc(3);
yMax = sc(4);

Functions

bar

Vertical bar plot.

Syntax

bar(y)
bar(x, y)
bar(x, y, w)
bar(..., kind)
bar(..., kind, style)
bar(......, id)

Description

bar(x,y) plots the columns of y as vertical bars centered around the corresponding value in x. If x is not specified, its default value is 1:size(y,2).

bar(x,y,w), where w is scalar, specifies the relative width of each bar with respect to the horizontal distance between the bars; with values smaller than 1, bars are separated with a gap, while with values larger than 1, bars overlap. If w is a vector of two components [w1,w2], w1 corresponds to the relative width of each bar in a group (columns of y), and w2 to the relative width of each group. Default values, used if w is missing or is the empty matrix [], is 0.8 for both w1 and w2.

bar(...,kind), where kind is a string, specifies the kind of bar plot. The following values are recognized:

'grouped'Columns of y are grouped horizontally (default)
'stacked'Columns of y are stacked vertically
'interval'Same as grouped with bars defined with min and max val.

With 'interval', intervals are defined by two consecutive rows of y, which must have an even number of rows.

The optional arguments style and id have their usual meaning.

Examples

bar([2,4,3,6;3,5,4,1]);                       % simple bar plot
bar(1:4, magic(4), [], 'stacked');            % stacked bar plot
bar(1:4, [2,4,3,1;5,6,4,6], [], 'interval');  % interval plot

See also

barh, plot

barh

Horizontal bar plot.

Syntax

barh(x)
barh(y, x)
barh(y, x, w)
barh(..., kind)
barh(..., kind, style)
barh(..., id)

Description

barh plots a bar plot with horizontal bars. Please see bar for a description of its behavior and arguments.

Examples

barh([2,4,3,6;3,5,4,1]);                       % simple bar plot
barh(1:4, magic(4), [], 'stacked');            % stacked bar plot
barh(1:4, [2,4,3,1;5,6,4,6], [], 'interval');  % interval plot

See also

bar, plot

bodemag

Magnitude Bode diagram for a continuous-time transfer function.

Syntax

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

Description

bodemag(numc,denc) plots the magnitude of the frequency response of the continuous-time transfer function numc/denc. 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 + 2 s^2 + 3 s + 4)), where s = jw
bodemag(1, [1, 2, 3, 4], 'g');

% idem, between w=0 and w=10
scale([0,10]);
bodemag(1, [1, 2, 3, 4], 'g');

See also

bodephase, dbodemag, sigma

bodephase

Phase Bode diagram for a continuous-time transfer function.

Syntax

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

Description

bodephase(numc,denc) plots the phase of the frequency response of the continuous-time transfer function numc/denc. The optional arguments style and id have their usual meaning.

bodemag(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 + 2 s^2 + 3 s + 4)), where s = jw
bodephase(1, [1, 2, 3, 4], 'g');

See also

bodemag, dbodephase

button

Button control.

Syntax

button(label,b,'checkmark',style,id)
button(label,n,'radiobutton',style,id)

Description

button(label,b,'checkmark',style,id) displays one or several checkmark controls. Checkmark controls are graphic elements whose state can be set on or off individually. The label argument contains several fields separated by tabulator characters (\t); the first field is displayed aligned to the left, and each subsequent field is displayed to the right of a checkmark button. The number of tabulators fixes the number of checkmarks. Each bit of the b argument corresponds to the state of one checkmark; the least significant bit corresponds to the leftmost checkmark. The style argument, if present and not empty, is a string which specifies the color of the controls, and the id argument is the object id (cf. their definition above).

Several rows of controls can be displayed by a single button command. Labels of each row are separated by newline characters (\n), and the state b becomes a column vector.

button(label,b,'checkmark',style,id) displays one or several radio buttons. Radio buttons are similar to checkmarks, but are mutually exclusive. Their state is given by the n argument, which is the number of the active radio button on that row. If n is smaller than 1 or larger than the number of radio buttons, none is displayed as active.

You can display one or several rows of buttons in a single subplot. You can mix them with text and sliders (commands text and slider), but not with other graphics.

Usually, figure which contain buttons are associated with a mousedrag handler. The new state is provided in _x1 and corresponds to the value of the second argument of button.

Examples

A single checkmark button:

settabs('Style:XX\t');
button('Style:\tbold', isBold, 'checkmark', '', 1);

Two rows of checkmark buttons:

settabs('Style:XX\t\bboldXXX\t');
button(['Style:\tbold\titalic\n',...
        'Border:\ttop\tbottom\tleft\tright'], ...
          [isBold+2*isItalic; borders], 'checkmark', '', 1);

Mutually-exclusive radio buttons on three lines:

settabs('Radio:XX\t\b1XX\t');
button('Radio:\t1\t2\t3\n\t4\t5\t6\n\t7\t8\t9', ...
          [x;x-3;x-6], 'radiobutton', '', 1);

See also

settabs, slider, text

circle

Add circles to the figure.

Syntax

circle(x,y,r)
circle(x,y,r,style)
circle(x,y,r,style,id)

Description

circle(x,y,r) draws a circle of radius r centered at (x,y). The arguments can be vectors to display several circles. The optional fourth and fifth arguments are the style and object id (cf. their definition above).

In mouse handlers, _x0 and _y0 correspond to the projection of the mouse click onto the circle; _nb is the index of the circle in x, y and r, and _ix is empty.

Examples

circle(1, 2, 5, 'r', 1);
circle(zeros(10,1), zeros(10, 1), 1:10);

See also

plot, line

clf

Clear the figure window.

Syntax

clf

Description

clf erases all the subplots, sets only one plot, and resets its scale. It can only be used from the command-line interface (directly or in a function), not in SQ files.

If graphic commands are issued at the command line interface without clf, but after an SQ file has been loaded, their behavior is undefined (currently, their output is directed to the last subplot, but it is erased immediately if an idle handler is defined).

contour

Level curves.

Syntax

contour(z)
contour(z, [xmin, xmax, ymin, ymax])
contour(z, [xmin, xmax, ymin, ymax], levels)
contour(z, [xmin, xmax, ymin, ymax], levels, style)

Description

contour(z) plots seven contour lines corresponding to the surface whose samples at equidistant points 1:size(z,2) in the x direction and 1:size(z,1) on the y direction are given by z. Contour lines are at equidistant levels. With a second non-empty argument [xmin, xmax, ymin, ymax], the samples are at equidistant points between xmin and xmax in the x direction and between ymin and ymax in the y direction. The optional third argument levels, if non-empty, gives the number of contour lines if it is a scalar or the levels themselves if it is a vector. The optional fourth argument is the style of each line, from the minimum to the maximum level (styles are recycled if necessary).

Example

u = -2 + (0:40) / 10;
x = repmat(u, 41, 1);
y = x';
z = exp(-((x-0.2).^2+(y+0.3).^2)) ...
      - exp(-((x+0.5).^2+(y-0.1).^2)) + 0.1 * x;
scale('equal');
contour(z, [-1,1,-1,1]);

See also

image

dbodemag

Magnitude Bode diagram for a discrete-time transfer function.

Syntax

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

Description

dbodemag(numd,dend,Ts) plots the magnitude of the frequency response of the discrete-time transfer function numd/dend with sample time Ts. 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

dbodephase

Phase Bode diagram for a discrete-time transfer function.

Syntax

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

Description

dbodemag(numd,dend,Ts) plots the phase of the frequency response of the discrete-time transfer function numd/dend with sample time Ts. 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

dimpulse

Impulse response plot for a discrete-time transfer function.

Syntax

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

Description

dimpulse(numd,dend,Ts) plots the impulse response of the discrete-time transfer function numd/dend with sample time Ts. 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, dinitial

dinitial

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

Syntax

dinitial(Ad, Bd, Cd, Dd, Ts, x0)
dinitial(Ad, Bd, Cd, Dd, Ts, x0, style)
dinitial(Ad, Bd, Cd, Dd, Ts, x0, 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. Sample time is Ts. The state-space model may have a scalar or vector output. 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

dnichols

Nichols diagram for a discrete-time transfer function.

Syntax

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

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.

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

Example

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

See also

nichols, ngrid, dnyquist

dnyquist

Nyquist diagram for a discrete-time transfer function.

Syntax

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

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

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

Example

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

See also

nyquist, hgrid, dnichols

drawnow

Immediate drawing of the plots.

Syntax

drawnow

Description

drawnow makes SysQuake immediately draws the result of graphical commands which were executed before. It should be used only from the command-line interface, or in functions called from the command line interface. Graphics generated for interactive subplots are buffered to provide optimal performances. drawnow may be useful for basic animations or for benchmarking SysQuake.

Example

tic;for i=1:100;clf;step(1,1:4);drawnow;end;toc
  2.2212

See also

clf, hgrid, dnichols

dsigma

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

Syntax

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

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 sample time. 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.

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

See also

dbodemag, dbodephase, sigma

dstep

Step response plot for a discrete-time transfer function.

Syntax

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

Description

dstep(numd,dend,Ts) plots the step response of the discrete-time transfer function numd/dend with sample time Ts. 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.

Example

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

See also

dimpulse, step, hstep

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

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. 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 0.2, 0.5, 0.8, 1, 1/0.8, 2, and 5; and to a closed-loop phase of plus or minus 0, 10, 20, 30, 45, 60, and 75 degrees.

Example

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

See also

ngrid, nyquist

hstep

Step response plot for 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 sample time 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 be used to 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

% unstable system continuous-time transfer function
num = 1;
den = [1, -1];
% sampling at Ts = 1 (maybe 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

image

Raster RGB or grayscale image.

Syntax

image(gray
image(red, green, blue)
image(gray, [xmin, xmax, ymin, ymax])
image(red, green, blue, [xmin, xmax, ymin, ymax])
image(..., style)
image(..., style, id)

Description

image displays a raster image (an image defined by a rectangular array of patches of colors called pixels). The raster image can be either grayscale or color. A grayscale image is defined by a matrix of pixel values in the range 0 (black) to 1 (white). A color image is defined by three matrices of equal size, corresponding to the red, green, and blue components. Each component is defined between 0 (black) to 1 (maximum intensity).

The position is defined by the the minimum and maximum coordinates along the horizontal and vertical axis. The raster image is scaled to fit. The first line of the matrix or matrices is displayed at the top. If style is 'e', the raster image is scaled down such that each pixel has the same size; otherwise, the specified position is filled with the raster image. You should use 'e' when you want a better quality, but do not add other elements in the figure (such as marks or lines) and do not have interaction with the mouse.

If style is '1', the pixel on the screen are interpolated using the bilinear method.

Examples

image(rand(10), rand(10), rand(10));

x = -pi:0.1:pi;
m = repmat(x,length(x),1).^2;
image(cos(m + m').^2, [-1,1,-1,1]);

See also

contour

impulse

Impulse response plot for a continuous-time transfer function.

Syntax

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

Description

impulse(numc,denc) plots the impulse response of the continuous-time transfer function numc/denc. 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, initial

initial

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

Syntax

initial(Ac, Bc, Cc, Dc, x0)
initial(Ac, Bc, Cc, Dc, x0, style)
initial(Ac, Bc, Cc, Dc, x0, 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. 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

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

See also

dinitial, impulse

label

Plot labels.

Syntax

label(label_x)
label(label_x, label_y)

Description

label(label_x, label_y) displays labels for the X and Y axis. Its arguments are strings. The label for the Y axis may be omitted.

Example

step(1,[1,2,3,4]);
label('t [s]', 'y [m]');

See also

text, title

line

Plot lines.

Syntax

line(A, b)
line(A, b, style)
line(A, b, style, id)

Description

line displays one or several straight line(s). Each line is defined by an equation of the form a1 x + a2 y = b. The first argument of line is a matrix which contains the coefficients a1 in the first column and a2 in the second column; each row corresponds to a different line. The second argument is a column vector which contains the coefficients b. If one of these arguments has one row and the other has several, the same row is reused multiple times.

In figures with a logarithmic scale, only horizontal and vertical lines are allowed.

The optional third and fourth arguments are the same as for all graphical commands.

In mouse handlers, _x0 and _y0 correspond to the projection of the mouse position onto the line; _nb is the index of the line in A and b, and _ix is empty.

Examples

Vertical line at x=5:

line([1,0],5)

Draggable horizontal lines at y=2 and y=3:

line([0,1],[2;3],'b',1)

See also

plot, circle

ngrid

Nichols chart grid.

Syntax

ngrid
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 optional argument specifies the style.

The whole grid is displayed only if the user selects it in the Grid menu. 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.

Example

ngrid;
nichols(7, 1:3);

See also

hgrid, nichols

nichols

Nichols diagram for a continuous-time transfer function.

Syntax

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

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.

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

Example

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

See also

dnichols, ngrid, nyquist

nyquist

Nyquist diagram for a continuous-time transfer function.

Syntax

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

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

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

Example

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

See also

dnyquist, hgrid, nichols

plot

Generic plot.

Syntax

plot(y)
plot(x, y)
plot(..., style)
plot(..., style, id)

Description

The command plot displays graphical data in the current figure. The data are given as two vectors of coordinates x and y. If x is omitted, its default value is 1:size(y,2). Depending on the style, the points are displayed as individual marks or are linked with lines. The stairs style ('s') can be used to link two successive points with an horizontal line followed by a vertical line. If x and y are matrices, each row is considered as a separate line or set of marks; if only one of them is a matrix, the other one, a vector, is reused for each line.

The optional fourth argument is an identification number which is used for interactive manipulation. It should be equal or larger than 1. If present and a mousedown, mousedrag and/or mouseup handler exists, the position of the mouse where the click occurs is mapped to the closest graphical element which has been displayed with an id; for the command plot, the closest point is considered (lines linking the points are ignored). If such a point is found at a small distance, the built-in variables _x0, _y0, and _z0 are set to the position of the point before it is moved; the variable _id is set to the id as defined by the command plot; the variable _nb is set to the number of the row, and the variable _ix is set to the index of the column of the matrix x and y.

Examples

Sine between 0 and 2 pi:

plot(2 * pi * (0:100) * 0.01, sin(2 * pi * (0:100) * 0.01));

Ten random crosses:

plot(rand(1,10), rand(1,10), 'x');

A complete SQ file for displaying a red triangle whose corners can be moved interactively:

variables x, y     // x and y are 1-by-3 vectors
init (x,y) = init  // init handler
figure "Triangle"
  draw drawTri(x, y)
  mousedrag (x, y) = dragTri(x, y, _ix, _x1, _y1)
functions
{@
function (x,y) = init
  x = [-1,1,0];
  y = [-1,-1,2];
  subplots('Triangle');
function drawTri(x,y)
  scale('equal', [-3, 3; -3, 3]);
  plot(x, y, 'rf', 1);  % filled red triangle with id 1
function (x, y) = dragTri(x, y, ix, x1, y1)
  if isempty(ix)
    cancel;             % not a click over a point
  end
  x(ix) = x1;
  y(ix) = y1;
@}

See also

line, circle

plotoption

Set plot options.

Syntax

plotoption(str)

Description

plotoption sets the initial value of one of the plot options the user can change. Its single argument, a character string, can take one of the following values.

'frame'
Rectangular frame with tick marks and a white background around the plot.
'noframe'
No frame, no tickmarks, no white background.
'label'
Subplot name above the frame.
'nolabel'
No subplot name.
'xgrid'
Grid of vertical lines for the x axis.
'noxgrid'
No grid for the x axis.
'ygrid'
Grid of horizontal lines for the y axis.
'noygrid'
No grid for the y axis.
'grid'
Normal details for grids displayed by sgrid, zgrid, etc.
'nogrid'
Removal of grids displayed by sgrid, zgrid, etc.
'fullgrid'
More details for grids displayed by sgrid, zgrid, etc.

Example

Display of a photographic image without frame:

plotoption noframe;
image(photo);

See also

scale

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.

Example

scale('equal');
plotroots(den,'x');
plotroots(num,'o');

See also

rlocus, erlocus, sgrid, zgrid, movezero

redraw

Force the display of new graphics.

Syntax

redraw

Description

redraw forces SysQuake to immediately update the display of all subplots. It can only be used from the command-line interface (directly or in a function). It is useful to update the graphics of an SQ script after the variables have been changed manually from the command-line interface, or for SQ files and SQ scripts whose graphics may change at each evaluation because of random data or data imported from the outside.

rlocus

Root locus.

Syntax

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

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 causal system with real coefficients, i.e. length(den)>=length(num). 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 by 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.

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

Example

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
@}

See also

plotroots, erlocus, sgrid, zgrid

scale

Set the scale.

Syntax

scale([xmin,xmax,ymin,ymax])
scale([xmin,xmax])
scale(features)
scale(features, usersettablefeatures)
scale(features, [xmin,xmax,ymin,ymax])
scale(features, usersettablefeatures, [xmin,xmax,ymin,ymax])
sc = scale

Description

Without output argument, the scale command, which should be placed in the draw handlers before any other graphic command, sets the scale and scale options. The last parameter contains the limits of the plot, either for both x and y axis or only for the x axis. The limits are used only if the user has not changed them by zooming.

The first parameter(s) specify some properties of the scale, and which one can be changed by the user. There are two ways to specify them: with a string or with one or two integer numbers. The recommended way is with a string. The list below enumerates the possible values.

'equal'
Same linear scale for x and y axis. Typically used for representation of the complex plane, such as the roots of a polynomial or a Nyquist diagram.
'lock'
See below.
'linlin'
Linear scale for both axis.
'linlog'
Linear scale for the x axis, and logarithmic scale for the y axis.
'loglin'
Logarithmic scale for the x axis, and linear scale for the y axis.
'loglog'
Logarithmic scale for both axis.
'lindb'
Linear scale for the x axis, and dB scale for the y axis.
'logdb'
Logarithmic scale for the x axis, and dB scale for the y axis.
'lindb/logdb'
Linear scale for the x axis, and dB scale for the y axis. The user can choose a logarithmic scale for the x axis, and a logarithmic or linear scale for the y axis.

This last setting shows how to enable the options the user can choose in SysQuake. The setting and the enabled options are separated by a dash; if a simple setting is specified, the enabled options are assumed to be the same. Enabling dB always permits the user to choose a logarithmic or linear scale, and enabling a logarithmic scale always permits to choose a linear scale. The 'equal' option cannot be combined with anything else.

When the properties are specified with one or two integer numbers, each bit corresponds to a property. Only the properties in bold in the table below can be set by the user, whatever the setting is.

BitMeaning
0log x
2tick on x axis
3grid for x axis
4labels on x axis
6log y
7dB y
8tick on y axis
9grid for y axis
10labels on y axis
12same scale on both axis
13minimum grid
14maximum grid

scale lock locks the scale as if the user had done it by hand. It fixes only the initial value; the user may change it back afterwards.

The scale is usually limited to a range of 1e-6 for linear scales and a ratio of 1e-6 for logarithmic scales. This avoids numerical problems, such as when a logarithmic scale is chosen and the data contain the value 0. In some rare cases, a large scale may be required. The 'lock' option is used to push the limits from 1e-6 to 1e-24 for both linear and logarithmic scales. A second argument must be provided:

scale('lock', [xmin,xmax,ymin,ymax]);

The command must be used in a draw handler (or from the command line interface). To add other options, use a separate scale command:

scale('logdb');
scale('lock', [1e-5, 1e8, 1e-9, 1e9]);

The scale is locked, and the user may not unlock it.

With an output argument, scale returns the current scale as a vector [xmin,xmax,ymin,ymax]. If the scale is not fixed, the vector is empty. If only the horizontal scale is set, the vector is [xmin,xmax]. During a mouse drag, both the x and y are fixed. The values returned by scale reflect the zoom chosen by the user. They can be used to limit the computation of data displayed by plot to the visible area.

Examples

Here are some suggestions for the most usual graphics:

Time response(default linlin is fine)
Bode magscale('logdb')
Bode phasescale('loglin')
D bode magscale('lindb/logdb',[0,pi/Ts])
D bode phasescale('linlin/loglin',[0,pi/Ts])
Polesscale('equal')
D polesscale('equal',[-1,1,-1,1])
Nyquistscale('equal',[-1.5,1.5,-1.5,1.5])
Nicholsscale('lindb')

Use of scale to display a sine in the visible x range:

scale([0,10]);     % default x range between 0 and 10
sc = scale;        % actual scale, as changed by the user (1x2 or 1x4)
xmin = sc(1);
xmax = sc(2);
x = xmin + (xmax - xmin) * (0:0.01:1);	% 101 values between xmin and xmax
y = sin(x);
plot(x, y);

See also

plotoption, subplotprops

settabs

Set the vertical alignment of text, buttons and sliders.

Syntax

settabs(str)
settabs(vec)

Description

settabs sets tabulator marks which are used by the commands text, slider, and button which follow. Its argument is either a string of runs of characters separated by the tabulator character (\t), or a vector of one or more integers representing the number of 'x' characters in runs. Each run is measured and correspond to the width of a column of text, sliders, and buttons. The argument of settabs is not displayed. It should typically match the widest string, plus some margin, to avoid overlapping columns. Right after a tabulator character, the backspace character (\b) represents the width of a checkmark or radio button.

If more columns are required by text, slider, or button than what is defined by settabs, the last column width is replicated.

Examples

Alignment of text:

settabs('Results:xx\t999.99 \t');
text(sprintf('Results:\t%.2f\t%.2f', 2.435, 5.243));
text(sprintf('Log:\t%.2f\t%.2f', log(2.435), log(5.243)));

Alignment of radio buttons:

settabs('Choice:XXX\t\boneXX\t');
button('Choice:\tone\ttwo\tthree', 2, 'radiobutton', '', 1);

Two ways to set one large column followed by multiple small columns:

settabs('xxxxxxxxxx\txxxxx\t');
settabs([10,5]);

See also

text, button, slider

sgrid

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

Syntax

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

Description

With no or one argument, sgrid plots a grid of lines with constant relative damping and natural frequencies in the complex plane of s. The style argument has its usual meaning.

With two or three arguments, sgrid plots only the lines for the specified dampings and natural frequencies. 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 whole grid is displayed only if the user selects it in the Grid menu. By default, only the imaginary axis (the stability limit) is displayed.

Example

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

scale('equal');
sgrid;
plotroots(pol);

See also

zgrid, plotroots, hgrid, ngrid

sigma

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

Syntax

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

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

slider

Slider control for interactive manipulation of a scalar.

Syntax

slider(label, x, [min,max])
slider(label, x, [min,max], scale)
slider(label, x, [min,max], scale, style)
slider(label, x, [min,max], scale, style, id)

Description

The two main ways to manipulate variables in SysQuake consist in moving an element of a figure or in entering new values in a dialog box. The command slider provides an additional mean. It displays a set of sliders in a subplot, i.e. user-interface objects with a cursor you can drag to change continuously a scalar value. Like for any other user manipulation in a subplot, the other subplots are updated continuously if a mousedrag handler is provided.

You can display one or several sliders in a single subplot. You can mix them with text and buttons (commands text and button), but not with other graphics.

The label argument is a string which contains the labels for each slider, separated by a linefeed character (\n). Its width can be set with the settabs command. Argument x is the current value of the slider. The rows of the third argument, a matrix of two columns, contain the minimum and maximum values corresponding to each slider when they are dragged to the left or right, respectively. Argument scale is a string made of characters '-' for a linear scale, and 'l' or 'L' for a logarithmic scale; each character corresponds to a slider. If the string is empty, all sliders are linear; if the string contains one character, it applies to all sliders. The style argument has its usual meaning; but only the color is used.

Sliders are either read-only if the id argument is missing, or interactive if it is provided. In the mousedown, mousedrag, and mouseup handlers, each slider is identified by _nb. The _x, _x0, and _x1 parameters can be used to obtain the value corresponding to the position of the click in the slider, the initial value, and the current value. Note that contrary to other plot commands where _x is always defined, _x is non-empty only if the click is made inside a slider; this is so because the scale can be different for each slider.

During a mouse drag, the range of the manipulated slider is locked by SysQuake, even if you change it in the draw handler. Thus, you can specify a range relative to the current value:

slider('x', x, [x-5, x+5], '', '', 1)

Example

Two sliders are displayed. The first one, for variable weight, is linear and has a fixed range between 0 and 1; the second slider, for variable alpha, has a logarithmic scale and a dynamic range between 20 % and 500 %.

variable weight, alpha
figure "Sliders"
  draw drawSliders(weight, alpha)
  mousedrag (weight, alpha) = dragSliders(weight, alpha, _nb, _x1)
functions
{@
  function drawSliders(w1, w2)
    slider('Weight (0-1):\nAlpha:', ...
           [weight; alpha], [0,1; alpha*[0.2,5]], ...
           '-L', 'k_r_', 1);
  function (w1, w2) = dragSliders(weight, alpha, nb, x1)
    if isempty(nb)
      cancel;
    end
    switch nb
      case 1
        weight = x1;
      case 2
        alpha = x1;
    end
@}

See also

settabs, button, text

step

Step response plot for a continuous-time transfer function.

Syntax

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

Description

step(numc,denc) plots the step response of the continuous-time transfer function numc/denc. 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(1, 1:4, 'b');

See also

impulse, dstep, hstep

subplot

Manage subplots.

Syntax

subplot(m, n, i)
subplot(mni)
subplot mni

Description

The subplot function specifies the layout of subplots and where the graphical output produced by the commands which follow will be displayed. It can be used from the command-line interface (directly or indirectly in functions) or in SQ scripts. SQ files rely on a different mechanism, where each subplot is defined with a different draw handler and may be displayed on demand.

subplot(m,n,i), subplot(mni) with a three-digits number, or subplot mni all set an m-by-n grid layout and select the i:th subplot, with i between 1 for the top-left subplot and m*n for the bottom-right subplot. subplot should be executed before each subplot with the same values of m and n.

Example

Four subplots in a 2-by-2 layout:

subplot 221
title('Top-left');
step(1,[1,2,3,4]);
subplot 222
title('Top-right');
plot(rand(10));
subplot 223
title('Bottom-left');
scale equal
nyquist(1,1:4);
subplot 224
title('Last one');
contour(randn(10));

See also

subplots, title

subplotparam

Get or restore the parameter of subplots.

Syntax

subplotparam({p1, p2, ...})
p = subplotparam

Description

The subplotparam function handles the parameter of each subplot. The subplot parameter is the value of _param, which is specific to each subplot and can contain any kind of data.

subplotpos({p1,p2,...}) sets the parameter of each subplot. Each element corresponds to a subplot.

Without input argument, subplotparam returns the list of parameters of all subplots.

subplotparam complements subplots, subplotprops, and subplotpos by getting or restoring the subplot positions set by the user. It is typically used in the input and output handlers. It may also be used in the init handler, in a menu handler, or in the command line interface. For restoring the settings, it must be placed after subplots.

See also

subplots, subplotprops, subplotpos, scale

subplots

Get or restore the number and kind of subplots.

Syntax

s = subplots
subplots(s)

Description

The subplots can be seen as a matrix of figures. Each figure is identified by the name given after the figure keyword in the SQ file; an empty name correspond to no subplot. The subplots function uses a single string to identify all the subplots. The names of subplots in a row are separated by the tabulator character '\t'; rows are separated by the linefeed character '\n'. These characters play the same role as respectively the comma and the semicolon in a numerical matrix. However, rows do not have to have the same length; the row with the more subplots determine the size of the subplot array.

The subplots command can be used either with no input and one output argument to retrieve the subplots currently displayed, or with one input and no output to set the number of subplots and their content. It should not be used in the draw, mousedown, mousedrag, or mouseup handlers. Its intended use is for the init, input and output handlers, but it can also be used in a menu handler or in the command line interface.

Example

subplots('Step\tNyquist\nPoles\tBode')

See also

subplotprops, subplotpos, subplotparam

subplotpos

Get or restore the position of subplots.

Syntax

subplotpos([left1,right1,top1,bottom1;...])
p = subplotpos

Description

The subplotpos function handles the position of subplots in Free Position mode, which can be enabled in the View menu.

subplotpos(M) sets the position of each subplot in the Figure window. Unit is typically 4 pixels, equal to the grid used to snap figures when you move or resize them with the mouse; the origin is at the top left corner of the window. subplotpos(M) enables Free Position mode. Each line corresponds to a subplot.

Without input argument, subplotpos returns the current position of all subplots if Free Position mode is enabled, or the empty matrix [] otherwise.

subplotpos complements subplots and subplotprops by getting or restoring the subplot positions set by the user. It is typically used in the input and output handlers. It may also be used in the init handler (even if using default settings is probably less confusing for the user), in a menu handler, or in the command line interface. For restoring the settings, it must be placed after subplots.

Example

x = subplotpos
  x =
    0 30.3125 0 20.625
    30.3125 60.625 0 20.625
    0 30.3125 20.625 41.25
    30.3125 60.625 20.625 41.25
subplotpos([0,29,0,20; 31,60,0,20;0,60,21,25])

See also

subplots, subplotprops, subplotparam, scale

subplotprops

Get or restore the properties of subplots.

Syntax

m = subplotprops
subplotprops([flags1,xmin1,xmax1,ymin1,ymax1;...])

Description

subplotprops complements subplots and subplotpos by getting or restoring the display options set by the user. These options include the kind of scale (linear, logarithmic or dB, equal for both axis or not), and the scale itself, set with the Zoom, Zoom X, and Drag modes. Each line corresponds to a subplot.

subplotprops is typically used in the input and output handlers. It may also be used in the init handler (even if using default settings is probably less confusing for the user), in a menu handler, or in the command line interface. For restoring the settings, it must be placed after subplots.

Example

subplotprops
  1 0.1 10 1 100
  0 -1 1 -1 1
  0 -2 0 -1 1
  1 0 10 0 0
subplotprops([1,0.1,10,1,100;0,-1,1,-1,1;0,-2,0,-1,1;1,0,10,0,0])

See also

subplots, subplotpos, subplotparam, scale

text

Display formatted text in a figure.

Syntax

text(string)
text(x, y, string)
text(x, y, string, justification)

Description

With a single argument, text displays its string argument in the current subplot figure. It can be mixed with sliders and buttons, but no other graphics should be displayed. The string is split in rows and columns; columns are separated by the tab character ('\t'), and lines by the linefeed character ('\n'). The width of the columns can be specified with settabs.

With three arguments, text displays a string centered at the specified position. The optional fourth argument specifies how the string should be aligned with respect to the position (x,y). It is a string of one or two characters from the following set:

Char.Alignment
cCenter (may be omitted)
lLeft
rRight
tTop
bBottom

For instance, 'l' means that the string is displayed to the right of the given position and is centered vertically, and 'rt', that the string is to the bottom left of the given position.

Examples

Two lines and two columns are displayed, with labels in the first column and numerical values in the second column. Note the use of sprintf to format the numbers.

text(sprintf('One\t%.2f\nPi\t%.f', 1, pi))

A line is drawn between (-1,-1) and (1,1) with labels at both ends.

plot([-1,1], [-1,1]);
text(-1,-1, 'p1', 'tr');
text(1, 1, 'p2', 'bl');

See also

label, settabs, slider, button, sprintf

title

Subplot title.

Syntax

title(string)

Description

title(string) sets or changes the title of the current subplot.

See also

label, text, sprintf

zgrid

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

Syntax

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

Description

With no or one argument, zgrid plots a grid of lines with constant relative damping and natural frequencies in the complex plane of z. The style argument has its usual meaning.

With two or three arguments, zgrid plots only the lines for the specified dampings and natural frequencies. 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 sample 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 whole grid is displayed only if the user selects it in the Grid menu. By default, only the unit circle (the stability limit) is displayed.

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


Copyright 1998-2001, Calerga.

All rights reserved.