Skip to content

MSD and the local exponent

msd computes the mean-squared displacement of the mobile species and the local exponent alpha(t) = d log(MSD) / d log(t). Treat it as a diagnostic of which diffusion regime the trajectory is in, not as a diffusivity.

mliport analyze runs/md msd --mobile Li --axes xyz

--mobile is required. If you analyze an external trajectory, say whether its coordinates are wrapped or unwrapped (--positions-convention) and give the saved frame spacing (--frame-interval-fs) when the metadata lacks it; with missing information mliport fails rather than assume.

Options you will use

Option Meaning
--mobile SPECIES the mobile species (required)
--axes x, y, z or a combination such as xy or xyz (default xyz)
--drift-reference, --drift-mode, --drift-indices how framework drift is removed: reference none, nonmobile, all or indices; mode none, arithmetic_mean or mass_weighted_com (default)
--start-frame, --stop-frame, --include-equilibration the analysis window
--method fft\|direct the MSD algorithm (default fft)
--fit-start-ps, --fit-stop-ps a fit window, recorded with the result
--alpha-window-decades full width of the local log–log regression window (default 0.25)
--alpha-min-points, --alpha-min-origins minimum points in a window (5) and time origins for an alpha point to count (8)
--alpha-consistency-band half-band around alpha = 1 accepted as diffusive (default 0.2)
--alpha-max-lag-ps ignore longer lags for alpha only; the raw MSD is untouched
--alpha-focus-band LOW HIGH, --alpha-log-x plot options: zoom the alpha figure, use a log time axis

Reading alpha

alpha ≈ 1 is consistent with Fickian diffusion, alpha < 1 with subdiffusion and alpha > 1 with superdiffusive or ballistic motion, but only inside the time window you fitted. A point outside the consistency band is marked not_diffusive; one with too few time origins is reported as insufficient support, not as an exponent. Read the whole alpha curve with its band, never a single number.

Other things that matter:

  • Drift removal changes the long-time MSD, so state the drift policy.
  • MSD is a statistical estimator. Report several fit windows or an uncertainty, not one fit.
  • Alpha is not a conductivity verdict. Conductivity needs the charge, collective correlations and a Nernst–Einstein treatment; use Transport.
mliport analyze runs/md-800K msd --mobile Li --axes xyz \
  --drift-reference nonmobile --drift-mode mass_weighted_com \
  --fit-start-ps 50 --fit-stop-ps 400 --alpha-focus-band 0.8 1.2

Short trajectories

A 5-step smoke trajectory is accepted. The result carries an explicit "insufficient diffusive window" status and the alpha and diagnostic fields stay finite. The acceptance suite treats that as an expected limitation, never as a diffusion measurement. For a real MSD give the run at least a few hundred saved frames and let the fit window cover a diffusive regime.

The results are written to results.json and the MSD and alpha tables and plots under <run>/analysis/msd/<analysis-id>/, including the exact fit and alpha windows that were used.