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:

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.

Memory

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.