Getting Started with SysQuake
This chapter describes the user interface of SysQuake, i.e. how you manipulate
its windows and what you can find in its menus.
First steps
Launch SysQuake by double-clicking its icon.
Then choose File/Open (i.e. click the File menu, then the Open item) and select the
file sampling.sq, which should be located in the "SQ_Files" folder, to learn basic
manipulations. The purpose of this SQ file is to show the effect of sampling (and
other method for converting systems from continuous time to discrete time) on the
frequency response and step response.

In the figure window, two graphics should be displayed. At the top, the
frequency response amplitude of a continuous-time third-order system is
represented as a black line. The red curve represents the frequency response
amplitude of the same system, but sampled. The sample frequency is represented
by the blue vertical line, and the Nyquist frequency (half of the sample
frequency) in green. The discrete-time curve has a periodicity equal to the
sample frequency. The bottom graphic represents the step response of the
system, again both in the continuous-time domain and in the discrete-time domain
(red circles).
If you click one of the vertical lines and hold down the mouse button, you can
move the line to the right to increase the sample frequency or to the left to
decrease it. More interesting is the effect on the discrete-time responses.
Both the frequency responses and the step responses are updated during the move.
If you decrease enough the sample frequency, the frequency response matches
more and more loosely the continuous-time response. In the time domain, you can see
that the samples do not follow the oscillations. You can also click and move
(or drag) one of the samples in the step response plot.
A very useful feature of SysQuake is the Undo command. You can undo and redo
any interactive manipulation, change of settings, zoom, and choice of figures to
display, as many times as memory permits. These commands can be found in the Edit
menu. They are your friends; learn to use them frequently!
Files
SysQuake has three kinds of files: SQ files, SQD (or SQ Data) files, and files
created programmatically. SQ files
are kinds of programs, or scripts, which implement figures,
menus and computation code for a given topic. Several SQ files are provided with SysQuake.
Some of them are suitable for
many problems in the same area and can be customized with your own data, for example
for the design of a digital filter, while others have more narrow applications.
You can also write your own SQ files with an external text editor. If you use a word processor,
make sure that you save SQ files as text only, or ASCII; many word processors
add formatting information (such as margins or character style) which is
not understood by SysQuake. On the Macintosh, SQ files are associated with
SysQuake and get an SQ file icon when you open them with SysQuake for the
first time, either from SysQuake (menu File/Open) or by dragging the document
icon onto SysQuake's; then you can simply double-click the SQ file icon in
the Finder to open it in SysQuake.
SQD files store the state of a session with SysQuake. They are always associated
with an SQ file. They only contain the data necessary to load back the SQ file and
restore the parameters, settings and figures which were defined when they were saved.
Typically, they are written and read by SysQuake; but since they are also text files,
you can easily create them by hand, read the values, or use them to exchange data
with other applications.
With its rich built-in language, SysQuake can also read and write arbitrary text
and binary files. What they contain and when they are created and read depend only
on the programmer. For example, an image processing SQ file could read TIFF files
(a popular file format for raster images) by adding a custom entry in the Settings
menu. This is actually what image.sq, one of the SQ files provided with SysQuake,
does.
Manipulation modes
There are five manipulation modes, which can be chosen in the Figure menu or in
the toolbar:

- Manipulate
- You can drag graphical elements in one of the subplots and see the effect
this has on other figures. Depending on the figure, you can drag graphical
elements horizontally, vertically, or in any direction. Not all the elements can
be dragged; the shape of the cursor usually indicates whether dragging is
enabled (hand with index finger) or disabled (standard arrow cursor). For some
figures, holding down the Shift key modifies the action performed by the
drag.
- In automatic control and filtering, the dynamic of linear systems is often
represented by poles and zeros symmetric with respect to the horizontal axis
(real axis). To enforce this symmetry, dragging a complex pole or zero (a pole or
zero not on the real axis) also moves the symmetric one; attempting to drag a
complex pole or zero to the other side of the real axis makes it stick to the
real axis; and dragging a pole or zero from the real axis can be done only upward
if there is at least one other pole or zero on the real axis, which becomes its
symmetric.
- Zoom
- You can click in a subplot to double the scale in both x and y directions, or
select the area you want to display by holding down the mouse button. To zoom
out, hold down the Shift key and click. To revert to the default scale, select
the subplot (see below) and select Figure/Automatic Scale. Many figures have
automatic scaling by default; to fix the scale without zooming, unselect
Figure/Automatic Scale.
- Zoom X Axis
- The zoom is constrained to the x axis. The scale remains automatic for the y axis
if it already was before the zoom. Note that figures where the scale for both axis
is constrained to be the same cannot be zoomed in or out in this mode.
- Drag
- You can click and drag a graphic to move it in its subplot region. The limits
of the displayed area of the plot are changed such that the point under the mouse
cursor moves with it. Hold down the Shift key to drag along the x axis.
- Select
- You can select a subplot by clicking it (this is necessary only if several
subplots are displayed simultaneously), and change what is displayed by choosing
an entry of the Plot menu or some options in the Figure menu. By holding down the
Shift key, you can select more than one subplot. You can also drag a figure from
one subplot slot to another one. The figure which was in the target subplot
replaces the dragged figure. The zoom factor and scale options are preserved. Some
commands are available from a contextual menu (hold down the Control key and
click in a figure on the Macintosh, or click with the right button on Windows);
you do not need to select a subplot before using it.
It is sometimes useful to synchronize the area displayed in two subplots. For
instance, if you display simultaneously the amplitude and the phase of a
frequency response, you may want to zoom along the X axis to display a smaller
frequency range, identical for both figures. To do that, first select both
subplots (switch to Select mode, click the first subplot, hold down the Shift
key, and click the second subplot). Then switch to Zoom, Zoom X, or Shift mode,
and change the scale of one of the selected subplot. All the selected subplots
will follow, provided that their scale was already the same before the
change.
Remark: with some versions of SysQuake, the middle button of
mouses with three buttons has the same effect as holding down the Shift key and
clicking with the left button.
Menus
This section describes the commands you can find in the menus. The most important
ones have keyboard shortcuts which are more efficient for the experienced user.
Note that some menu entries are enabled or disabled by the content of the SQ
file currently loaded. For example, in many figures, such as those with negative values,
the logarithmic scale is disabled.
File

The File menu contains the commands which handle SQ files as a whole (file operations
and reset to the default values) and quit SQ itself.
-
Open
-
Opens either an SQ file or an SQD file, i.e. a file which contains customized
values and settings as well as a reference to the related SQ file. When you open
an SQD file, SysQuake loads its related SQ file first, then restores the state of
the data and the figures which prevailed when the SQD file was saved.
-
Reload
-
Reloads the current SQ file. This is especially useful when developing your
own SQ files with an external text editor.
-
Figure Window (Macintosh only)
-
Displays the figure window. The figure window is the window where
graphics created by SQ scripts or from the Command window are displayed. On
Macintosh computers, interactive graphics of SQ files have their own windows.
-
Command Window (Macintosh only)
-
Displays the command window.
The command window is a window where you can type commands and evaluate expressions,
as well as see the textual output (if any) of the execution of SQ files. This is
especially useful when you develop your own SQ files.
-
Close (Macintosh only)
-
Closes the active window. The Figure window and the Command window are only hidden
and can be shown again with the menu entries described above.
-
Save
-
Saves the current values and settings with a reference to the SQ file in the
current SQD file. For an SQD file to be considered as "current",
it must have been opened, or already saved with Save As. Otherwise, you must
select Save As to provide a file name for the new SQD file.
-
Save As
-
Same as Save, but a file name and location is requested.
-
Save As SQ File
-
Same as Save As, except that an SQ file is written instead of an SQD file. The
SQ file has the advantage of being self-contained and independent from the
original SQ file, and the disadvantage of requiring more disk storage and
not benefiting from improvements made to the original SQ file. If the SQ file
contains a help text, the mention Saved as SQ file (default values are new)
is appended to make clear that the SQ file has been modified. You can edit the
SQ file to change the help message (as well as other elements) if the SQ file
author permits you to do so.
-
Dump Data
-
Writes what would be saved in an SQD file by the Save command to the Command
window or panel. Usually, the result corresponds to the variables used by
the SQ file and contains the numerical values the figures are based on.
-
Reset Data
-
Reverts to the default values of the SQ file or the values of the SQD file.
-
Print
-
Prints the contents of the figure window. Depending on the operating system,
it may also be possible to print the command window or panel, to specify
printing options, and to preview what would be printed.
-
Quit or Exit
-
Quits SysQuake.
Edit

The Edit menu contains the commands which manipulate the clipboard for data exchange
within SysQuake and with other programs, and the Undo/Redo commands. Note that the command-line
interface (the text window where you can type direct commands) may support only Undo or
no Undo at all, depending on the platform.
- Undo
- Reverts to the situation which prevailed before the last user action. Most figure
interactive manipulation and setting in the Settings menu can be undone. Undo can
be used as many times as memory permits.
- Redo
- Undoes the last undo.
- Cut, Copy, Paste, and Clear
- Standard editing operations. In the figure window, only Copy is supported; it makes
a copy of the selected subplot, or of all the subplots, as graphics (the exact
format depends on the operating system).
- Select All
- Selects all the subplots.
- Preferences
- Preferences permit some customization of the way SysQuake interacts with the
operating system. The settings are saved and restored the next time SysQuake
is launched.
- Set SQ File Path
- When an SQD file is opened, SysQuake looks for the name of the SQ file associated
with it. Then it looks in prespecified folders to load the SQ file and set
the variables based on the contents of the SQD file. With Set SQ File Path, you
can check and change where SysQuake looks for SQ files. By default, this is
in the folder "SQ_files", itself located at the same place as SysQuake; but you can
change it, or add your personal folders.
Each path is relative to SysQuake, and folders are separated with new lines.
Each path is prepended to the SQ file name; hence it must ends with a folder
separator such as : or \. The syntax of paths depends on the operating system:
- Mac OS
- Relative paths begin with a colon (':'), and absolute paths begin with the volume
name. Each element is separated by a colon. To go up one level, add a second colon
at the beginning of the relative path (e.g. if SysQuake is in folder SQ, itself
in a folder which contains the folder MySQFiles, you can have ::MySQFiles:).
- Windows
- Relative paths begin with a backslash ('\'), and absolute paths begin with
the volume letter followed by a colon (e.g. 'C:'). Each element is separated
by a backslash.
- Startup Commands
- Startup commands are LME commands executed every time SysQuake is launched.
Typically, if you often use functions from libraries (such as
stdlib for basic function which extend
the built-in functions of SysQuake or stat
for advanced functions related to statistics), you can add
use statements as startup
commands to make them always available:
use stdlib, stat
- Functions are imported only for usage
in the command-line interface, not in SQ files which must specify explicitely
the libraries the use.
- Memory
-
The memory usage is adjusted automatically when required. However, depending on
your needs, it may be better to allocate a large amount of memory at startup or
to limit the maximum amount of memory. In addition on the Macintosh, you can specify
whether you want to use temporary memory or not. Temporary memory is memory not used
by any other application, while application memory (whose amount is set in the
Finder) is reserved when the application is launched. We recommend that you keep
the default values, except for the minimum memory which can be increased but should
be kept lower than your physical memory for best performances.
- Handle SQ Files (Windows only)
-
Windows stores information about which application should be invoked when a document
icon is double-clicked in a central location called the Registry. If you move SysQuake,
or if you install a new version (e.g. by upgrading from SysQuake LE to SysQuake),
you should tell Windows if you want the SysQuake which is currently running to open
and print SQ files. You do so by choosing Handle SQ Files. Then the menu entry is
checked and disabled, because you cannot revert your action. To select another
version of SysQuake, run it and select Handle SQ Files from it.
- Font
-
A dialog box offers the choice of the font for the command window or panel.
- Code Optimization
-
Programming code of SQ files is converted to an intermediate code for faster
execution. Code optimization further speeds up its execution by replacing some
sequences of code with faster alternatives. Most of the time, you should keep
this option set.
- SQ File Possible Error Warnings
- When you develop new SQ files, SysQuake can help you to find potential problems.
In addition to errors which prevent the SQ file to run at all, which are always reported,
SysQuake can analyze your code and find programming patterns which are often
not intended and cause errors difficult to find. You should leave this option off
for SQ files which are known to be correct, because warnings do not always correspond
to errors and do not mean that the SQ file has a lower quality.
- Thick Lines
-
When selected, all lines in graphics are displayed with thicker lines. This may
be useful for demonstrations.
- Figure Font
-
A dialog box offers the choice of font for the figures.
- Interactive Figure Hilight
- When selected, the frame around interactive figures (subplots where there
are elements which can be manipulated with the mouse) is displayed in red instead
of black. In many cases, the mouse cursor also changes when the mouse is over an
element which can be manipulated.
- Background Color
- A dialog box is displayed to change the background of figures, between
subplots.
Settings
The Settings menu, available only for some SQ files, contains actions defined in the
current SQ file. These actions typically modify the system in a noninteractive way, for
example to enter numerical values for the coefficients of a model or to change the structure
of a controller.
When a dialog box is displayed, the edit field contains the current values of one
or several parameters, separated by commas. Values can be real or complex, scalar, vector,
matrices, lists, structures or inline functions. Polynomials are represented by their
coefficients, in decreasing power, in a row vector. Here are some examples:
Real scalar |
1, 2.3, -3.2e5 |
Complex scalar |
3i, 1.2-5.4j |
Row vector |
[4,2,6] |
Column vector |
[4;2;6] |
Polynomial |
[1,2,5] |
Matrix |
[1,3;2,8] |
Set of polynomials |
[1,4.9,3.1;1,6.2,2.6] |
Identity matrix |
eye(3) |
Range |
1:10 |
List |
{1,2:5,'abc'} |
Structure |
struct('A',[1,2;3,-1],'B',[3;5]) |
Inline function |
inline('2*exp(-t/tau)','t','tau') |
Plots
The Plots menu, available for most SQ files, contains the list of figures
which can be displayed. General-purpose SQ files usually define figures for
everything you might want to observe, but only display a few of them by default.
More specialized SQ files can have one or two plots which are displayed by
default; in this case, the Plots menu is less useful.
To change one of the figures, first select it (click the selection button in the
toolbar or choose Select in the Figure menu), then choose one of the entries of the
Plots menu. You can change the number of figures which are displayed simultaneously
with the Layout menu (see below).
Figure

The Figure menu permits to select one of the five modes of operation on the figures,
as described above, and to change display options for the selected subplot(s).
A subplot is selected either if it has been clicked in Select mode, or if it
is alone. Depending on the figure, some options may be disabled.
- Manipulate, Zoom, Zoom X, Drag, and Select
- Selects one of the modes of operation.
- Locked Scale
- SQ files typically define a default scale for each figure. The scale may adapt
to the figure contents. When you zoom or drag the figure, the scale is locked.
You can unlock the scale of the selected subplot and revert to the default scale
by unselecting Locked Scale; you can also lock an unlocked figure, e.g. if you want
to better observe small amplitude changes when you manipulate another graphic.
Note that the figure which is manipulated has always its scale locked during
the manipulation.
- Log X, Log Y, and dB Y
- With Log X, the horizontal scale becomes logarithmic, and negative values
are discarded. With Log Y, the vertical scale becomes logarithmic. dB Y is the
same as Log Y as far as the contents of the figure are concerned; however, the
axis is labeled in dB's, i.e. a linear scale where a difference of 20
represents a factor 10 for the data: y'[dB] = 20 log10(y) (decibels
are defined with 10 instead of 20 for powers; the definition used by SysQuake
is valid for voltages, currents, mechanical displacements, etc. which are
proportional to the square root of powers).
- Options
- The Options submenu has two items which may be enabled or disabled. Frame
displays a rectangular frame around the graphics with ticks and a white
background. Label displays the title of the figure.
- Grid
- The Grid submenu sets the level of detail of the grid which is displayed in the back of the
selected subplot(s). The availability and the kind of grid depend on the figure.
- Idle Processing
- Some SQ files perform computations even when you do not interact with them,
for example for animated simulations. The computation may slow down the whole
computer. To suspend it, unselect Idle Processing. Note that the menu entry
is disabled if the SQ file does not implement idle processing.
Layout

The Layout menu permits to choose the number of subplots to be displayed
simultaneously.
- 1x1, 1x2, 2x1, 2x2, 2x3, 2x4, 3x2, 3x4, 3x4, 4x4
- The corresponding number of subplots is displayed. If some subplots were
selected, they are preserved in the new layout; otherwise, the subplots
remain at the same position.
- Free
- Instead of being constrained on a regular grid, the subplots can be
freely moved and resized with the mouse (in Select mode).
View (Windows)
On Windows, the View menu permits to show or hide toolbars and panels.
- Command Panel
- The command line interface is available in a subpanel of the
main window. You can show it or hide it with the menu entry View/Command Panel.
When is it shown, you can resize it by dragging the separation with the mouse.
- Toolbar
- The toolbar can be hidden or shown. It can also been torn off
or docked with the mouse.
- Status Bar
- The status bar (the region at the bottom of the main window where
status messages are displayed) can be shown or hidden.
Apple (on Macintosh) or Help (on Windows)
The first or last menu is platform-specific; it contains at least an entry
About SysQuake which displays information about the version you use and whom SysQuake is
registered to.
Contextual menu
Some commands which are related to the currently selected figure(s) are available
from a contextual menu. On Macintosh computers, hold down the Control key (ctrl, usually
at the lower left of the keyboard) and click in a figure; on Windows, click with the
right button in a figure. The figure becomes selected, and a contextual menu appears
right under the mouse cursor with commands for choosing the figure and changing the
scale and the grid. This is very convenient to avoid switching to and from
the Select mode.
Command-Line Interface
The command-line interface is useful for two purposes:
- as a powerful calculator, where you can type expressions and get
answers;
- as an help for developing, testing and debugging new SQ files.
You can ignore it if you use existing SQ files. Note also that you
cannot add interactivity from the command line; interactivity requires SQ files
(or SQ scripts, which are very close to the commands you can type in the
command-line interface).
The command-line interface,
SQ scripts,
and SQ files are detailed in other chapters.
Interruption Key
The goal of SysQuake is to be as interactive as possible. However, nothing in its
design prevents it from doing long computations, from the command line as well as in
SQ files. You can interrupt it by pressing the following keys:
- On the Macintosh:
- Esc or Command-dot (hold down the Command (Apple) key, then type a dot).
- On Windows:
- Esc or Break.
Note that the execution can be interrupted only at the end of loops and in
user function calls, so that normal operations are almost not slowed down. You should
avoid slow operations on very large matrices, such as fft(1:1e6) or
eig(rand(1000)), which cannot be interrupted.
LME uses a block of memory of fixed size. If a function call requires more
space than the current size of the block allows, e.g. magic(500) for
a 500x500 magic array, an error occurs. However, after the error, an attempt is
made to increase the available memory. If you typed the command in the
command-line interface (see below), you can retry (use the Up arrow key to
retrieve the previous command from the history buffer). But if the error occurred
during the execution of a handler (a function defined in an SQ file), SysQuake
will retry automatically. This procedure is usually transparent for the user,
unless a dialog box has been presented to the user; in that case, it may be
displayed several times before either enough space is allocated or no more memory
is available.
Copyright 1998-2001, Calerga.
All rights reserved.