pygfn0-torch 0.1.0

Unofficial differentiable LibTorch implementation of a GFN0-xTB-like Hamiltonian as a parameter laboratory.

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:

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

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

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:

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:

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:

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:

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

The D4 command writes:

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

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

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

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.

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.

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:

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.

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.