nucl-parquet

Nuclear data as Parquet files — cross-sections, stopping powers, decay data, and isotopic abundances from all major evaluated libraries. Queryable with DuckDB, Polars, Pandas, or any Arrow-compatible tool.

Installation

pip install nucl-parquet

The pip package is a thin loader (~50 KB). Data files are either cloned from the git repo or downloaded from GitHub Releases:

import nucl_parquet

# Download the latest data tarball to ~/.nucl-parquet/ (first time only)
nucl_parquet.download()

# Or pin a specific CalVer release
nucl_parquet.download(data_version="2026.05.11")

# Inspect which data version a checkout pins
nucl_parquet.data_version()  # → "2026.05.11"

Or clone the repo directly for the full dataset:

git clone https://github.com/exoma-ch/nucl-parquet.git
export NUCL_PARQUET_DATA=/path/to/nucl-parquet/data

Release scheme — data on CalVer, code on semver

Data tarballs and code packages release on independent cadences. Data refreshes when upstream sources (NIST/Geant4/strata) update — tracked as data-YYYY.MM.DD tags on GitHub. Code releases follow conventional-commit semver via release-please as vX.Y.Z tags. The active data version a checkout pins lives at data/catalog.json::data_version.

Per-package code semver (split MCP from core, etc.) is tracked in #150.

Verifying a data release

Data releases from data-2026.8.2 onward are signed with minisign; the signature ships as nucl-parquet-data-<CalVer>.tar.zst.minisig on the GitHub release.

just verify-release              # verify the version in data/catalog.json
just verify-release 2026.8.2     # verify a specific CalVer

Releases from data-2026.8.3 also carry a signed content manifest (*.manifest.json + .minisig) listing every file's SHA-256. Content-scanning gateways at air-gapped sites repack archives, which breaks the tarball signature while leaving the data intact — the manifest still verifies, and makes a partial transfer checkable too:

just verify-extracted /path/to/extracted 2026.8.3 --partial

The data_sha256 pin and the signature answer different questions — "are these the bytes that build was tested against?" versus "did these bytes come from the nuclear-data team?". Only the second survives re-pinning, since GitHub's asset digest is only as trustworthy as the account. The public key consumers pin, the grandfathering rule for older unsigned releases, and the rotation runbook are in docs/security/data-signing.md.

Usage

import nucl_parquet

db = nucl_parquet.connect()

# Cross-section query
db.sql("SELECT * FROM tendl_2023_iso WHERE target_A=63 AND residual_Z=30")

# Compare all libraries
db.sql("SELECT library, energy_MeV, xs_mb FROM xs WHERE target_A=63 AND residual_Z=30")

# Decay chain
db.sql(nucl_parquet.DECAY_CHAIN_SQL, params={"parent_z": 92, "parent_a": 238})

# Stopping power — light ions (NIST PSTAR/ASTAR/ESTAR; catima for ³He)
nucl_parquet.elemental_dedx(db, "p", 29, 10.0)     # protons in Cu at 10 MeV
nucl_parquet.elemental_dedx(db, "a", 29, 5.0)      # α in Cu at 5 MeV (NIST ASTAR)
nucl_parquet.elemental_dedx(db, "e", 29, 1.0)      # electrons in Cu at 1 MeV
nucl_parquet.compound_dedx(db, "p", [(29, 0.5), (30, 0.5)], 10.0)

# Stopping power — heavy ions (CatIMA, any isotope of Z=1-92)
nucl_parquet.elemental_dedx(db, "c12",  6, 12 * 100.0)   # C-12 in C at 100 MeV/u
nucl_parquet.elemental_dedx(db, "pb208", 82, 208 * 50.0)  # Pb-208 in Pb at 50 MeV/u
nucl_parquet.elemental_dedx(db, "xe132", 14, 132 * 50.0)  # Xe-132 in Si at 50 MeV/u

# Heavy-ion total reaction cross-sections (Tripathi 1997)
db.sql("SELECT * FROM hi_xs WHERE target_Z=29 ORDER BY energy_MeV")  # c12 on Cu
db.sql("""
    SELECT energy_MeV, energy_MeV/12 AS energy_MeV_u, xs_mb
    FROM hi_xs WHERE target_Z=6
""")  # c12 on C — typical carbon therapy channel

# Heavy-ion production cross-sections (Geant4 INCL++/ABLA07)
# σ(Zf, Af, E) per residual isotope — 6 projectiles × 92 targets × ~60 energies
db.sql("""
    SELECT residual_Z, residual_A, energy_MeV, xs_mb
    FROM hi_xs_prod
    WHERE target_Z=29 AND library='hi-xs-prod'
    ORDER BY residual_Z, residual_A, energy_MeV
""")  # all C-12 fragmentation products on Cu

# Nuclear structure & decay (v0.11+ — Geant4-derived from strata HF dataset)
db.sql("SELECT * FROM nuclides WHERE Z=43 AND A=99")            # Tc-99g + Tc-99m
db.sql("SELECT * FROM radiation WHERE Z=63 AND A=152 AND state=''")  # Eu-152 lines
db.sql("SELECT * FROM coincidences WHERE Z=27 AND A=60")        # Co-60 cascade pairs
db.sql("SELECT * FROM decay_detailed WHERE Z=43 AND A=99")      # per-shell EC fractions

# Photon-matter interaction (v0.12+ — Geant4 G4EMLOW8.8)
db.sql("SELECT * FROM photon_pe WHERE Z=82 AND shell=0")        # Pb K-shell σ_PE(E)
db.sql("SELECT * FROM photon_compton WHERE Z=29")               # Cu Compton σ(E)
db.sql("SELECT * FROM photon_pair WHERE Z=82 AND channel='total'")  # Pb pair σ(E)
db.sql("SELECT * FROM photon_rayleigh_cdf WHERE Z=82")          # angular sampling CDF
db.sql("SELECT * FROM atomic_relaxation WHERE Z=53 AND vacancy_shell='K'")  # I K-vacancy
db.sql("SELECT * FROM fluorescence WHERE Z=82")                 # Pb fluorescence yields

# Electron-matter interaction (v0.13+ — Geant4 G4EMLOW8.8)
db.sql("SELECT * FROM electron_brem WHERE Z=82")                # Pb bremsstrahlung σ_brem(E)

# NUDEX detailed nuclear data (v0.14+ — Geant4 G4NUDEXLIB1.0)
db.sql("SELECT * FROM nudex_levels WHERE Z=27 AND A=60")        # Co-60 full level scheme
db.sql("SELECT * FROM nudex_level_gammas WHERE Z=82 AND A=208") # Pb-208 transitions
db.sql("SELECT * FROM capture_gammas WHERE Z=27 AND A=60")      # 59Co(n,γ)60Co primaries
db.sql("SELECT * FROM icc_factors WHERE Z=82 AND shell='K'")    # Pb K-shell BrIcc
db.sql("SELECT * FROM psf_e1 WHERE Z=82 AND A=208")             # Pb-208 SMLO E1 GDR
db.sql("SELECT * FROM level_density_bfm WHERE Z=82 AND A=208")  # Pb-208 BFM params

Data resolution

connect() finds data in this order:

1. Explicit data_dir argument
2. $NUCL_PARQUET_DATA environment variable
3. Sibling repo checkout (when running from source)
4. ~/.nucl-parquet/ (downloaded via nucl_parquet.download())

Why Parquet instead of ENDF-6?

The ENDF-6 format dates from the 1960s. It was designed for Fortran on punch cards: 80-character fixed-width records, implicit column positions, and a cryptic MF/MT numbering system.

Size comparison for the same data:

Libraries included

Parquet schemas

Evaluated cross-sections ({library}/xs/*.parquet):

state is not a partition — "sum" is a sum over "g"/"m", not a peer of them. ENDF gives the channel total in MF=3 and the ground/metastable split in MF=10, so both land as rows: IRDFF-II's Al-27(n,2n) is one 177 mb "sum" row and a 114 mb "g" + 65 mb "m" pair. GROUP BY residual_Z, residual_A with SUM(xs_mb) therefore double-counts. Filter state = 'sum' for totals, or state <> 'sum' for the split.

The join invariant. state is the third component of nuclide identity, so it is a join key against nuclides:

SELECT * FROM xs JOIN nuclides USING (Z, A, state)

"g", "m", "m2", "m3" name a nuclide state and join. "sum" names no state and joins nothing — it is an aggregate over the very rows it would otherwise match, so a "sum" row that comes back carrying a half-life has silently been given the ground state's. "l" (an isomer, unresolved which) and NULL join nothing either.

"" is retired from the cross-section tables, where it meant "summed over states" (ENDF) or "not stated" (EXFOR) with nothing to tell those apart.

The join works once the catalogue migration is run. nuclides still spells the ground state "" on disk, so today the join misses every real ground-state row. The fix is written and tested — scripts/migrate_state_vocabulary.py --table meta/ensdf — and lands with the next data release, because rewriting the parquets is one.

What it does, and why it is not a rename: 3,148 of the 3,161 "" rows sit at level_keV = 0.0 and become "g". The other 13 are excited levels that inherited the ground-state label because G4ENSDFSTATE does not list those nuclides' ground states at all — four of them carry ENSDF's +X floating flag, so their excitation is relative to an unknown offset. Those become NULL. Calling a 2166 keV level "the ground state" would be a plausible value under an identity nobody checked.

Until the migration runs, join nuclides on (Z, A) and filter state yourself. The ground_states view already matches both spellings, so it needs no change either side of it.

The vocabulary itself lives in nucl_parquet/state_vocabulary.py, which every builder imports, and tests/test_state_vocabulary.py enforces it per table.

kind is not a partition either. production rows are our sum over every channel reaching a residual (MT null); channel rows are one ENDF MT (MT set). Both describe the same evaluation, so always filter one or the other:

-- what produces Fe-55?
SELECT * FROM xs WHERE kind='production' AND residual_Z=26 AND residual_A=55
-- what is U-235 fission?
SELECT * FROM xs WHERE kind='channel' AND MT=18 AND target_Z=92 AND target_A=235

Channels that name no single product — total (MT=1), elastic (2), inelastic (4), fission (18) — carry residual_Z/residual_A as NULL, not 0. WHERE residual_Z IS NULL is the query for them.

Within kind='channel', ENDF's own redundancy applies: MT=1 already contains MT=2, MT=4 contains MT=51–91, MT=18 contains MT=19–21. The endf_mt view says which MTs are sums and what they sum over, so summing is checkable rather than folklore:

SELECT * FROM xs JOIN endf_mt USING (MT)
WHERE kind='channel' AND NOT endf_mt.redundant AND NOT endf_mt.particle_production

endf_mt is built from nucl_parquet/endf_mt.py, not from a parquet — it is available on a plain checkout with no data download.

EXFOR experimental (exfor/*.parquet):

Stopping powers (stopping/{source}.parquet — one file per source):

Files: PSTAR.parquet, ASTAR.parquet, ESTAR.parquet, dSTAR.parquet, tSTAR.parquet, and the federated CaTiMA heavy-ion shards catima_<Sym><A>.parquet — one per beam isotope (≈399 files spanning every Z=1–99 isotope in the inventory, each covering all 92 targets), build-generated by build_heavy_ions.py. Each shard carries both energy_MeV_u (per-nucleon) and energy_MeV (total) so it is queryable as an isotope table or as a NIST-style source. The former single 92×92 monolith was removed in favour of the shards (#252).

PSTAR and ASTAR are reproducible from NIST CGI via uv run python -m nucl_parquet.build_stopping. ESTAR is rebuilt from the strata-data em/estar_long.parquet upstream via uv run python -m nucl_parquet.build_em_stopping (which also emits the richer stopping/em/electron_stopping.parquet and stopping/em/density_effect_params.parquet; see "Electron-matter tables" below). dSTAR and tSTAR are velocity-scaled from PSTAR (exact, same Z=1, just relabel energy axis) by build_light_ions.py. ³He has no published NIST table; α and ³He earlier shipped via wrong-by-4× files that have been removed (#137) — α now uses NIST ASTAR (ICRU-49 reference), ³He uses CaTiMA. NIST PSTAR/ASTAR only publish 25 elemental targets; for elements outside that list (e.g. Tc, Pm, Po, Rn), elemental_dedx() falls back to CaTiMA (Bethe-Bloch), which covers all Z=1–92.

Heavy-ion total reaction cross-sections (hi-xs/xs/{proj}_{target}.parquet):

Tripathi (1997) semi-empirical parameterization — total reaction cross-sections for all 12 projectiles against all 92 target elements. Energy stored as total MeV for the projectile; 1–1000 MeV/u range, 60 log-spaced points.

Heavy-ion production cross-sections (hi-xs-prod/xs/{proj}_{target}.parquet):

Geant4 11.3.2 FTFP_INCLXX physics list (INCL++ cascade + ABLA07 de-excitation) — per-isotope fragment production cross-sections σ(Zf,Af,E) in mb, normalized to Tripathi (1997) σ_R. Covers C-12, O-16, Ne-20, Si-28, Ar-40, Fe-56 projectiles against all 92 target elements, ~60 log-spaced energy points from 1–1000 MeV/u.

Heavy-ion stopping powers (stopping/catima.parquet):

Full 92×92 matrix — all projectile elements Z=1–92 against all target elements Z=1–92, computed with CatIMA. Energy stored in MeV/u; isotope-independent (divide total MeV by A to look up).

Nuclear structure & decay (v0.11+, Geant4-derived)

Sourced from the strata project's HuggingFace dataset, which republishes G4ENSDFSTATE3.0 + PhotonEvaporation6.1.2 + RadioactiveDecay6.1.2 as Parquet. Replaces the v0.10.x IAEA-LiveChart pipeline; six bug classes eliminated by construction (see ADR-0002). Stable isotopes ship half_life_s = +inf (use is_finite(half_life_s) to test).

Photon-matter interaction (v0.12+, G4EMLOW8.8)

Per-process cross-sections + sampling kernels for "photon hits material" queries. Lets users break down xcom's integrated µ/ρ into the dominant processes (PE / Compton / Rayleigh / pair / atomic relaxation). All views live under data/em/; epic #95.

Worked example — "what fraction of 511 keV photons in lead Compton-scatter vs photoelectric-absorb?"

WITH pe_total AS (
    SELECT Z, energy_MeV, SUM(sigma_b) AS sigma_pe
      FROM photon_pe
     WHERE Z = 82 AND ABS(energy_MeV - 0.511) < 1e-3
     GROUP BY Z, energy_MeV
)
SELECT 'PE' AS process, sigma_pe AS sigma_b FROM pe_total
UNION ALL
SELECT 'Compton', sigma_b FROM photon_compton
 WHERE Z = 82 AND ABS(energy_MeV - 0.511) < 1e-3;

Electron-matter interaction (v0.13+, G4EMLOW8.8)

Per-process electron transport cross-sections — companion to the v0.12 photon-matter views. Epic #114 tracks the full electron-matter rollout (bremsstrahlung shipped; Seltzer-Berger DCS, MSC, DPWA, ESTAR migration in progress).

Detailed nuclear data — NUDEX (v0.14+, G4NUDEXLIB1.0)

Where nuclides / radiation / coincidences ship the summary G4 PhotonEvaporation tables, the NUDEX views below import the fully-detailed ENSDF source — every known nuclear level, every measured gamma transition, full BrIcc internal-conversion tables, neutron-capture primary spectra, photon strength functions, and statistical-model level density parameters. Epic #115 (5/5 sub-issues complete).

Schema overlap with v0.11: nudex_levels and ensdf_levels coexist by design. Use ensdf_levels for transport-aligned queries (matches G4's bundled level set); use nudex_levels for high-fidelity gamma spectroscopy and statistical decay calculations.

Worked example — "predict the prompt-gamma signature of a neutron-irradiated Co-59 sample"

SELECT energy_keV, intensity_pct
  FROM capture_gammas
 WHERE Z = 27 AND A = 60 AND variant = 'default'
 ORDER BY intensity_pct DESC
 LIMIT 10;

All registered views

The complete inventory of DuckDB views registered by nucl_parquet.connect(). All views are declared in catalog.json::views — adding a new data table to the catalog makes it queryable with zero code changes across all clients (Python, TypeScript, Rust).

Regulatory limits — Swiss StSV Annex 3 (v0.18+)

Annex 3 of the Swiss Radiological Protection Ordinance (StSV, SR 814.501) as a queryable table instead of a PDF annex — 792 radionuclide entries, consolidation of 2026-07-01.

# Clearance limit (Freigrenze) for Co-60, in Bq/g
duckdb -c "SELECT nuclide_label_en, value, unit FROM 'data/stsv/limits/*.parquet'
           WHERE quantity='LL' AND nuclide_Z=27 AND nuclide_A=60"

# Everything below 1 Bq/g clearance
duckdb -c "SELECT nuclide_label_en, value FROM 'data/stsv/limits/*.parquet'
           WHERE quantity='LL' AND value < 1 ORDER BY value"

Two tables, both long (one row per nuclide × quantity):

They are split because one is Swiss law and the other is jurisdiction-neutral physics (ICRP / Petoussi et al.), with different revision cadences.

Three things the schema carries that the PDF makes easy to lose:

• value_is_upper_bound — 233 cells are written <0.001, not 0.001. The bound travels with the number rather than being flattened into a false measurement.
• chemical_form / isomer / includes_daughters — H-3 appears three times (OBT, HTO, gas) with three different licensing limits, Sb-124n carries a second isomeric state, and some entries cover a whole decay chain. Each is a different kind of claim and gets its own column; keying on (Z, A) alone silently merges them.
• source_note — the ordinance's footnote markers, recording which IAEA basis a clearance limit came from and whether daughter nuclides were folded in.

Values come from the authoritative German text; nuclide_label_en from Fedlex's official English translation, which is marked "not an official language of the Swiss Confederation". The build cross-checks every numeric cell across both languages and fails on divergence, so a non-binding translation can never move a number.

Not copyrightable subject matter: Swiss URG Art. 5(1)(a) excludes Gesetze, Verordnungen … und andere amtliche Erlasse from protection. Rebuild with python scripts/fetch_stsv.py --out data/stsv.

MCP servers

Three MCP servers expose nucl-parquet data to AI assistants:

All three read catalog.json::views for view registration and catalog.json::libraries for cross-section libraries. The Rust MCP uses the ParquetStore from the nucl-parquet client crate for zero-dependency Parquet I/O.

Development

# Install dev dependencies
uv sync --dev

# Run unit tests (no data needed)
uv run pytest tests/test_loader.py -v

# Run full test suite (requires data)
uv run pytest tests/ -v

License & data attribution

Code & conversion: MIT (see LICENSE).

Bundled nuclear data: third-party — MIT does not apply to it. Each library keeps its own terms and required citation; see ATTRIBUTION.md (machine-readable in data/licenses.toml) and the NOTICE. The data is provided as-is — see DISCLAIMER.md.