pygfn0-torch 0.1.1

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

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:

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

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:

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)

# 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

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.

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.