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:
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
Cannot be used in draw functions
|
|
|
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
> 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.
Color | Character |
---|---|
black | k |
blue | b |
green | g |
cyan | c |
red | r |
magenta | m |
yellow | y |
white | w |
Dash Pattern | Character |
---|---|
solid | _ (underscore) |
dashed | - |
dotted | : |
dash-dot | ! |
Shape | Character |
---|---|
point | . |
circle | o |
cross | x |
star | * |
triangle up | ^ |
triangle down | v |
square | [ |
diamond | < |
stairs | s |
Miscellaneous | Character |
---|---|
fill | f |
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.
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);
Vertical bar plot.
bar(y) bar(x, y) bar(x, y, w) bar(..., kind) bar(..., kind, style) bar(......, id)
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.
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
Horizontal bar plot.
barh(x) barh(y, x) barh(y, x, w) barh(..., kind) barh(..., kind, style) barh(..., id)
barh plots a bar plot with horizontal bars. Please see bar for a description of its behavior and arguments.
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
Magnitude Bode diagram for a continuous-time transfer function.
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)
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
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.
% 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');
Phase Bode diagram for a continuous-time transfer function.
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)
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
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.
% green plot for angle(1 / (s^3 + 2 s^2 + 3 s + 4)), where s = jw bodephase(1, [1, 2, 3, 4], 'g');
Button control.
button(label,b,'checkmark',style,id) button(label,n,'radiobutton',style,id)
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.
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);
Add circles to the figure.
circle(x,y,r) circle(x,y,r,style) circle(x,y,r,style,id)
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.
circle(1, 2, 5, 'r', 1); circle(zeros(10,1), zeros(10, 1), 1:10);
Clear the figure window.
clf
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).
Level curves.
contour(z) contour(z, [xmin, xmax, ymin, ymax]) contour(z, [xmin, xmax, ymin, ymax], levels) contour(z, [xmin, xmax, ymin, ymax], levels, style)
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).
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]);
Magnitude Bode diagram for a discrete-time transfer function.
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)
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
z X(z) = Ad X(z) + Bd U(z) Y(z) = Cd X(z) + Dd U(z)
where
With output arguments, dbodemag gives the magnitude and the frequency as column vectors. No display is produced.
dbodemag(1,poly([0.9,0.7+0.6j,0.7-0.6j]),1);
Phase Bode diagram for a discrete-time transfer function.
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)
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
z X(z) = Ad X(z) + Bd U(z) Y(z) = Cd X(z) + Dd U(z)
where
With output arguments, dbodephase gives the phase and the frequency as column vectors. No display is produced.
dbodephase(1,poly([0.9,0.7+0.6j,0.7-0.6j]),1);
Impulse response plot for a discrete-time transfer function.
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(...)
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
With output arguments, dimpulse gives the output and the time as column vectors. No display is produced.
dimpulse(1, poly([0.9,0.7+0.6j,0.7-0.6j]), 1, 'r');
Time response plot for a discrete-time state-space model with initial conditions.
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(...)
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
With output arguments, dinitial gives the output and the time as column vectors. No display is produced.
Nichols diagram for a discrete-time transfer function.
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)
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
With output arguments, dnichols gives the magnitude and phase of the frequency response and the frequency as column vectors. No display is produced.
scale('lindb'); ngrid; dnichols(3, poly([0.9,0.7+0.6j,0.7-0.6j]))
Nyquist diagram for a discrete-time transfer function.
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)
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
With output arguments, dnichols gives the real and imaginary parts of the frequency response and the frequency as column vectors. No display is produced.
scale('equal'); hgrid; dnyquist(3, poly([0.9,0.7+0.6j,0.7-0.6j]))
Immediate drawing of the plots.
drawnow
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.
tic;for i=1:100;clf;step(1,1:4);drawnow;end;toc 2.2212
Singular value plot for a discrete-time state-space model.
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)
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
With output arguments, dsigma gives the singular values and the frequency as column vectors. No display is produced.
Step response plot for a discrete-time transfer function.
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(...)
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
With output arguments, dstep gives the output and the time as column vectors. No display is produced.
dstep(1, poly([0.9,0.7+0.6j,0.7-0.6j]), 1, 'g');
Root locus of a polynomial with coefficients bounded by an ellipsoid.
erlocus(C0, P) erlocus(C0, P, sizes, colors)
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.
scale('equal', [-2,2,-2,2]); erlocus(poly([0.8, 0.7+0.6j, 0.7-0.6j]), eye(3)); zgrid;
Hall chart grid.
hgrid hgrid(style)
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.
scale('equal', [-1.5, 1.5, -1.5, 1.5]); hgrid; nyquist(20, poly([-1,-2+1j,-2-1j]))
Step response plot for a discrete-time transfer function followed by a continuous-time transfer function.
hstep(numd, dend, Ts, numc, denc) hstep(numd, dend, Ts, numc, denc, style) hstep(numd, dend, Ts, numc, denc, style, id)
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.
% 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');
Raster RGB or grayscale image.
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)
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.
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]);
Impulse response plot for a continuous-time transfer function.
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(...)
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
With output arguments, impulse gives the output and the time as column vectors. No display is produced.
impulse(1, 1:4, 'm');
Time response plot for a continuous-time state-space model with initial conditions.
initial(Ac, Bc, Cc, Dc, x0) initial(Ac, Bc, Cc, Dc, x0, style) initial(Ac, Bc, Cc, Dc, x0, style, id) (y, t) = initial(...)
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
With output arguments, initial gives the output and the time as column vectors. No display is produced.
initial([-0.3,0.1;-0.8,-0.4],[2;3],[1,3;2,1],[2;1],[5;3])
Plot labels.
label(label_x) label(label_x, label_y)
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.
step(1,[1,2,3,4]); label('t [s]', 'y [m]');
Plot lines.
line(A, b) line(A, b, style) line(A, b, style, id)
line displays one or several straight line(s). Each line is
defined by an equation of the form
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.
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)
Nichols chart grid.
ngrid ngrid(style)
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
ngrid; nichols(7, 1:3);
Nichols diagram for a continuous-time transfer function.
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)
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
With output arguments, nichols gives the phase and magnitude of the frequency response and the frequency as column vectors. No display is produced.
scale('lindb'); ngrid; nichols(20,poly([-1,-2+1j,-2-1j]))
Nyquist diagram for a continuous-time transfer function.
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)
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
With output arguments, nyquist gives the real and imaginary parts of the frequency response and the frequency as column vectors. No display is produced.
scale('equal'); hgrid; nyquist(20, poly([-1,-2+1j,-2-1j]))
Generic plot.
plot(y) plot(x, y) plot(..., style) plot(..., style, id)
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.
Sine between 0 and
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; @}
Set plot options.
plotoption(str)
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.
Display of a photographic image without frame:
plotoption noframe; image(photo);
Roots plot.
plotroots(pol) plotroots(pol, style) plotroots(pol, style, id)
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.
scale('equal'); plotroots(den,'x'); plotroots(num,'o');
rlocus, erlocus, sgrid, zgrid, movezero
Force the display of new graphics.
redraw
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.
Root locus.
rlocus(num, den) rlocus(num, den, style) rlocus(num, den, style, id)
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
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).
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 @}
plotroots, erlocus, sgrid, zgrid
Set the scale.
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
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.
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.
Bit | Meaning |
---|---|
0 | log x |
2 | tick on x axis |
3 | grid for x axis |
4 | labels on x axis |
6 | log y |
7 | dB y |
8 | tick on y axis |
9 | grid for y axis |
10 | labels on y axis |
12 | same scale on both axis |
13 | minimum grid |
14 | maximum 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.
Here are some suggestions for the most usual graphics:
Time response | (default linlin is fine) |
Bode mag | scale('logdb') |
Bode phase | scale('loglin') |
D bode mag | scale('lindb/logdb',[0,pi/Ts]) |
D bode phase | scale('linlin/loglin',[0,pi/Ts]) |
Poles | scale('equal') |
D poles | scale('equal',[-1,1,-1,1]) |
Nyquist | scale('equal',[-1.5,1.5,-1.5,1.5]) |
Nichols | scale('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);
Set the vertical alignment of text, buttons and sliders.
settabs(str) settabs(vec)
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.
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]);
Relative damping and natural frequency grid for the poles of a continuous-time system.
sgrid sgrid(style) sgrid(damping, freq) sgrid(damping, freq, style)
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
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.
Typical use for poles or zeros displayed in the s plane:
scale('equal'); sgrid; plotroots(pol);
zgrid, plotroots, hgrid, ngrid
Singular value plot for a continuous-time state-space model.
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)
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.
Slider control for interactive manipulation of a scalar.
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)
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)
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 @}
Step response plot for a continuous-time transfer function.
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(...)
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
With output arguments, step gives the output and the time as column vectors. No display is produced.
step(1, 1:4, 'b');
Manage subplots.
subplot(m, n, i) subplot(mni) subplot mni
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.
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));
Get or restore the parameter of subplots.
subplotparam({p1, p2, ...}) p = subplotparam
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.
subplots, subplotprops, subplotpos, scale
Get or restore the number and kind of subplots.
s = subplots subplots(s)
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.
subplots('Step\tNyquist\nPoles\tBode')
subplotprops, subplotpos, subplotparam
Get or restore the position of subplots.
subplotpos([left1,right1,top1,bottom1;...]) p = subplotpos
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.
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])
subplots, subplotprops, subplotparam, scale
Get or restore the properties of subplots.
m = subplotprops subplotprops([flags1,xmin1,xmax1,ymin1,ymax1;...])
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.
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])
subplots, subplotpos, subplotparam, scale
Display formatted text in a figure.
text(string) text(x, y, string) text(x, y, string, justification)
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 |
---|---|
c | Center (may be omitted) |
l | Left |
r | Right |
t | Top |
b | Bottom |
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.
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');
label, settabs, slider, button, sprintf
Subplot title.
title(string)
title(string) sets or changes the title of the current subplot.
Relative damping and natural frequency grid for the poles of a discrete-time system.
zgrid zgrid(style) zgrid(damping, freq) zgrid(damping, freq, style)
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
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.
Typical use for poles or zeros displayed in the z plane:
scale('equal',[-1.2,1.2,-1.2,1.2]); zgrid; plotroots(pol);
sgrid, plotroots, hgrid, ngrid