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.
Launch Sysquake, 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
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 sampling 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 sampling 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!
Sysquake uses several kinds of files: SQ files, SQD (or SQ Data) files, libraries, and files created by programs. 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 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.
Libraries are collections of functions which complement the built-in functions of Sysquake's language. They are made available explicitly to SQ files or other libraries which request them.
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.
There are five manipulation modes, which can be chosen in the Figure menu or in
the toolbar (toolbars differ slightly on Mac OS
- 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.
- 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.
- In 3D figures, a click zooms in, or zooms out if the Shift key is held down.
- 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.
- In 3D figures, a click zooms in or out with orthographic projection. With perspective projection, a mouse drag toward the center of the figure moves the point of view closer to the target point, keeping the zoom factor such that the image size is preserved. A mouse drag from the center of the figure has the opposite effect, moving the point of view further from the target point.
- You can click and drag a figure 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.
- In 3D figures, a mouse drag moves the point of view around the target point, as if the mouse cursor dragged a sphere around the object. If the Shift key is held down, both the point of view and the target point are moved (i.e. the camera dollies parallel to the image).
- 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 (click in the figure with the right button, or hold down the Control key and click in a figure on Macintosh with a single-button mouse); 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.
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 contents of the SQ file currently loaded. For example, in many figures, such as those with negative values, the logarithmic scale is disabled.
The File menu
- Opens a new text editor window, where you can type the source code of an SQ file or the contents of any text file. This is used mainly to develop new Sysquake applications, but can be convenient as a general-purpose text editor.
- Open and Run
- 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.
- Open and Edit
- Opens a text file in the editor window without attempting to running it as an SQ file. You can then inspect it, edit it, save it, and (if it is an SQ file) run it.
- Command Window
- 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. On Macintosh, Command Window is in the Window menu.
- Figure Window
- 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, Figure Window is in the Window menu.
- 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.
- 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. On Windows, Save As SQ File is an option of the Save As dialog.
- Export Graphics As
- The contents of the figure window are saved as an EPS (encapsulated PostScript) or PDF (Portable Document Format) file, i.e. a high-quality graphics file which can be imported in many programs.
- Reloads the current SQ file. This is especially useful when developing your own SQ files with an external text editor.
- Reset Data
- Reverts to the default values of the SQ file or the values of the SQD file.
- 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 numeric values the figures are based on.
- Edit SQ File
- When the figure window of an SQ file is frontmost, Edit SQ File switches to its source code in a text editor window. You can inspect the code, modify it and reload it.
- 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.
- Recent files
- The most recent files can be opened without having to find them with the Open menu entry.
- Quit or Exit
- Quits Sysquake. On macOS, the Quit entry is located in the Sysquake menu.
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.
- 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.
- 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.
- Copy As
- For SQ files which can export data by copying it to the clipboard, the submenu items show what can be exported. Once copied, data can be pasted in another SQ file or another application. For example, an SQ file for identifying the parameters of a model based on experiments performed on a real process may be copied to the clipboard and pasted into another SQ file for the design of a feedback controller.
- Paste As
- For SQ files which can import data by pasting it from the clipboard, the submenu items show what can be imported. Data which can be imported have typically been copied in another SQ file, but can also come from another application.
Depending on the platform, preferences are grouped in a single dialog window or available separately from a submenu. On macOS, preferences are found in the Sysquake menu. 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 first in the folder of the SQD file, then 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. Paths also specify where libraries and help files are searched. Each path is relative to Sysquake, and folders are separated with new lines.
- A path can be:
- The directory which contains the files; the path of the file is obtained by concatenating this directory and the file name, with a separator such as / or \ if it is missing.
- A string with character sequences %b, %s and/or %f which are replaced respectively by the file base name without suffix, the suffix (extension such as sq for SQ files or lml for libraries), and the file name with suffix.
- The syntax of paths depends on the operating system. On 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 with a backslash. On macOS, folders are selected in a dialog window.
- On most platforms, Sysquake also supports URL. SQ files and functions defined in libraries obtained with a URL path are executed in a sandbox. See function path for more details.
- Startup commands
- Startup commands are LME commands executed every time Sysquake is launched. Some global settings can be changed by calling functions: for instance, format sets the way results are displayed, and defaultstyle sets the default style of new figures.
- Another use is to import libraries at startup. If you often call functions from the same 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 explicitly the libraries they use.
- 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. 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 to Sysquake Pro), 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.
- 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.
- 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.
- Background color
- A dialog box is displayed to change the background of figures, between subplots.
- Ignore assert
- In Sysquake programs, the assert function can help in reporting errors during development. If Ignore Assert is on, the evaluation of assert is skipped, which can provide slightly improved performance. Usually, you should switch it on during development, and off when using SQ files whose you trust the quality.
- Ignore private and hideimplementation attributes of functions
- Functions stored in library files can be public, i.e. accessible from other libraries and SQ files, or private, i.e. available only to other functions in the same library. Their implementation can be hidden, so that error messages are the same as for native functions and do not contain information about the error location; and debugging cannot step into them. If Ignore private and hideimplementation attributes is on, private functions can be executed as if they were public and hideimplementation is ignored. This can be useful for development, to debug functions from the Command window.
- 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.
- Rate Limit to Mouse Drag and Move Handlers
- Sysquake programs often perform repeated computation when the mouse is moved. When Rate Limit is on, the rate of these computations is limited to 25 times per second; otherwise, it is limited only by the processing power of the computer. Limiting the rate can reduce the power consumption, with increased battery autonomy on laptop computers and less fan noise on desktop computers.
- 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.
- Default Sandbox Mode for SQ Files
- SQ files can not only perform mathematical calculation, but also access files, network, or other devices. This makes the execution of SQ files obtained from trusted sources potentially dangerous. The sandbox is a secure environment where all commands which could be harmful are disabled. It can be accessed by code with the sandbox function, or enforced globally for SQ files. The Default Sandbox Mode specifies whether the sandbox mode is enabled when new SQ files are opened.
- Ask Before Closing
- If you have change the state of an SQ file (typically by manipulating the graphics interactively) and Ask Before Closing is on, Sysquake will ask you if you want to save it to an SQD file when you close the window.
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 numeric values for the coefficients of a model or to change the structure of a controller. SQ files can also redefine the menu name and define several menus.
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 or anonymous functions. Polynomials are represented by their coefficients, in decreasing power, in a row vector. Here are some examples:
|1, 2.3, -3.2e5
|Set of polynomials
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).
The Figure menu
- 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 figure. 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).
- The Options submenu has three items which may be enabled or disabled. Frame displays a rectangular frame around the graphics with ticks and a white background. Margin leaves room around the frame for the title and axis labels. Label displays the title of the figure. Legend displays the meaning of symbols and colors in figures, provided the feature is implemented in the SQ file. Legends are located in one of the four corners of figures; they can be moved with the mouse.
- 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.
- Sandbox Mode
- Sandbox Mode specifies whether potentially harmful commands (commands which give access to files, network and devices) are disabled (see above).
- 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.
The Layout menu
- 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.
- Instead of being constrained on a regular grid, the subplots can be freely moved and resized with the mouse (in Select mode). When the window is resized, all subplots are scaled the same way.
- Fixed Size
- The subplots can be freely moved and resized with the mouse like with Free layout, but their size and position remain fixed when the window is resized.
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.
- 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.
The Help menu provides information about Sysquake with access to the online version of its user manual and a simple integrated SQ file; and about the SQ file in the front window. The entry "About Sysquake" is located in the Sysquake menu on macOS. Selecting it displays information about the version of Sysquake and whom it is registered to.
Some commands which are related to the currently selected figure(s) are available from a contextual menu, obtained by clicking with the right button of the mouse (on Macintosh with a single-button mouse, hold down the Control key and click). 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.
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 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 Windows:
- Break (Control-Pause).
- On macOS:
- Esc or Command-dot (hold down the Command (Apple) key, then type a dot).
- On Linux:
When the computations take more than half a second in an SQ file, a mark is displayed at the bottom left of the window.
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; in that case, it may be displayed several times before either enough space is allocated or the maximum amount of memory is reached.
Sysquake is an self-contained application which does not rely on other files to run, except for the registration file SQ_Reg.key for versions which require it.
With Sysquake Pro, it is possible to add optional functionality with the help of extension files. For instance, additional high-quality numeric functions are provided by the file "LMELapack".
At startup, Sysquake scans the folder "LMEExt" located in the same folder as Sysquake Pro itself and loads all extensions it finds there. Other files are ignored. Extensions may be removed without harm; note however that some libraries and SQ files may require them to run correctly.
Sysquake retains information about the user preferences between invocations. The location where this information is stored depends on the platform.
Preferences are stored in the system registry, in HKEY_CLASSES_ROOT for information related to the association between Sysquake, its files and icons (preference "Handle SQ Files" as described above) and in HKEY_CURRENT_USER/Software/Calerga for other preferences.
Preferences are stored in the file "com.calerga.sysquake.plist" located in the preference folder, "~/Library/Preferences". The file has the structure of standard preference files on macOS and can be edited with the application Property List Editor which comes with the Apple developer tools.
Preferences are stored in the home directory in the following files:
- Main preferences (text file with pairs name="value")
- Past commands, as they can be retrieved with the up arrow key in the command window, as a text file. Entries are separated with lines containing two exclamation marks.
- Startup commands (text file)
Preferences of other applications of the Sysquake software suite are stored in ".sqappbuilderprefs", ".sqruntimeprefs", and ".sysquakeleprefs".
Environment variables are named strings which can be specified for each running application. They are supported on many platforms, including Windows, macOS and Linux. How they are used and which name is meaningful depend on the application, its libraries and the operating system.
In Sysquake, environment variable values are obtained with the function getenv defined in the Shell extension. In addition, Sysquake for Linux uses the following environment variables:
- Home directory, where preference files are found. This variable is set automatically by Linux.
- Base directory of Sysquake, where the standard directories "SQ_files", "Lib" and "LMEExt" are located. If this variable is not defined, Sysquake attempts to use its own name as it is provided by the operating system (this works only if Sysquake is launched by specifying a relative or absolute path, not if the path is implicitly found in the PATH environment variable); or as a last resort, the fixed directory "/usr/local/sysquake" or "/usr/local/sysquakepro".
- Path of the registration file, whose name is usually "SQ_Reg.key" or "SQ.key". If this variable is not defined, the registration file is searched successively in "SYSQUAKEDIR/SQ_Reg.key", "HOME/.Sysquake/SQ_Reg.key", "HOME/SQ_Reg.key", and "./SQ_Reg.key", where SYSQUAKEDIR and HOME are the values of environment variables SYSQUAKEDIR and HOME respectively, and "." is the current working directory.
- X11BROWSER or BROWSER
- Path of the HTML application to use to display the documentation. If neither of these variables is defined, Sysquake tries to execute htmlview, firefox, mozilla, netscape, opera, and finally konqueror. In versions of Sysquake which support it, the launchurl command uses the same browser.