The `MCPL_input` Component

Source-like component that reads photon state parameters from an mcpl-file.

Identification

Author: Erik B Knudsen, Gregory S Tucker and Peter Willendrup
Origin: DTU Physics / European Spallation Source ERIC
Date: Aug 2016, consolidated with McStas MCPL_input_once Oct 2026

Description

Source-like component that reads photon state parameters from a binary mcpl-file.

MCPL is short for Monte Carlo Particle List, and is a format for sharing events
between e.g. MCNP(X), Geant4 and McXtrace.

The --ncount given on the commandline is overwritten by
(#particles in the file) x repeat_count. Particles that are not photons, or are
outside [Emin, Emax], are counted but ABSORBed.

The rays form a stream that runs through the file repeat_count times. As in McStas'
KDSource, this stream is split into one contiguous chunk per MPI process: each process
seeks once to its start and reads on, wrapping around to the start of the file (with
preload=1 it loads only the part of the file its chunk covers). Every event is thus used
repeat_count times across the whole run, and its weight is divided by repeat_count.
All passes after the first are smeared using E_smear, pos_smear and dir_smear (the first
pass is too if always_smear is set), so repeat_count > 1 MUST be combined with at least
one *_smear option; if all are 0, repeat_count is reset to 1.

With replicate_across_processes=0 (the default) the file is shared between the
MPI processes and --mpi=N does not change the number of rays.
replicate_across_processes=1 restores the pre-Oct 2026 MPI behaviour: repeat_count is
rounded up to a multiple of the number of MPI processes, so that every process runs
through the whole file at least once, and all but the first pass on the master are
smeared (or, with all *_smear=0, are identical copies).

This is the same implementation as McStas' MCPL_input, adapted to photons.

Example: MCPL_input(filename=voutput,verbose=1,repeat_count=1,E_smear=0.1,pos_smear=0.001,dir_smear=0.01)

Input parameters

Parameters in boldface are required; the others are optional.

Name	Unit	Description	Default
filename	str	Name of photon mcpl file to read	0
polarisationuse		If !=0 read polarisation vectors from file	1
verbose		Print debugging information for the first 10 photons read (on the master process)	0
Emin	keV	Lower energy bound. Particles found in the MCPL-file below the limit are skipped	0
Emax	keV	Upper energy bound. Particles found in the MCPL-file above the limit are skipped	FLT_MAX
repeat_count	1	Replay the contents of the MCPL file this number of times, dividing the event weights by the same number. MUST be combined with _smear options!	1
E_smear	1	When replaying events, make a flat MC choice within E_smear*E around particle energy E	0
pos_smear	m	When replaying events, make a flat MC choice of position within pos_smear around particle starting position	0
dir_smear	deg	When replaying events, make an MC choice of direction within dir_smear around particle direction	0
preload		Load particles during INITIALIZE. On GPU preload is forced	0
always_smear		If !=0, also smear the events on their first pass through the file	0
replicate_across_processes		If !=0, with MPI round repeat_count up to a multiple of the number of processes, so that each process runs through the whole file	0

AT (	,	,		) RELATIVE
ROTATED (	,	,		) RELATIVE

McXtrace - An X-ray ray-trace simulation package

The MCPL_input Component

Identification

Description

Input parameters

Links

The `MCPL_input` Component