muonic_xray_dataset/README.md

Muonic X-ray Dataset

This repository contains the packaged pre-publication preview dataset:

• states.parquet — repaired exact muonic state energies.
• transitions.parquet — complete MOCCA radiative transition table.
• states.atlas.pdf — interfamily energy atlas used for visual inspection of the state energies.
• LICENSE.md — custom pre-publication preview terms.
• README.md — this description.

The transition table contains 73,622,816 radiative transition rows for 3,082 isotopes. It is complete in the practical sense used by this workflow: all radiative lines emitted by MOCCA for the supplied isotope/state table with n_max = 20, zero output intensity threshold, and the model settings described below.

Status and Use

Copyright (c) 2026 Michael W. Heiss.

Affiliation: Paul Scherrer Institute, Villigen PSI, Switzerland.

This is a pre-publication research dataset / preview release. It is made available for inspection, testing, and scientific evaluation, but is not yet released for production use, redistribution, substantial extraction, or incorporation into downstream reference databases.

A citable publication and stable data release are planned. Until then, please contact the author before using this dataset in published, production, engineering, or reference-data contexts. See LICENSE.md for the full pre-publication preview terms.

Software

The dataset was generated in two stages using two separate codes.

MuDirac (Sturniolo & Hillier, 2020; https://github.com/muon-spectroscopy-computational-project/mudirac) solves the Dirac equation for muonic atoms. It provides the relativistic bound-state energies used as the sole source of level energies for this dataset. Note that the energies were computed with a custom, patched version of MuDirac (see below); the patches will be submitted to the upstream repository in the near future.

MOCCA (Muon Cascade Code, written by Michael W. Heiss, Paul Scherrer Institut; michael.heiss@psi.ch) is the cascade simulation code. It is a complete C++ rewrite of the original muonic atom cascade program by Akylas & Vogel (1978), with significant changes to the transition-rate formulas, matrix-element precision, and cascade propagation logic. MOCCA uses the exact state energies from MuDirac as input and computes the radiative transition energies, rates, and line intensities. It will be made publicly available as open source in the near future.

This dataset builds on the upstream software, physical models, and reference data sources cited below. The upstream authors and data providers are not responsible for the repaired state table, MOCCA cascade settings, transition intensities, file layout, or any errors in this preview release.

Patched MuDirac Code

The custom MuDirac branch used for the state-energy production was based on MuDirac 1.2.1 and extended mainly to make complete, auditable all-state runs practical:

• A state-only execution path was added. The new state_max_n and states inputs make MuDirac compute requested bound states directly, write a .states.out table with n, l, s, binding energy, total energy, and per-state error messages, and optionally run independent state jobs in parallel.
• The state solver was hardened for difficult high-n cases. The patched C++ code preserves structured convergence errors, catches turning-point failures, supports seeded starting energies from previous .states.out files, can apply explicit binding-energy windows, and can tighten searches with same-shell trend brackets and wrong-basin deflection retries.
• Several numerical guardrails and small physics-input fixes were added: configurable inner/outer radial-grid tolerances, validation of potential-grid array sizes, corrected electronic-background grid boundary defaults, fallback handling for missing isotope radii, and a fallback for inconsistent light-nucleus FERMI2 radius/thickness combinations.
• High-n state labels were supported by extending MuDirac's shell-letter notation beyond the conventional X-ray shells, so all states through n = 20 can be represented unambiguously in the output tables.

The same branch also contains Python workflow utilities for running element/isotope batches, retrying failed states with targeted settings, plotting energy-atlas diagnostics, and exporting workflow tables. Those utilities orchestrate and audit the production run; the state energies in this dataset come from the patched C++ solver output, followed by the post-processing described below.

MuDirac Level Energies

MuDirac was run for every isotope present in the dataset, computing all bound Dirac states through n = 20. The base physics settings used were:

state_max_n:        20
state_print_precision: 3
output:             1
nuclear_model:      FERMI2       (Fermi two-parameter charge distribution)
uehling_correction: TRUE          (vacuum-polarization correction)

The electronic background was set by the workflow to the Z-1 element label (neutral atom one element below) when available.

The resulting all-state table contains every Dirac state branch through n = 20: l = 0..n-1, with the relativistic fine-structure branch encoded as s. For l = 0 only s = 1 exists; for l > 0, s = 0 corresponds to j = l - 1/2 and s = 1 corresponds to j = l + 1/2. This gives n^2 state rows per isotope, or 400 rows per isotope at n_max = 20.

The key MuDirac model choices are:

• Relativistic bound-state energies from the Dirac equation, not a non-relativistic approximation.
• Fermi two-parameter finite nuclear charge distribution (FERMI2).
• Uehling vacuum-polarization correction enabled.
• Isotope-specific Z, A, lifetime, abundance, and nuclear parameters.

Post-Processing: State-Energy Repair

The raw MuDirac all-state table was visually and algorithmically checked before building the final transition dataset. Most rows are direct MuDirac results. Rows with clear convergence or pathology issues were replaced or modelled before running MOCCA.

The final repaired exact-state parquet (states.parquet) has 1,232,800 rows with columns:

Z, A, lifetime, abundance, state, n, l, s, energy_ev, error_ev

Two repair layers were applied:

1. Sanitizer pre-pass. A MuDirac state-energy sanitizer catches gross wrong-n convergence failures, especially collapsed fine-structure branches where one (n,l,s) branch lands on a neighboring shell. It also repairs high-error same-shell outliers and obvious adjacent-n trend breaks when local branch fits support the replacement.

2. Low-Z/high-n repair. MuDirac high-n states become numerically unstable at low Z. Full-shell replacement is used for He from n = 12, Li from n = 14, Be from n = 15, B from n = 17, C from n = 18, and N from n = 19. Oxygen uses only sparse exception repairs. The full-shell model is element-level: it uses trusted lower-n shells across all isotopes of the element, enforces an n^2-scaled backbone, uses an empirical l-shape, ties the two fine-structure branches at the same (n,l) to the same energy, applies a small isotope anchor scale, and calibrates selected n = 20 endpoints to the visually accepted scale.

Sparse repairs are used for manually flagged or warning-valued rows outside the full modeled shells. They use a same-n, same-s quadratic fit over l. For Z >= 9 the fit excludes l = 0,1,2; for lighter elements it excludes only l = 0.

The error_ev convention is:

• error_ev = 0 — state taken directly from MuDirac with no repair.
• Sanitizer repairs set error_ev to at least the absolute correction size, or retain the larger pre-existing input error.
• Full-shell and sparse shell-fit replacements set error_ev from the robust fit scatter, with a floor of 0.05 eV; full-shell extrapolations also include a small distance factor for farther high-n shells.
• error_ev is a bookkeeping uncertainty for repaired/extrapolated state energies. It is not a detector resolution and should not be interpreted as a full physical uncertainty budget.

The interfamily atlas used to visually inspect the state energies is states.atlas.pdf.

MOCCA Cascade Settings

The final transition parquet was generated with the following MOCCA settings:

• Isotope selection: all isotopes present in the repaired exact-state parquet.
• Cascade limit: n_max = 20.
• Initial capture population: statistical_l. The incoming muon is distributed across orbital angular momentum states proportional to degeneracy, i.e., pl[l] ∝ (2l+1).
• Capture alpha: 0.0. An exponential bias factor that modifies the capture distribution as pl[l] ∝ (2l+1) × exp(α × l). A value of 0.0 means no bias — a pure statistical distribution.
• Radiative line threshold: 0.0 (MOCCA does not cut lines by intensity).
• Radiative multipoles exported: DIP, QUA, OCT, mapped to E1, E2, E3.
• E2/E3 rate correction coefficients: defaults [0, 1, 0]; no empirical E2/E3 rate correction applied.
• Matrix-element precision: 120 decimal digits.
• Factorial divider: 15.0. A scaling factor used in the radiative matrix-element summations to distribute factorial terms across recursive steps, preventing overflow during high-precision arithmetic. The value 15.0 is the default from the original Akylas & Vogel cascade code.
• Mass constants: muon_electron_masses = 206.7682827, electron_mass_ev = 510998.95069, nucleon_mass_mev = 931.49410372.

The already-sanitized exact-state parquet is supplied directly to MOCCA — all state-energy repairs are already embedded in the input.

Electronic Shell Inputs

MOCCA requires electronic shell inputs for the cascade calculation. The shell binding-energy slots are mapped to K, L1, M1. Shell edges are resolved from NIST FFAST and X-ray Transition Energy databases, supplemented by the Fricke et al. (1977) superheavy shell data for Z > 92.

The tauscher_static effective shell-charge model was used. This model is based on the effective shell-charge approach described by Tauscher et al. (Ref. 4). MuDirac uses a more detailed screening model based on the same approach, incorporating additional electron shells. MOCCA's version is simplified to the three shells required by the cascade calculation (K, L1, M1) and uses the following formulas:

ZK* = max(Z - 1, 1)
ZL* = max(Z - 1 - NK, 1)
ZM* = max(Z - 1 - NK - NL, 1)

where NK = 2 × pop(1s) and NL = 2 × pop(2s) + 6 × pop(2p). For Z <= 30, explicit neutral occupations are used for the first K/L/M subshells; for Z > 30, the subshells are treated as fully occupied.

Output Schema

The transition parquet (transitions.parquet) has one row per MOCCA-emitted radiative line:

Column	Meaning
Z	Atomic number.
A	Mass number.
lifetime	Isotope lifetime from the exact-state table. Stable isotopes are stored as infinite.
abundance	Isotopic abundance from the exact-state table.
transition_type	Radiative multipole: E1, E2, or E3.
upper_state	State label of the upper transition endpoint.
upper_n, upper_l, upper_s	Quantum labels of the upper endpoint.
lower_state	State label of the lower transition endpoint.
lower_n, lower_l, lower_s	Quantum labels of the lower endpoint.
transition_energy_ev	MOCCA line energy in eV, computed from the injected exact state energies.
transition_error_ev	sqrt(error_upper² + error_lower²) from the state-energy table.
intensity	MOCCA cascade intensity for this radiative line.

The intensities are model cascade intensities per captured muon. They are not experimental detector yields, and should be interpreted together with the relative capture probability, self-absorption effects, efficiency-corrections, etc.

Practical Caveats

This table is complete only within the supplied state grid and MOCCA model: n ≤ 20, radiative E1/E2/E3 lines, and the configured cascade model. It does not include non-radiative Auger lines as output rows.

Rows with transition_error_ev = 0 connect two direct, unrepaired MuDirac states. Nonzero transition errors indicate that at least one endpoint was repaired or extrapolated. For low-Z high-n states, the repaired values are deliberately smooth, physically constrained extrapolations rather than additional MuDirac convergences. They preserve the visually confirmed energy behavior and avoid known wrong-branch convergence artifacts in the raw high-n input.

References

1. S. Sturniolo and A. Hillier, "MuDirac: A Dirac equation solver for elemental analysis with muonic X-rays," X-Ray Spectrometry 49(5), 450–466 (2020). https://doi.org/10.1002/xrs.3212

2. V. R. Akylas and P. Vogel, "Muonic atom cascade program," Computer Physics Communications 15(3-4), 291–302 (1978). https://doi.org/10.1016/0010-4655(78)90099-1

3. MOCCA (Muon Cascade Code), by Michael W. Heiss, Paul Scherrer Institut, Villigen PSI, Switzerland (michael.heiss@psi.ch). Based on the cascade code by Akylas & Vogel (1978), Ref. 2.

4. L. Tauscher, G. Backenstoss, K. Fransson, H. Koch, A. Nilsson, J. De Raedt, "Precision measurement of the muonic 5-4 transitions in Pb and 4-3 transitions in Ba as a test for the validity of QED," Zeitschrift für Physik A: Atoms and Nuclei 285, 139–158 (1978). https://doi.org/10.1007/BF01408741