Skip to content

Diffusivity Analysis

Estimate diffusivity from trajectory MSD using Einstein-relation fitting.

This module computes diffusion coefficients by fitting mean-squared displacement trends over selected frames and dimensions. It is scoped to diffusivity estimation and relies on MSD-derived displacement data.

Usage context

  • Transport studies: Estimate diffusion constants for selected atom sets.
  • Comparative analysis: Compare diffusivity across atom types or conditions.
  • Kinetic reporting: Export fit-ready diffusivity tables and slopes.

Request: DiffusivityRequest

Request payload for diffusivity analysis via Einstein relation.

Defines atom selection, frame sampling, MSD dimensional setup, and fitting dimensionality used to estimate diffusion coefficients.

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 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.
d float 3.0 Einstein relation dimensionality in MSD = 2dD*t.
unwrap bool True Unwrap coordinates across periodic boundaries when cell data is available.
max_lag Optional[int] Maximum lag in number of selected frames for MSD fitting.
delta_t_ps float 1.0 Time between selected trajectory frames.

Examples

req = DiffusivityRequest(atom_types=["Li"], dims=("x", "y", "z"), d=3.0)

Sample output: DiffusivityRequest(...) Meaning: The request configures per-atom diffusivity estimation for selected atoms.

Task: DiffusivityTask

Estimate per-atom diffusivity using Einstein's relation.

Einstein relation: MSD(t) = 2 * d * D * t

Build default table/plot presentations for diffusivity outputs.

Works on

Analyzer task output payloads

Parameters

Name Type Description
_result DiffusivityResult 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 grouped atom-diffusivity plot views.

Examples

specs = DiffusivityTask.recommended_presentations(result, payload)

Sample output: A list with a table view and a diffusivity-by-atom plot view. Meaning: UIs can render diffusivity results with default mappings.

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

Estimate diffusivity from time-origin averaged MSD.

Uses MSD = 2 * d * D * t, so D = slope / (2*d).

Result: DiffusivityResult

Result payload for diffusivity estimation.

Stores fit-derived diffusion metrics per atom together with the request configuration used to produce them.

Fields

Field Type Default Help Choices
table pd.DataFrame
request DiffusivityRequest

Examples

result = DiffusivityTask().run(data, req)
result.table[["atom_id", "diffusivity"]]

Sample output: DataFrame rows mapping each selected atom to a diffusion coefficient. Meaning: Each row summarizes one linear MSD fit and the resulting D estimate.