Ripple-hpc 1.3.5

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 combines ASE-compatible trajectory input, reusable NumPy memmap caches, and threaded C++ kernels for large workstation and HPC workflows.

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

• RDF: radial distribution function
• SSF: static structure factor
• VHF: self and distinct van Hove functions
• ISF: self and distinct intermediate scattering functions
• Diffusion: MSD, cMSD, OLS/GLS diffusion tensor fits
• Non-Gaussian metrics: alpha2 and fourth-order cumulant tensor kappa4
• Four-point dynamics: chi4(t), G4(r,t), and S4(q,t)

Basic Workflow

Ripple uses a two-step workflow:

1. prepare_* reads trajectory frames and writes reusable cache files.
2. *_cal() runs the compiled kernel and returns a typed result object.

Use reuse_memmap=True with a stable trajectory_tag when running several analyses on the same trajectory.

Minimal Example

from ase.io import iread

from ripple.prepare_diffusion import prepare_diffusion
from ripple.prepare_rdf import prepare_rdf

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

rdf_job = prepare_rdf(
    traj,
    target_atoms1=species,
    target_atoms2=species,
    n_frames=1000,
    save_dir="ripple_cache",
    trajectory_tag="run_001",
    reuse_memmap=True,
)
rdf = rdf_job.rdf_cal(mode="abc", r_max=10.0, dr=0.05, n_workers=8)
print(rdf.bins, rdf.rdf)

diff_job = prepare_diffusion(
    traj,
    target_atoms=species,
    timestep_ps=0.1,
    n_frames=1000,
    save_dir="ripple_cache",
    trajectory_tag="run_001",
    reuse_memmap=True,
)
msd = diff_job.msd_cal(n_workers=8)
alpha2 = diff_job.alpha2_cal(n_workers=8)
fit = msd.diffusion_tensor(method="ols")
print(msd.msd_tensor.shape, alpha2.alpha2.shape, fit.D_tensor)

Public Entry Points

Observable	Preparation function	Main calculation methods
RDF	prepare_rdf	rdf_cal
SSF	prepare_ssf	ssf_cal
VHF	prepare_vhf_self, prepare_vhf_distinct	vhf_self_cal, vhf_distinct_cal
ISF	prepare_isf_self, prepare_isf_distinct	isf_self_cal, isf_distinct_cal
Diffusion	prepare_diffusion	msd_cal, cmsd_cal, alpha2_cal, kappa4_cal
Four-point dynamics	prepare_4pcf	chi4_cal, G4_cal, S4_cal

Notes

• Trajectories may be passed as sequences, iterables with n_frames, or factories such as lambda: ase.io.iread(...).
• 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.
• Prepared objects provide .clean() to remove their cache directory.

License

MIT. See LICENSE.