High-level Pythonic API: generated enums, validation, and numpy/pandas/matplotlib helpers

[grzanka]

Part of #130. Builds on the nanobind core (companion issue) and complements #117/#114.

Context

The nanobind core exposes the raw C API. On top of it we want a friendly, idiomatic Python layer so that examples and notebooks read naturally (e.g. Program.PSTAR, Material.WATER) and users never pass magic integers. This is the layer the user docs/notebooks (companion docs issue) are written against.

Proposed change

• Enums Program, Ion, Material (IntEnum) generated from the C headers (src/dedx_program_const.h, include/dedx_elements.h) by a small generator + a drift test in CI — never hand-copied. Provide Material.from_name(...) / .label (ties into refactor: replace program/target/ion magic numbers with named constants #114 and display names Add public dedx_get_material_display_name() and make C the single source of truth for display names #120).
• Errors: LibdedxError mapping numeric codes from dedx_error.h to readable messages; raise on non-zero *err.
• Validation: check program/ion/material combinations (and energy ranges via min/max-energy) in Python before calling C, to avoid hard crashes on bad input (relates to bug: out-of-bounds read in dedx_get_*_name / dedx_get_program_version on invalid id #110, Add proper handling of missing ion+material+program combinations #51).
• numpy-first functions: scalar or array-like energies in → numpy arrays out (stopping power, CSDA, inverse).
• Optional extras (lazy-imported): libdedx[pandas] → tidy DataFrame tables; libdedx[plot] → matplotlib convenience plots; libdedx[all].

Acceptance criteria

• Generated Program/Ion/Material enums with a CI drift-guard against the C headers.
• LibdedxError with code→message mapping; consistent raise-on-error across the API.
• Input validation prevents segfaults on invalid combinations/energies (tested).
• numpy in/out core; optional pandas + matplotlib helpers under extras, lazily imported.
• Public API documented with NumPy-style docstrings (consumed by the docs issue).

References

Relates to #117, #114, #120, #110, #51, #79.

---

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