Stopping power functions with MeV energy units

[witNie]

This pull request adds new API functions to the stopping power calculation code, allowing users to compute stopping powers using total kinetic energy values in MeV (as opposed to only MeV/u), for both single particles and arrays of particles. The changes also include thorough documentation for the new functions.

New API functions for stopping power calculations:

• Added AT_Mass_Stopping_Power_E_MeV_with_no and AT_Stopping_Power_E_MeV_with_no functions to compute mass stopping power and stopping power in keV/um, respectively, for arrays of particles given total kinetic energies in MeV. These functions handle conversion from MeV to MeV/u internally. [1] [2] [3] [4]
• Added single-particle variants: AT_Stopping_Power_E_MeV_single, AT_Mass_Stopping_Power_E_MeV_single, AT_Stopping_Power_E_MeV_u_single, and AT_Mass_Stopping_Power_E_MeV_u_single, which provide stopping power calculations for individual particles using either MeV or MeV/u as input. [1] [2]

Documentation improvements:

• Added detailed Doxygen-style comments for all new functions, describing parameters, expected input formats, and return values to improve clarity and usability of the API. [1] [2] [3]

These changes enhance the flexibility and usability of the stopping power calculation library, making it easier to work with kinetic energy values in MeV and to process both single and multiple particles efficiently.

[grzanka]

see comments inline

[Copilot]

Copilot review overview

🟢 Approval recommended

The additions are small, correct, delegate to existing well-established routines with proper unit conversion, and the only findings are optional robustness nits around unchecked allocations.

Review effort: Balanced
Findings: 1

Open (1)

• Check malloc return before dereferencing buffer · New

What changed in this PR

This PR extends the stopping-power API in the libamtrack C library by adding convenience functions that accept total kinetic energy in MeV (rather than the library's native MeV/u). Each new MeV-based array function converts the input energies to MeV/u via AT_E_MeV_u_from_E_MeV (per-particle, using the atomic weight) and delegates to the existing _with_no routines. The PR also adds single-particle wrappers for both MeV and MeV/u inputs, improving ergonomics for callers that work with one particle at a time.

Changes:

• Added array functions AT_Mass_Stopping_Power_E_MeV_with_no and AT_Stopping_Power_E_MeV_with_no that convert MeV→MeV/u before computing stopping power.
• Added single-particle wrappers: AT_Stopping_Power_E_MeV_single, AT_Mass_Stopping_Power_E_MeV_single, AT_Stopping_Power_E_MeV_u_single, and AT_Mass_Stopping_Power_E_MeV_u_single.
• Added matching Doxygen-documented declarations in the public header.

File	Description
src/​AT_StoppingPower.c	Implements the new MeV-based array functions (with per-particle unit conversion) and the four single-particle wrappers; delegates to existing _with_no routines.
include/​AT_StoppingPower.h	Declares the new functions with consistent Doxygen documentation describing units and conversion behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.