Metadata-Version: 2.4
Name: dftb-rs-python
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.20
Requires-Dist: ase>=3.22 ; extra == 'ase'
Provides-Extra: ase
License-File: LICENSE
Summary: Pure-Rust density functional tight binding (DFTB1/2/3, LC-DFTB, TD-DFTB, spin, +U, dispersion) with an ASE calculator
Keywords: dftb,tight-binding,quantum-chemistry,ase,computational-chemistry
Author: ss0832
License: GPL-3.0-or-later
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Source, https://github.com/ss0832/dftb-rs

# dftb-rs

Pure-Rust density functional tight binding (DFTB).

## What it does

- **DFTB1** (non-SCC), **DFTB2** (SCC) and **DFTB3**, plus the multipole-extended
  **mDFTB2/mDFTB3**, **DFTB+U**, long-range-corrected **LC-DFTB** and **D3**
  dispersion
- **Molecular or periodic**: Γ-point and Monkhorst-Pack k-sampling with
  time-reversal reduction, Ewald electrostatics
- **Spin**: colinear, with optional constrained magnetization, and non-colinear
  two-component spinors
- **Derivatives**: analytic gradients and stress throughout; analytic Hessians
  with vibrational analysis; third derivatives; phonons at finite `q`
- **Geometry optimization**: L-BFGS at fixed cell, with the trajectory streamed
  to extended XYZ as it runs
- **Excited states**: TD-DFTB, LC-TD-DFTB, spin-flip TD-SF-DFTB and the
  non-colinear response, with analytic `∂ω/∂R` for most of them
- **Divide-and-conquer** (experimental): a linear-scaling *diagonalization* for
  DFTB1/2/3, energy and analytic gradient — 14× faster than the full solve at 384
  atoms and agreeing with it to 1e-10 Ha per atom. The electrostatics is **not**
  made linear and is the next wall
- **Interfaces**: a Rust library, a CLI, Python bindings and an ASE calculator

**[docs/scope.md](docs/scope.md) is the authoritative list** — every combination
that is supported, every one that is refused and why, and what "validated" means
here. It is worth reading before comparing a number against another code.

Where something is missing the library says so and stops, rather than returning
a number computed from a different model. The larger gaps: linear response
beyond Γ, the gradient of a non-colinear response state, the periodic
long-range-corrected Hessian, and phonons by perturbation theory rather than by
supercell.

## Using it

Rust:

```rust
use dftb_rs::model::{compute, DftbOptions};
use dftb_rs::structure::Structure;

let water = Structure::from_xyz_str("3\n\nO 0 0 0\nH 0 0.757 0.587\nH 0 -0.757 0.587\n")?;
let result = compute(&water, &DftbOptions::default())?;
println!("{:.6} Ha, gap {:.3} Ha", result.energy, result.gap().unwrap());
```

Command line:

```bash
cargo run --bin dftb_rs_cli -- energy water.xyz --level 3 --params 3ob
```

Subcommands: `energy`, `grad`, `opt`, `stress`, `freq`, `phonon`, `third`, `td`,
`td-grad`, `sf-td`, `sf-td-grad`, `params`, `info`. Divide-and-conquer is reached
from the library and the Python bindings, not the CLI.

```bash
cargo run --bin dftb_rs_cli -- opt water.xyz --traj traj.xyz --out relaxed.xyz
```

```bash
cargo run --bin dftb_rs_cli -- td-grad water.xyz --root 1
```

Python, through ASE:

```python
from ase.build import molecule
from dftb_rs.calculator import DFTB

atoms = molecule("H2O")
atoms.calc = DFTB(params="3ob", level=3)
print(atoms.get_potential_energy(), "eV")
print(atoms.get_forces())
```

or directly:

```python
import dftb_rs

result = dftb_rs.compute([8, 1, 1], [[0, 0, 0], [0, 1.430, 1.109], [0, -1.430, 1.109]])
print(result["energy"], "hartree")
```

**Units.** The library works in hartree and bohr, and `dftb_rs` — the functions
in `dftb_rs.native`, re-exported at the top level — hands them back unchanged.
The ASE calculator in `dftb_rs.calculator` is the one place a conversion
happens, because ASE means eV and Ångström by a number. If it came from
`dftb_rs`, it is atomic units; if it came from `DFTB`, it is eV/Å. Vibrational
and phonon frequencies are cm⁻¹ on both sides.

Heavy properties on the calculator — the Hessian, phonons, excited-state forces
— are computed on first request and cached against the geometry they were
computed for. Asking for an energy never triggers one.

Full API documentation: [docs/rust-api.md](docs/rust-api.md),
[docs/python-api.md](docs/python-api.md); what is and is not implemented, in
detail: [docs/scope.md](docs/scope.md).

### Building the Python package

```bash
pip install maturin
maturin develop --features python,embed-minimal
```

## Design

- **Pure Rust, `#![forbid(unsafe_code)]`** — dense linear algebra via
  [faer](https://github.com/sarah-quinones/faer-rs), special functions via
  `libm`, no LAPACK/BLAS/FFI.
- One generic SCC driver over the matrix scalar: `f64` for molecular and Γ real
  paths, `c64` for k-point sampling and non-colinear spinors.
- Charge-functional energy terms (γ, DFTB3, spin-W) compose through a
  `PotentialTerm` trait. Terms that need the density *matrix* rather than the
  charges — `+U` and long-range exchange — join the SCC iteration variables
  instead, so the mixer accelerates them. The same split runs through the
  response: a moment-space coupled-perturbed solve for the first kind, an
  iterated density-matrix one for the second.
- Two-centre kernels are written once, generically over a `Scalar` AD trait, and
  instantiated at `f64` / `Dual` / `Dual2` / `Dual3` for values, gradients,
  Hessians and third derivatives.
- Internal units: hartree and bohr.

## Testing

```bash
cargo test                      # Rust
python -m pytest python/tests   # Python bindings and the ASE calculator
```

The suite is built around independent checks rather than pinned numbers — finite
difference ladders against the analytic derivatives, sum rules, and limits that
must hold exactly. Several implementation bugs were found only because those
comparisons existed; each is recorded in the commit that fixed it.
[docs/scope.md](docs/scope.md#what-validated-means-here) sets out what is checked
and why reference numbers from another code are not the primary check.

## Parameters

Curated Slater-Koster sets are bundled with their license and provenance notices
(mio, 3ob, ob2, pbc, matsci, trans3d, rare — all CC-BY-SA 4.0 from the
[dftbparams](https://github.com/dftbparams) project). Only a minimal subset ships
in the crate and the wheel, to stay inside the crates.io size limit; fetch the
rest with `scripts/fetch_params.py` or `dftb_rs.params.fetch(...)`, then point
`DFTB_RS_PARAMS` at the result or pass a directory as the `params` option.

D3 dispersion reference data is **not** bundled: the C₆ tables are large and the
damping parameters are fitted per method, so shipping values that could not be
checked against their source would be worse than requiring
`scripts/fetch_dftd3.py`.

Sets are not interchangeable — see
[docs/scope.md](docs/scope.md#parameter-sets).

## References

The methods this implements, and where they are defined. Where the
implementation departs from a paper — or where a paper's number and this
crate's would not be comparable — [docs/scope.md](docs/scope.md) says so.

**DFTB1** — the non-SCC tight-binding basis of everything below:

- D. Porezag, Th. Frauenheim, Th. Köhler, G. Seifert, R. Kaschner, *Construction
  of tight-binding-like potentials on the basis of density-functional theory:
  Application to carbon*, Phys. Rev. B **51**, 12947 (1995).
- G. Seifert, D. Porezag, Th. Frauenheim, *Calculations of molecules, clusters,
  and solids with a simplified LCAO-DFT-LDA scheme*, Int. J. Quantum Chem. **58**,
  185 (1996).

**DFTB2 (SCC-DFTB)** and **DFTB3**:

- M. Elstner, D. Porezag, G. Jungnickel, J. Elsner, M. Haugk, Th. Frauenheim,
  S. Suhai, G. Seifert, *Self-consistent-charge density-functional tight-binding
  method for simulations of complex materials properties*, Phys. Rev. B **58**,
  7260 (1998).
- Y. Yang, H. Yu, D. York, Q. Cui, M. Elstner, *Extension of the
  self-consistent-charge density-functional tight-binding method: third-order
  expansion of the density functional theory total energy…*, J. Phys. Chem. A
  **111**, 10861 (2007).
- M. Gaus, Q. Cui, M. Elstner, *DFTB3: Extension of the self-consistent-charge
  density-functional tight-binding method (SCC-DFTB)*, J. Chem. Theory Comput.
  **7**, 931 (2011).

**mDFTB** — the atomic-multipole extension implemented here as mDFTB2/mDFTB3:

- V.-Q. Vuong, B. Aradi, A. M. N. Niklasson, Q. Cui, S. Irle, *Multipole
  expansion of atomic electron density fluctuation interactions in the
  density-functional tight-binding method*, J. Chem. Theory Comput. **19**, 7592
  (2023). [doi:10.1021/acs.jctc.3c00778](https://doi.org/10.1021/acs.jctc.3c00778)
- For the same idea in a related method: C. Bannwarth, S. Ehlert, S. Grimme,
  *GFN2-xTB — an accurate and broadly parametrized self-consistent tight-binding
  quantum chemical method with multipole electrostatics and density-dependent
  dispersion contributions*, J. Chem. Theory Comput. **15**, 1652 (2019).

**Spin**, colinear and non-colinear, and **DFTB+U**:

- C. Köhler, G. Seifert, U. Gerstmann, M. Elstner, H. Overhof, Th. Frauenheim,
  *Approximate density-functional calculations of spin densities in large
  molecular systems and complex solids*, Phys. Chem. Chem. Phys. **3**, 5109 (2001).
- C. Köhler, Th. Frauenheim, B. Hourahine, G. Seifert, M. Sternberg, *Treatment
  of collinear and noncollinear electron spin within an approximate density
  functional based method*, J. Phys. Chem. A **111**, 5622 (2007).
- B. Hourahine, S. Sanna, B. Aradi, C. Köhler, T. Niehaus, Th. Frauenheim,
  *Self-interaction and strong correlation in DFTB*, J. Phys. Chem. A **111**,
  5671 (2007).
- S. L. Dudarev, G. A. Botton, S. Y. Savrasov, C. J. Humphreys, A. P. Sutton,
  *Electron-energy-loss spectra and the structural stability of nickel oxide: an
  LSDA+U study*, Phys. Rev. B **57**, 1505 (1998).

**LC-DFTB** — the long-range correction:

- T. A. Niehaus, F. Della Sala, *Range separated functionals in the density
  functional based tight-binding method: formalism*, Phys. Status Solidi B
  **249**, 237 (2012).
- V. Lutsker, B. Aradi, T. A. Niehaus, *Implementation and benchmark of a
  long-range corrected functional in the density functional based tight-binding
  method*, J. Chem. Phys. **143**, 184107 (2015).

**TD-DFTB** — linear response, and its excited-state gradients:

- M. E. Casida, *Time-dependent density functional response theory for
  molecules*, in *Recent Advances in Density Functional Methods, Part I*, World
  Scientific (1995), p. 155 — the response equations this solves.
- T. A. Niehaus, S. Suhai, F. Della Sala, P. Lugli, M. Elstner, G. Seifert,
  Th. Frauenheim, *Tight-binding approach to time-dependent density-functional
  response theory*, Phys. Rev. B **63**, 085108 (2001).
- D. Heringer, T. A. Niehaus, M. Wanko, Th. Frauenheim, *Analytical excited state
  forces for the time-dependent density-functional tight-binding method*,
  J. Comput. Chem. **28**, 2589 (2007).
- J. J. Kranz, M. Elstner, B. Aradi, Th. Frauenheim, V. Lutsker, A. D. Garcia,
  T. A. Niehaus, *Time-dependent extension of the long-range corrected density
  functional based tight-binding method*, J. Chem. Theory Comput. **13**, 1737
  (2017) — LC-TD-DFTB.

**SF-TD-DFTB** — the spin-flip response:

- Y. Shao, M. Head-Gordon, A. I. Krylov, *The spin-flip approach within
  time-dependent density functional theory: theory and applications to
  diradicals*, J. Chem. Phys. **118**, 4807 (2003) — the formulation.
- M. Inamori, T. Yoshikawa, Y. Ikabata, Y. Nishimura, H. Nakai, *Spin-flip
  approach within time-dependent density functional tight-binding method: theory
  and applications*, J. Comput. Chem. **41**, 1538 (2020).
  [doi:10.1002/jcc.26197](https://doi.org/10.1002/jcc.26197)
- For the non-colinear response: F. Wang, T. Ziegler, *Time-dependent density
  functional theory based on a noncollinear formulation of the
  exchange-correlation potential*, J. Chem. Phys. **121**, 12191 (2004).

**Dispersion**:

- S. Grimme, J. Antony, S. Ehrlich, H. Krieg, *A consistent and accurate ab
  initio parametrization of density functional dispersion correction (DFT-D) for
  the 94 elements H-Pu*, J. Chem. Phys. **132**, 154104 (2010).
- S. Grimme, S. Ehrlich, L. Goerigk, *Effect of the damping function in
  dispersion corrected density functional theory*, J. Comput. Chem. **32**, 1456
  (2011) — Becke-Johnson damping.

**ASE** — the calculator interface in `dftb_rs.calculator` targets:

- A. Hjorth 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)

**The reference implementation**, for anyone comparing:

- B. Hourahine *et al.*, *DFTB+, a software package for efficient approximate
  density functional theory based atomistic simulations*, J. Chem. Phys. **152**,
  124101 (2020).

Slater-Koster parameter sets carry their own citations — `dftb_rs.params.citation(name)`
returns the one for a set, and the CC-BY-SA 4.0 terms ask for it.

## License

GPL-3.0-or-later. © ss0832.

Bundled Slater-Koster parameter data (under `params/`) is CC-BY-SA 4.0 — see the
per-set `LICENSE`/`NOTICE`/`SOURCE.txt` files and `THIRD_PARTY_NOTICES.md` for
attribution. CC-BY-SA 4.0 is one-way compatible with GPLv3, so the combination
distributes under the GPL while the data keeps its own terms.

