Metadata-Version: 2.4
Name: pygfn0-torch
Version: 0.1.0
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.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/PyTorch 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, generated kernel CSV
files, SRB support tables, or generated D4 support TSVs. Calculations require
local support files supplied or generated by the user. 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.
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 `param_gfn0-xtb.txt` from a fixed upstream `xtb` release into a
local directory outside the package source tree. 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)
```

## 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.


## 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.
