Additional public material/ion accessors required by libamtrack (electron density, mean ⟨Z⟩, ⟨A⟩, Z/A)

[grzanka]

Part of #130. Complements #119 (which adds density / nucleon number / atom mass / is-gas).

Context

For libamtrack to use libdedx as its material/particle database (AT_DataMaterial / AT_DataParticle replacement), it needs a few derived material/ion quantities beyond those in #119. Some already exist publicly:

• ✅ dedx_get_i_value(target, *err) — mean excitation potential (eV)
• ✅ dedx_get_composition(target, ...) — elemental composition (Z, mass fraction)
• 🔜 dedx_get_density / dedx_get_nucleon_number / dedx_get_atom_mass / dedx_is_gas — Expose nucleon number, atom mass, density and is-gas in the public header #119

Still missing (used heavily by libamtrack dosimetry — fluence↔dose, electron-density-dependent models):

• Electron density (per cm³ and per g),
• Average atomic number ⟨Z⟩ and average mass number ⟨A⟩,
• Z/A (effective charge-to-mass ratio of the material).

These are all derivable from the composition + density libdedx already stores, so this is about exposing them with a stable, bounds-checked public signature rather than every binding recomputing them.

Proposed change

Public, bounds-checked declarations in include/dedx.h (final names a maintainer call), e.g.:

double dedx_get_electron_density_per_cm3(int material, int *err); /* e-/cm^3 */
double dedx_get_electron_density_per_g(int material, int *err);   /* e-/g    */
double dedx_get_average_z(int material, int *err);                /* <Z>     */
double dedx_get_average_a(int material, int *err);                /* <A>     */
double dedx_get_z_over_a(int material, int *err);                 /* Z/A     */

Acceptance criteria

• Declarations in include/dedx.h with Doxygen comments and explicit units.
• Invalid material returns a safe sentinel and sets *err (consistent with bug: out-of-bounds read in dedx_get_*_name / dedx_get_program_version on invalid id #110/Expose nucleon number, atom mass, density and is-gas in the public header #119).
• Values validated against reference materials (e.g. water, air) in tests/.
• Documented as part of the "material database" surface libamtrack will consume.

References

Complements #119 · part of the Phase 0 C-API contract in #130.

---

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