View on GitHub


Monte Carlo Particle Lists

Download this project as a zip file Download this project as a tar.gz file

Using MCPL from the command line

The MCPL distribution includes a handy command-line tool, mcpltool, which can be used to either inspect MCPL files, or to carry out a limited number of operations on them. Since release 1.2, it also includes a second tool, pymcpltool, which provides additional inspection features in the form of plots and statistics display.

This page includes a few examples of how the command-line tools can be used, but users are referred to the MCPL paper (section 2.3) for more information.

At the bottom of the page is also included recipes for how the commands can be quickly obtained without first downloading and installing the MCPL distribution (note that users of McStas, McXtrace and the ESS dgcode framework already have access to the command).


A few examples of how to use the command-line tools are provided here. Note that a small sample MCPL file is included with the MCPL distribution at examples/example.mcpl, in case new users would like something to try the mcpltool on.

Inspect file contents

Simply invoking mcpltool or pymcpltool on a file with no additional arguments, results in a summary of the header information being printed, in addition to the particle state information of the first ten particles in the file:

$ mcpltool example.mcpl
Opened MCPL file example.mcpl:

  Basic info
    Format             : MCPL-3
    No. of particles   : 1006
    Header storage     : 140 bytes
    Data storage       : 36216 bytes

  Custom meta data
    Source             : "G4MCPLWriter [G4MCPLWriter]"
    Number of comments : 1
          -> comment 0 : "Transmission spectrum from 10GeV proton beam on 20cm lead"
    Number of blobs    : 0

  Particle data format
    User flags         : no
    Polarisation info  : no
    Fixed part. type   : no
    Fixed part. weight : no
    FP precision       : single
    Endianness         : little
    Storage            : 36 bytes/particle

index     pdgcode   ekin[MeV]       x[cm]       y[cm]       z[cm]          ux          uy          uz    time[ms]      weight
    0          22      1.2635     -3.5852    -0.81223          20    -0.41453   -0.022799     0.90975  7.3389e-07           1
    1          22      2.6273     0.85935      10.196          20   0.0031473     0.75937     0.65065  8.6567e-07           1
    2         211      1050.4      2.9741    -0.32269          20     0.24133   0.0099724     0.97039  7.1473e-07           1
    3        2112     0.26395     -2.7828      -4.709          20     -0.7575    0.041025     0.65154  2.7656e-05           1
    4        2112     0.34922     0.42959     -11.636          20     0.22266    -0.82642     0.51716  1.9382e-05           1
    5        2112      1.4445      3.8808      14.263          20   -0.036128     0.47899     0.87708  1.9604e-05           1
    6        2112     0.21436     -20.706    0.071227          20    -0.42916     0.43638     0.79082  1.1434e-05           1
    7        2112     0.27496     -6.9939      7.9537          20    -0.47614     0.36919     0.79812  6.8358e-05           1
    8        2112     0.41955     -3.0206     0.11889          20    -0.62614    0.040539     0.77866  2.7557e-05           1
    9        2112     0.64336     -11.788      12.976          20    -0.77018    -0.35919     0.52707  6.1839e-05           1

The -l (limit) and -s (skip) flags can be used to change which particles are printed (use -l0 to print all particles), and -j can be used to suppress the header information.

Extract some particles from a file

Using the --extract flag to mcpltool, it is possible to extract a subset of particles from a file, into a new file. Using the -p flag, one can select according to particle type (2112=neutron, 22=gamma, etc.).

mcpltool --extract -p2112 example.mcpl justneutrons.mcpl
MCPL: Attempting to compress file justneutrons.mcpl with gzip
MCPL: Succesfully compressed file into justneutrons.mcpl.gz
MCPL: Succesfully extracted 726 / 1006 particles from examples/example.mcpl into justneutrons.mcpl.gz

Note that the output file is currently always compressed into .mcpl.gz when possible (this behaviour might change in the future).

You can also use the -l and -s flags to extract particles according to their position in the file, which might for instance be useful to extract a specific interesting particle from a huge file. Here we extract 1 particle starting from position 123:

mcpltool --extract -l1 -s123  examples/example.mcpl selected.mcpl
MCPL: Attempting to compress file selected.mcpl with gzip
MCPL: Succesfully compressed file into selected.mcpl.gz
MCPL: Succesfully extracted 1 / 1006 particles from examples/example.mcpl into selected.mcpl.gz

Merging compatible files

Using the --merge flag to mcpltool, it is possible to merge contents from a list of compatible files into a single new one. Here four existing files are merged, creating newfile.mcpl as a result:

mcpltool --merge newfile.mcpl file1.mcpl file2.mcpl file3.mcpl file4.mcpl

Note that files are considered compatible if and only if they have similar settings and meta-data such as comments and binary blobs. Thus, the resulting file will have the same such settings and meta-data as the originals.

Merging incompatible files (“forcemerge”)

Occasionally, the compatiblity requirements for the –merge option can not be satisfied. At the expense of discarding descriptive meta-data such as comments and binary blobs, a brute-force merge of the files can be instead performed with the --forcemerge flag:

mcpltool --forcemerge newfile.mcpl file1.mcpl file2.mcpl file3.mcpl file4.mcpl

The settings and per-particle storage requirements of the resulting file will automatically be adapted to be such that particles from all the input files can be safely represented. For example, even if just one input file use double-precision storage for its particles, the merged output file will use double-precision for all of its particles.

Due to the loss of meta-data, the usage of the --forcemerge option should be considered as a last-resort only and is in general not recommended.

Get full usage instructions

Full usage instructions are obtainable with the --help flag:

$ mcpltool --help
Tool for inspecting or modifying Monte Carlo Particle List (.mcpl) files.

The default behaviour is to display the contents of the FILE in human readable
format (see Dump Options below for how to modify what is displayed).

This installation supports direct reading of gzipped files (.mcpl.gz).

  mcpltool [dump-options] FILE
  mcpltool --merge [merge-options] FILE1 FILE2
  mcpltool --extract [extract-options] FILE1 FILE2
  mcpltool --repair FILE
  mcpltool --version
  mcpltool --help

Dump options:
  By default include the info in the FILE header plus the first ten contained
  particles. Modify with the following options:
  -j, --justhead  : Dump just header info and no particle info.
  -n, --nohead    : Dump just particle info and no header info.
  -lN             : Dump up to N particles from the file (default 10). You
                    can specify -l0 to disable this limit.
  -sN             : Skip past the first N particles in the file (default 0).
  -bKEY           : Dump binary blob stored under KEY to standard output.

Merge options:
  -m, --merge FILEOUT FILE1 FILE2 ... FILEN
                    Creates new FILEOUT with combined particle contents from
                    specified list of N existing and compatible files.
  -m, --merge --inplace FILE1 FILE2 ... FILEN
                    Appends the particle contents in FILE2 ... FILEN into
                    FILE1. Note that this action modifies FILE1!
  --forcemerge [--keepuserflags] FILEOUT FILE1 FILE2 ... FILEN
               Like --merge but works with incompatible files as well, at the
               heavy price of discarding most metadata like comments and blobs.
               Userflags will be discarded unless --keepuserflags is specified.

Extract options:
  -e, --extract FILE1 FILE2
                    Extracts particles from FILE1 into a new FILE2.
  -lN, -sN        : Select range of particles in FILE1 (as above).
  -pPDGCODE       : select particles of type given by PDGCODE.

Other options:
  -r, --repair FILE
                    Attempt to repair FILE which was not properly closed, by up-
                    dating the file header with the correct number of particles.
                    Read particle contents of MCPLFILE and write into OUTFILE
                    using a simple ASCII-based format.
  -v, --version   : Display version of MCPL installation.
  -h, --help      : Display this usage information (ignores all other options).

Running instead pymcpltool --help shows identical options as for the mcpltool, with the exception that the merge, extract and repair options are absent and that instead options to extract statistics are available:

Stat options:
  --stats FILE    : Print statistics summary of particle state data from FILE.
  --stats --pdf FILE
                  : Produce PDF file mcpl.pdf with histograms of particle state
                    data from FILE.
  --stats --gui FILE
                  : Like --pdf, but opens interactive histogram views directly.

Extract statistics from a file

Using the pymcpltool with the --stats flag, it is possible to analyse a file to get statistics of the contained particles and the distribution of their state parameters:

pymcpltool --stats example.mcpl
nparticles   : 1006
sum(weights) : 1006
             :            mean             rms             min             max
ekin   [MeV] :          52.165         548.838      0.00139345         9724.96
x       [cm] :       -0.248153         12.0726        -60.0882         65.8944
y       [cm] :         2.54021         12.7636        -61.3354         57.6935
z       [cm] :              20               0              20              20
ux           :       0.0216263        0.487791       -0.994109        0.995773
uy           :     -0.00868233         0.47584       -0.994904        0.979886
uz           :        0.690676        0.240955       -0.734438        0.999994
time    [ms] :     5.04828e-05      0.00010785     7.01658e-07      0.00166018
weight       :               1               0               1               1
polx         :               0               0               0               0
poly         :               0               0               0               0
polz         :               0               0               0               0
pdgcode      :        2112 (n)                   726 (72.17%)
                        22 (gamma)               239 (23.76%)
                        11 (e-)                   15 ( 1.49%)
                      2212 (p)                    10 ( 0.99%)
                       -11 (e+)                    8 ( 0.80%)
                       211 (pi+)                   5 ( 0.50%)
                      -211 (pi-)                   2 ( 0.20%)
                        14 (nu_mu)                 1 ( 0.10%)
                     [ values ]             [ weighted counts ]
userflags    :           0 (0x00000000)         1006 (100.00%)
                     [ values ]             [ weighted counts ]

Or, one can view the parameter distributions graphically by adding --gui:

pymcpltool --stats --gui example.mcpl

Resulting in plots of the file contents like these:

pdgcode distribution x distribution uz distribution

Or one can produce a PDF file like this one containing the plots by adding instead the --pdf flag:

pymcpltool --stats --pdf example.mcpl

Extract file contents to text file

Using the mcpltool or pymcpltool with the --text flag (available since MCPL version 1.2.0), it is possible to extract particle data from MCPL files into simple text (ASCII) files. This might be useful for compatibility with software expecting data in column-based text files, but the resulting files are obviously significantly larger and less efficient to use than the original MCPL files:

mcpltool --text example.mcpl out.txt

Quick and dirty ways to get the mcpltool

Compile a single C file …

Rather than downloading and building the full MCPL distribution, it is possible to get hold of the mcpltool command simply by downloading and saving the single-file (“fat”) version of the code found at this link: mcpltool_app_fat.c.

Next, compile it with the command (exchange “gcc” with the name of your compiler - e.g. “clang” on OS X):

gcc -std=c99 mcpltool_app_fat.c -lm -o mcpltool

And you are ready to run! For instance you can inspect an MCPL file with:

./mcpltool <my-mcpl-file>

… or just download and run the pymcpltool

Assuming your machine has Python and NumPy available, one can simply download the MCPL Python module, which is a single file with no compiled dependencies, and which if executed as a script actually is the pymcpltool. So download and save the file: pymcpltool, and make it executable with chmod +x ./pymcpltool. Then you are all set, for instance you can inspect an MCPL file with:

./pymcpltool <my-mcpl-file>

An alternative (and possibly simpler) option, is to install the pymcpltool via python -mpip install mcpl, as discussed here.

Note that as described above, the pymcpltool only provides read-only access to MCPL files, but on the other hand it has the advantage of providing statistics and plotting capabilities which are not currently available when using the compiled mcpltool. Use pymcpltool --help for details.