revertex.generators package¶

Submodules¶

revertex.generators.alpha_n module¶

revertex.generators.alpha_n._check_for_container_runtime_and_image(runtime, image)¶

Helper function to check if the specified container runtime and image are available.

Parameters:

runtime (str)
image (str)

Return type:

None

revertex.generators.alpha_n._detect_container_runtime(input_data)¶

Select container runtime, preferring docker and falling back to shifter.

Parameters:: input_data (dict)
Return type:: str

revertex.generators.alpha_n.calculate_integral_yield(weights, particle, n_events, decay_chain)¶

Helper function to calculate the integral neutron yield per decay of the source-chain initial isotope.

Parameters:

weights (ndarray)
particle (ndarray)
n_events (int)
decay_chain (str)

Return type:

float

revertex.generators.alpha_n.generate_alpha_n_spectrum(input_data)¶

Generate an (alpha, n) spectrum using SaG4n and save it in LH5 format.

There are several ways one can use this wrapper:

pre-prepared input_file_sag4n: The user provides a path input_file_sag4n to a valid SaG4n input file. Then only output_file has to be provided.
pre-prepared sub_material string: The user provides a sub_material string substituted into the template input file. In addition, the user has to provide source_chain and output_file.
material read from a gdml file: The user provides a gdml_file and part name for a logical volume contained in the gdml file. The script will identify the material definition of this part and automatically generate the sub_material. In addition, the user has to provide source_chain and output_file.

Additional optional input is:

n_events: Number of events to simulate in SaG4n. Default is 10 million.
seed: Random seed for the SaG4n simulation. Default is 1234567.
container_runtime: Container runtime to use (docker or shifter). If omitted, the script auto-detects (docker first, then shifter).
container_image: Name of the container image used to run SaG4n. Default is moritzneuberger/sag4n-for-revertex:latest.
output_file_sag4n: Folder and stem path of SaG4n output files (.out, .root, .log). These are usually temporary files deleted after processing.

Parameters:: input_data (dict)
Return type:: None

revertex.generators.alpha_n.generate_material_input(gdml_file, part)¶

Helper function to generate material definition for the input file.

Parameters:

gdml_file (str | Path)
part (str)

Return type:

str

revertex.generators.alpha_n.generate_sag4n_input_file(input_data)¶

Helper function to generate valid SaG4n input files. Assumes input_data already has required fields: sub_material, source_chain, output_file_sag4n. Validation is the caller’s responsibility.

Parameters:: input_data (dict)
Return type:: str

revertex.generators.alpha_n.prepare_sag4n_output_for_lh5(ak_array)¶

Helper function to format the SaG4n output to remage readable output.

Parameters:: ak_array (Array)
Return type:: Array

revertex.generators.alpha_n.read_sag4n_output(input_data)¶

Helper function to read the SaG4n output files.

Parameters:: input_data (dict)
Return type:: dict

revertex.generators.alpha_n.run_sag4n(input_data)¶

Wrapper for SaG4n.

Parameters:: input_data (dict)
Return type:: None

revertex.generators.alpha_n.save_sag4n_output_to_lh5(output_data, output_file, eunit='MeV', tunit='ns')¶

Helper function to save the SaG4n generated events and integral yield to lh5 file.

Parameters:

output_data (dict)
output_file (str | Path)
eunit (str)
tunit (str)

Return type:

None

revertex.generators.beta module¶

revertex.generators.beta.generate_beta_spectrum(size, *, energies, phase_space, seed=None, eunit='keV')¶

Generate samples from a beta spectrum defined by a list of energies and phase space values.

This function interprets the energies and phase_space as a histogram and samples energies from this. These are then converted into momenta. The energies should be the left edge of the bin of a histogram

Parameters:

energies (ArrayLike) – the energy values
spectrum – the phase space values
size (int) – number of events to generate
seed (int | None) – random seed.
eunit (str) – the unit for energy in the input file, default keV.
phase_space (ArrayLike)

Returns:

An awkward array with the sampled kinematics, in keV.

Return type:

Array

revertex.generators.beta.save_beta_spectrum(n_gen, in_file, out_file, seed=None, eunit='keV')¶

Save positions generated by the function to a file.

Parameters:

func – function which generates the positions, must return an ak.Array of positions.
n_gen (int) – number of positions to generate
in_file (str) – path to the CSV theory file.
out_file (str) – path to the output file.
seed (int | None) – random seed, for each chunk will be multiplied by 7.
lunit – The length unit returned by the function.
**kwargs – keyword arguments to be passed to the function.
eunit (str)

Return type:

None

revertex.generators.borehole module¶

revertex.generators.borehole._sample_hpge_borehole_impl(size, hpge, seed=None)¶

Generate events on the surface of a single HPGe.

Parameters:

n – number of vertexs to generate.
hpge (pygeomhpges.HPGe) – pygeomhpges object describing the detector geometry.
surface_type – Which surface to generate events on either nplus, pplus, passive or None (generate on all surfaces).
seed (int | None) – seed for random number generator.
size (int)

Returns:

Array with shape (n,3) describing the local (x,y,z) positions for every vertex

Return type:

NDArray

revertex.generators.borehole.sample_hpge_borehole(n_tot, *, seed=None, hpges, positions)¶

Generate events on many HPGe boreholes weighting by the volume.

Parameters:

n_tot (int) – total number of events to generate
seed (int | None) – random seed for the RNG.
hpges (dict[str, pygeomhpges.HPGe] | pygeomhpges.HPGe) – List of pygeomhpges.HPGe objects.
positions (dict[str, ArrayLike] | ArrayLike) – List of the origin position of each HPGe.

Returns:

Array of global coordinates.

Return type:

NDArray

revertex.generators.musun_gs module¶

revertex.generators.musun_gs._check_image(runtime, image)¶

Parameters:

runtime (str)
image (str)

Return type:

None

revertex.generators.musun_gs._detect_runtime(requested)¶

Parameters:: requested (str | None)
Return type:: str

revertex.generators.musun_gs._parse_global_intensity(log_text)¶

Parameters:: log_text (str)
Return type:: float | None

revertex.generators.musun_gs._parse_output(path)¶

Parse musun-gs ASCII output into kinematic and position ak.Arrays.

Output columns: muon_num id_part energy_GeV x_cm y_cm z_cm mx my mz id_part: GEANT3 (10 = mu+, 11 = mu-)

Parameters:: path (Path)
Return type:: tuple[Array, Array]

revertex.generators.musun_gs._run_container(n_muons, seed, dx_cm, dy_cm, dz_cm, center_x_cm, center_y_cm, center_z_cm, runtime, image)¶

Parameters:

n_muons (int)
seed (int)
dx_cm (float)
dy_cm (float)
dz_cm (float)
center_x_cm (float)
center_y_cm (float)
center_z_cm (float)
runtime (str)
image (str)

Return type:

tuple[Array, Array, float | None]

revertex.generators.musun_gs._write_namelist(path, n_muons, seed, dx_cm, dy_cm, dz_cm, center_x_cm, center_y_cm, center_z_cm)¶

Parameters:

path (Path)
n_muons (int)
seed (int)
dx_cm (float)
dy_cm (float)
dz_cm (float)
center_x_cm (float)
center_y_cm (float)
center_z_cm (float)

Return type:

None

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

revertex.generators.shell module¶

revertex.generators.shell._sample_hpge_shell_impl(size, hpge, surface_type, distance, seed=None)¶

Generate events on a shell around a single HPGe. This uses rejection sampling.

Parameters:

size (int) – number of vertexs to generate.
hpge (pygeomhpges.HPGe) – pygeomhpges object describing the detector geometry.
surface_type (str | None) – Which surface to generate events on either nplus, pplus, passive or None (generate on all surfaces).
distance (float) – Size of the hpge shell to generate in.
seed (int | None) – seed for random number generator.

Returns:

Array with shape (n,3) describing the local (x,y,z) positions for every vertex

Return type:

NDArray

revertex.generators.shell.sample_hpge_shell(n_tot, *, seed=None, hpges, positions, distance, surface_type=None)¶

Generate events on many HPGe’s shells weighting by the surface area.

Parameters:

n_tot (int) – total number of events to generate
seed (int | None) – random seed for the RNG.
hpges (dict[str, pygeomhpges.HPGe] | pygeomhpges.HPGe) – List of pygeomhpges.HPGe objects.
positions (dict[str, ArrayLike] | ArrayLike) – List of the origin position of each HPGe.
surface_type (str | None) – Which surface to generate events on either nplus, pplus, passive or None (generate on all surfaces).
distance (float)

Returns:

Array of global coordinates.

Return type:

NDArray

revertex.generators.surface module¶

revertex.generators.surface._sample_hpge_surface_impl(n, hpge, surface_type, depth=None, seed=None)¶

Generate events on the surface of a single HPGe.

Parameters:

n (int) – number of vertexs to generate.
hpge (pygeomhpges.HPGe) – pygeomhpges object describing the detector geometry.
surface_type (str | None) – Which surface to generate events on either nplus, pplus, passive or None (generate on all surfaces).
depth (rv_continuous | None) – scipy rv_continuous object describing the depth profile, if None events are generated directly on the surface.
seed (int | None) – seed for random number generator.

Returns:

Array with shape (n,3) describing the local (x,y,z) positions for every vertex

Return type:

NDArray

revertex.generators.surface.sample_hpge_surface(n_tot, seed=None, *, hpges, positions, surface_type=None)¶

Generate events on many HPGe’s weighting by the surface area.

Parameters:

n_tot (int) – total number of events to generate
hpges (dict[str, pygeomhpges.HPGe] | pygeomhpges.HPGe) – List of pygeomhpges.HPGe objects.
positions (dict[str, ArrayLike] | ArrayLike) – List of the origin position of each HPGe.
surface_type (str | None) – Which surface to generate events on either nplus, pplus, passive or None (generate on all surfaces).
seed (int | None) – seed for random number generator.

Returns:

Array of global coordinates.

Return type:

NDArray