Documentation of ISALEPlot

iSALEPlot is a plotting program for visualization and post-processing of data produced by iSALE.

iSALEPlot is controlled by options in an input file and command line arguments. The primary purpose of iSALEPlot is to visualise iSALE data using 2D contour (colormap) plots or 1D linegraph profiles. These plots are created by selecting a Plot type: a variable label stored by iSALE (e.g., Den, Pre, etc.). In addition, by selecting other optional Plot types iSALE can be used to perform a number of common post-processing tasks, such as constructing crater profiles, measuring crater dimensions and summing the mass of target and projectile material exposed to different shock pressures.

The standard iSALEPlot options are described below, followed by some examples of common specific tasks.

Command-line arguments

Type iSALEPlot -h to view a list of command-line arguments.

  usage: $(PROGRAM) [flag arg] ...                                  
  POSSIBLE FLAGS:                                                   
  -h          : print this help and exit                            

  -f FILE     : name of iSALEPlot input file (default iSALEPlot.inp)
  -m FILE     : name of iSALE data file (compulsory for J-format)   
  -d DIR      : name of output directory (default PlotType(1:2))    
  -C FILE     : Additional configuration file for tracer processing 
  -T #        : Number of specific tracer (or cell) to process      
  -P #        : Radius of target planet (integer in km)             
  -x EXT      : data file extension (default dat)                   

-f <filename>

Use this flag to choose a specific file as the iSALEPlot input file. If this flag is not used, iSALEPlot will read options from the default input file name iSALEPlot.inp.

-m <filename>

Use this flag to choose a specific file as the iSALE data file. This flag is compulsory if using JPEG-format iSALE data files (the default iSALE data format).

-d <dirname>

Use this flag to change the name of the output directory to which images will be stored. By default the directory will be named after the two variables plotted (e.g., MatDen).

-C <filename>

Use this flag to choose the name of the ``collision'' input file. Activating this input file allows tracer particles to be processed and visualised in an alternative manner to the default behaviour. For more details see section.

-T <integer>

Use this flag to select a specific tracer to analyse and output data for. The tracer number is a single integer, which counts left-to-right and top-to-bottom, first through each object (projectile) and then through the target. For example, in a simulation with 256 tracers in the projectile and 100 x 100 tracers in the target, the tracer number of the tracer ten rows into the target and ten columns from the symmetry axis is given by 256 + 9 x 100 + 10 = 1166. The output when -T is used is a single text file, named tracer-1<tracer number>.txt, with columns: time, x-position, y-position, plot variable 1, plot variable 2.

When -T is used in conjunction with -L, iSALE analyses a single cell, rather than a tracer. In this case, the argument is the cell number, which is counted left-to-right, bottom-to-top. The output in this case is a text file, cell-1<tracer number>.txt.

-P <integer>

Use this flag when processing an iSALE output file generated using setup type 2 (PLANET MODE) to specify the radius of the target planet (in whole km). This ensures that the profiling and crater measurement routines take into account the curvature of the target planet.

-x <file extension>

Use this flag to change the default iSALE data file extension from the default dat. Rarely used.

Input file options

An example of the input file is provided with the demo2D example. Here we describe each line.

The first three lines are the header of the iSALEPlot input file. These should not change. Note that lines beginning with a - or ! are treated as comments, so the second line is just a separator to make the file easier to understand.

VERSION   __DO NOT MODIFY__                       : 2.0

Plot type

PLOTTYPE  Type of plot (right and left panel)     : Dam : Pre

This line defines the type of plot that will be produced. If a single-panel plot is being produced, only the (first) right-hand panel variable will be plotted. The list of available plots is as follows (NOTE that only variables recorded by iSALE can be plotted!).

In most cases, the plots (or other output) will be created in a subdirectory of the directory in which the data file(s) are located. The subdirectory is named after the variables to be plotted. I.e in the example, a directory DamPre is created and the plots saved in there.

Standard mesh variables (2D contour plots; 1D line graphs):

  • Mat -- Material plot (2D only)
  • Dam -- damage plot
  • TPS -- Total plastic strain
  • Sie -- Specific internal energy (logarithmic scale)
  • Pre -- Pressure (normal scale)
  • Prl -- Pressure (logaritmic scale)
  • Tmp -- Temperature
  • Den -- Density
  • Yld -- Yield strength
  • YAc -- Acoustic fluidization strength
  • Con -- Volume fraction of solid matter (concentration of matter).
  • V_x -- Cell-centered horizontal velocity component
  • V_y -- Cell-centered vertical velocity component
  • VSt -- Volume strain
  • Alp -- Distension
  • Dm1 -- Dummy variable 1 (used for development)
  • Dm2 -- Dummy variable 2 (used for development)

Tracer particle variables:

  • Trs -- Tracer particles plotted in horizontal stripes (right-hand side)
  • Trs -- Tracer particles plotted in vertical stripes (left-hand side)
  • TrP -- Tracer particles colored according to peak shock pressure
  • TrT -- Tracer particles colored according to peak temperature
  • TrO -- Tracer particles colored according to peak shock pressure and plotted at original location
  • Trp -- Tracer particles colored according to pressure
  • TrA -- Tracer particles colored according to distension
  • TrV -- Tracer particles colored according to volume strain
  • TrM -- Tracer particles colored according to melt fraction

Additional post-processing options:

  • Pro -- Creates crater profiles and measures crater dimensions.
  • Shk -- Sums tracer particles with peak pressures above certain levels
  • T_C -- Sums cells heated to certain post-shock temperatures
  • Vel -- Monitors velocity and accelerations of tracer particles
  • V_xV_y -- Constructs individual tracer trajectories for many tracers
  • TrpTrt -- Analyses pressure-temperature paths of tracers to estimate melt fraction
  • AlpDen -- Computed total amount of compaction (volume compacted)
  • Oce -- Analyses water surface to measure wave characteristics?

See the sections below for more detailed descriptions of these post-processing options.

Plot range

TIMESTEP  First and last files to be read         :   0 :  200
INCREMNT  Spacing between files to be read        :   10

These lines define the number of the first and last steps in the data file to be read, interpreted and plotted, and the spacing between steps. For example, if the numbers were 3, 9, 2 then the program would read the data steps 3, 5, 7, 9. The plots are numbered in the same way.

GRIDH     Min and max i number for plotting       :   1 :  112
GRIDV     Min and max j number for plotting       :   1 :  140

These lines define the i- and j-range for the plots.

If the range of cells to be plotted in the i direction is less than 20, the plotting routine assumes that the plots are for debugging purposes and writes the value of the mesh variable in the center of the cell as well as coloring the cell appropriately.

If the i or j limits are equal, iSALEPlot will produce a profile line graph, rather than a contour plot. For example, if the minimum and maximum i values are 20, and the j-range is 1-100, then the program will plot a vertical profile through the mesh from j=1 to j=100 through the cells where i=20.

Tracer info

TR_TYPE   Tracer lines, grid or points    (1,2,3) :   -2
TR_SPACE  Spacing between tracers to be plotted   :   5
TR_SIZE   Size of tracer plot marker              :   1

When visualising a field on the mesh, iSALEPlot can overlay tracer particle locations. TR_TYPE defines the type of tracer overlay: 1 = horizontal lines; 2 = grid; 3 = points. A positive value will just overlay tracers over the right-hand plot; a negative value will overlay tracers over both plots.

TR_SPACE defines the spacing between tracer (lines/points). If the spacing between tracers is 0, no tracer will be plotted. If non-zero, this value defines the spacing between horizontal/vertical tracer lines or points.

For tracer-particle plots of the type Trs the spacing between tracers defines the stripe thickness for the horizontal and vertical layers of tracers plotted. For all other tracer-particle plots, this value should be set to 1, to ensure that the location of all tracer particles is plotted.

The size of the tracer plot marker (TR_SIZE) defines the size of the marker particle (default=1)

Output (graphics or ascii data)

TITLES    Should titles be plotted?  (1=yes,0=no) :   1

This option should be set to 1 if labels and titles are desired. Enter 0 if you want the labels omitted (used for manuscript-figure preparation, for example).

PANEL     Double (2) or single (1) panel plot     :   2

If this input is a positive number, it defines whether to plot one variable or two. If this is set to 1, just the right-panel variable will be plotted; if 2, both panels will be plotted. If this is a negative number, it defines whether to export to a text file data for one variable (the first plot type) or two. When exporting data, a directory export/ is created and into this ascii files, named PlotType(1)//PlotType(2)//<time step number>.txt are written (e.g., PreDen00010.txt). The format of the export files are pairs of co-ordinates (x and y of cell-center location) followed by one or two variables (depending on whether -1 or -2 is selected). The data is written from the bottom left of the mesh; left-to-right, bottom-to-top.

PLOTSIZE  Plot width and Height (inches)          :   12. :  9.
DEVICE    Graphics device and extension           :   png/png

PLOTSIZE defines the size of the graphic output. DEVICE defines the graphics device for plotting; only devices supported by your installation of PGPLOT are possible. Examples:

  • png/png -- Portable Network Graphics format with extension .png
  • gif/gif -- Standard gif with extension .gif
  • vgif/gif -- Vertical gif with extension .gif
  • ps/eps -- post-script with extension .eps
  • cps/eps -- color post-script with extension .eps
  • vps/eps -- vertical post-script with extension .eps
  • vcps/eps -- vertical color post-script with extension .eps

NOTE: pngs are recommeded--large meshes imply very large post-script files.

Color-scale limits

VALRANGE1 Min and max values for 1st plot         :   0.0e+0 :  1.0e+0
VALRANGE2 Min and max values for 2nd plot         :   0.0e+0 :  1.0e+9

Define the minimum and maximum values for the variables being plotted.


Dam, SDa, TDa, Con, YAc:  0. -- 1.
Yld:                      0. -- 1.e9
Pre:                      1. -- 1.e9
Sie:                      1. -- 1.e6
Tmp:              0. -- 1.5e3
Den:                      0. -- 3.e3 

Material type

MAT_TYPE  Material type for materials 1,2,3       :  Rck1 : Rck2 : Rck3

These flags are used for coloring of material in Mat plot and coloring the
damage plots. Possible options are Rock, Rck1, Rck2, Rck3, Liqu and Ice_.


DISTUNIT  Units for distance         (mm,cm,m,km) :   km
TIMEUNIT  Units for times          (mks,ms,s,min) :   s

Select the most appropriate unit for distance and time.

Data format

FORMAT    Data format for the files     (a,b,c,j) :   J

Set this the same as the format for the data files output by iSALE. b -- binary data files; c -- character format; J -- jpeg compressed files. Note that J is the preferred format.

ZIPPED    Are the data files zipped? (1=yes,0=no) :   0

Plotting options

Set this to 1 if the data files need to be unzipped before being opened; generally, this is the case for data formats 'b' and 'c', but not 'j'.

BOUNDS    Plot boundaries?           (1=yes,0=no) :   1

Set this to 1 if you want iSALEPlot to plot the material interfaces.

COLOUR    Colour scheme                     (1-4) :   1
Four color schemes are available:
  1. Color plots on white background.
  2. Grey-scale plots on white background.
  3. Color plots on black background.
  4. Grey-scale plots on black background.
PLOTGRID  Should the grid be plotted?(1=yes,0=no) :   0
Plot the grid. Useful when running in Lagrangian mode with a relatively small number of cells.
ALE_MODE  ALE mode      (0=Eulerian,1=Lagrangian) :   0

Set this option to 1 if iSALE was run in Lagrangian or ALE mode. Use of this flag requires that variables C_x and C_y (the node coordinates) were stored by iSALE. Note also that the options to plot tracers and/or material boundaries are not available in this mode.

-C additional configuration input file options

An additional configuration file can be used with iSALEPlot to allow tracer particles to be processed in an alternative manner to the default behaviour. This can be useful when using iSALE with more than one projectile. To run iSALEPlot in collision mode, the command line option -C <additional filename> should be used. An example of the additional input file is provided in the dat/ directory. Below we describe each line.

VERSION   __DO NOT MODIFY__                       : 2.0
TR_END   End of tracer search (0=nmtot,1=nmproj) : 1
PROJ_NUM Number of projectiles                   : 2
TR_PROJ  Number of tracers in each projectile    :  3930 : 3930
PLEVELS  Number of pressure levels required      : 15
PLEVEL1  End of tracer search (0=nmtot,1=nmproj) : 5.D8
PLEVEL2  End of tracer search (0=nmtot,1=nmproj) : 1.D9
PLEVEL3  End of tracer search (0=nmtot,1=nmproj) : 2.D9
PLEVEL4  End of tracer search (0=nmtot,1=nmproj) : 5.D9
PLEVEL5  End of tracer search (0=nmtot,1=nmproj) : 10.D9
PLEVEL6  End of tracer search (0=nmtot,1=nmproj) : 15.D9
PLEVEL7  End of tracer search (0=nmtot,1=nmproj) : 20.D9
PLEVEL8  End of tracer search (0=nmtot,1=nmproj) : 25.D9
PLEVEL9  End of tracer search (0=nmtot,1=nmproj) : 30.D9
PLEVEL10  End of tracer search (0=nmtot,1=nmproj) : 35.D9
PLEVEL11  End of tracer search (0=nmtot,1=nmproj) : 40.D9
PLEVEL12  End of tracer search (0=nmtot,1=nmproj) : 45.D9
PLEVEL13  End of tracer search (0=nmtot,1=nmproj) : 50.D9
PLEVEL14  End of tracer search (0=nmtot,1=nmproj) : 75.D9
PLEVEL15  End of tracer search (0=nmtot,1=nmproj) : 100.D9


Choose whether to process all tracers in the mesh (0), or only tracers in projectiles (1).


The number of projectiles in the model (this information can be found at the end of the /INFO/setup_report.txt file).


How many tracers are present in each projectile (this information can be found at the end of the /INFO/setup_report.txt file).


When used in conjunction with the Shk,TrP or TrO plot types, the additional input file allows the user to input an arbitrary number of shock pressure levels to be processed. When used in conjunction with the T_C plot type, the additional input file allows the user to input an arbitrary number of temperature levels to be processed. Set PLEVELS to the number of pressure/temperature levels you wish to process.

For each pressure/temperature level, PLEVEL#, set the shock pressure/temperature required, in GPa/K.


When used in conjunction with the Shk,TrP or TrO plot types, the additional input file allows the user to input an arbitrary number of shock pressure levels to be processed. Set TLEVELS to the number of pressure levels you wish to process.

For each pressure level, TLEVEL#, set the shock pressure required, in GPa.

Common post-processing tasks

Generating crater profiles and measuring crater dimensions

Perform this by setting the first plot type (for the right panel) to Pro (the second plot type is ignored, so can be set to XXX).

In this case, iSALEPlot will examine the portion of the mesh inside the plotting range for each time step and trace the free surface from the left to the right plot limit. Each profile is stored in a text file in the directory ProXXX/, named <time step number>.txt.

In addition, iSALEPlot attempts to extract the crater diameter, volume and depth as a function of time. These data are output as eight columns in a text file cratersize.txt. The odd colums are data in SI units; the even columns are data in scaled units. Time is non-dimensionalised as Ut/a, where U is the impact velocity and a is the impactor radius. Crater depth and radius are non-dimensionalised as d/a and R/a, respectively. Crater volume is non-dimensionalised as \rho V/m where \rho is the target density and m is the projectile mass.

NOTE: correct scaling requires that iSALEPlot knows the impact velocity, impactor radius, impactor density and target density for the simulation analysed. These data are set using additional iSALEPlot options:

VELOCITY  Impactor velocity (m/s)                 :   5.0e+3
RADIUS    Impactor radius (m)                     :   1.0e+2
DENSITY   Impactor and target density (kg/m^3)    :   2.6e+3 :  3.5e+3

Analysing the amount of shock heated material with tracer particles

Perform this analysis by setting the first plot type (for the right panel) to Shk (the second plot type is ignored, so can be set to XXX).

In this case, iSALEPlot will examine each tracer in the mesh (or the range of tracers defined in the additional (-C <filename>) input file) at each time step and sum the mass and volume of material shock heated to each pressure level. By default, the pressures are defined as 1GPa, 5GPa, 10GPa, 20GPa and 50GPa. (These values can be changed in the tracermass.f90 source code file -- if you do this iSALEPlot will need to be recompiled). Alternatively, by running iSALEPlot with the flag -C <filename>, it is possible to define an arbitrary number of pressure levels to be processed.

Output for this plot type is placed in a directory named ShockP. For each timestep analysed, data is written to the output files masvol-<time step number>.txt and totals-<time step number>.txt. If run with the flag -C <filename>, additional output files are written: projmas-<time step number>.txt and projvol-<time step number>.txt.

  • masvol-<time step number>.txt: This file contains information for each tracer particle at this time step: x- and y-locations, tracer volume, tracer mass, and peak shock pressure.
  • totals-<time step number>.txt: This file contains the sum of all tracer masses and volumes above the given shock pressure levels.
  • projmas-<time step number>.txt and projvol-<time step number>.txt: Similar to the totals-<time step number>.txt output file, these output files contain the sum of the tracer masses or volumes shock heated above wach pressure level, but values are given for each projectile, as well as a total for all material analysed.

Analysing the amount of shock heated material without tracer particles

Perform this analysis by setting the first plot type (for the right panel) to T_C (the second plot type is ignored, so can be set to XXX).

This analysis loops over all the cells in the mesh for each timestep, and sums volume and mass of cells which have a temperature above 6 pre-defined levels (0K, 500K, 750K, 1000K, 1250K and 1373K). (These values can be changed in the \verb+temp_contour+ subroutine in the tracermass.f90 source code file, and iSALEPlot recompiled). Alternatively, by running with the flag -C <filename>, an arbitrary number of temperature coutours can be defined in the additioanl configuration file, using the lines normally used to define pressure levels (line 5 onwards). N.B. in this case, the tracer parameters on lines 1--4 of the additional file are not used.

Output is placed in a directory named Temp_C. For each timestep, an output file totals-<time step number>.txt is written, which contains the mass and volume of material with a temperature above each temperature level defined. Two files, contour_mass.txt and contour_vol.txt output the heated mass or volume at each temperature for each timestep, to allow plotting of the growth of heated areas through time, for example.