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. :attr REQUIRED_HEADER_KEYS: Required header keys for parsing stopping power tables. :attr REQUIRED_DICT_KEYS: Required dictionary keys for internal representation. :attr DEFAULT_TARGET: Default target material (WATER_LIQUID).

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 serialized dictionary.

The input dictionary must contain at least the required fields listed in StoppingPowerTable.REQUIRED_DICT_KEYS, also listed below.

Expected dictionary format:

{
    "ion_symbol": H,                    # str, symbol of the ion
    "energy": [...],                    # list/array of float, energy values (MeV/u)
    "let": [...],                       # list/array of float, corresponding stopping powers (MeV/cm)
    "mass_number": 1,                   # int, mass number of the ion
    "source_program": fluka_2020_0      # str, program used to generate data
    "ionization_potential": 75.0        # float, ionization potential (eV)
}

Parameters:: data (dict) – Dictionary containing serialized table data.
Returns:: A new 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.

The input file must contain a header with required fields and a data section with energy and LET values. The header must include the Ion, AtomicNumber, MassNumber, SourceProgram, IonizationPotential, and Target (case-sensitive) fields.

Example header:

SourceProgram=fluka_2020_0
Target=WATER_LIQUID
IonizationPotential=77.0
Ion=H
AtomicNumber=1
MassNumber=1

The data section should contain energy and LET values in two columns, expressed in MeV/u and MeV/cm respectively.

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, ax: Axes | None = None)[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().
ax (Optional[matplotlib.axes.Axes]) – Matplotlib Axes object to draw on. If None, a new figure is created.

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