Metadata-Version: 2.4
Name: cp2k-rs
Version: 0.3.0
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
Requires-Dist: numpy>=1.20.0
Requires-Dist: ase>=3.22 ; extra == 'ase'
Requires-Dist: torch>=2.7 ; extra == 'skala'
Provides-Extra: ase
Provides-Extra: skala
License-File: LICENSE
License-File: NOTICE
Summary: Python bindings for CP2K quantum chemistry package via Rust
Home-Page: https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs
Author: Nils Holle
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://gitlab.git.nrw/uni-ms/ag-salinga/cp2k-rs/-/blob/main/CHANGELOG.md
Project-URL: Documentation, https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs
Project-URL: Homepage, https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs
Project-URL: Issue Tracker, https://gitlab.git.nrw/uni-ms/ag-salinga/cp2k-rs/-/work_items
Project-URL: Repository, https://gitlab.git.nrw/uni-ms/ag-salinga/cp2k-rs

# cp2k-rs

Rust and Python bindings for [CP2K](https://www.cp2k.org/), the
electronic-structure and *ab initio* molecular-dynamics package.

**[Documentation](https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs)** ·
[Examples](https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs/examples.html) ·
[Changelog](CHANGELOG.md) ·
[Issues](https://gitlab.git.nrw/uni-ms/ag-salinga/cp2k-rs/-/work_items)

```bash
pip install "cp2k-rs[ase]"
```

```python
from ase.build import molecule
from ase.optimize import BFGS
from cp2k_rs.ase import CP2K

atoms = molecule("H2O")
atoms.center(vacuum=4.0)

with CP2K(nproc=4) as calc:           # CP2K on 4 MPI ranks
    atoms.calc = calc
    BFGS(atoms).run(fmax=0.05)        # each step reuses the force environment
```

No CP2K installation, no BLAS/LAPACK/FFTW/ScaLAPACK to build, no `mpi4py` in your
script.

## What it gives you

**One command to install.** The wheel is ~0.6 MB; a pre-built, statically linked
worker binary carrying CP2K and its whole numerical stack is fetched on first
use. The default CPU worker needs only your C library and host MPI; CUDA/ROCm
workers additionally need their matching runtime, and the opt-in Skala worker
needs a compatible PyTorch installation.

**MPI without mpi4py.** CP2K runs in a separate worker process. Rank 0 talks to
your Python process over a Unix-domain socket and broadcasts commands to the
other ranks, so an ordinary script drives a fully parallel calculation.

**Errors you can catch.** Most `libcp2k` functions return `void` and call
`MPI_ABORT` on failure. cp2k-rs isolates CP2K, detects the abort and raises a
typed exception instead of taking your process down with it.

**More than energies and forces.** Eigenvalues, HOMO–LUMO gaps, Mulliken and
Hirshfeld charges, the electron density on the real-space grid, MO coefficients,
and the AO overlap and Kohn–Sham matrices — dense or sparse, at Γ and at
arbitrary k-points.

For advanced calculations, Python can also render a complete typed CP2K input
tree. The package includes GauXC and SIRIUS plane-wave DFT, plus optional static
backends such as DFT-D4, tblite, PLUMED, GreenX, TREXIO and libvdwxc.

## Supported platforms

**Linux on x86-64 (glibc), with MPI on the host.** macOS and Windows are not
supported: the worker links CP2K, OpenBLAS, ScaLAPACK, ELPA, SIRIUS and about
twenty other libraries statically against glibc and the GCC Fortran runtime.

```bash
sudo dnf install openmpi && module load mpi/openmpi-x86_64   # Fedora / RHEL
sudo apt install openmpi-bin libopenmpi3                     # Debian / Ubuntu
```

Published worker variants: `v3` (AVX2, default), `v4` (AVX-512), CUDA, ROCm, and
Skala for machine-learned functionals. See
[Installation](https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs/installation.html).

## Using it from Rust

```rust
use cp2k_rs::{init, finalize, ForceEnv};

init()?;
let mut force_env = ForceEnv::new("input.inp", "output.out")?;
force_env.calc_energy_force()?;
println!("{:.10} Ha", force_env.get_potential_energy()?);
finalize()?;
```

```toml
cp2k-rs = { version = "0.3", features = ["mpi", "extended", "build-cp2k"] }
```

See [Using cp2k-rs from Rust](https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs/rust.html).

## Building from source

Only needed to develop cp2k-rs or to target an architecture with no published
worker — `pip install cp2k-rs` is the supported path for using it.

```bash
module load mpi/openmpi-x86_64
cargo build --release --features mpi,extended,build-cp2k
```

The first build compiles CP2K and every dependency from source: ~8 GB of disk and
10–15 minutes. Full instructions, build-control variables and GPU builds are in
[Building from source](https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs/building.html).

`NOTICE` lists every statically linked library with its version and upstream
source.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and the
[test guide](https://uni-ms.pages.git.nrw/ag-salinga/cp2k-rs/testing.html).
Bug reports and merge requests are welcome on
[GitLab](https://gitlab.git.nrw/uni-ms/ag-salinga/cp2k-rs).

## Citing

See [CITATION.cff](CITATION.cff). Please cite CP2K itself as well — cp2k-rs is
an interface, and the science is CP2K's.

## License

GPL-2.0-or-later, the same as CP2K. Bundled dependencies keep their own
licenses; see `NOTICE`.

