Metadata-Version: 2.4
Name: rust_dftb
Version: 0.1.1
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Dist: numpy>=1.23
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: maturin>=1.5,<2 ; extra == 'dev'
Requires-Dist: ruff>=0.5 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'test'
Provides-Extra: dev
Provides-Extra: test
License-File: LICENSE
Summary: Rust/Rayon implementation for DFTB calculations.
Author: ss0832
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Rust_DFTB

`rust_dftb` is a Rust/Rayon implementation for DFTB-style calculations with a Python interface.  The repository is intended for development and verification of the Rust backend, Python API, and ASE wrapper.

This package does **not** bundle Slater-Koster parameter files.  Pass an external directory containing `.skf` files through `skf_dir`.

## Requirements

- Python >= 3.10
- Rust toolchain >= 1.76, including `cargo`
- `maturin >= 1.5,<2`
- NumPy >= 1.23
- A BLAS/LAPACK backend
- Optional: ASE, for `rust_dftb.ase` and the ASE examples

The default Cargo feature set uses `openblas-system`, so the build expects system OpenBLAS with CBLAS/LAPACKE headers and libraries.  On Debian/Ubuntu-like systems this usually means installing the OpenBLAS development package before building.


## Development install

```bash
python -m pip install -U pip maturin numpy
maturin develop --release --features python
```

For ASE support:

```bash
python -m pip install ase
```

For tests and development tools:

```bash
python -m pip install -e ".[dev]"
python -m pytest
cargo test
```

## Minimal Python API example

```python
import numpy as np
from rust_dftb import DftbCalculator, backend_info

z = np.array([1, 1], dtype=np.int64)
positions = np.array(
    [[0.0, 0.0, 0.0], [0.74, 0.0, 0.0]],
    dtype=np.float64,
)

print(backend_info())

calc = DftbCalculator(skf_dir="/path/to/skf", order=2, parallel=True)
print(calc.energy(z, positions))
print(calc.forces(z, positions))
```

For periodic calculations, pass a cell in Angstrom:

```python
cell = np.eye(3) * 20.0
print(calc.energy(z, positions, cell_angstrom=cell))
print(calc.stress(z, positions, cell_angstrom=cell))
```

## Minimal ASE example

```python
from ase import Atoms
from rust_dftb.ase import ase_calculator

atoms = Atoms("H2", positions=[[0.0, 0.0, 0.0], [0.74, 0.0, 0.0]])
atoms.calc = ase_calculator(skf_dir="/path/to/skf", order=2, parallel=True)

print(atoms.get_potential_energy())
print(atoms.get_forces())
```

ASE-facing quantities use ASE conventions: positions and cells in Angstrom, energies in eV, forces in eV/Angstrom, and stress in eV/Angstrom^3.  The lower-level Python API uses the native units documented in the implementation and examples.

## Examples

More complete usage examples are in `examples/`:

```bash
python examples/python_api_all_levels.py --skf-dir /path/to/skf --structure water
python examples/ase_all_levels.py --skf-dir /path/to/skf --structure methane --levels dftb2
```

See `examples/README.md` for the longer walkthroughs.

## References

The implementation and examples in this repository are related to the following DFTB, SCC-DFTB, DFTB3, multipole-extended DFTB, and ASE references.

1. D. Porezag, T. Frauenheim, T. Köhler, G. Seifert, and R. Kaschner,
   “Construction of tight-binding-like potentials on the basis of density-functional theory:
   Application to carbon,” *Phys. Rev. B* **51**, 12947 (1995).
   DOI: [`10.1103/PhysRevB.51.12947`](https://doi.org/10.1103/PhysRevB.51.12947).

2. M. Elstner, D. Porezag, G. Jungnickel, J. Elsner, M. Haugk, T. Frauenheim,
   S. Suhai, and G. Seifert, “Self-consistent-charge density-functional tight-binding method
   for simulations of complex materials properties,” *Phys. Rev. B* **58**, 7260 (1998).
   DOI: [`10.1103/PhysRevB.58.7260`](https://doi.org/10.1103/PhysRevB.58.7260).

3. M. Gaus, Q. Cui, and M. Elstner, “DFTB3: Extension of the self-consistent-charge
   density-functional tight-binding method (SCC-DFTB),” *J. Chem. Theory Comput.* **7**,
   931-948 (2011). DOI: [`10.1021/ct100684s`](https://doi.org/10.1021/ct100684s).

4. V.-Q. Vuong, T. W. Williams, J. Li, Q. Cui, and I. S. Ufimtsev,
   “Multipole expansion of atomic electron density fluctuation interactions in the
   density-functional tight-binding method,” *J. Chem. Theory Comput.* **19**, 8152-8171
   (2023). DOI: [`10.1021/acs.jctc.3c00778`](https://doi.org/10.1021/acs.jctc.3c00778).

5. A. H. Larsen et al., “The atomic simulation environment — a Python library for working
   with atoms,” *J. Phys.: Condens. Matter* **29**, 273002 (2017).
   DOI: [`10.1088/1361-648X/aa680e`](https://doi.org/10.1088/1361-648X/aa680e).

## License

GPL-3.0-or-later.

