RMSD Calculator

GitHub Link to Code

Calculator utilities for RMSD computations.

class mdxplain.analysis.structure.calculators.rmsd_calculator.RMSDCalculator(trajectories: Iterable, chunk_size: int, use_memmap: bool)

Perform RMSD calculations with optional chunk-aware processing.

The calculator accepts a collection of trajectory-like objects and exposes three computation modes:

• RMSD to an externally supplied reference frame.

• Frame-to-frame RMSD with configurable lag.

• Window-based RMSD in frame_to_start/frame_to_frame modes.

All calculations are vectorised and can operate on streamed chunks when the caller indicates use_memmap=True. The class itself performs only the numerical work; selection of trajectories, atom filters, and reference frames happens in mdxplain.analysis.structure.services.rmsd_variant_service.RMSDVariantService.

__init__(trajectories: Iterable, chunk_size: int, use_memmap: bool) → None

Initialise the calculator with shared runtime settings.

The calculator stores the trajectory collection alongside the streaming configuration so all subsequent computations can reuse the same setup.

Parameters

trajectoriesIterable

Iterable of trajectory-like objects.

chunk_sizeint

Chunk size used for streaming calculations.

use_memmapbool

Flag indicating whether the trajectories are memory mapped.

Returns

None

The initializer does not return anything.

Raises

ValueError

If no trajectories are supplied.

Examples

>>> topology = md.Topology()
>>> _ = topology.add_chain()
>>> trajectory = md.Trajectory(np.zeros((5, 1, 3), dtype=np.float32), topology)
>>> calculator = RMSDCalculator([trajectory], chunk_size=100, use_memmap=False)
>>> calculator.chunk_size
100

rmsd_to_reference(reference_frame: Trajectory, atom_indices: Sequence[int] | None, metric: Literal['mean', 'median', 'mad']) → List[ndarray]

Compute RMSD of each frame against a reference frame.

Each trajectory is streamed in chunks, squared deviations towards the reference frame are accumulated and the requested metric is applied to obtain frame-wise RMSD values.

Parameters

reference_framemd.Trajectory

Single-frame trajectory used as reference.

atom_indicesSequence[int] or None

Atom indices used for the RMSD calculation. None selects all atoms.

metric{‘mean’, ‘median’, ‘mad’}

Robust aggregation metric applied to atom-wise squared deviations.

Returns

list of numpy.ndarray

List containing RMSD values for each trajectory.

Examples

>>> topology = md.Topology()
>>> _ = topology.add_chain()
>>> trajectory = md.Trajectory(np.zeros((5, 1, 3), dtype=np.float32), topology)
>>> calculator = RMSDCalculator([trajectory], chunk_size=100, use_memmap=False)
>>> values = calculator.rmsd_to_reference(trajectory[0], atom_indices=None, metric="mean")
>>> isinstance(values[0], np.ndarray)
True

frame_to_frame(atom_indices: Sequence[int] | None, lag: int, metric: Literal['mean', 'median', 'mad']) → List[ndarray]

Compute frame-to-frame RMSD with a configurable lag.

Coordinates are paired according to the requested lag and the robust metric is applied per frame to obtain RMSD trajectories.

Parameters

atom_indicesSequence[int] or None

Atom indices used for the RMSD calculation. None selects all atoms.

lagint

Distance between frames when calculating the RMSD.

metric{‘mean’, ‘median’, ‘mad’}

Robust aggregation metric applied to atom-wise squared deviations.

Returns

list of numpy.ndarray

List containing RMSD values for each trajectory.

Examples

>>> topology = md.Topology()
>>> _ = topology.add_chain()
>>> trajectory = md.Trajectory(np.zeros((5, 1, 3), dtype=np.float32), topology)
>>> calculator = RMSDCalculator([trajectory], chunk_size=100, use_memmap=False)
>>> values = calculator.frame_to_frame(atom_indices=None, lag=1, metric="median")
>>> isinstance(values[0], np.ndarray)
True

window(atom_indices: Sequence[int] | None, window_size: int, stride: int, metric: Literal['mean', 'median', 'mad'], mode: str = 'frame_to_start', lag: int | None = None) → List[ndarray]

Compute window-based RMSD according to the requested mode.

Depending on mode the method either compares all frames in a window with the first frame or evaluates lag-separated frame pairs. The final window value is derived by applying the metric across frames.

Parameters

atom_indicesSequence[int] or None

Atom indices used for the RMSD calculation. None selects all atoms.

window_sizeint

Number of frames per window.

strideint

Step size when advancing the window.

metric{‘mean’, ‘median’, ‘mad’}

Robust aggregation metric applied to atom-wise squared deviations and to the frame summary inside each window.

modestr, optional

Window mode: "frame_to_start" (default) or "frame_to_frame".

lagint, optional

Lag between frames when mode is "frame_to_frame". Must be positive.

Returns

list of numpy.ndarray

Window-wise RMSD arrays for each trajectory.

Examples

>>> topology = md.Topology()
>>> _ = topology.add_chain()
>>> trajectory = md.Trajectory(np.zeros((5, 1, 3), dtype=np.float32), topology)
>>> calculator = RMSDCalculator([trajectory], chunk_size=100, use_memmap=False)
>>> windows = calculator.window(
...     atom_indices=None,
...     window_size=3,
...     stride=1,
...     metric="mad",
... )
>>> windows[0].shape[0] > 0
True