Free-form text area

Please describe what your PR is adding in terms of features or bugfixes:

MCPL_input: consolidate with MCPL_input_once (MPI slicing + repeat_count)

MCPL_input and MCPL_input_once are merged into one implementation in MCPL_input. MCPL_input_once moves to obsolete/ as DEFINE COMPONENT MCPL_input_once INHERIT MCPL_input, so existing instruments keep working.

What MCPL_input does now

• MPI: the file is split between processes as MCPL_input_once did it. Each process reads, or preloads, only its own slice, so every event is used once per repetition across the whole run.
• repeat_count: kept from the old MCPL_input. Each process replays its slice repeat_count times. Every pass after the first is smeared with v_smear / pos_smear / dir_smear. The new always_smear=1 smears the first pass too.
• Weights: scaled by (#events on the process) / (#rays on the process), which is 1/repeat_count without MPI. This also corrects for uneven slices when the event count doesn't divide by the number of processes.
• ncount: set to #events × repeat_count, independent of the number of MPI processes.

Behaviour changes

• With MPI, the run is no longer bigger. The old MCPL_input gave every process the whole file, smeared on all but the master, so --mpi=N meant N× the rays. Now it's 1×.
• Empty input is an error. An empty file, or an energy window that keeps no events, stops the run.
• repeat_count>1 with all *_smear=0: still reset to 1, but without the 10 s sleep.
• verbose: now defaults to 0, and prints the first 10 particles read.
• Cleanup moved to FINALLY. The file is closed and memory freed there instead of in SAVE, which can run mid-simulation when a signal arrives.
• MCPL_input_once (now in obsolete/): keeps all its parameters and gains repeat_count (default 1). Its parameter order now follows MCPL_input; instruments that set parameters by name are unaffected.

McXtrace

MCPL_input gets the same implementation adapted to photons (E_smear, keV, k, E-field). This fixes two bugs in the old McXtrace version:

• Without preload, |k| was computed as sqrt(E·E2K) instead of E·E2K, so energies were wrong.
• With preload, positions were divided by 100 twice.

Other changes

• ESS_butterfly_MCPL_test uses MCPL_input with repeat_count=repeat instead of the commented-out alternative.
• The Test_MCPL_input_once description is updated.

Manuals

• misc/MCPL_input.tex (McStas and McXtrace) regenerated with mcdoc --tex.
• The MCPL_input_once snippet moves from misc/ to obsolete/, regenerated. A new obsolete/MCPL_input_once_static.tex points to MCPL_input's parameters, since mcdoc does not list inherited ones.
• obsolete.tex lists and includes MCPL_input_once.
• misc.tex: the MCPL section gets a short paragraph on MPI slicing and repeat_count.
• misc/MCPL_output.tex (McStas and McXtrace) regenerated: the weight_mode default is shown as 1, following dacc4b87c.

Testing

Built from source on Linux with OpenMPI, comparing the old and new components on the same input. "Old" means the previous MCPL_input.

• repeat_count=1, serial, preload 0 and 1: new, old, new-once and old-once give identical results (m1 I=2.27516e11, N=1000).
• repeat_count=1 with MPI:
  • --mpi=2: identical to the serial run. The old MCPL_input emitted 2000 rays.
  • --mpi=3: 999 rays, I=2.27488e11. The old MCPL_input_once gave 2.27252e11, losing intensity on the uneven slice.
• repeat_count=3, serial and MPI 2/3: the total intensity on an all-accepting time monitor is preserved.
• ESS_BEER_MCPL (repeat_count=50), 10 seeds: new 150.7 ± 0.9, old 150.5 ± 0.5.
• McXtrace round trip (Source_flat → MCPL_output → MCPL_input): the new component reproduces the source's mean energy of 9.9917 keV serial and with MPI 2/3, preload 0 and 1. The old one without preload put nothing on the energy monitor.
• mctest, --comp MCPL_input and --comp MCPL_input_once: no wrong values.
• Manual snippets: the committed .tex files are byte-identical to mcdoc --tex output from the current components.

Not tested

• OpenACC/GPU. That path always preloads and picks events by _uid, as MCPL_input_once already did.
• The mcstas-antlr code generator. Whole-component INHERIT is already used by Diaphragm.
• Running ESS_butterfly_MCPL_test, whose input file is downloaded at build time ([CI/repo]: Use GitHub LFS / cache to make MCPL-input for ESS instrument available #2628). It does generate and compile.
• Building the manual PDF; the .tex changes are not compiled.

Notes

• The %Example reference values look stale. Test_MCPL_input and Test_MCPL_input_once reach 94% of reference, and ESS_BEER_MCPL 110%, with both the old and new components.

Declaration of use of AI-tools

• Please add a checkmark here if you used AI-tools during the work for this contribution
• Furter, please describe how / where and for what the tools were used:

^ 🤖 Generated with Claude Code

Development OS / boundary conditions

Please describe what OS you developed and tested your additions on, and if any special dependencies are required:

PR Checklist for contributing to McStas/McXtrace

For a coherent and useful contribution to McStas/McXtrace, please fill in relevant parts of the checklist:

• My contribution includes patches to an existing component file

  • I have used the mcdoc utility and rendered a reasonable documentation page for the component (please attach as screenshot in comments!)
  • I have ensured that basic use of the component is OK (e.g. an instrument using it compiles?)
  • I have used the mctest utility to test one or more instruments making use of the component (please attach mcviewtest report as screenshot in comments)
  • I have used the mccode-clangformat tool to apply the standard McCode component indentation scheme
  • I have used the mcrun --c-lint "linter" and followed advice to remove most / all warnings that are raised

• My contribution contains something else

  • Explanation is added in free form text above or below the checklist