Ripple-hpc 1.4.1

High-performance molecular dynamics trajectory analysis (RDF, SSF, VHF, ISF, four-point functions, diffusion and non-Gaussian metrics).

Ripple

Ripple is a high-performance Python package for molecular dynamics trajectory analysis. It turns ASE-compatible trajectories into reusable NumPy memory-mapped caches and evaluates structural, dynamical, diffusion, non-Gaussian, and four-point correlation observables with threaded C++ kernels.

The package is designed for repeated analysis of large trajectories on workstations and high-performance computing systems. A trajectory is prepared once, written to a compact cache, and then reused by multiple calculations without rereading the original trajectory file.

Installation

pip install ripple-hpc

Ripple requires Python 3.10+. The only hard runtime dependency is NumPy. Prebuilt wheels are published for the supported CPython versions; source builds require a C++17 compiler and CMake.

What It Computes

• Pair structure:
  • radial distribution functions for same-species or cross-species pairs
  • shell-averaged partial static structure factors in reciprocal space
• Single-particle dynamics:
  • self part of the van Hove correlation function
  • self part of the intermediate scattering function
• Distinct-particle dynamics:
  • distinct part of the van Hove correlation function
  • distinct part of the intermediate scattering function
• Diffusion and transport:
  • mean-squared displacement tensor curves
  • collective mean-squared displacement tensor curves
  • diffusion tensor fitting by ordinary least squares or generalized least squares
• Non-Gaussian displacement statistics:
  • lag-resolved scalar non-Gaussian parameter alpha_2(t)
  • fourth-order displacement cumulant tensor kappa_4(t)
  • directional and covariance-whitened summaries of the fourth-order cumulant
• Dynamic heterogeneity and four-point correlations:
  • four-point dynamic susceptibility chi_4(t)
  • real-space four-point correlation function G_4(r,t)
  • shell-averaged four-point structure factor S_4(q,t)

Mathematical Reference

The formulas below use plain text notation for consistent rendering on package indexes. Ripple applies shell averaging, selected-lag averaging, and normalization inside the calculation methods.

Density mode:
rho_A(q,t) = sum_{i in A} exp[i q . r_i(t)]

Radial distribution function:
g_AB(r) = < sum_{i in A} sum_{j in B}' delta(r - |r_j - r_i|) >
          / [rho_B shell_measure(r)]

Partial static structure factor:
S_AA(q) = < |rho_A(q,t)|^2 / N_A >
S_AB(q) = < Re[rho_A(q,t) rho_B(q,t)^*] / sqrt(N_A N_B) >

Self van Hove correlation function:
G_s(r,t) = < delta(r - |r_i(t0 + t) - r_i(t0)|) >

Distinct van Hove correlation function:
G_d(r,t) = < sum_{i in A} sum_{j in B}'
                 delta(r - |r_j(t0 + t) - r_i(t0)|) >

Self intermediate scattering function:
F_s(q,t) = < exp[i q . (r_i(t0 + t) - r_i(t0))] >

Distinct intermediate scattering function:
F_d(q,t) = < Re[rho_A(q,t0) rho_B(q,t0 + t)^*] >

Mean-squared displacement tensor:
M_self(t) = < Delta r_i(t) Delta r_i(t)^T >

Collective mean-squared displacement tensor:
M_collective(t) = (1 / N) < Delta R(t) Delta R(t)^T >
Delta R(t) = sum_i Delta r_i(t)

Diffusion tensor model:
M(t) = 2 D t + C

Scalar non-Gaussian parameter:
alpha_2(t) = 3 < |Delta r(t)|^4 > / [5 < |Delta r(t)|^2 >^2] - 1

Fourth-order displacement cumulant tensor:
kappa_4,ijkl(t) =
    < delta r_i delta r_j delta r_k delta r_l >
  - < delta r_i delta r_j >< delta r_k delta r_l >
  - < delta r_i delta r_k >< delta r_j delta r_l >
  - < delta r_i delta r_l >< delta r_j delta r_k >

Binary mobility field for four-point correlations:
c_i(t0,t; a) = Theta(|r_i(t0 + t) - r_i(t0)| - a)
delta c_i(t0,t) = c_i(t0,t; a) - <c(t)>

Four-point dynamic susceptibility:
chi_4(t) = N Var_t0[(1 / N) sum_i c_i(t0,t; a)]

Real-space four-point correlation function:
G_4(r,t) = < sum_{i != j} delta c_i(t0,t) delta c_j(t0,t)
                 delta(r - |r_j(t0) - r_i(t0)|) >

Four-point structure factor:
S_4(q,t) = (1 / N) < |sum_i delta c_i(t0,t) exp[i q . r_i(t0)]|^2 >

Basic Workflow

Ripple uses a two-step workflow:

1. memmap_create(...) reads trajectory frames and writes one reusable PreparedTrajectory cache.
2. *_cal(prepared, ...) derives any observable-specific memmaps it needs, runs the compiled kernel, and returns a typed result object.

Use memmap_load(...) with the same save_dir and trajectory_tag to reuse an existing cache without rereading the original trajectory.

Minimal Example

from ase.io import iread

from ripple import alpha2_cal, memmap_create, msd_cal, rdf_cal

traj = lambda: iread("trajectory.extxyz", format="extxyz", index=":")
species = "Li"

prepared = memmap_create(
    traj,
    n_frames=1000,
    save_dir="ripple_cache",
    trajectory_tag="run_001",
    pos_dtype="float64",
)
rdf = rdf_cal(
    prepared,
    target_atoms1=species,
    target_atoms2=species,
    mode="abc",
    r_max=10.0,
    dr=0.05,
    n_workers=8,
)
print(rdf.bins, rdf.rdf)

msd = msd_cal(
    prepared,
    target_atoms=species,
    timestep_ps=0.1,
    n_workers=8,
    drift_correction="framework_equal",
)
alpha2 = alpha2_cal(
    prepared,
    target_atoms=species,
    timestep_ps=0.1,
    n_workers=8,
    drift_correction="framework_equal",
)
fit = msd.diffusion_tensor(method="ols")
print(msd.msd_tensor.shape, alpha2.alpha2.shape, fit.D_tensor)

Public Entry Points

• Prepare/load: memmap_create(...), memmap_load(...), returning PreparedTrajectory.
• Radial distribution function: rdf_cal(prepared, ...).
• Static structure factor: ssf_cal(prepared, ...).
• Self and distinct van Hove correlation functions: vhf_self_cal(prepared, ...) and vhf_distinct_cal(prepared, ...).
• Self and distinct intermediate scattering functions: isf_self_cal(prepared, ...) and isf_distinct_cal(prepared, ...).
• Mean-squared displacement, collective mean-squared displacement, and non-Gaussian displacement statistics: msd_cal(prepared, ...), cmsd_cal(prepared, ...), alpha2_cal(prepared, ...), and kappa4_cal(prepared, ...).
• Four-point dynamic susceptibility, real-space four-point correlation function, and four-point structure factor: chi4_cal(prepared, ...), G4_cal(prepared, ...), and S4_cal(prepared, ...).

Notes

• Trajectories may be passed as sequences, iterables with n_frames, or factories such as lambda: ase.io.iread(...).
• Radial real-space calculations support one-, two-, and three-dimensional periodic subspaces through the mode argument. Reciprocal-space structure factors require full three-dimensional periodic boundary conditions.
• Static-cell trajectories store one cell frame in the cache. Variable-cell trajectories store the cell for every frame and the kernels account for the changing geometry.
• Periodic analyses validate the required periodic axes before entering the C++ kernels.
• The diffusion module requires continuous unwrapped trajectory coordinates. It uses Atoms.positions directly and does not unwrap periodic images during preparation.
• PreparedTrajectory.clean() removes the full cache directory owned by the object, including main cache files and lazily generated derived memmaps.

License

MIT. See LICENSE.