Using the GMT imaging software for 2D plots
Graphical output from PEPC can be created using the postprocessor slicer, which converts the particle data into 'fluid' quantities such as mass density, flow velocity and temperature etc. on a 3D grid. This is then used to create 2D slices/projections in the xy and xz planes, along with lineouts at positions specified in an input file.
The particle data is assumed to be in the form of the PEPC dump file:
x, y, z, px, py, pz, q, m, Ex, Ey, Ez, potential, owner, plabel
The postprocessor program slicer.f90 is in the tools directory. To (re)compile it, use:
> make clean > make slicer
The input files read by this program from the run directory are:
grid_defs.in dumps/parts_info.TTTTTT timestamps
where TTTTTT is the snapshot timestep. This should be entered in the timestamps file, which may contain a snapshot series. If timestamps is empty, a new one will be generated by inspecting all the parts_info.* in the run directory - not recommended if there are a large number of snapshots.
An example of the grid_defs.in file is given below and can also be found in the tools directory. Copy this into your run directory and edit accordingly. In particular, make sure the # particles matches (or is less than) the number in the particle dump. The slicer program assumes formatted data, so care should be taken not to alter the order or integer/float representation of the numbers. The variable names in front of the equals sign can be changed, however.
n= 1000000 # particles to process
ngx= 200 # grid points in x
ngy= 200 # grid points in y
ngz= 50 # grid points in y
ngux= 100 # " " in vx
nguy= 100 # " " in vy
nguz= 100 # " " in vz
nalpha= 100
xmin= 100. box xmin
xmax= 600.0 box xmax
xtick= 100. box tick interval on x-axis
ymin= 200.0 box ymin
ymax= 700.0 box ymax
ytick= 100.0 interval y-axis
zmin= -50.0 box zmin
zmax= 150.0 box zmax
ztick= 100.0 interval z-axis
uxmin= -5.0 vxmin for phase space plots
uxmax= 5.0 vymax
uxtick= 2.5 interval
uymin= -5.0 box vymin
uymax= 5.0 box vymax
uytick= 2.5 interval
uzmin= -2.0 box vzmin
uzmax= 2.0 box vzmax
uztick= 1.0 interval
umevmax= 20. max energy for f(u)
uximin= -3.0 box parameters ions
uximax= 3.0 (see above)
uxitick= 1.5
uyimin= -3.0
uyimax= 3.0
uyitick= 1.5
uzimin= -3.0
uzimax= 3.0
uzitick= 1.5
uimevmax= 1.
aimin= -60. min/max angles
aimax= 60.
uimev1= 1.
uimev2= 3.
yslice= 400.0 y-position of slice for xz plots
zslice= 50.0 z-position of slice for xy plots
xrear = 80.0
mratio= 1836. mass density scaling factor
rhomax= 10. max density
temin= 0.001 min electron temperature
temax= 0.1 max electron temperature
tmin= 0.001 min ion temperature
tmax= 0.3 max ion temperature
jemax= 1.0
vmax= 2.0 max velocity
emax= 0.5 max E field
fpmax= 10.
jevec= 10. scaling factor for current
vvec= 5. s.f. for velocity arrows
evec= .5 " " field arrows
eps= 1.0
tcold= 100.0
xbox= 2.
ybox= 2.
zbox= 2.
yshift= 3.6 shift (inches) for legend
zshift= 3.6
pshift= 3.4 as above for phase-space plots
iskip3d=1
The slicer program can be used on its own to generate gridded data: these subsequently appear in a subdirectory TTTTTT corresponding to the to parts_info.TTTTTT.
Tips:
- Make sure the grid lengths (ie: xmax-xmin etc.) are easily divisible by the number of mesh points (ngx).
- Use a coarse grid to start with (eg 100x100x50) and refine later.
- For quick previews, reduce the number of particles read in.
For convenience, a number of scripts are made available which combine the slicer output with command-line graphics tools from the GMT (Generic Mapping Tools) package. The latter is assumed to be installed locally under $HOME/gmt, with the appropriate environment (GMTHOME) and path variables set. If not, it is freely available from
The postprocessing scripts are located in pepc/bin and have the form:
make_density make_snaps
etc. Calling a script without parameters will usually result in a help message, for example:
> make_snaps Call parameters: run# runpp/nopp plot/noplot >
First, the script checks whether the particle data have already been merged from the 'pe' directories. If so, there will be a large file in dumps/parts_dump.TTTTTT If not, the merge1_dump script is called to do this task. Then, the slicer program is called to produce the gridded data in TTTTTT/xy_slice_den etc. Finally, a series of GMT tools are called to generate the images.
The make_snaps script will produce snapshots for the whole sequence given in the timestamps file, eg: suppose the timestamps file contains:
000100 000200 000300
Then:
> make_snaps disc1 runpp plot
will perform the postprocessing and produce plots at timesteps 100, 200 and 300. The first parameter is an arbitary run label which will get stamped on the corner of the plots together with the date for identification purposes. Use the runpp option the first time you generate grid data, or if you change any parameters in the grid_defs.in file. Otherwise, nopp will use the available data and jump straight to the graphics tools. The noplot option can be used to suppress postscript image generation (postprocess only).
The plots are in high-quality postscript format and are placed in subdirectory pepc/plots/. A compressed tar file images.tar.gz containing all plots is also generated by the script. Fine-tuning of the plots can be done by editing the scripts - make_snaps, etc. This will require some knowledge of the GMT package, which is comprehensively documented in GMT_Docs.pdf and GMT_Tutorial.pdf from the distribution.
