Metadata-Version: 2.2
Name: Ripple-hpc
Version: 1.4.2
Summary: High-performance molecular dynamics trajectory analysis (RDF, SSF, VHF, ISF, four-point functions, diffusion and non-Gaussian metrics).
Author: Frost research group
License: MIT License
         
         Copyright (c) 2025 Frost research group
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Project-URL: Homepage, https://github.com/Lucius2019/Ripple-hpc
Project-URL: Source, https://github.com/Lucius2019/Ripple-hpc
Project-URL: Issues, https://github.com/Lucius2019/Ripple-hpc/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26.4
Description-Content-Type: text/markdown

# Ripple

[![PyPI version](https://img.shields.io/pypi/v/ripple-hpc.svg)](https://pypi.org/project/ripple-hpc/)
[![Python versions](https://img.shields.io/pypi/pyversions/ripple-hpc.svg)](https://pypi.org/project/ripple-hpc/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

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

```bash
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.

```text
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

```python
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](LICENSE).
