pymkm.io.stopping_power¶

Representation of stopping power data for individual ions.

This module defines the StoppingPowerTable, which stores and validates LET vs. energy curves for a given ion in liquid water.

Main features¶

Parsing from text files or dictionaries
Interpolation and resampling
Plotting
Metadata handling (Z, A, source, ionization potential)

This class serves as the core data structure for model computations.

Examples

>>> from pymkm.io.stopping_power import StoppingPowerTable
>>> spt = StoppingPowerTable.from_txt("defaults/mstar_3_12/Z06_A12_Carbon.txt")
>>> spt.ion_symbol
'C'
>>> spt.energy[:3]
array([1.0, 2.0, 3.0])
>>> spt.plot(show=False)

class pymkm.io.stopping_power.StoppingPowerTable(ion_input: str | int, energy: ndarray, let: ndarray, mass_number: int | None = None, source_program: str | None = None, ionization_potential: float | None = None)[source]¶

Bases: object

Class for representing and handling stopping power (LET) data for ions in liquid water.

Provides utilities for data validation, plotting, serialization, and interpolation.

DEFAULT_TARGET = 'WATER_LIQUID'¶

REQUIRED_DICT_KEYS = ['ion_symbol', 'atomic_number', 'mass_number', 'source_program', 'ionization_potential', 'target']¶

REQUIRED_HEADER_KEYS = ['Ion', 'AtomicNumber', 'MassNumber', 'SourceProgram', 'IonizationPotential', 'Target']¶

property energy_grid: ndarray¶

Access the energy array (grid).

Returns:: Energy values.
Return type:: np.ndarray

static from_dict(data: Dict) → StoppingPowerTable[source]¶

Create a StoppingPowerTable instance from a dictionary.

Parameters:: data (dict) – Dictionary containing all required fields.
Returns:: StoppingPowerTable instance.
Return type:: StoppingPowerTable
Raises:: ValueError – If required fields are missing.

static from_txt(filepath: str) → StoppingPowerTable[source]¶

Create a StoppingPowerTable from a .txt file containing header and data.

Parameters:: filepath (str) – Path to the input .txt file.
Returns:: StoppingPowerTable instance parsed from file.
Return type:: StoppingPowerTable
Raises:: ValueError – If required header keys or element definitions are missing or inconsistent.

classmethod get_lookup_table() → Dict[str, Dict[str, int]][source]¶

Retrieve the ion properties lookup table used to resolve ion metadata.

The table maps element names (e.g., “Carbon”) to their symbol, atomic number, mass number, and display color. Based on IUPAC reference data from: https://ciaaw.org/atomic-weights.htm

Returns:: A dictionary with element names as keys and their properties as nested dictionaries.
Return type:: dict[str, dict[str, int]]

interpolate(*, energy: ndarray | None = None, let: ndarray | None = None, loglog: bool = True)[source]¶

Interpolate LET or energy values using internal data.

Delegates to Interpolator and supports log-log interpolation.

Parameters:

energy (Optional[np.ndarray]) – Energy values at which to compute LET.
let (Optional[np.ndarray]) – LET values at which to compute corresponding energies.
loglog (bool) – Whether to perform interpolation in log-log space.

Returns:

Interpolated LETs or a dict of energies for each LET.

Return type:

np.ndarray or dict[float, np.ndarray]

property ion_name: str¶

Get the ion symbol (e.g., “C” for carbon).

Returns:: Ion symbol string.
Return type:: str

plot(label: str | None = None, show: bool = True, new_figure: bool = True)[source]¶

Plot stopping power (LET) as a function of energy.

Parameters:

label (Optional[str]) – Optional label for the plot legend.
show (bool) – Whether to call plt.show().
new_figure (bool) – If True, create a new figure and title; otherwise, reuse the current axes.

resample(new_grid: ndarray)[source]¶

Resample the LET curve onto a new energy grid using log-log interpolation.

Parameters:: new_grid (np.ndarray) – The target energy grid (must be strictly increasing).
Raises:: ValueError – If the new grid is not strictly increasing.

property stopping_power: ndarray¶

Access the LET (stopping power) array.

Returns:: LET values.
Return type:: np.ndarray

to_dict() → Dict[source]¶

Serialize the object to a dictionary.

Returns:: Dictionary containing ion metadata and LET table.
Return type:: dict