MCPL hooks in McStas

• How to use the components
  • MCPL_input
  • MCPL_output
• Notes for users of McStas version 2.3
• Notes for users running in special environments
• Notes for ESS users of McStas and MCPL

MCPL input or output from McStas is handled via two components, MCPL_input and MCPL_output, which users can activate by adding entries at relevant points in their instrument files. Please refer to the MCPL paper (section 3.3) for a more detailed discussion of these.

Users of McStas do not need to download MCPL themselves, as it is included inside McStas already since version 2.3 (but note that McStas 2.3 users need to update their components as explained here). In addition to the MCPL_input and MCPL_output components, this also gives McStas users access to the mcpltool command.

How to use the components

MCPL_input

In its most simple form, users can add the following lines to their instrument files in order to inject particles from an MCPL file into their instrument simulations:

COMPONENT vin = MCPL_input( filename="myfile.mcpl" )
AT(0,0,0) RELATIVE Origin

The initial position of the particles will be given by the coordinates found in the MCPL file, relative to the position of the MCPL_input component in the instrument. In the example above, the particle coordinates will thus be interpreted as being relative to the Origin component.

For further details, refer to the MCPL paper (section 3.3) and/or bring up documentation specific to the actual version of MCPL_input being used by typing:

mcdoc MCPL_input

MCPL_output

In its most simple form, users can add the following lines to their instrument files at a given point in order to capture a snapshot of particles at that point in their instrument simulations and store them in an MCPL file:

COMPONENT mcplout = MCPL_output( filename="myoutput.mcpl" )
AT(0,0,0) RELATIVE PREVIOUS

The coordinates of the stored particle will be relative to the MCPL_output component itself. Thus, the above lines captures particles relative to the previous component. This could for instance make sense if the previous component was the sample component, and you need the coordinates to be written to be relative to the sample position. If instead you need the coordinates to be absolute, you could either specify ABSOLUTE or the Origin component:

COMPONENT mcplout = MCPL_output( filename="myoutput.mcpl" )
AT(0,0,0) RELATIVE ABSOLUTE

For further details, refer to the MCPL paper (section 3.3) and/or bring up documentation specific to the actual version of MCPL_output being used by typing:

mcdoc MCPL_output

Notes for users of McStas version 2.3

If you are an user of McStas version 2.3, you should download an updated version of the component you will be using and place it in your run directory:

• MCPL_input.comp
• MCPL_output.comp

This is because several important issues were identified and fixed in the component codes after the release (in particular a nasty memory leak in MCPL_output). Users of McStas 2.4 do not need this, although a small issue (see here) remains for MCPL output, which was fixed in 2.4.1.

Notes for users running in special environments

As from release 2.3 of McStas, linking to the MCPL-library distributed with McStas is automatic when using the GUI or the utility scripts like mcrun. If neither is available, such as may be the case in an HPC-environment, library and include paths must be added to the build step. An example of this could be (assuming McStas is installed in /usr/share/mcstas/2.3):

mcstas -t MyInstrument.instr 
cc -o MyInstrument.out MyInstrument.c \
   -I/usr/share/mcstas/2.3/libs/mcpl -L/usr/share/mcstas/2.3/libs/mcpl \
   -lmcpl -lm -O2

Notes for ESS users of McStas and MCPL

If you wish to use MCPL input as an ESS source term in a McStas simulation, please consult the relevant page in the ESS Confluence.