Structure Calculation Helper

GitHub Link to Code.

Shared helper functions for structure calculations.

These helper provide chunk iteration and stacking utilities that allow structure analyses to process large trajectories without loading all frames into memory simultaneously.

class mdxplain.analysis.structure.helper.structure_calculation_helper.StructureCalculationHelper

Bundle of shared low-level operations for structure analysis.

The helper centralises chunk iteration and frame stacking logic so higher level services/calculators can operate on homogeneous APIs regardless of whether trajectories are processed in-memory or via memmap streaming.

static iterate_chunks(trajectory: md.Trajectory | DaskMDTrajectory, chunk_size: int) → Iterator[Tuple[md.Trajectory, int, int]]

Yield slices of a trajectory with the requested chunk size.

Parameters

trajectorymd.Trajectory or DaskMDTrajectory: Trajectory object supporting slicing via __getitem__.
chunk_sizeint: Number of frames processed per chunk. Values less than one default to the full trajectory length.

Returns

Iterator[Tuple[md.Trajectory, int, int]]: Iterator yielding tuples containing (chunk, start_index, end_index).

Notes

When chunking is disabled the helper yields a single tuple containing the original trajectory and the full frame range.

Examples

>>> topology = md.Topology()
>>> chain = topology.add_chain()
>>> residue = topology.add_residue("ALA", chain)
>>> topology.add_atom("CA", md.element.carbon, residue)
>>> coords = np.zeros((5, 1, 3), dtype=np.float32)
>>> traj = md.Trajectory(coords, topology)
>>> iterator = StructureCalculationHelper.iterate_chunks(traj, chunk_size=2)
>>> chunk, start, end = next(iterator)
>>> (chunk.n_frames, start, end)
(2, 0, 2)

static stack_frames(frames: Iterable[Trajectory]) → Trajectory

Stack individual frames into a single trajectory.

Parameters

framesIterable[md.Trajectory]: Iterable of trajectories with exactly one frame each.

Returns

md.Trajectory: Combined trajectory containing the stacked frames.

Raises

ValueError: If the iterable is empty.

Examples

>>> topology = md.Topology()
>>> chain = topology.add_chain()
>>> residue = topology.add_residue("ALA", chain)
>>> topology.add_atom("CA", md.element.carbon, residue)
>>> frame = md.Trajectory(np.zeros((1, 1, 3), dtype=np.float32), topology)
>>> stacked = StructureCalculationHelper.stack_frames([frame, frame])
>>> stacked.n_frames
2