torchref.io.ihm_mapping module

Intermediate representation for IHM mmCIF ensemble data.

Provides dataclasses that map between IHM categories and torchref’s ModelCollection / DatasetCollection structures. This mapping can be:

  1. Populated by IHMReader from an IHM mmCIF file

  2. Constructed programmatically (e.g., from a kinetic model)

  3. Passed to IHMWriter for round-trip output

Concept Mapping

IHM state -> base model (ModelFT) in ModelCollection IHM model group -> timepoint entry (_SharedMixedModel) in ModelCollection IHM population fraction -> fraction_params in _SharedMixedModel

class torchref.io.ihm_mapping.IHMStateInfo(state_id, name, details='', model_num=1)[source]

Bases: object

Metadata for a single structural state (e.g., ground state, intermediate).

Parameters:

  • state_id (int) – Unique identifier matching _ihm_multi_state_modeling.state_id.

  • name (str) – Human-readable name (e.g., "ground_state", "intermediate_1").

  • details (str) – Free-text description of this state.

  • model_num (int) – pdbx_PDB_model_num in the _atom_site loop that corresponds to this state’s coordinates.

state_id: int
name: str
details: str = ''
model_num: int = 1
__init__(state_id, name, details='', model_num=1)
class torchref.io.ihm_mapping.IHMModelGroupInfo(group_id, name, state_fractions=<factory>, time_delay=None, time_delay_units='s')[source]

Bases: object

Metadata for a model group (experimental condition / timepoint).

Parameters:

  • group_id (int) – Unique identifier matching _ihm_model_group.id.

  • name (str) – Human-readable name (e.g., "dark", "1ps", "5ps").

  • state_fractions (Dict[int, float]) – Mapping of state_id -> population fraction for this group. Fractions should sum to 1.0.

  • time_delay (float, optional) – Time delay in time_delay_units (for time-resolved experiments).

  • time_delay_units (str) – Units for time_delay. Default "s" (seconds).

group_id: int
name: str
state_fractions: Dict[int, float]
time_delay: float | None = None
time_delay_units: str = 's'
__init__(group_id, name, state_fractions=<factory>, time_delay=None, time_delay_units='s')
class torchref.io.ihm_mapping.IHMEnsembleMapping(states=<factory>, model_groups=<factory>, cell=None, spacegroup=None, atom_data_per_state=None)[source]

Bases: object

Complete mapping between IHM mmCIF categories and torchref structures.

This is the central interchange object: both IHMReader and IHMWriter operate through it. It can also be constructed manually for programmatic workflows (e.g., building an IHM file from a KineticRefinement result without reading one first).

Parameters:

  • states (List[IHMStateInfo]) – Structural states (one per base model in ModelCollection).

  • model_groups (List[IHMModelGroupInfo]) – Model groups / timepoints (one per timepoint in ModelCollection).

  • cell (list of float, optional) – Unit cell parameters [a, b, c, alpha, beta, gamma].

  • spacegroup (str, optional) – Space group name (Hermann-Mauguin notation).

  • atom_data_per_state (dict, optional) – Mapping of state_id -> pandas DataFrame with atom data. Populated by IHMReader.read_atom_data().

states: List[IHMStateInfo]
model_groups: List[IHMModelGroupInfo]
cell: List[float] | None = None
spacegroup: str | None = None
atom_data_per_state: Dict[int, DataFrame] | None = None
get_state_ids()[source]

Return state IDs ordered by state_id.

get_timepoint_names()[source]

Return model group names ordered by group_id.

get_fractions_for_group(group_name)[source]

Return population fractions for a model group, ordered by state_id.

Parameters:

group_name (str) – Name of the model group.

Returns:

Fractions ordered by ascending state_id.

Return type:

list of float

Raises:

KeyError – If no group with the given name exists.

identify_dark_group()[source]

Heuristic: identify the reference / dark group.

Returns the name of the first model group where a single state has population fraction >= 0.95, or None if no such group exists.

get_state_by_id(state_id)[source]

Look up a state by its ID.

Raises:

KeyError – If no state with the given ID exists.

get_group_by_name(name)[source]

Look up a model group by name.

Raises:

KeyError – If no group with the given name exists.

validate()[source]

Check internal consistency.

Raises:

ValueError – If states are empty, fractions don’t reference valid states, or fractions don’t sum to ~1.0 for any group.

__init__(states=<factory>, model_groups=<factory>, cell=None, spacegroup=None, atom_data_per_state=None)