Muon Collider Plotting

mucoll-plotting streams reconstructed muon-collider events from EDM4hep ROOT files and produces comparison plots for Monte Carlo particles, tracks, calorimeter clusters, and particle-flow objects (PFOs). It uses Uproot and Awkward Array so large samples can be processed in batches instead of loaded entirely into memory.

Workflows

Two workflows are available:

• overlay compares MC particles, tracks, clusters, and PFOs. It plots object multiplicity, angles, energy and transverse momentum, plus thrust and sphericity-tensor event shapes.
• track_analysis plots track holes, hits, degrees of freedom, chi-squared, and reduced chi-squared.

The overlay workflow treats stable MC particles as generator status 1, can remove all neutrinos, treats clusters as massless objects pointing from the origin, and uses a massless approximation for track four-momenta.

Event-shape code attribution

The thrust implementation is adapted from the Rivet 1.1.3 Thrust implementation, authored by Andy Buckley. That source also credits Stefan Gieseke's Herwig++ recoding of the HERWIG tasso code as the basis of the Rivet implementation.

The linearized 3D sphericity tensor and the aplanarity, C-parameter, and D-parameter calculations are adapted from the Rivet analysis ATLAS_2020_I1808726, authored by Javier Llorente and Deepak Kar.

Setup

From this directory, create a virtual environment and install the pinned dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

The input directory must contain one or more reconstruction .root files with an events tree and the EDM4hep collections used by the readers under plotting/readers/. These files can be produced with the MuonColliderSoft mucoll-benchmarks chain driven by mucoll-slurm.

Edit the Oscar and laptop path blocks near the top of run_plots.py. The script uses the Oscar paths when OSCAR_DATA_DIR exists and otherwise uses the laptop paths.

Run interactively

Run all configurations in CONFIGS:

python run_plots.py

On Oscar, first request an interactive worker node; do not run a full plotting job on a login node. If mucoll-slurm is checked out beside this repository, its interactive helper can be used:

source ../mucoll-slurm/scripts/interact.sh
python run_plots.py

The current script runs the barrel configuration followed by the barrel-plus-endcap configuration. Each configuration runs its workflows in the listed order. Interactive output is written to the terminal; log files are created only for Slurm batch jobs.

Configuration

Configuration lives directly in run_plots.py.

COMMON_CONFIG contains settings shared by every angular acceptance. BARREL_CONFIG and BARREL_ENDCAP_CONFIG add only their output directory, job identifier, and polar-angle bounds:

BARREL_CONFIG = {
    **COMMON_CONFIG,
    "output_dir": str(OUTPUT_ROOT / "barrel"),
    "job_id": "bib_full_B",
    "min_theta": 40,
    "max_theta": 140,
}

BARREL_ENDCAP_CONFIG = {
    **COMMON_CONFIG,
    "output_dir": str(OUTPUT_ROOT / "barrel-endcap"),
    "job_id": "bib_full_BE",
    "min_theta": 10,
    "max_theta": 170,
}

CONFIGS determines which configurations run and their order. Remove an entry to disable it or append another configuration to add a new acceptance.

The configuration fields have the following meanings:

Field	Meaning
input_dir	Directory searched as *.root; each file must contain an events tree.
output_dir	Directory where PNG plots are written; it is created if needed.
job_id	Suffix added to every output filename.
step_size	Uproot batch size, such as 10 MB. This bounds memory per reader batch.
min_theta, max_theta	Inclusive polar-angle acceptance bounds in degrees.
min_obj_energy	Inclusive minimum per-object energy in GeV, or None to disable it.
min_event_energy	Inclusive minimum total selected-object energy in GeV, or None to disable it.
neutrino_cut	If True, remove MC particles with absolute PDG ID 12, 14, or 16.
track_state_location	Track state used for kinematics: interaction_point or first_hit.
track_max_holes	Inclusive maximum number of track holes, or None.
track_max_reduced_chi2	Inclusive maximum track chi-squared/NDF, or None.
track_min_hits	Inclusive minimum number of tracker hits, or None.
workflows	Ordered list containing overlay, track_analysis, or both.

Object cuts are applied first. If min_event_energy is enabled, event energy is then computed from only the objects that survived those cuts.

Outputs

The default two-acceptance run produces this layout:

OUTPUT_ROOT/
├── barrel/
├── barrel-endcap/
└── logs/                 # Slurm batch logs only

Depending on the selected workflows, each acceptance directory receives:

• event_shape_distributions_<job_id>.png
• energy_distributions_<job_id>.png
• angle_distributions_<job_id>.png
• multiplicity_<job_id>.png
• track_quality_distributions_<job_id>.png

Submit with Slurm

run_plots.sh submits one Slurm job that runs every configuration in CONFIGS sequentially:

./run_plots.sh

The launcher locates the repository automatically, reads OUTPUT_ROOT from run_plots.py, creates OUTPUT_ROOT/logs, and uses the basename of OUTPUT_ROOT in the Slurm job name. Standard output and error are written as:

OUTPUT_ROOT/logs/plots_<study>_<slurm-job-id>.out
OUTPUT_ROOT/logs/plots_<study>_<slurm-job-id>.err

Review WALLTIME, MEMORY, and CPUS near the top of run_plots.sh before submitting.

Code organization

run_plots.py                 paths, run configurations, and workflow dispatch
run_plots.sh                 Oscar Slurm submission and batch-log locations
plotting/readers/            batched ROOT branch readers
plotting/interpreters/       common kinematics and units
plotting/cuts/               object- and event-level selections
plotting/observables/        thrust and tensor event shapes
plotting/histograms/         histogram specifications and accumulation
plotting/workflows/          end-to-end analysis workflows
plotting/plotters.py         PNG rendering helpers
notebooks/                   exploratory analysis notebooks

To add a histogram, define its bins and reduction type in plotting/histograms/build.py, then include its name in the appropriate workflow. To add a workflow, expose a run(config) function and register it in WORKFLOW_MAP in run_plots.py.