If you haven't already seen it, our ASCEND overview is a good first place to start reading about ASCEND, and includes quite a few introductory screenshots.
There are two user interfaces for ASCEND. The older, more mature user interface (and the only one offered in the 'stable' 2000 release) is the Tcl/Tk GUI, for which screenshots are not shown here. This page shows the newer Python/PyGTK GUI that has been under development more recently by John Pye For instructions on getting it running, see the PythonWrapper page.
- 1 Browser
- 2 Plotting with PyGTK GUI
- 3 Editing solver parameters
- 4 Viewing an incidence matrix
- 5 Observers
- 6 Manipulating variable properties
- 7 Viewing Relations and residuals
- 8 'Block Diagnose' feature
- 9 Solver status popup
- 10 Running under Windows
- 11 Editing with TextPad on Windows
- 12 Integrator (dynamic simulation)
- 13 Launching ASCEND from Gedit
- 14 Plotting from external Python methods
- 15 IPython console
- 16 Units of measurement
- 17 Incidence graph
This is the main instance browser in the PyGTK ASCEND GUI. Fixed solver_vars are shown in green, free ones are shown in blue, all other instances/variables are shown in black. Values of all of these can be edited directly in-place. Errors and messages are shown in the lower pane, methods can be run from the combobox at the top.
The ASCEND GUI is different from the Tcl/Tk GUI in that it concentrates the user interface into a single window as far as possible, to make ASCEND more 'approachable' for new users. Solver selection and parameter control is the via menus. The 'Library' concept is mostly bypassed, as models loaded from the shell (for example by typing ascend mymodel.a4c) are immediately opened, and, if they contain a 'self-titled' MODEL declaration (eg MODEL mymodel REFINES mybasetype), then that model is instantiated and its on_load method is run. The 'Modules' allows types to be selected from any of the loaded modules, but often now it is not needed. It is also automatically emptied when the user requests to instantiate load a new module; there is no way of having multiple models at a time.
Note: the above is running on Linux (Ubuntu 9.10).
Plotting with PyGTK GUI
To plot from the PyGTK GUI, you must set up your model according to Chapter 4 of the User's Manual (1 MB .pdf). Then, you can right-click on an instance of plt_plot_integer or plt_plot_symbol and click 'Plot' and your plot should appear in a new window.
Plotting under PyGTK is done with the matplotlib library, which gives the additional benefit of allowing plots to be easily exported in a variety of formats including SVG and EPS, PNG and JPEG, etc.
You can also produce thiese plots programmatically using the PythonWrapper as follows:
Most of the functionality that extracts the plot data from the ASCEND instance hierarchy in provided through the SWIG interface, allowing other scripting languages to access the raw plot data.
Here is a screenshot of a the 'plotbvp' demo from the ASCEND standard models:
Editing solver parameters
Recently we've added support for editing solver parameters through the PyGTK GUI. Any parameter that you've changed shows in yellow until you click 'apply'. Note that your parameters aren't saved: if you reload your model they will be reset to their default values. Unfortunately.
Viewing an incidence matrix
This is a simple overall view of the sparsity matrix for a system, either before or after you've solved it. It permits zooming and exporting of the image to various output formats, which should be useful in some case. Mouse-ing over the matrix will show you the variable and relation you're looking at, via the text in the bottom-right of the window (see also the 'Diagnose' feature below). Fixed variables are shown in green, solved free variables are shown in black. We haven't checked out how this stuff works for conditional modelling cases just yet.
Here is a screenshot of the observer functionality, which is roughly equivalent to the 'PROBE' in the Tcl/Tk GUI. In the 'simulation' window you can set which solver variables you want to observe (right click, select 'Observe') and they will appear in your Observer tab.
Each time you have solved a scenario that you want to keep, press ctrl-K to keep the current observed values in the observer data window.
Note that the bold row in the table is 'live'; its values will follow your current simulation, and it is is editable. Edit any bold entry in the table, and so long as it corresponds to a FIXED variable, the results will show up immediately in the other columns (assuming you have set 'Auto' on).
When you have run all the scenarios you want, hit 'ctrl-C' and you can copy your scenario data to another application. You can see here that the results paste into OpenOffice spreadsheets in an immediately useful form:
The Observer tab is also used, in slighly adapted form, as the method in which integration results (time series) are viewed.
You can also plot from the observer tab. Just click the 'plot' button and the second column will be plotted against the first column.
Manipulating variable properties
You can set upper and lower bounds and scaling values for variables via the Properties command. Effort has been made to ensure it can be very easily navigated using the keyboard: F4 opens the variable properties windows, Tab between fields, Enter to confirm, Escape to cancel. If you omit to enter any units, the 'preferred' units will be assumed. If you enter a value in incompatible units, the edit box will show red and you will have to correct it or else click 'cancel'.
Viewing Relations and residuals
The same 'F4' shortcut can be used to review the definitions of relation instances:
'Block Diagnose' feature
This is a new idea for examining the non-converging block or blocks in your model. After you have attempted to solve your model, this screen can be used to look at the structure of the block which is causing trouble, and directly examine the equations and variables that are involved. Below is a preview of this feature:
In the above, it is intended that
- values at or near their bounds should be red
- large-valued variables should be coloured in bright pink,
- largish values in orange
- values near nominal in green
- smallish values in pale blue
- very small values in bright blue
Probably we'll find that different colouring schemes are suitable for different occasions. For example, finding equations with large residuals would use colouring by residual magnitude. Perhaps colouring by magnitude of elements in the jacobian would be useful as well. Would appreciate comments on this.
We plan to add a graph view to this window as well, which would show the actual connection between variables and relations, so that the evaluation 'loops' would be more clearly identifiable.
Solver status popup
You can follow the solver's progress using the 'Solver Status' popup, It reports the number of variables that have been solved, the size of the current block, the current RMS residuals, elapsed time, total iterations and iterations in the current block.
The popup can also be used to interrupt the solver. It can be set to close automatically once the solver has completed (via the Tools menu). We plan to add similar functionality to the 'Diagnose' window so that step-by-step solving can be performed from there as well.
Running under Windows
The PyGTK GUI for ASCEND runs under Windows as well. This version was compiled using MinGW and run using Python 2.5 for Windows plus the Windows port of GTK+, and a couple of other python-related libraries.
Editing with TextPad on Windows
Integrator (dynamic simulation)
Here is the new Integrator window in the PyGTK GUI. It supports the LSODE, IDA and DOPRI5 integrators, although the latter two are still being developed. Support for setting the solution tolerance needs to be added, as well as possibly alternative methods for specifying the integration timesteps. Timesteps aren't currently 'units aware', either.
Here is the progress dialog:
Launching ASCEND from Gedit
We provide syntax highlighting to for the gedit edit on GNOME (Ubuntu, Fedora, etc). Note also the PyGTK GUI command-line parameters, which can be of use when integrating with gedit. In current versions of Fedora and Ubuntu, the tools/gtksourceview-2.0/ of our gedit syntax highlighting must be used. Otherwise, use the tools/gedit/.
Plotting from external Python methods
The ExtPy module allows general scripts to be run from inside ASCEND METHODS. Using the PythonWrapper you can then do anything you like with the ASCEND engine, such as running a model with a range of parameters and plotting the output, as with this simple four-bar linkage example (See fourbar.a4c and fourbarplot.py).
Another example is using a ExtPy script to perform a plot of the roots of a dynamic system
See Python console support for details.
Units of measurement
You can set the preferred Units of measurement for a variable using a popup window:
One you have 'built' a system, you can use ASCEND to view an incidence graph that shows the sequence of calculation in a convenient form. This functionality is not currently available on Windows, only Linux at the moment. See Incidence Graph for more information.