[tkittel]

Lots of back and forth here, the issues raised in #61 are not something with a general fits-all solution.

Claude says:

Handling of stat:sum values in MCPL files (fixes #61):

• MCPLGen divides the weights by stat:sum:initial_ray_count if the input file has it. Files written by the McStas MCPL_output component with weight_mode=1 (the default since McStas 3.10) have this value, and store the weights multiplied by the number of rays. The value of the whole file is always used, also with skip_events or a limited number of events, so the results of jobs which each process a part of a file can be added up. Files without the value are used as before. Files with a value which is unavailable (-1) or not positive give an error. The new parameter normalise_by_initial_ray_count (default true) can be disabled to always use the weights as stored.
• MCPLWriter writes stat:sum:geant4_nevts (the number of simulated events) and stat:sum:initial_geant4_weights (the sum of the weights of their primary particles, in the same convention as the weights in the file) to its output files. A header comment in the output files explains them.
• The initial_ray_count convention assumes that each particle is an independent ray, which is usually not the case for files written by Geant4. So by default, MCPLWriter writes the weights as used in Geant4, and records the initial_ray_count of an MCPLGen input file as stat:sum:original_initial_ray_count (which is passed on again when such a file is used as input). With the new opt_initial_ray_count keyword of --mcpl (or setWriteInitialRayCount(True)), it instead records it as stat:sum:initial_ray_count, with the weights in the same convention as in the input file.
• Custom stat:sum values can be added to all output files, from Python with G4MCPLPlugins.MCPLWriter.addStatSum(key,value), or from C++ via the new G4MCPL/OutputStatSums.hh registry (which MCPLGen also uses to provide the values of its input file). When multiprocessing, values describing the whole job are divided between the processes, so the merged file gets the value.
• sb_mcplextra_filterfile keeps stat:sum values when filtering particles, but marks them as unavailable when only a part of the file is used due to the -l limit.
• The ExprParser exception classes now have out-of-line destructors, so exceptions thrown in one module can be caught in another on platforms comparing type information by address (Intel macOS).
• CI: added an Intel macOS (macos-15-intel) job to condatest.
• MCPL 2.2.8 or later is now required.

A new test (G4MCPLTests/testmcplstatsums) covers normalisation, partial reading, multiprocessing, unavailable and invalid values, the opt_initial_ray_count keyword, reading output files again, custom values, and sb_mcplextra_filterfile. The reference logs of testmcplgen and testmcplwrite are updated. The documentation of the MCPL support is updated.

assisted-by: claude