stopping power and mass stopping power implemetations

[witNie]

No description provided.

[grzanka]

Add some python examples demonstrating if it works as expected...

Try reproducing in Python plot like that:

add another data serie for carbon ion on same plot

[witNie]

It looks similar

[witNie]

this as well checks out

[Copilot]

Pull request overview

This PR adds new stopping power APIs to the pyamtrack.stopping nanobind module, exposing libamtrack stopping power calculations to Python (with vectorization support via the existing wrapper utilities).

Changes:

• Add new C++ wrapper functions mass_stopping_power() and stopping_power() (nanobind-friendly, vectorized/cartesian-product capable).
• Expose these functions in the stopping Python extension module.
• Add a Jupyter notebook example demonstrating stopping power calculations.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/stopping/stopping_power.h	Declares new stopping power API functions/constants for the stopping module.
src/stopping/stopping_power.cpp	Implements stopping power wrappers, argument normalization, and Particle/Material handling.
src/stopping/stopping_bindings.cpp	Registers the new functions in the nanobind module (and currently exports a debug function).
src/stopping/electron_range.cpp	Makes get_id static to avoid external linkage conflicts.
examples/stopping.ipynb	Adds an example notebook (currently has a unit/label mismatch vs the function called).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot review overview

🔵 Needs a closer look

It adds a substantial native binding module with intricate numeric/memory logic and introduces a functional regression (empty models submodule breaks pyamtrack.stopping.models.* used by an existing example), so human review is warranted.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Remove or restore empty models submodule population · New
• Expand stopping_power docstring to match API · New
• Delete large commented-out test blocks · New

[grzanka]

Good feature overall (vectorised API, return_source, thorough mass_stopping_power docstring). Findings below, most important first.

🔴 P1 – blockers

1. Tests are disabled. In tests/test_stopping.py ~177 of 397 lines are commented out: all 7 pre-existing electron_range tests plus 9 earlier new tests (invalid-argument, Ion/Material argument, string/enum source, …). Green CI no longer covers electron_range (touched here) or the type-validation paths. Restore the old tests; revive or delete (not comment out) the new ones.
2. Unrelated breaking change: pyamtrack.stopping.models.* constants are gone. The loop populating models in stopping_bindings.cpp is commented out, so stopping.models.tabata / .edmund raise AttributeError. examples/example.ipynb (l. 222, 289, 321, 327) still uses them, and (1) hides it. Restore, or deprecate explicitly in a separate PR. No commented-out code, please.

🟠 P2 – should fix before merge

3. Inconsistent error contract. Docstring promises TypeError for a bad source type, but parse_stopping_power_source throws invalid_argument (→ ValueError) and silently accepts ints 0–3 (undocumented). For list/array input the shared wrapper rewraps everything as RuntimeError("Error processing 1-D NumPy array: …"), so scalar → ValueError, vector → RuntimeError (the new tests assert both). Pick one contract and document it.
4. No physics anchors in tests. Active tests compare the function to itself (scalar vs vector vs cartesian) or check > 0. Add 2–3 NIST PSTAR reference values with a tolerance (e.g. 100 MeV p in liquid water ≈ 7.289 MeV·cm²/g).
5. Re-implements libamtrack internals. stopping_power.cpp hand-declares extern AT_stopping_power_ICRU_table[2] / PSTAR_data (not in public headers) and hard-codes material_no - 1, Z > 18, He ≤ 250 MeV/u, materials Water_Liquid..Copper. This silently rots if upstream changes. Prefer upstream status codes / a public API; at minimum name and comment the constants and pin them with a test.
6. source="default" silently switches physics model per element (PSTAR→Bethe outside the table), and allow_multiple_sources=False then raises a generic "Inconsistent stopping power source selection" with no element/energy and no hint about the flag. Consider dropping the flag (and its stateful mutable lambda) in favour of return_source / a warning, or at least make the message actionable.
7. API shape. return_source=True changes the return type (value → tuple); prefer a separate function or result object. help() shows source=0 while docs say "default". .export_values() leaks DEFAULT/BETHE/PSTAR/ICRU into the pyamtrack.stopping namespace.

🟡 P3 – maintainability

8. Formatting churn mixed with logic (~100 lines of clang-format reflow in particles.cpp/.h, ion.h). Split it out so the functional diff is reviewable.
9. Dead code: Particle::get_id() is unused; Particle::get_particle_no() (throwing, non-virtual, hidden by Ion::) is unreachable; select_stopping_power_source(…, particle_no) ignores its parameter; parse_/select_stopping_power_source are internal but exported in stopping_power.h.
10. Duplicate passes: validate_particle_argument + parse_particle_argument (same for material) walk the same structure twice (tolist() twice for arrays), then the wrapper walks it again. One normalize_* returning validated IDs would do.
11. Portability: source_ids use long (int32 on Windows, int64 elsewhere) → use int64_t. windows.yml doesn't run on PRs, so this is unexercised.

🟢 P4 – docs / hygiene

12. docs/naming_convention.md lists every public pyamtrack.stopping function and argument, but was not updated (mass_stopping_power, stopping_power, particle, source, allow_multiple_sources, return_source, StoppingPowerSource). stopping_power has no Parameters/Returns/Raises docstring.
13. examples/stopping_power.ipynb is a scratch notebook (one ad-hoc call, leftover outputs, empty last cell) that duplicates stopping.ipynb; drop it. stopping.ipynb again ends with an empty code cell.
14. Empty PR description, typo in title ("implemetations"), 21 commits incl. "refactor wip" and 4 merges. Describe scope and API, squash on merge.

[grzanka]

see comemnts