pySALEPlot manual


pySALEPlot is a new plotting tool for iSALE datafiles. A gallery of example plots that can be made with pySALEPlot can be found here.

The purpose of pySALEPlot is to allow access of the data stored within the iSALE datafiles from within python, so that flexible analyses and plotting can be performed by the user (for example using the matplotlib libraries).

Conditions of use

pySALEPlot has been developed by Tom Davison, but is intended to help the whole iSALE community. Thus, we ask two things:
  • First, please consider submitting example scripts so that others can quickly see how to make a particular type of plot.
  • Second, if you have used pySALEPlot to make figures for use in a publication, please add the following (or similar) to your acknowledgments: "Some plots in this work were created with the pySALEPlot tool written by Tom Davison".

Tutorial slides

Some tutorial slides are available here.


pySALEPlot can be compiled by adding the --with-pysaleplot flag to your configure command. You will need to make clean before running make, if you have already run make in your iSALE directory. Prerequisites for pySALEPlot are python version 2.3 or higher and the numpy (numerical python) package.

When you run make, a library will be compiled, called When you run make install, that library and the python module are copied to the lib directory in your iSALE installation path. These two files must accessible by python — i.e. they should be in your PYTHONPATH. The simplest way to do this is to add the /path/to/iSALE/install/lib directory to your PYTHONPATH. If you use the bash shell, this can be done by adding the following line to your ~/.bashrc:

 export PYTHONPATH="<path/to/iSALE/install>/lib:\${PYTHONPATH}" 

where you should replace <path/to/iSALE/install> with the install path you supplied as the --prefix in your configure command. If you use a different shell (other than bash), this command will be different (for example you should use setenv for tsch, etc.).

If you have any functions that you find you use often, you can include them in a file, which should be in the same lib directory as the rest of your pySALEPlot installation. These will get automatically imported with the rest of the pySALEPlot library.

Using pySALEPlot

pySALEPlot can be used in two ways. First, it can be used in an interactive python session, and second it can be used in a python script. The main commands you need to use pySALEPlot are given in this section. For some detailed examples of python scripts that use pySALEPlot, see the pySALEPlot/example directory in the repository.

Load the pySALEPlot module:

import pySALEPlot as psp

Open an iSALE datafile:


Read a time step:


(note, by default, this will read the pressure field, 'Pre', or whatever the last field(s) you read for this model were)

Read a particular field from a time step:


Read an arbitrary number of fields from a time step:


Read a particular time step:




Read the last timestep:


Note, once a time step has been read, pySALEPlot automatically advances you to the next time step, so running:


would read three consecutive timesteps into step1, step2 and step3.

The data fields that you have read in (the plottype option to readStep, can then be accessed in two ways:

  1. Each of the data fields is stored in a list called data, in the order you requested them in readStep. For example:
    Tmp =[0]
    Pre =[1]
    Den =[2]
    Sie =[3]
  2. As a convenience, these fields are also directly accessible from the step instance, using the short field code that you used in readStep. So, in the above example,[0] is equivalent to step.Tmp, etc.
    Tmp = step.Tmp  # =[0]
    Pre = step.Pre
    Den = step.Den
    Sie = step.Sie

Plot a field (using matplotlib's pcolormesh function):


Plot two fields (flipped about a symmetry axis):


Change the length scale of the grid:

model.setScale('m') [default]

Set the axes limits to only show the hi-resolution zone:


Print some information from the model header:


Print some information about all tracer units:


Print some information about a specific tracer unit:


Print some information about the time step:


Close the datafile:


Hints and tips

  • If you want to save your images to pdf format, and have plotted a field using pcolormesh, the filesize can be very large if you have a large mesh size. I have found using the rasterized=True option for pcolormesh to be very helpful here. The pcolormesh part of the plot will no longer be vector graphics, but all other parts of the plot (i.e. all text, axes, contour lines using contour, etc.) will still be vectorised, so this is a nice compromise.

pySALEPlot example scripts

Example simulations to use each script on in parentheses. A thumbnail gallery of these example plots can be found here.

Plot one field (demo2D)
Plot two fields (demo2D)
Plot an arbitrary number of fields (Collision2D)
Make a material plot (Collision2D)
Plot material boundaries (Collision2D)
Plot tracers (Collision2D)
Plot tracer lines and grids (Collision2D)
Plot multiple models (Aluminium11002D and Aluminium60612D)
Plot vertical profiles (Chicxulub)

Please consider submitting more examples if you create a type of plot not listed here, so others in the community can benefit from it.

pySALEPlot.pdf (165 KB) Thomas Davison, 11/01/2016 05:39 PM