Skip to content

Msd Analysis

Compute mean-squared displacement (MSD) from trajectory coordinates.

This module implements an engine-agnostic analyzer task that computes per-atom MSD over selected frames and coordinate dimensions, with optional periodic boundary unwrapping before displacement evaluation. It is scoped to displacement series generation and does not estimate diffusion coefficients directly.

Usage context

  • Trajectory analysis: Quantify per-atom displacement growth over time.
  • Diffusion workflows: Export MSD tables for downstream fitting and plotting.
  • Comparative studies: Filter by atom IDs or atom types within one run.
Notes

Diffusivity estimation is implemented in reaxkit.analysis.trajectory.diffusivity and reuses this module's MSD outputs.

Request: MSDRequest

Request payload for MSD analysis.

Defines frame, atom-selection, dimensionality, and unwrapping controls used by the MSD task to compute displacement values from trajectory data.

Fields

Field Type Default Help Choices
atom_ids Optional[list[int]] Atom IDs to include. Empty means all atoms.
atom_types Optional[list[str]] Element symbols to include when atom_ids is empty.
dims Sequence[str] x, y, z Coordinate axes used in MSD calculation. x, y, z
origin Union[str, int] first Reference frame: 'first' or an explicit frame index.
frames Optional[Sequence[int]] Frame indices to evaluate. Empty means all frames.
every int 1 Stride over selected frames.
unwrap bool True Unwrap coordinates across periodic boundaries when cell data is available.
max_lag Optional[int] Maximum lag time in number of frames. If empty, all selected frames are used.
delta_t_ps float 1.0 Time between selected trajectory frames.

Examples

Sample request payload/object:
`MSDRequest(atom_types=["O"], dims=("x", "y", "z"), frames=[0, 10, 20], every=1, origin="first", unwrap=True)`
This sample computes oxygen-atom MSD on selected frames using full 3D
displacement from the first selected frame as reference.

Task: MSDTask

Per-atom mean-squared displacement over selected frames/dimensions.

When dims contains multiple axes (for example ("x", "y", "z")), the returned msd is the sum across those axes, and dim is stored as the joined label (for example "x,y,z").

Build default presentation specs for MSD outputs.

Selects a table view and a 2D plot mapping based on available payload columns, preferring iter as x-axis when present.

Works on

Analyzer task output payloads

Parameters

Name Type Description
_result MSDResult Analysis result object for the executed task.
payload dict[str, Any] Serialized result payload used by presentation dispatch.

Returns

Type Description
list[PresentationSpec] Recommended table and plot presentation specifications.

Examples

>>> specs = MSDTask.recommended_presentations(result, payload)
>>> len(specs) >= 1
True
Sample output meaning: returned specs describe how MSD results should be
rendered (table view and, when possible, an MSD-vs-time plot).

Method: run(data: TrajectoryData, request: MSDRequest, reporter=None)

Run time-origin averaged MSD analysis.

This implementation follows the Vale 2005 Fortran-style MSD algorithm:

MSD(lag) = average over atoms and all valid time origins of
           |r(t + lag) - r(t)|^2

Unlike a simple MSD relative to the first frame, this method averages over multiple time origins, which gives smoother and more statistically stable MSD curves.

Expected optional request attributes

request.max_lag : int, optional Maximum lag in number of frames. If missing, uses all selected frames. request.delta_t_ps : float, optional Time spacing between selected trajectory frames in ps. If missing, uses 1.0 ps.

Result: MSDResult

Result payload for MSD analysis.

Stores the computed MSD table together with the request used to generate it, so downstream consumers can preserve analysis provenance.

Fields

Field Type Default Help Choices
table pd.DataFrame
request MSDRequest

Notes

When multiple dimensions are selected (for example x,y,z), msd is the summed squared displacement across those dimensions.

Examples

Sample output payload/object:
`MSDResult(table=<DataFrame rows with frame_index/iter/atom_id/atom_type/dim/msd>, request=<MSDRequest ...>)`
The output table represents per-atom MSD values at each evaluated frame,
with `dim` indicating which coordinate components were included.