[Tracking] libdedx health review — correctness, API hygiene, docs & ecosystem (web + Python) #108

libdedx health-review epic

A full read-through of libdedx (source, headers, embedded data, tests, CI, Python binding, docs).

Verdict: the repo is in good shape. It configures and builds cleanly with CMake; all 27 ctests pass, including physics reference-value tests against NIST PSTAR/ASTAR and ICRU/MSTAR at a 0.5 % relative tolerance. CI is solid (Linux + Windows build/test, Valgrind leak check, coverage, clang-format, clang-tidy, Python tests on 3.9/3.13, docs). Stopping-power data is embedded into headers (no runtime file deps), and the public headers are well Doxygen-documented.

So no emergency refactor is required to trust the numbers. This is a parent tracking issue: the work is broken into focused child issues, each with its own context and acceptance criteria. Priorities reflect the stated goals — correct physics first, then API hygiene, then explaining purpose/role, then the web + Python ecosystem.

Verification: cmake -S . -B build && cmake --build build && ctest --test-dir build → 27/27 passed (Linux, gcc).

P0 — Correctness & trust

• bug: library writes to stdout via stray printf in load_config_clean #109 — bug: stray printf to stdout in load_config_clean (good first issue)
• bug: out-of-bounds read in dedx_get_*_name / dedx_get_program_version on invalid id #110 — bug: out-of-bounds read in dedx_get_*_name / dedx_get_program_version
• Make Bragg/stoichiometric fallback transparent (surface bragg_used) and add accuracy tests #111 — make Bragg/stoichiometric fallback transparent (bragg_used) + accuracy tests
• Bethe: update nucleon mass may lead to slightly better dEdx and ranges. #95 — revisit hard-coded Bethe nucleon mass (940 → 931.494 MeV/c²) (pre-existing)

P1 — API hygiene & robustness

• refactor: namespace public convert_units() as dedx_convert_units() #112 — refactor: namespace convert_units() → dedx_convert_units()
• bug: dedx_get_ion_list() returns a thread-unsafe function-local static buffer #113 — bug: thread-unsafe function-local static buffer in dedx_get_ion_list() (relates to make library thread-safe #86)
• refactor: replace program/target/ion magic numbers with named constants #114 — refactor: replace program/target/ion magic numbers with named constants
• bug: license metadata mismatch — Python binding declares LGPL-2.0 but library is GPL-3.0 #115 — bug: license metadata mismatch (Python LGPL-2.0 vs library GPL-3.0)
• make library thread-safe #86 — make library thread-safe (pre-existing, umbrella)

P2 — Documentation: purpose & role

• docs: add high-level "purpose, role & how to read the numbers" guide #116 — docs: high-level "purpose, role & how to read the numbers" guide (subsumes Check mass stopping power units #48 units)
• Add man pages #28 — man pages for CLI tools (pre-existing)

P3 — Ecosystem: web frontend & Python wrapper

• Expand the Python binding to cover the full C API and publish wheels #117 — expand Python binding to full C API + publish wheels
• Add query API for valid (program, ion, material) combinations to support GUI/frontend development #79 — query API for valid (program, ion, material) combinations (pre-existing; web GUI)
• Add proper handling of missing ion+material+program combinations #51 — proper handling of missing program/ion/material combinations (pre-existing)
• GUI frontend #25 — GUI frontend (pre-existing)
• simple override of elemental I-values #6 — per-element I-value override (pre-existing)
• add script for generating simple stopping power tables for a given material #96 — table-generation script for external codes (pre-existing)

Backlog — future physics

• add ESTAR tables #5 — ESTAR electron stopping power · [ ] add nuclear stopping power tables #3 — nuclear stopping power · [ ] Add super-relativistic stopping power data #8 — super-relativistic data · [ ] Look into SRIM #21 — SRIM comparison

New child issues (#109–#117) were created by an automated health review (Claude Code); pre-existing issues are linked, not re-parented unless noted.