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

[grzanka]

Part of #130. Design + implementation spec for the libdedx ↔ libamtrack boundary.

Context

libamtrack and libdedx model the same physics with different identifiers, units, and energy conventions. Before libdedx can replace AT_StoppingPower* / AT_DataMaterial / AT_DataParticle, these must be reconciled and documented as a stable contract. Decision (per #130): adopt libdedx IDs as canonical, with a one-time compatibility mapping/shim for the transition.

Concern	libamtrack	libdedx	Resolution
Material IDs	AT_DataMaterial material numbers	DEDX_* material enum (dedx_elements.h)	mapping table; libdedx canonical
Particle IDs	particle codes (AT_DataParticle)	ion enum + DEDX_PROTON/ELECTRON/...	mapping table; libdedx canonical
STP "source"	source numbers/keywords (PSTAR/ICRU/Bethe…)	program enum (DEDX_PSTAR, …)	source↔program map
Units	keV/µm and MeV·cm²/g	MeV·cm²/g (+ dedx_convert_units to keV/µm/MeV/cm)	use convert_units; needs density (#119)
Energy	"specific energy" (MeV/u)	MeV/nucl	confirm identical; guard at boundary

Proposed change

• A documented mapping table (libamtrack ↔ libdedx) for materials, particles, and STP sources, with a generated/checked-in form and a drift test.
• A thin compatibility shim libamtrack can call during the incremental refactor so existing callers/tests keep working until they migrate to libdedx IDs.
• Confirm and assert MeV/nucl ≡ MeV/u at the boundary; centralize any conversion.
• Unit handling via dedx_convert_units (refactor: namespace public convert_units() as dedx_convert_units() #112), relying on the density getter (Expose nucleon number, atom mass, density and is-gas in the public header #119) for keV/µm and MeV/cm.

Open decisions

• Does the mapping table live in libdedx (as an optional compatibility header) or in libamtrack? (Leaning: in libamtrack, since it encodes libamtrack's legacy numbering.)
• Granularity of the shim — per-call adapter vs a generated translation layer.

Acceptance criteria

• Documented, tested mapping for materials, particles, and STP sources.
• Boundary energy-convention assertion + tests.
• keV/µm / MeV/cm conversions validated against libamtrack reference values within an agreed tolerance.
• Contract documented so the libamtrack refactor and pyamtrack can rely on it.

References

Relates to #112, #119, and the additional-accessors child of #130. Drives the libamtrack/library refactor (filed separately).

---

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