Jump to: navigation, search

You're probably looking for the page Scripting ASCEND using Python instead of this one!

Python Interface for ASCEND

Basic operations can be performed on the ASCEND engine from Python. At present you can

  • Create a library and load files into it, query the library to see what it contains
  • Query the library to see what external functions have been loaded
  • Instantiate types from the library
  • Set values of bool and integer values in the model instance
  • Get/set real-valued instances including units of measurement; calculate conversions from any given measurement unit back to SI.
  • (Invisibly) store your preferred units of measure for different real-atom types
  • Run METHODs defined in your model
  • Fix and free solver variables in your model
  • Solve the instance using solver with expressions compiled in native C
  • Access plot data and meta-data from 'plottable' instances in the model heirarchy
  • Examine all variables in your model; set values, bounds, scaling.
  • Register solvers, query solvers for their names, apply specific solvers to simulation instances
  • Clear the library
  • Query an instance to get the string representation of a relation/equation.
  • View the entire incidence matrix in graphical form, zoom in and move around.
  • Set the solver parameters for a particular simulation
  • Get the solver's incidence matrix, and examine which rows and columns correspond which relations and variables.
  • Attach callback functions to monitor solver status, residuals, iterations, etc as iteration proceeds.

A preliminary PyGTK GUI interface (see PyGTK Screenshots) has also been developed which allows some interactive work on a model instance. Currently, it allows you to

  • Open ASCEND modules from the GUI (only one is open at a time, opening a new one empties the library)
  • Browse modules present in memory, instantiate a specified model
  • Run methods
  • Adjust values of real, bool and int variables and constants
  • Fix and free different variables including units of measurement
  • View plots of plottable instances
  • Specify (and read off) values in your preferred units of measurement for each real-atom type
  • View relations (as string, on the console)
  • View and set solver parameters for a particular simulation.
  • Plot the solver incidence matrix
  • Create an 'observer' into which you can record your different scenario data points
  • View block-by-block breakdown of your system and examine the equations and variables assigned to each block
  • Set upper and lower bounds for variables, set scaling values.
  • Follow solver progress: current block, elapsed time, RMS residual, etc, using a popup window

Errors are reported in a friendly way at the bottom of the screen and when a value is update, the solver can be set to automatically re-solve the model, so for small models you canvery quickly perform 'what if' analysis; very similar to using a standard spreadsheet.

Building the Python Interface

This article is about planned development or proposed functionality. Comments welcome.

The Python interface code is in the code repository under trunk/pygtk/interface.

(See for Art Westerberg's experience to build this interface. page has been lost.)

To compile the Python interface you will need

  • SWIG version 1.3.24. (the default FC4 version is good) Versions 1.3.27 and newer should be OK as well, but haven't been tried yet.
  • Python version 2.4 including developer header files. You will also need libglade and its python bindings.

To run the PyGTK GUI you will additionally need (be sure to read PythonGUIOnWindows if you are on Windows)

We don't recommend that you build all of the above from source. Instead use your distribution's package manager to download and install binary versions of these.

For example, the above can very easily be installed in Fecora Core 4 (the platform used by most of the developers), provided you have your FC4 'updates' and 'extras' repositories enabled, by typing:

yum install swig python-devel pygtk2 python-libglade python-matplotlib

Once you have the prerequisites, you need to build the ASCEND static libraries. We recommend using the Autotools build process: cd trunk/base/autotools && ./reconfig && make libs works for me, but you may find you need to run ./configure directly with platform-specific settings.

Next change to the trunk/pygtk/interface directory and type make.

Note that Python 2.3 is not currently supported. Let us know if that's a problem for you

Launching the PyGTK GUI

If the build completes correctly, set your ASCENDLIBRARY environment variable to the location of your model files (for example ~/src/ascend/trunk/models) then:

  • Launch the PyGTK GUI: ./ascend
  • Launch the GUI and load a specific module: ./ascend johnpye/testlog10.a4c (for example)
  • Instantiate a specific model: ./ascend johnpye/testlog10.a4c -m testlog10 (for example)

So far the PyGTK GUI has only been used successfully on Linux, but we're confident that it should run OK on Windows without too much extra work.