Legacy

Original pure-NumPy mean-squared-displacement and cross-displacement-correlation operators. The maintained trunk lives in Compute (e.g. molpy.compute.MSD, molpy.compute.MCDCompute); the operators here are retained for direct NDArray workflows that do not need trajectory coupling.

Quick reference

Symbol	Summary	Preferred for
MSD	Mean squared displacement	Diffusion analysis on raw arrays
msd(positions)	Convenience function for MSD	Quick MSD calculation
DisplacementCorrelation	Cross-displacement correlation	Ion transport correlations
displacement_correlation(...)	Convenience function	Quick correlation calculation

Canonical example

from molpy.legacy import MSD

msd = MSD(max_lag=3000)
msd_values = msd(unwrapped_positions)  # shape (max_lag,)

---

Full API

MSD

msd

Mean Squared Displacement computation (legacy NumPy path).

Operates on plain NDArrays — no trajectory coupling.

MSD dataclass

MSD(max_lag)

Bases: Compute

Compute mean squared displacement at each time lag.

MSD(dt) = <(r_i(t+dt) - r_i(t))^2>_{i, t}

Parameters:

Name	Type	Description	Default
max_lag	int	Maximum time lag in frames.	required

Examples:

Self-diffusion::

cation_coords = unwrapped[:, cation_mask, :]  # (n_frames, n_cations, 3)
msd = MSD(max_lag=3000)
msd_values = msd(cation_coords)               # -> NDArray (max_lag,)

Polarization MSD (no dedicated class needed)::

polarization = (
    coords[:, cat_mask, :].sum(axis=1)
    - coords[:, an_mask, :].sum(axis=1)
)  # (n_frames, 3)
pmsd_values = msd(polarization[:, None, :])    # -> NDArray (max_lag,)

run

run(positions)

Compute MSD from positions.

Parameters:

Name	Type	Description	Default
positions	NDArray	Coordinate array with shape (n_frames, n_particles, n_dim). For polarization MSD, reshape a (n_frames, 3) vector to (n_frames, 1, 3).	required

Returns:

Type	Description
NDArray	MSD values at each time lag, shape (max_lag,).

msd

msd(positions, *, max_lag)

Compute MSD. Shorthand for MSD(max_lag=max_lag)(positions).

Cross-Displacement Correlation

cross_correlation

Cross-displacement correlation computation (legacy NumPy path).

Operates on plain NDArrays — no trajectory coupling.

DisplacementCorrelation dataclass

DisplacementCorrelation(max_lag, exclude_self=False)

Bases: Compute

Compute cross-displacement correlation between two groups.

For two groups A and B the correlation at time lag dt is:

C(dt) = <sum_i dr_i^A(dt) . sum_j dr_j^B(dt)> / N_A

where dr_i(dt) = r_i(t+dt) - r_i(t).

When exclude_self=True and both inputs are the same species, the self-terms are subtracted so only distinct correlations remain:

C_distinct(dt) = <dr_i . (sum_j dr_j - dr_i)>_{i, t}

Parameters:

Name	Type	Description	Default
max_lag	int	Maximum time lag in frames.	required
exclude_self	bool	If True, subtract self-correlation (for same-species distinct diffusion).	False

Examples:

Cross-species (cation-anion)::

xdc = DisplacementCorrelation(max_lag=3000)
corr = xdc(cation_coords, anion_coords)  # -> NDArray (max_lag,)

Same-species distinct (exclude self-correlation)::

xdc = DisplacementCorrelation(max_lag=3000, exclude_self=True)
corr = xdc(cation_coords, cation_coords)  # -> NDArray (max_lag,)

run

run(positions_a, positions_b)

Compute displacement correlation.

Parameters:

Name	Type	Description	Default
positions_a	NDArray	Coordinates of group A, shape (n_frames, n_a, n_dim).	required
positions_b	NDArray	Coordinates of group B, shape (n_frames, n_b, n_dim).	required

Returns:

Type	Description
NDArray	Correlation values at each time lag, shape (max_lag,).

displacement_correlation

displacement_correlation(positions_a, positions_b, *, max_lag, exclude_self=False)

Compute displacement correlation.

Shorthand for DisplacementCorrelation(max_lag=max_lag, exclude_self=exclude_self)(positions_a, positions_b).