[Tracking] Adopt libdedx as libamtrack's stopping-power & material/particle backend, and ship a nanobind Python package on PyPI

[grzanka]

Goal

Make libdedx the canonical stopping-power and material/particle database for libamtrack/library (replacing AT_StoppingPower* + AT_DataMaterial/AT_DataParticle), and at the same time turn the libdedx Python binding into a first-class, pip-installable package (pip install libdedx) built the same way as libamtrack/pyamtrack.

This epic coordinates the libdedx-side work. The libamtrack and pyamtrack halves are tracked in their own repos (see Cross-repo below).

Why now

• pyamtrack already exists and is actively developed (alpha releases through 2026), built on scikit-build-core + nanobind, cibuildwheel (auto64, CPython 3.9–3.14), numpy, setuptools_scm, vcpkg/GSL. Aligning libdedx packaging with it gives one mental model across the ecosystem.
• The libdedx C API is already rich and self-contained (embedded data, no GSL): workspace/config model, custom compounds, composition + I-value accessors, inverse STP/CSDA, convert_units (incl. keV/µm), min/max energy, program/ion/material lists. The current Python wrapper exposes only ~6 simple wrappers — so most of the library is unreachable from Python today (Expand the Python binding to cover the full C API and publish wheels #117).
• libamtrack's stopping-power/material subsystem (AT_StoppingPowerData{PSTAR,ICRU,Bethe}.c, AT_DataMaterial.c, AT_DataParticle.c) maps almost 1:1 onto libdedx (PSTAR/ASTAR/MSTAR/ICRU49/ICRU73/Bethe-ext + element/material DB), making it a natural replacement.

Architecture decision — the C API is a shared contract

Three independent consumers will bind the same libdedx C library, so dedx.h / dedx_tools.h / dedx_wrappers.h / dedx_elements.h must be treated as a stable, versioned contract before this work scales:

1. the standalone libdedx Python package (nanobind),
2. pyamtrack (its own nanobind binding — bind independently),
3. libamtrack C (full refactor, libdedx as canonical source).

Decisions taken (design discussion)

• Distribution: bundled, self-contained wheels (pip install libdedx with no C toolchain). Easy here because libdedx is self-contained → statically link it into the extension.
• Binding tech: switch from ctypes to nanobind + scikit-build-core, matching pyamtrack. (Refines Expand the Python binding to cover the full C API and publish wheels #117.)
• Python API: full "scientific" layer — generated enums, validation, numpy-first, optional pandas/matplotlib.
• Versioning: lockstep with the C library via setuptools_scm (one tag → one release).
• pyamtrack relationship: both bind libdedx C independently; share generator/casting idioms where practical.
• libamtrack refactor: full refactor adopting libdedx IDs as canonical — but executed incrementally behind a green regression suite, backend-by-backend, before old code is deleted.
• C getters: yes, add density + related material/ion accessors (Expose nucleon number, atom mass, density and is-gas in the public header #119 + electron density / ⟨Z⟩ / ⟨A⟩ / Z·A).
• Tabulated-STP-from-file parity with libamtrack's AT_StoppingPowerDataFromFile: out of scope (custom compound + Bethe is sufficient).
• PyPI name: libdedx — owner contact is available.

Workstreams / checklist

Phase 0 — C API contract (keystone)

• Expose nucleon number, atom mass, density and is-gas in the public header #119 — public dedx_get_density / nucleon / atom-mass / is-gas (existing)
• Additional public material/ion accessors required by libamtrack (electron density, mean ⟨Z⟩, ⟨A⟩, Z/A) #133 — additional accessors for libamtrack (electron density, ⟨Z⟩, ⟨A⟩, Z/A)
• Public custom-compound config builder + flat forward/inverse/peak wrappers #123 — public custom-compound config builder (existing)
• refactor: namespace public convert_units() as dedx_convert_units() #112 — namespace convert_units() → dedx_convert_units() (existing)
• bug: dedx_get_ion_list() returns a thread-unsafe function-local static buffer #113 — thread-unsafe static buffer; make library thread-safe #86 — thread safety (existing; needed for parallel consumers)
• freeze dedx.h v1 + semver/ABI policy + conformance test suite (to file once Expose nucleon number, atom mass, density and is-gas in the public header #119/Additional public material/ion accessors required by libamtrack (electron density, mean ⟨Z⟩, ⟨A⟩, Z/A) #133/Public custom-compound config builder + flat forward/inverse/peak wrappers #123 land)

Python package

• Expand the Python binding to cover the full C API and publish wheels #117 — full C-API coverage + wheels (existing; binding-tech superseded by Build the Python binding with nanobind + scikit-build-core and ship bundled wheels (binding-tech decision; refines #117) #131)
• Build the Python binding with nanobind + scikit-build-core and ship bundled wheels (binding-tech decision; refines #117) #131 — nanobind + scikit-build-core + bundled wheels + PyPI/TestPyPI
• High-level Pythonic API: generated enums, validation, and numpy/pandas/matplotlib helpers #132 — high-level scientific layer (enums/validation/numpy/pandas/plot)
• bug: license metadata mismatch — Python binding declares LGPL-2.0 but library is GPL-3.0 #115 — fix license metadata (LGPL-2.0 → GPL-3.0) (existing)
• refactor: replace program/target/ion magic numbers with named constants #114 — named constants / enums source-of-truth (existing)

Docs

• Docs: executable Jupyter notebooks + Python API reference (myst-nb + autodoc) #135 — executable Jupyter notebooks + API reference (myst-nb/autodoc)
• docs: add high-level "purpose, role & how to read the numbers" guide #116 — high-level purpose/role guide (existing)

libamtrack integration

• libamtrack integration contract: ID mapping, units (keV/µm), and energy-convention reconciliation #134 — integration contract: ID mapping, units (keV/µm), energy convention

Cross-repo (to be filed in their own repos)

• libamtrack/library: Replace AT_StoppingPower* + AT_DataMaterial/AT_DataParticle with libdedx as the canonical backend (incremental, regression-gated).
• libamtrack/pyamtrack: Bind libdedx C independently via nanobind and consume the same pinned libdedx version.

Note: these two repos are outside this session's scope, so the issues above are drafted but not yet filed there.

---

Filed via Claude Code (model: Claude Opus 4.8) as part of the libdedx → libamtrack integration & Python-packaging plan.