Atmospheric muon generator (musun-gs)

MUSUN is a Fortran code that samples single atmospheric muons underground based on muon propagation code. musun-gs is a specific version generated for the Gran Sasso underground laboratory (LNGS) fit to LVD data. The source code can be obtained by contacting the author of the above paper.

The revertex interface runs musun-gs inside a container (Docker or Shifter), parses the ASCII output, and saves the result to an LH5 file following the remage vtx specification.

Prerequisites

A pre-built container image of musun-gs must be available. Users can obtain it by pulling the image directly:

$ docker pull ghcr.io/legend-exp/musun-gs:latest

or (recommended) by pulling the image from the GitHub Container Registry (GHCR):

$ docker login ghcr.io (provide username and personal access token with read:packages scope)
$ docker pull ghcr.io/legend-exp/musun-gs:latest

When using Shifter, the container can be pulled and run with the following commands:

$ shifterimg login ghcr.io (provide username and personal access token with read:packages scope)
$ shifterimg pull ghcr.io/legend-exp/musun-gs:latest

Usage

Command line

$ revertex musun-gs \
    --out-file muons.lh5 \
    --n-events 1000000

The sampling cuboid is selected with --default-dimensions, which defaults to the musun original. Pass one of the predefined sets (original or hall_c) to use its dimensions:

$ revertex musun-gs \
    --out-file muons.lh5 \
    --n-events 5000000 \
    --seed 42 \
    --default-dimensions hall_c \
    --container-image ghcr.io/legend-exp/musun-gs:latest

When a predefined set is used, the individual --dx-cm, --dy-cm, --dz-cm and --center-*-cm options are ignored. To specify the cuboid by hand, pass --default-dimensions custom together with all six dimension options:

$ revertex musun-gs \
    --out-file muons.lh5 \
    --n-events 5000000 \
    --seed 42 \
    --default-dimensions custom \
    --dx-cm 4000 --dy-cm 2000 --dz-cm 3500 \
    --center-x-cm 0 --center-y-cm 0 --center-z-cm 0

Full option reference:

$ revertex musun-gs --help

Geometry and coordinate system

Muons are sampled on the surface of a rectangular parallelepiped (cuboid) centred at the origin. The three parameters dx_cm, dy_cm, dz_cm are the full widths of the cuboid in each direction (not half-widths).

The axes follow the LVD coordinate system used internally by musun-gs:

  • x — short side of Hall A (south-west direction)

  • y — long side of Hall A (south-east direction)

  • z — vertical (upward)

Default values of musun-gs reproduce the LNGS Hall A geometry (40 × 20 × 35 m³).

Several predefined dimension sets are available (DEFAULT_DIMENSIONS), selected with default_dimensions= (Python) or --default-dimensions (CLI). Pass custom to specify the cuboid by hand. The figures below show each predefined cuboid (orange outline, with dimension labels) overlaid on a parallel-projection view of the LEGEND-1000 geometry for scale. Each preset is shown from the front (looking along x) and from the top (looking along z).

The original musun-gs dimensions (40 × 20 × 35 m³) centered at the origin:

:::{image} images/musun_gs_sampling_original_front.png :height: 300px :::

:::{image} images/musun_gs_sampling_original_top.png :height: 300px :::

The hall_c dimensions (22.5 × 22.5 × 21.45 m³) centered at center_z_cm = 597.5 such that there are 2 m of rock above the top of the cuboid and the bottom of the cuboid is at the same height as the bottom of the LEGEND-1000 cryostat:

:::{image} images/musun_gs_sampling_hall_c_front.png :height: 300px :::

:::{image} images/musun_gs_sampling_hall_c_top.png :height: 300px :::

:::{note}

The figures are pre-rendered and committed. Regenerate them with docs/generate_docs_images.py whenever the default dimensions change. :::

Output format

The generator writes a single unified table to the LH5 file:

vtx/kin : Kinematic and position properties of each muon.

field

unit

description

ekin

keV

kinetic energy

px

keV/c

x-component of momentum

py

keV/c

y-component of momentum

pz

keV/c

z-component of momentum

time

ns

always 0

g4_pid

—

PDG code: −13 (μ⁺) or 13 (μ⁻)

n_part

—

always 1 (one muon per primary)

xloc

mm

x-coordinate of entry point on cuboid surface

yloc

mm

y-coordinate of entry point on cuboid surface

zloc

mm

z-coordinate of entry point on cuboid surface

vtx/rate : Scalar. Global muon intensity for the configured geometry as reported by musun-gs at startup, in units of (s)^-1. Useful for normalising simulation results.

Chunking and reproducibility

If more than 1 × 10⁶ muons are requested, the generator runs the container multiple times (chunks of 1 × 10⁶). Each chunk receives a different seed (seed × 7ⁱ for chunk i), following the same convention as all other revertex generators.

API reference

revertex.generators.musun_gs.generate_musun_primaries(n_muons, out_file, seed=None, *, dx_cm=4000.0, dy_cm=2000.0, dz_cm=3500.0, center_x_cm=0.0, center_y_cm=0.0, center_z_cm=0.0, default_dimensions=None, container_image='ghcr.io/legend-exp/musun-gs:latest', container_runtime=None)

Generate atmospheric muon kinematics using musun-gs and save to LH5.

Runs the musun-gs Fortran code inside a container, parses its ASCII output, and writes kinematic and position data to an LH5 file in the remage vtx format.

Generates n_muons total by running the container in chunks of up to 1,000,000 muons. Each chunk uses a different seed so the results are statistically independent.

Parameters:

  • n_muons (int) – Total number of muons to generate.

  • out_file (str) – Path to the output LH5 file.

  • seed (int | None) – Base RANLUX seed. Successive chunks multiply the seed by 7 (same convention as other revertex generators). If None, chunks use deterministic seeds 1, 2, 3, ... based on their index.

  • dx_cm (float) – Full width of the sampling cuboid along x [cm], centred at the origin. Default corresponds to the LNGS Hall A geometry (40 m).

  • dy_cm (float) – Full width of the sampling cuboid along y [cm] (default 20 m).

  • dz_cm (float) – Full height of the sampling cuboid along z [cm] (default 35 m).

  • center_x_cm (float) – x-coordinate of the cuboid center [cm] (default 0).

  • center_y_cm (float) – y-coordinate of the cuboid center [cm] (default 0).

  • center_z_cm (float) – z-coordinate of the cuboid center [cm] (default 0).

  • default_dimensions (str | None) – If not None, overrides the cuboid dimensions with a predefined set with the options defined in DEFAULT_DIMENSIONS.

  • container_image (str) – Docker/Shifter image reference.

  • container_runtime (str | None) – "docker" or "shifter". If None, the first available runtime on PATH is used.

Return type:

None