Metadata-Version: 2.4
Name: pygfn0-torch
Version: 0.1.1
Summary: Unofficial differentiable LibTorch implementation of a GFN0-xTB-like Hamiltonian as a parameter laboratory.
Keywords: gfn0,xtb,tight-binding,libtorch,ase,computational-chemistry
Author: ss0832
License-Expression: GPL-3.0-or-later
License-File: COPYING.LESSER
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Repository, https://github.com/ss0832/PyGFN0Torch
Project-URL: Issues, https://github.com/ss0832/PyGFN0Torch/issues
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: torch<2.7,>=2.4
Requires-Dist: tad-dftd4>=0.8
Requires-Dist: tad-multicharge>=0.3
Provides-Extra: ase
Requires-Dist: ase>=3.22; extra == "ase"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: ase>=3.22; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: GPL-3.0-or-later -->

# pygfn0_torch

`pygfn0_torch` is an unofficial LibTorch/C++ implementation
of a GFN0-xTB-like tight-binding model with automatic differentiation support.

The package is intended for research and development workflows that need
energies, forces, coordinate derivatives, response tensors, and parameter
derivatives from a differentiable model.

This project does not bundle fitted GFN0 parameter files, fitted/global GFN0
scalar defaults, generated kernel CSV files, SRB support tables, or generated D4
support TSVs. A complete user-supplied `param_gfn0-xtb.txt` or equivalent
external metadata is required; global parameters are included in that
requirement. With `include_d4=True`,
D4 support is obtained either from explicit local TSV paths or from runtime
TSV generation using the installed `tad-dftd4` / `tad-multicharge` providers.



## Status

This is a pre-release implementation. API stability, packaging layout, and
high-order derivative paths may still change.


## Requirements

- Python 3.10 or newer
- PyTorch / LibTorch compatible with the build environment
- CMake
- Ninja or another supported CMake generator
- `pybind11`
- `scikit-build-core`
- `numpy`
- `tad-dftd4`
- `tad-multicharge`

Optional:

- `ase` for the ASE adapter and ASE examples



## Installation

From the repository root:

```bash
python -m pip install -e . --no-build-isolation
```

If LibTorch is not found automatically, set `LIBTORCH_HOME` before installing:

```bash
export LIBTORCH_HOME=/path/to/libtorch
python -m pip install -e . --no-build-isolation
```

After C++ changes, rebuild the extension. `PYTHONPATH=src` is useful for
Python-only smoke tests, but it does not rebuild or replace the compiled
extension.

For the ASE adapter and ASE examples, install the optional dependency:

```bash
python -m pip install -e .[ase] --no-build-isolation
```

Alternatively, install `ase` into the same environment.

## Local support files

Ordinary GFN0-xTB calculations need these local inputs:

1. A local `param_gfn0-xtb.txt` parameter file.
2. A local SRB support table generated from `approxrab.f90`.
3. For `include_d4=True`, either explicit local D4 support TSV files or installed
   `tad-dftd4` / `tad-multicharge` providers for runtime TSV generation.

These files are intentionally not bundled with this package. The package keeps
schema, parsers, tensor accessors, and unit conversions, but not fitted/global
GFN0 numerical defaults.
For reproducible local preparation, use pinned upstream release tags rather than
moving branches. The recommended fixed source points are:

- `grimme-lab/xtb` tag `v6.7.1` for `param_gfn0-xtb.txt` and
  `src/approxrab.f90`: `https://github.com/grimme-lab/xtb/releases/tag/v6.7.1`.
- `pprcht/gfn0` tag `v0.1` for the STO/Gaussian expansion provenance recorded
  in `NOTICE` and `THIRD_PARTY_NOTICES.md`:
  `https://github.com/pprcht/gfn0/releases/tag/v0.1`.

A typical explicit-file layout is:

```text
support/
  param_gfn0-xtb.txt
  approxrab.f90
  srb_support.tsv
  d4_reference_states.tsv
  d4_eeq_element_params.tsv
```

## Preparing support files

Prepare or copy a complete `param_gfn0-xtb.txt` from a fixed upstream `xtb`
release into a local directory outside the package source tree. The file must
include the required global scalar block; the package will not fill missing
GFN0 global values with compiled-in defaults. A reproducible source point is
`grimme-lab/xtb` tag `v6.7.1`; the raw file path is
`https://raw.githubusercontent.com/grimme-lab/xtb/v6.7.1/param_gfn0-xtb.txt`.

Generate the SRB support table from `src/approxrab.f90` from the same fixed
upstream release. A reproducible raw source path is
`https://raw.githubusercontent.com/grimme-lab/xtb/v6.7.1/src/approxrab.f90`:

```bash
python -m pygfn0_torch.support extract-srb \
  ./support/approxrab.f90 \
  ./support/srb_support.tsv
```

Generate D4 support TSV files when you want explicit, reproducible local D4
inputs:

```bash
python -m pygfn0_torch.support extract-d4 ./support
```

The D4 command writes:

```text
support/d4_reference_states.tsv
support/d4_eeq_element_params.tsv
```

If `include_d4=True` and these TSV paths are omitted, the Python API attempts to
materialize equivalent runtime support files from the installed `tad-dftd4` /
`tad-multicharge` providers. For release-controlled or containerized workflows,
prefer generating the TSVs explicitly and passing their paths.

## Basic Python usage

```python
import numpy as np
from pygfn0_torch import Calculator

z = np.array([8, 1, 1], dtype=np.int64)
positions = np.array(
    [
        [0.0000000000, 0.0000000000, 0.0000000000],
        [0.7586020000, 0.0000000000, 0.5042840000],
        [-0.7586020000, 0.0000000000, 0.5042840000],
    ],
    dtype=np.float64,
)

calc = Calculator(
    parameter_file="./support/param_gfn0-xtb.txt",
    parameter_format="xtb",
    srb_support_table="./support/srb_support.tsv",
    d4_refs_tsv="./support/d4_reference_states.tsv",
    d4_eeq_tsv="./support/d4_eeq_element_params.tsv",
)

energy = calc.energy(z, positions)
forces = calc.forces(z, positions)

print("energy:", energy)
print("forces:")
print(forces)

# Inspect the exact local files used by this Calculator instance.
print(calc.parameter_sources())
# Or print a compact human-readable report at construction time:
# calc = Calculator(..., print_parameter_sources=True)
```

## Parameter/source provenance

For reproducibility and packaging audits, `Calculator.parameter_sources()` returns
the resolved user parameter file, the temporary generated kernel CSV when one is
materialized, SRB support metadata, D4 support TSV paths, and installed
`tad-dftd4` / `tad-multicharge` versions when D4 support is generated at
runtime.  Use `Calculator(..., print_parameter_sources=True)` or
`calc.print_parameter_sources()` when a simple log-style printout is enough.

The D4 TSV writer also embeds provider-version comments into generated TSV
headers, and `python -m pygfn0_torch.support extract-d4 ./support` prints the
resolved output paths and provider versions.

## ASE usage

```python
from ase import Atoms
from ase.optimize import BFGS
from pygfn0_torch.ase import GFN0ASECalculator

atoms = Atoms(
    "H2O",
    positions=[
        [0.0000000000, 0.0000000000, 0.0000000000],
        [0.7586020000, 0.0000000000, 0.5042840000],
        [-0.7586020000, 0.0000000000, 0.5042840000],
    ],
)

atoms.calc = GFN0ASECalculator(
    parameter_file="./support/param_gfn0-xtb.txt",
    parameter_format="xtb",
    srb_support_table="./support/srb_support.tsv",
    d4_refs_tsv="./support/d4_reference_states.tsv",
    d4_eeq_tsv="./support/d4_eeq_element_params.tsv",
)

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

opt = BFGS(atoms)
opt.run(fmax=0.05, steps=20)
```

## Disabling D4


```python
calc = Calculator(
    parameter_file="./support/param_gfn0-xtb.txt",
    parameter_format="xtb",
    srb_support_table="./support/srb_support.tsv",
    include_d4=False,
)
```

When `include_d4=False`, D4 support files are not required.

## Parameter export

The calculator can export its current live parameter tensors back to an xtb-like
text parameter file.

```python
calc = Calculator(
    parameter_file="./support/param_gfn0-xtb.txt",
    parameter_format="xtb",
    srb_support_table="./support/srb_support.tsv",
    d4_refs_tsv="./support/d4_reference_states.tsv",
    d4_eeq_tsv="./support/d4_eeq_element_params.tsv",
)

calc.write_xtb_parameters("./exported_param_gfn0-xtb.txt")
```

This export path is useful for diagnostics and parameter studies. Check the
result with a controlled round-trip test before using it as input to a separate
workflow.

The exported parameter file may contain values derived from the user-supplied
GFN0-xTB fitted parameter file. Do not commit or redistribute exported parameter
files unless you have verified the license and redistribution terms of the
source parameter file.

## Parameter derivatives

Parameter derivatives require trainable parameter tensors.

```python
calc = Calculator(
    parameter_file="./support/param_gfn0-xtb.txt",
    parameter_format="xtb",
    srb_support_table="./support/srb_support.tsv",
    d4_refs_tsv="./support/d4_reference_states.tsv",
    d4_eeq_tsv="./support/d4_eeq_element_params.tsv",
    trainable_parameters=True,
)

grads = calc.parameter_gradients(z, positions, component="total")
```

For a single named parameter:

```python
grad = calc.parameter_gradient(z, positions, parameter="global.ks")
```

## Hessians and high-order derivatives

Dense Hessians and force-constant tensors are intended for small systems.

```python
hessian = calc.hessian(z, positions)
fc3 = calc.fc3_tensor(z, positions)
fc4 = calc.fc4_tensor(z, positions)
```

For larger systems, prefer directional or block APIs where available.

## Examples

The `examples/**` directory is the public usage surface.

## Reference

### GFN0-xTB

- Pracht, P.; Caldeweyher, E.; Ehlert, S.; Grimme, S. A Robust Non-Self-Consistent Tight-Binding Quantum Chemistry Method for Large Molecules. June 27, 2019. https://doi.org/10.26434/chemrxiv.8326202.v1.


### ASE

- Hjorth Larsen, A.; Jørgen Mortensen, J.; Blomqvist, J.; Castelli, I. E.; Christensen, R.; Dułak, M.; Friis, J.; Groves, M. N.; Hammer, B.; Hargus, C.; Hermes, E. D.; Jennings, P. C.; Bjerre Jensen, P.; Kermode, J.; Kitchin, J. R.; Leonhard Kolsbjerg, E.; Kubal, J.; Kaasbjerg, K.; Lysgaard, S.; Bergmann Maronsson, J.; Maxson, T.; Olsen, T.; Pastewka, L.; Peterson, A.; Rostgaard, C.; Schiøtz, J.; Schütt, O.; Strange, M.; Thygesen, K. S.; Vegge, T.; Vilhelmsen, L.; Walter, M.; Zeng, Z.; Jacobsen, K. W. The Atomic Simulation Environment—a Python Library for Working with Atoms. *J. Phys.: Condens. Matter* **2017**, *29* (27), 273002. https://doi.org/10.1088/1361-648X/aa680e.

- Bahn, S. R.; Jacobsen, K. W. An Object-Oriented Scripting Interface to a Legacy Electronic Structure Code. *Comput. Sci. Eng.* **2002**, *4* (3), 56–66. https://doi.org/10.1109/5992.998641.

### Related work

This project is independent of `dxtb`, but follows the same broad direction of
using automatic differentiation for extended tight-binding models. See:

- Friede, M.; Hölzer, C.; Ehlert, S.; Grimme, S.
  dxtb—An Efficient and Fully Differentiable Framework for Extended Tight-Binding.
  *The Journal of Chemical Physics* **2024**, *161* (6), 062501.
  https://doi.org/10.1063/5.0216715

  
## License

This project is distributed under GPL-3.0-or-later. See `LICENSE`.


Binary wheels and source distributions are published from the same release
source tree; the matching source distribution or GitHub release tag provides the
source for a given wheel.

Users are responsible for verifying the upstream license, notices, and
redistribution terms of any downloaded or generated support files, including
`param_gfn0-xtb.txt`, `approxrab.f90`, and generated D4 TSVs, before copying,
publishing, redistributing, containerizing, or otherwise sharing those files as
part of a workflow or artifact.




The runtime model also depends on the upstream `xtb` ecosystem for user-supplied
GFN0-xTB parameter/support inputs such as `param_gfn0-xtb.txt` and SRB support
data. Those files remain external to this distribution.

