Metadata-Version: 2.2
Name: Ripple-hpc
Version: 1.5.0
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 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

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

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

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