pymkm.io.table_set¶

Management of multiple ion stopping power tables.

This module defines the StoppingPowerTableSet, a high-level container for managing multiple StoppingPowerTable instances, each representing LET vs. energy data for a different ion in liquid water.

Main features¶

Add, remove, or retrieve tables by ion name, symbol, or atomic number
Batch interpolation, resampling, filtering, and plotting
JSON and directory-based I/O
Support for internal default sources: mstar_3_12, geant4_11_3_0, fluka_2020_0

Used throughout pyMKM to provide LET data to physical and biological models.

Examples

>>> from pymkm.io.table_set import StoppingPowerTableSet
>>> s = StoppingPowerTableSet.from_default_source("mstar_3_12")
>>> sorted(s.get_available_ions())
['Beryllium', 'Boron', 'Carbon', 'Fluorine', 'Helium', 'Hydrogen',
 'Lithium', 'Neon', 'Nitrogen', 'Oxygen']
>>> s.get("Carbon").plot(show=False)

class pymkm.io.table_set.StoppingPowerTableSet[source]¶

Bases: object

A container for managing multiple StoppingPowerTable instances.

Provides unified access to stopping power curves for multiple ions, identified by name, symbol, or atomic number. Supports serialization, resampling, filtering, and plotting.

add(ion_input: str, table: StoppingPowerTable)[source]¶

Add a stopping power table to the set.

Parameters:

ion_input (str) – Ion identifier (name, symbol, or atomic number).
table (pymkm.io.stopping_power.StoppingPowerTable) – Instance of StoppingPowerTable to add.

filter_by_ions(ion_inputs: List[str]) → StoppingPowerTableSet[source]¶

Create a subset containing only the specified ions. Each table is a StoppingPowerTable instance.

Parameters:: ion_inputs (list[str]) – List of identifiers (names, symbols, or atomic numbers).
Returns:: New StoppingPowerTableSet with selected ions.
Return type:: StoppingPowerTableSet

classmethod from_default_source(source: str) → StoppingPowerTableSet[source]¶

Load tables from a default internal source (e.g., “mstar_3_12”).

Parameters:: source (str) – Name of the predefined source directory.
Returns:: Table set initialized from source.
Return type:: StoppingPowerTableSet
Raises:: RuntimeError – If any file cannot be loaded.

classmethod from_dict(data: Dict[str, dict]) → StoppingPowerTableSet[source]¶

Create a table set from a dictionary.

Parameters:: data (dict[str, dict]) – Dictionary mapping ion names to serialized tables.
Returns:: StoppingPowerTableSet instance.
Return type:: StoppingPowerTableSet
Raises:: ValueError – If tables have inconsistent source program or ionization potential.

classmethod from_directory(directory: str) → StoppingPowerTableSet[source]¶

Load all .txt stopping power tables from a directory.

Parameters:: directory (str) – Path to directory containing .txt files.
Returns:: StoppingPowerTableSet with all successfully loaded tables.
Return type:: StoppingPowerTableSet

classmethod from_json(json_str: str) → StoppingPowerTableSet[source]¶

Create a table set from a JSON string.

Parameters:: json_str (str) – JSON-formatted table set string.
Returns:: Deserialized StoppingPowerTableSet.
Return type:: StoppingPowerTableSet

get(ion_input: str) → StoppingPowerTable | None[source]¶

Retrieve a table by ion identifier.

Parameters:: ion_input (str) – Ion name, symbol, or atomic number.
Returns:: Corresponding StoppingPowerTable or None.
Return type:: pymkm.io.stopping_power.StoppingPowerTable or None

get_available_ions() → List[str][source]¶

Get the list of ion names present in the set.

Returns:: List of ion names.
Return type:: list[str]

get_common_energy_range() → List[float] | None[source]¶

Get the overlapping energy range across all tables.

Returns:: [min, max] energy range, or None if no common range exists.
Return type:: list[float] or None

get_energy_grid(ion_input: str) → ndarray[source]¶

Get the energy grid for a given ion.

Parameters:: ion_input (str) – Ion identifier.
Returns:: Energy array.
Return type:: np.ndarray

get_stopping_power(ion_input: str) → ndarray[source]¶

Get the stopping power values for a given ion.

Parameters:: ion_input (str) – Ion identifier.
Returns:: LET array.
Return type:: np.ndarray

interpolate_all(energy: ndarray, loglog: bool = True) → Dict[str, ndarray][source]¶

Interpolate LET values at given energies for all tables.

Parameters:

energy (np.ndarray) – Energy values at which to interpolate.
loglog (bool) – Use log-log interpolation if True.

Returns:

Dictionary mapping ion names to interpolated LET arrays.

Return type:

dict[str, np.ndarray]

items()[source]¶

keys()[source]¶

classmethod load(filepath: str) → StoppingPowerTableSet[source]¶

Load a table set from a JSON file.

Parameters:: filepath (str) – Path to JSON file.
Returns:: Loaded StoppingPowerTableSet.
Return type:: StoppingPowerTableSet

plot(ions: List[str] | None = None, show: bool = True, single_plot: bool = True)[source]¶

Plot stopping power curves for one or more ions.

Parameters:

ions (Optional[List[str]]) – List of ion identifiers to plot. If None, all are plotted.
show (bool) – Whether to display the plot using plt.show().
single_plot (bool) – If True, plot all ions on one figure; otherwise, one figure per ion.

remove(ion_input: str)[source]¶

Remove a table by ion identifier.

Parameters:: ion_input (str) – Ion name, symbol, or atomic number.

resample_all(new_grid: ndarray)[source]¶

Resample the LET curves of all tables onto a new energy grid.

Parameters:: new_grid (np.ndarray) – Strictly increasing energy grid in MeV/u.
Raises:: ValueError – If the grid is not strictly increasing.

save(filepath: str)[source]¶

Save the table set to a JSON file.

Parameters:: filepath (str) – Output file path.

to_dict() → Dict[str, dict][source]¶

Serialize all tables to a dictionary.

Returns:: Dictionary of ion names to serialized data.
Return type:: dict[str, dict]

to_json() → str[source]¶

Serialize the set to a JSON string.

Returns:: JSON-formatted string.
Return type:: str

values()[source]¶