create lund overview

This page is generated from docs/create-lund/index.md. Do not edit it directly; change the repository source and let automation publish the Wiki.

Create LUND files

create-lund writes LUND text files containing particles before detector simulation. You choose where those particles come from with --source:

Source	Program	Use
uniform	uniform-lund-creator	Sample deliberately unphysical momentum and angle ranges for detector-acceptance studies
physical	event-generator-to-lund-converter	Copy supported particles from existing physical event-generator truth

Both applications use the same code to read settings, sample vertex positions in the target, write LUND records, split files, name directories, and record the settings and counts. The uniform LUND creator randomly chooses momenta and angles and saves plots of them. The physical LUND converter reads those momenta from existing input; its format-specific reader, called an adapter, must not invent missing particle kinematics (momenta and angles).

For example, --event-generator genie-gst selects the physical-input adapter that reads GENIE GST events. The adapter translates their particle content; the shared LUND-writing code handles files, vertex positions, and logs.

A sample profile is a key = value configuration file describing the particles, beam, target, and sampling or conversion settings for one sample. Launcher settings and submission configuration are separate inputs. See the sample profiles before selecting a profile with --config.

Creation lifecycle

1. Read built-in defaults, an optional key = value profile, and command-line overrides.
2. Replace auto settings with their calculated values and check all settings.
3. Check the input required by the selected source before deleting output where possible.
4. Print the complete run directory. If it exists, warn, delete it and everything inside it, and recreate it.
5. Write numbered LUND files; uniform creation also saves monitoring histograms and plots.
6. Write lund-creation-log.json last, listing the settings, files, and event counts.

The LUND creation log is that final JSON file. Its presence marks completion of the program’s checked creation stages. Uniform PDF/PNG exports still need the monitoring checks. A failed run may leave partial LUND files; without the final LUND creation log, do not submit them.

Reading order

1. Choose the uniform LUND creator guide or physical LUND converter guide for the source you need.
2. Use the configuration reference to choose settings and understand their defaults.
3. For uniform samples, read monitoring to inspect the generated kinematics.
4. Use examples for additional commands.

Read the LUND data contract when inspecting records or extending the writer. Path placeholders follow the output notation.

Creating LUND files never submits detector simulation. That remains a separate ifarm submission workflow.