Metadata-Version: 2.4
Name: gfn0-rs-python
Version: 0.4.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.24
Requires-Dist: ase>=3.22
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: THIRD_PARTY_RUST_NOTICES.md
License-File: third_party/dftd4/COPYING
License-File: third_party/dftd4/COPYING.LESSER
License-File: third_party/xtb/COPYING
License-File: third_party/xtb/COPYING.LESSER
License-File: third_party/xtb-srb/COPYING
License-File: third_party/xtb-srb/COPYING.LESSER
License-File: third_party/mctc-lib/LICENSE
License-File: third_party/multicharge/LICENSE
Summary: Unofficial GFN0-xTB in Rust with Python/ASE bindings: analytic derivatives through sixth order, periodic extensions, parameter gradients, a neural parameter field (NN-GFN0), and experimental multipole/exchange corrections
Keywords: chemistry,tight-binding,xtb,gfn0,quantum-chemistry
Author-email: ss0832 <highlightly876@gmail.com>
License-Expression: GPL-3.0-or-later
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/ss0832/gfn0-rs/tree/main/docs
Project-URL: Homepage, https://github.com/ss0832/gfn0-rs
Project-URL: Issues, https://github.com/ss0832/gfn0-rs/issues
Project-URL: Repository, https://github.com/ss0832/gfn0-rs

# gfn0-rs

Version 0.4.1 bundles three **experimental trained NN checkpoints**, callable from
Rust, Python native and ASE. No predictive-performance claim is made.
See [usage for all three APIs](docs/api.md#experimental-bundled-models-v041)
and [checkpoint provenance](models/PROVENANCE.md).

An **unofficial** Rust implementation of the GFN0-xTB semiempirical
tight-binding method with fully analytic derivatives, a command-line
interface, and Python (native and ASE) bindings.

> **Disclaimer**
>
> This is an unofficial, independent reimplementation. Molecular results
> are validated against the official `xtb 6.7.1 --gfn 0` binary, but the
> periodic extension beyond the Γ-point CCM scheme, the higher-order force
> constants, the strain-derivative machinery, and the EEQ-BC options are
> **extensions that GFN0-xTB itself does not provide** — they are verified
> by internal consistency, not against any official result. Use at your
> own risk.

## Features

| Boundary condition | Energy | Gradient | Hessian | FC3–FC6 | FC7+ | Stress | d²E/dε², d²E/dεdx | dE/dθ |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Molecular (non-PBC) | ✓ | ✓ | ✓ | ✓ | ✓ (research) | — | — | ✓ |
| Γ-point PBC (CCM; Bloch sum with `--gamma-bloch`) | ✓ | ✓ | ✓ | ✓ (dense/blocks/components) | — | ✓ | ✓ | ✓ |
| k-point PBC (Bloch) | ✓ | ✓ | ✓ | ✓ (dense/blocks/components) | — | ✓ | ✓ | ✓ |

- Every derivative is **analytic closed form** (implicit KKT charge response,
  divided-difference spectral traces, set-partition chain rules). Finite
  differences appear only inside tests as independent oracles.
- Force-constant tensors of any order 1–6 are available as complete packed
  symmetric tensors, as **atom-restricted blocks**, as **single components**,
  and as **mixed directional derivatives** along arbitrary displacement fields
  (the directional path costs about as much as one component, not a tensor
  contraction). Dense tensors, blocks, and components all work for
  **periodic systems** too (Γ-point CCM, the Γ-point Bloch sum on request,
  and k-point meshes; metallic fillings run through a joint
  common-chemical-potential response over the whole mesh).
- **Arbitrary-order nuclear derivatives** (7th order and beyond) through the
  same component and directional APIs for molecular systems. Orders above six
  are intended for mathematical research, not chemical applications: the
  recurrences stay exact at every order, but the cost grows combinatorially,
  so they are practical only for few-atom systems.
- **Second-order strain response** for periodic systems (Γ-point CCM and
  k-point meshes, metallic fillings included through the common
  chemical-potential coupling): the strain-strain block `d²E/dε²` (9×9) and
  the mixed strain-coordinate block `d²E/dεdx` (9×3N) of the same affine
  deformation whose first derivative is the analytic virial/stress.
- Finite electronic temperature (Fermi smearing, 300 K default) consistent
  with the official implementation, including fractional occupations and open
  shells.
- **Orbital analysis and Molden output**: orbital energies, occupations,
  coefficients and aufbau-defined HOMO/LUMO from the Rust API, the CLI
  (`orbitals`, `molden`) and Python/ASE, with every smeared or degenerate
  frontier flagged instead of reported as a clean gap; the Molden file
  writes the STO-nG basis as the primitive Gaussians the crate evaluates,
  in Molden's `[5D]` convention, so a viewer shows the orbitals the
  calculation actually produced.
- Analytic parameter gradients `dE/dθ` for the fitted GFN0 globals,
  element/shell values, Slater exponents, pair scalings, SRB support, and
  D4-EEQ support parameters.
- Preconditioned L-BFGS geometry optimization on the analytic forces (fixed
  cell for periodic systems), with optional live XYZ trajectory output. The
  default graph-Laplacian ("Exp") preconditioner takes coherent steps along
  collective soft modes, which substantially deepens fixed-budget
  optimizations of molecular clusters; disable it with
  `GeometryOptimizationOptions { precondition: false, .. }`.
- Experimental **EEQ-BC-2025** charge model, selectable independently for the
  D4 dispersion charges (`d4_charge_model`), for the H0 onsite shifts
  (`hamiltonian_charge_model`), and for the isotropic electrostatic energy
  term (`electrostatic_charge_model`, molecular systems only; the EEQ-BC
  electrostatic energy is the implementation-defined variational energy of
  the bond-capacity system).
- Experimental opt-in **linear-scaling electronic solvers** (all default off,
  energies/gradients/stress; divide-and-conquer also relaxes geometries):
  divide-and-conquer (`--dc`, configurable
  core size and buffer radius), Chebyshev Fermi-operator expansion (`--foe`),
  and McWeeny/SP2 purification (`--mcweeny`, gapped systems at zero
  electronic temperature). A conjugate-gradient EEQ solver engages
  automatically for large systems.
- Direct-comparison validation harness against the official `xtb` binary
  (energies, components, charges, gradients, Hessians).

## Requirements

- **Rust 1.85 or newer** for the library, the CLI and the Python extension —
  the crate is on edition 2024, which is stable from 1.85, and `Cargo.toml`
  records that as `rust-version`, so an older toolchain stops with a version
  message instead of a page of syntax errors. See
  [Installing Rust](docs/README.md) for how to get one on each
  platform, including what to do when a distribution ships an older `rustc`.
- `maturin` for the Python wheel, and Python 3.9 or newer.
- No parameter file is required: the fitted `param_gfn0-xtb.txt` is **bundled**
  under [`third_party/xtb/`](third_party/xtb/PROVENANCE.md) as a verbatim copy
  of the upstream [xtb](https://github.com/grimme-lab/xtb) file
  (LGPL-3.0-or-later) and is embedded in the binary. It stays replaceable at
  runtime — the resolution order is `--param` → `GFN0_XTB_PARAM` → `XTBPATH` →
  bundled default — so any modified or newer parameter file can be substituted
  without rebuilding.

```sh
# Rust library + CLI
cargo build --release

# Full physics test suite; no environment setup needed (bundled parameters)
cargo test

# Python wheel (distribution gfn0-rs-python, import name gfn0_rs)
pip install maturin
maturin build --release
pip install target/wheels/gfn0_rs_python-*.whl
```

## Quick start

```sh
# Works as-is on the bundled parameterization; export this only to override it.
# export GFN0_XTB_PARAM=/path/to/share/xtb/param_gfn0-xtb.txt

gfn0_rs_cli energy   molecule.xyz
gfn0_rs_cli stress   crystal.extxyz --second
gfn0_rs_cli optimize cluster.xyz --traj traj.xyz
gfn0_rs_cli sources                      # which parameter set is active
```

```rust
use gfn0_rs::{Gfn0Calculator, Gfn0Parameters, System};

let params = Gfn0Parameters::load_resolved(None)?;
let calculator = Gfn0Calculator::new(params);
let system = System::from_xyz_file("crystal.extxyz", 0.0, false)?;
let energy = calculator.energy(&system)?.total;
let elastic = calculator.elastic_properties(&system)?;
```

```python
import gfn0_rs

calc = gfn0_rs.Gfn0NativeCalculator(kmesh=(2, 2, 2))
energy = calc.energy(numbers, positions_bohr, cell_bohr=cell, pbc=(True,) * 3)

from gfn0_rs import GFN0RSCalculator   # ASE interface (eV/A)
```

## Documentation

The complete API reference lives under [`docs/`](docs/README.md):

- [`docs/README.md`](docs/README.md) — which toolchain
  version this needs and how to get one, per platform; what an out-of-date
  distribution package looks like; offline and cross-compiled builds.
- [`docs/api.md`](docs/api.md) — calculator options, single-point
  properties, force constants through sixth order (dense, block, component,
  directional), mixed strain/coordinate derivatives, elastic constants
  (second through fourth order), Grüneisen parameters, phonons,
  piezoelectric tensors, equations of state, molecular vibrations, geometry
  optimization, parameter gradients, environment variables.
- [`docs/api.md`](docs/api.md) — native calculator
  (Hartree/bohr), periodic helpers, ASE calculator (eV/Å).
- [`docs/cli.md`](docs/cli.md) — every subcommand with flags and examples.
- [`docs/methods.md`](docs/methods.md) — the external-field model,
  its boundary conditions and what it deliberately leaves out.
- [`docs/api.md`](docs/api.md) — the complete unit map across Rust,
  Python, CLI, and ASE.
- [`docs/limitations.md`](docs/limitations.md) — honest notes on model and
  numerical edges.

## Units and conventions

- Rust and the native Python API use Hartree atomic units throughout; the
  ASE calculator converts to Å/eV.
- Strain derivatives use the affine map `r' = (I + ε)r`; strain components
  are indexed `s = 3*row + column` in 9-blocks and Voigt order in 6-blocks.
- The reported energy at finite electronic temperature is the Mermin free
  energy, consistent with the analytic forces, Hessians, and stress.


## License

GPL-3.0-or-later (see [LICENSE](LICENSE)). Bundled third-party parameter data
and their licenses are documented in
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md); this includes the fitted GFN0
parameter file, redistributed verbatim under LGPL-3.0-or-later in
[`third_party/xtb/`](third_party/xtb/PROVENANCE.md).

## References

- **GFN0-xTB**: P. Pracht, E. Caldeweyher, S. Ehlert, S. Grimme,
  *A Robust Non-Self-Consistent Tight-Binding Quantum Chemistry Method for
  Large Molecules*, ChemRxiv (2019).
  DOI: [10.26434/chemrxiv.8326202.v1](https://doi.org/10.26434/chemrxiv.8326202.v1)
- **xtb program package**: C. Bannwarth, E. Caldeweyher, S. Ehlert, A. Hansen,
  P. Pracht, J. Seibert, S. Spicher, S. Grimme, *Extended tight-binding
  quantum chemistry methods*, WIREs Comput. Mol. Sci. **11**, e1493 (2021).
  DOI: [10.1002/wcms.1493](https://doi.org/10.1002/wcms.1493)
- **ASE**: 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)
- **DFT-D4**: E. Caldeweyher, S. Ehlert, A. Hansen, H. Neugebauer,
  S. Spicher, C. Bannwarth, S. Grimme, *A generally applicable atomic-charge
  dependent London dispersion correction*, J. Chem. Phys. **150**, 154122
  (2019). DOI: [10.1063/1.5090222](https://doi.org/10.1063/1.5090222)
- **EEQ-BC charge model** (experimental options): T. Froitzheim, M. Müller,
  A. Hansen, S. Grimme, *g-xTB: A general-purpose extended tight-binding
  electronic structure method for the elements H to Lr (Z = 1–103)*,
  J. Chem. Phys. **162**, 214109 (2025).
  DOI: [10.1063/5.0268978](https://doi.org/10.1063/5.0268978); parameters from
  [grimme-lab/multicharge](https://github.com/grimme-lab/multicharge) v0.5.0.
- **NN-xTB-inspired neural parameter field** (experimental implementation): Y. Xia, A. Thie, J. Soon, G. M. J. Barca, *NN-xTB: density functional
  accuracy at semi empirical speed with neural network extended tight binding*, Nature Communications **17**, 7302
  (2026). DOI: [10.1038/s41467-026-73184-z](https://doi.org/10.1038/s41467-026-73184-z).

### Calculation and training commands

Use `gfn0-rs energy INPUT.xyz` for GFN0-xTB calculations, including inference
with `--nn-model MODEL`. Training and model evaluation have their own command:

```text
gfn0-train nn-train --data DATA --out MODEL
gfn0-train nn-eval --help
gfn0-train nn-info MODEL
```

Both commands are installed by Cargo or pip. `gfn0_rs_cli` remains a legacy
calculation alias in Cargo installations. Training commands are no longer
accepted by calculation entry points. One `--lr` updates NN weights, learned
physical coefficients and risk thresholds through the same Adam optimizer.

The calculation command is `gfn0-rs` in both Cargo and pip installations;
the training command is `gfn0-train`. On Windows MSVC, the calculation
binary writes its debug symbols to a separate build output path so they
do not overwrite the library debug symbols.

