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.,
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.
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) ###################################################################
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
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).
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.,
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.
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.
-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,
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
! are treated as comments, so the second line is just a separator to make the file easier to understand.
#ISPLT ----------------------------------------------------------------------- VERSION __DO NOT MODIFY__ : 2.0
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)
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
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.
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.
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.
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
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
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.
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
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) : 1Four color schemes are available:
- Color plots on white background.
- Grey-scale plots on white background.
- Color plots on black background.
- 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_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.
#ISCOL ----------------------------------------------------------------------- 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 ----------------------------------------------------------------------- <<END
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
How many tracers are present in each projectile (this information can be found at the end of the
When used in conjunction with the
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
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
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
<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
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>.txtoutput 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
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_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.