mcpl - A wrapper for the MCPL file format & library

MCPL stands for Monte Carlo Particle Lists. It is a binary file format to interoperate between different (typically Monte Carlo based) physics simulation software packages. The file format stores particle information like energy, direction, position etc.

This library is a wrapper of the C library of the same name:

https://mctools.github.io/mcpl/

The full particle_t type is defined by:

typedef struct {
  double ekin;            /* kinetic energy [MeV]             */
  double polarisation[3]; /* polarisation vector              */
  double position[3];     /* position [cm]                    */
  double direction[3];    /* momentum direction (unit vector) */
  double time;            /* time-stamp [millisecond]         */
  double weight;          /* weight or intensity              */
  int32_t pdgcode;    /* MC particle number from the Particle Data Group (2112=neutron, 22=gamma, ...)        */
  uint32_t userflags; /* User flags (if used, the file header should probably contain information about how). */
} mcpl_particle_t;

which (currently) maps to this Nim type:

particle_t* {.bycopy.} = object
  ekin*: cdouble             ##  kinetic energy [MeV]
  polarisation*: array[3, cdouble] ##  polarisation vector
  position*: array[3, cdouble] ##  position [cm]
  direction*: array[3, cdouble] ##  momentum direction (unit vector)
  time*: cdouble             ##  time-stamp [millisecond]
  weight*: cdouble           ##  weight or intensity
  pdgcode*: cint          ##  MC particle number from the Particle Data Group (2112=neutron, 22=gamma, ...)
  userflags*: cuint       ##  User flags (if used, the file header should probably contain information about how).

A wrapper around this object for a nicer & safer interface will be added.

Installation

First of all make sure you have mcpl (the C library) installed, in particular the shared library libmcpl.so.

In case you don’t, we can build the library quickly ourselves:

Build libmcpl.so

To build the library you need cmake.

First clone the git repository somewhere:

cd ~/src
git clone https://github.com/mctools/mcpl/

Now create some build directory:

cd ~/src/mcpl
mkdir build

and time to configure and build:

cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME/src/mcpl/build/ -DBUILD_WITHG4=OFF

(make sure to fit the install prefix path accordingly, if you didn’t clone to ~/src) where we disable Geant4 support.

Now just make it:

make install

(feel free to add -j32 or whatever, but the library is small).

This should have generated (among others) a libmcpl.so inside of the build directory.

Place this wherever appropriate on your system (e.g. /usr/local/lib or /opt/lib or whatever you may use). Alternatively, tell your system where to find additional shared libraries by adding a foo.conf file to /etc/ld.so.conf.d/foo.conf with the full path to the directory (make sure to run a ldconfig after adding such a path!).

If you don’t want to do either of these things, just make sure to run any program using mcpl with:

LD_LIBRARY_PATH=/path/to/libmcpl.so ./the_mcpl_using_binary

Install the Nim library

The Nim library is simply installed via:

nimble install https://github.com/SciNim/mcpl

Example

Consider the example examples/read_example.nim. Compile it:

nim c examples/read_example.nim

which is a straight Nim port of the same C example: https://github.com/mctools/mcpl/blob/master/examples/rawexample_readmcpl.c

and now feed it the examples/example.mcpl file:

examples/read_example examples/example.mcpl