Build the Python binding with nanobind + scikit-build-core and ship bundled wheels (binding-tech decision; refines #117)

[grzanka]

Part of #130. Refines the Proposed change of #117.

Context

#117 proposes extending the existing ctypes binding (python/libdedx/_api.py) to cover the full C API and publish wheels. After reviewing the ecosystem, we are recording a binding-technology decision: replace the ctypes binding with a nanobind extension built by scikit-build-core, matching libamtrack/pyamtrack's stack.

Rationale:

• One build/CI/packaging idiom shared with pyamtrack (which also uses scikit-build-core + nanobind, cibuildwheel auto64, CPython 3.9–3.14, numpy, setuptools_scm).
• Cleanly exposes the workspace/config object model (allocate workspace → load config → evaluate), which is awkward to express well in raw ctypes.
• libdedx is self-contained (embedded data, no GSL), so the extension can statically link libdedx → a single-file extension and trivially self-contained wheels (simpler than pyamtrack, which must vendor GSL).

Proposed change

• python/pyproject.toml → build-backend = "scikit_build_core.build"; build-requires nanobind, scikit-build-core>0.10, setuptools_scm>=8; runtime dep numpy.
• CMake target building a libdedx._core nanobind module that statically links the libdedx C library; use nb::ndarray for zero-copy numpy in/out.
• Expose the full C API the current wrapper omits:
  • workspace/config lifecycle, custom compounds (Z + atoms/mass-fractions, ρ, per-element I-value),
  • dedx_get_stp / CSDA / inverse STP / inverse CSDA,
  • dedx_convert_units (incl. keV/µm, see refactor: namespace public convert_units() as dedx_convert_units() #112),
  • composition / I-value / density accessors (Expose nucleon number, atom mass, density and is-gas in the public header #119),
  • min/max energy, program/ion/material lists and names,
  • Bragg-fallback provenance (bragg_used, Make Bragg/stoichiometric fallback transparent (surface bragg_used) and add accuracy tests #111).
• Wheels: cibuildwheel, auto64, CPython 3.9–3.14, skip PyPy, macOS target 11.0; install-and-import smoke test each wheel.
• Release: setuptools_scm lockstep with the C library; PyPI Trusted Publishing (OIDC) on v* tags with a TestPyPI dry-run first.
• Fix the license metadata while here (bug: license metadata mismatch — Python binding declares LGPL-2.0 but library is GPL-3.0 #115).

Open decisions

• macOS: universal2 vs separate x86_64 + arm64 wheels.
• aarch64 Linux (manylinux) now, or defer to keep early build times down.
• Keep a minimal ctypes fallback for source installs, or nanobind-only (lean: nanobind-only).

Acceptance criteria

• pip install libdedx from a published wheel works with no local C build, on Linux/macOS/Windows × CPython 3.9–3.14.
• Low-level module exposes workspace/config, custom compounds, inverse STP/CSDA, unit conversion, accessors, lists/names; covered by tests.
• Wheels are install-smoke-tested in CI before publish; TestPyPI dry-run wired before PyPI.
• Version is lockstep with the C library (setuptools_scm).
• License metadata corrected (bug: license metadata mismatch — Python binding declares LGPL-2.0 but library is GPL-3.0 #115); ruff + pytest green.

References

Refines #117 · depends on/relates to #112, #115, #119, #123, #111, #86/#113.

---

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