Ripple-hpc 1.5.0

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 prepares ASE-compatible trajectories as reusable NumPy memmap caches and evaluates structural, dynamical, diffusion, non-Gaussian, and four-point correlation observables with threaded C++ kernels.

The package is intended for repeated analysis of large trajectories on workstations and HPC systems: prepare once, reuse the cache, and compute several observables without rereading the original trajectory.

Installation

python -m pip install ripple-hpc

Ripple requires Python 3.10+ and NumPy at runtime. Source builds require a C++17 compiler and CMake; binary wheels are provided for supported CPython versions.

Documentation

Full usage documentation is available in docs/, including cache preparation, atom selections, observable-specific guides, examples, and API reference pages. Build the local HTML documentation with:

python -m pip install -r docs/requirements.txt
python -m sphinx -b html docs docs/_build/html

Basic Workflow

Ripple uses a two-step workflow.

1. Prepare or load a trajectory cache with memmap_create(...) or memmap_load(...). Each cache is identified by a user-supplied trajectory_tag.
2. Pass the resulting PreparedTrajectory to analysis functions such as rdf_cal(...), msd_cal(...), or isf_self_cal(...).

from ase.io import iread

from ripple import memmap_create, rdf_cal, msd_cal, alpha2_cal

frames = lambda: iread("trajectory.extxyz", format="extxyz", index=":")

prepared = memmap_create(
    frames,
    save_dir="ripple_cache",
    trajectory_tag="run_001",
    n_frames=1000,
    pos_dtype="float64",
)

rdf = rdf_cal(
    prepared,
    target_atoms1="Li",
    target_atoms2="Li",
    mode="abc",
    r_max=10.0,
    dr=0.05,
    n_workers=8,
)

msd = msd_cal(
    prepared,
    target_atoms="Li",
    timestep_ps=0.1,
    drift_correction="off",
    n_workers=8,
)

alpha2 = alpha2_cal(
    prepared,
    target_atoms="Li",
    timestep_ps=0.1,
    drift_correction="off",
    n_workers=8,
)

fit = msd.diffusion_tensor(method="ols")
print(rdf.rdf.shape, msd.msd_tensor.shape, alpha2.alpha2.shape, fit.D_tensor)

Observables

Ripple currently provides:

• Pair structure: rdf_cal(...), ssf_cal(...).
• Self and distinct dynamics: vhf_self_cal(...), vhf_distinct_cal(...), isf_self_cal(...), isf_distinct_cal(...).
• Diffusion and displacement statistics: msd_cal(...), cmsd_cal(...), alpha2_cal(...), kappa4_cal(...).
• Dynamic heterogeneity: chi4_cal(...), G4_cal(...), S4_cal(...).

All functions return typed result objects containing the computed arrays, lag/time axes where applicable, and metadata needed to interpret the result.

Selections and Caches

Atoms can be selected by species labels, such as target_atoms="Li", or by explicit zero-based indices, such as target_indices=[0, 4, 7].

The full unwrapped Cartesian trajectory is stored once in the main cache. Correlation kernels read selected atoms from that cache by contiguous spans when possible, or by explicit index arrays otherwise. This avoids materializing a separate unwrapped Cartesian memmap for every atom selection.

Some analyses still create observable-specific derived caches, such as scaled wrapped coordinates, drift centers, summed positions, or reciprocal-space sampling grids. These files are part of the prepared cache and are reused when valid.

Practical Notes

• Input frames should be ASE Atoms objects or ASE-compatible frame sequences.
• Atoms.positions are treated as continuous unwrapped Cartesian coordinates for diffusion and displacement observables. Ripple does not reconstruct unwraps from wrapped trajectories during preparation.
• Diffusion analyses can subtract a framework drift reference when appropriate; use drift_reference_indices for explicit control.
• Real-space radial observables support one-, two-, and three-dimensional periodic subspaces through the mode argument. Reciprocal-space observables require full three-dimensional periodic boundary conditions.
• Static-cell trajectories store one cell frame; variable-cell trajectories store one cell per frame and are handled by the kernels.
• validate_main_cache(...) checks whether a prepared cache is valid without loading the original trajectory.
• PreparedTrajectory.clean() removes the cache directory owned by the object.

License

MIT. See LICENSE.