Metadata-Version: 2.4
Name: cuRDF
Version: 0.2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: torch>=2.8.0
Requires-Dist: nvalchemi-toolkit-ops>=0.2.0
Requires-Dist: MDAnalysis
Requires-Dist: ase
Requires-Dist: matplotlib
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# cuRDF

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1085332119.svg)](https://doi.org/10.5281/zenodo.1085332119) [![PyPI](https://img.shields.io/pypi/v/cuRDF.svg)](https://pypi.org/project/cuRDF/)


CUDA-accelerated radial distribution functions using [NVIDIA ALCHEMI Toolkit-Ops](https://github.com/NVIDIA/nvalchemi-toolkit-ops) O(N) neighbor lists and PyTorch. Compatible with ASE Atoms or MDAnalysis Universe objects.

## Install
Latest release:
```
pip install cuRDF
```
For development:
```
git clone https://github.com/joehart2001/curdf.git
cd curdf
pip install -e .
```

## Quickstart
ASE Atoms object:
```python
from ase.io import read
from curdf import rdf

# Load trajectory or frame e.g. XYZ, extxyz, traj, LAMMPS data/dump
atoms = read("md_run.extxyz")

# Compute RDF between species C and O from 1.0 to 8.0 Å
bins, gr = rdf(
  atoms,
  species_a="C",
  species_b="O", # species b can be the same as species a
  r_min=1.0,
  r_max=8.0,
  nbins=200 # resolution of rdf histogram binning
)
```



MDAnalysis Universe (topology and trajectory):
```python
import MDAnalysis as mda
from curdf import rdf

u = mda.Universe("topology.data", "traj.dcd")
bins, gr = rdf(u, species_a="C", species_b="O", r_min=1.0, r_max=8.0, nbins=200)
```

## CLI
ASE (XYZ/extxyz/traj/LAMMPS data or dump)
```
curdf --file structure.xyz --species-a C --species-b O --min 1 --max 8 --nbins 200 --device cuda
```

LAMMPS dump (lammpstrj) via MDAnalysis:
```
curdf --file dump.lammpstrj --species-a C --species-b O --min 1 --max 8 --nbins 200 --device cuda
```

MDAnalysis:
```
curdf --topology top.data --trajectory traj.dcd --species-a C --species-b C --min 1 --max 8 --nbins 200 --device cuda --out results/rdf.npz --plot results/rdf.png
# If the LAMMPS data file needs a specific atom_style, pass --atom-style "id type x y z" (default)
# If the LAMMPS data file lacks atom names, map types to elements: --atom-types "1:C,2:O"
```

`--no-wrap` leaves coordinates unwrapped if you already wrapped them upstream. Half-fill is chosen automatically based on species (same-species → half-fill).

## Citation
If you use cuRDF in your work, please cite:
```
@software{cuRDF,
  author    = {Hart, Joseph},
  title     = {cuRDF: GPU-accelerated radial distribution functions},
  month     = dec,
  year      = 2025,
  publisher = {Zenodo},
  version   = {0.1.0},
  doi       = {10.5281/zenodo.1085332119},
  url       = {https://doi.org/10.5281/zenodo.1085332119}
}
```
