xTBloom for Python

xTBloom provides batched GFN2-xTB energies, analytic forces, and atomic charges through a NumPy-friendly interface backed by the same stable C ABI used by native C and C++ applications.

It supports restricted and unrestricted GFN2-xTB, native ragged batches, explicit point charges with force output, caller-supplied periodic charge response, CPU and CUDA backends, ASE, dpdata, and eager Array API/DLPack arrays.

Installation

xTBloom is not yet published on PyPI. From a source checkout, sync the locked, non-editable package into uv's project environment:

uv sync --locked --no-editable --no-default-groups --reinstall-package xtbloom

CUDA build selection defaults to AUTO: an available nvcc enables CUDA; otherwise the package is CPU-only. Add --extra cuda12 to the command when the supported CUDA 12 host libraries are not supplied by the system.

Optional integrations can be combined with either backend. For example, add ASE and dpdata to the CUDA environment with:

uv sync --locked --no-editable --no-default-groups \
  --extra cuda12 --extra ase --extra dpdata --reinstall-package xtbloom

Run commands with uv run --no-sync or activate .venv directly.

Python 3.10 or newer is required. Linux wheels include a private LP64 OpenBLAS provider for CPU inference; scipy-openblas32 is used only while building the wheel and is not installed as a runtime dependency. A CUDA-enabled wheel additionally needs an NVIDIA driver and compatible CUDA 12 host libraries; the cuda12 extra supplies the supported nvidia-* packages. CUDA libraries are not bundled inside the xTBloom wheel.

Ordinary source builds do not bundle OpenBLAS. They auto-discover a compatible system monolithic LP64 LAPACKE+CBLAS runtime; if none is discoverable, add CMAKE_ARGS="-DXTBLOOM_CPU_LINALG_LIBRARY=/absolute/path/to/provider.so" to the sync command. Keep --reinstall-package xtbloom when changing this path or explicitly overriding the XTBLOOM_ENABLE_CUDA=AUTO default, because uv's local wheel cache does not key native builds by those environment variables.

A normal branch checkout must include complete Git tag history; an exact-tag Python build is the documented shallow-checkout exception. Source builds need C/C++ compilers with C11/C++17 support, and repository test configurations require Python 3.11 or newer. CMake, GCC/Clang, NVCC/CUDA Toolkit, Ninja/uv, BLAS, platform, driver, and wheel/source-build boundaries are listed in the authoritative prerequisites matrix.

Source-build and package-boundary details are in the developer guide.

Single-point calculation

The high-level API uses atomic units: positions are in bohr, energies in Hartree, forces in Hartree/bohr, and charges in elementary-charge units. electronic_temperature is the exception: Python accepts kelvin.

import numpy as np
from xtbloom import Calculator

numbers = np.array([8, 1, 1])
positions = np.array(
    [
        [0.0000000000, 0.0000000000, -0.7357858611],
        [1.4418315287, 0.0000000000, 0.3678929305],
        [-1.4418315287, 0.0000000000, 0.3678929305],
    ]
)

backend = "cuda"  # Use "cpu" to require CPU execution instead.
with Calculator("GFN2-xTB", numbers, positions, backend=backend) as calc:
    result = calc.singlepoint()

print(result["energy"])
print(result["forces"])
print(result["charges"])

result["gradient"] is the negative of result["forces"]. At finite electronic temperature, the reported variational energy is the electronic Helmholtz free energy.

Set backend="cpu" or backend="cuda" to require one backend. The CUDA quickstart above deliberately uses "cuda" so an unavailable GPU fails clearly instead of running on CPU. "auto" prefers CUDA but falls back to CPU. Compatible calls can opt into electronic warm starts; the default is an independent fresh SCC solve.

Native ragged batches

BatchCalculator packs differently sized Structure objects into one native request. Per-system SCC or eigensolver failures remain local: successful peers are preserved, and failed floating-point slices contain NaNs plus diagnostics.

import numpy as np
from xtbloom import BatchCalculator, Structure

structures = [
    Structure([1, 1], np.array([[-0.7, 0.0, 0.0], [0.7, 0.0, 0.0]])),
    Structure(
        [8, 1, 1],
        np.array(
            [
                [0.0000, 0.0000, -0.7358],
                [1.4418, 0.0000, 0.3679],
                [-1.4418, 0.0000, 0.3679],
            ]
        ),
    ),
]

with BatchCalculator(structures, backend="cuda") as calc:  # Use "cpu" for CPU-only builds.
    batch = calc.compute()

print(batch.energies)
print(batch[1].forces)
print(batch.failed_indices)

compute(auto_batch_size=True) can split very large workloads into conservative CUDA chunks while preserving input order.

Advanced array and CUDA paths

ArrayBatch accepts packed ragged descriptors from eager NumPy, CuPy, JAX, or PyTorch arrays through __dlpack__ and __dlpack_device__. Host arrays map to host descriptors; CUDA arrays can remain device-resident. By default, results return as host NumPy arrays.

Use an out= mapping for caller-owned NumPy, CuPy, or PyTorch output buffers, or result_memory="cuda" for one xTBloom-owned packed device arena exported as DLPack producers. Exact dtype, shape, layout, lifetime, stream, and ownership rules are documented in the Python API guide.

xtbloom_torch(positions, atomic_numbers, atom_offsets, molecular_charges, unpaired_electrons, ...) runs xTBloom inference on PyTorch tensors (host or CUDA) and is the only autograd entry point in the Python API. It supports exactly the positions gradient dE/dR = -F; autograd on any other input, or a gradient flowing through the forces output (the Hessian), raises XTBloomNotSupportedError. Higher-order differentiation is likewise rejected explicitly rather than returning a partial or zero Hessian. The native data plane is a compiled extension written against the LibTorch Stable ABI (torch >= 2.10), so a single binary works across torch releases; its stable headers are vendored in cmake/3rdparty/torch-stable and it links a build-time-only stub, so building xTBloom never downloads or requires torch (torch is still required at runtime to call xtbloom_torch). PyTorch is imported only when the op is called. CPU execution is synchronous; CUDA follows torch.cuda.current_stream() and returns the ordinary (energies, forces) pair. See docs/user-guide/python.md for the full contract.

Charge, spin, and embedding

Use either multiplicity or uhf = multiplicity - 1 for open-shell calculations. Open-shell Python calculations default to two unrestricted spin channels; spin_channels=1 requests the restricted open-shell form.

PointCharge inputs participate in every SCC iteration, and xTBloom can return forces on both QM atoms and point charges. ChargeResponse(shifts=b, matrix=A) supplies a caller-owned b + A q operator on the atomic-charge channel. Returned forces hold those external fields fixed; callers own their coordinate derivatives and classical MM-MM terms.

See the QM/MM guide for the complete contract.

ASE and dpdata

ASE exposes xTBloom through its usual eV and angstrom conventions:

from ase.build import molecule
from xtbloom.ase import XTBloom

atoms = molecule("H2O")
atoms.calc = XTBloom(method="GFN2-xTB")
energy_ev = atoms.get_potential_energy()
forces_ev_per_angstrom = atoms.get_forces()

dpdata can label systems through the xTBloom driver:

import dpdata

system = dpdata.System("geometry.xyz", fmt="xyz")
labeled = system.predict(driver="xtbloom", charge=0, multiplicity=1)

The dpdata integration also provides a batch-native minimizer built from repeated xTBloom single-point calls. This is a higher-level adapter, not native geometry optimization in the C ABI.

Scope

GFN1-xTB, ROCm, lattice/PBC inputs, solvation, native geometry optimization, molecular dynamics, Hessians, and higher-order autograd are not implemented. The high-level Calculator and BatchCalculator APIs use host NumPy arrays; direct device and mixed descriptors are exposed through ArrayBatch and the low-level C ABI.

More documentation

Project links

Data verified by PyPI on Aug 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for njzjz from gravatar.com njzjz

Credits

Author: xTBloom developers

Maintainer: Jinzhe Zeng

GitHub Statistics

Data verified by PyPI on Aug 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.10

Provides Extra

ase dpdata cuda12 test

Tags

xtb tight-binding semiempirical qm gpu

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xtbloom-0.1.1.tar.gz (1.9 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

xtbloom-0.1.1-py3-none-win_arm64.whl (5.9 MB view details)

Uploaded Python 3Windows ARM64

xtbloom-0.1.1-py3-none-win_amd64.whl (7.9 MB view details)

Uploaded Python 3Windows x86-64

xtbloom-0.1.1-py3-none-pyemscripten_2026_0_wasm32.whl (3.2 MB view details)

Uploaded PyEmscripten 2026.0 wasm32Python 3

xtbloom-0.1.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (23.7 MB view details)

Uploaded Python 3manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

xtbloom-0.1.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl (24.1 MB view details)

Uploaded Python 3manylinux: glibc 2.27+ ARM64manylinux: glibc 2.28+ ARM64

xtbloom-0.1.1-py3-none-macosx_11_0_arm64.whl (7.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

xtbloom-0.1.1-py3-none-macosx_10_15_x86_64.whl (11.4 MB view details)

Uploaded Python 3macOS 10.15+ x86-64

File details

Details for the file xtbloom-0.1.1.tar.gz.

File metadata

  • Download URL: xtbloom-0.1.1.tar.gz
  • Upload date:
  • Size: 1.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xtbloom-0.1.1.tar.gz
Algorithm Hash digest
SHA256 45cff9e87d5c7b8571a79f0f652370adda61eb072d9efc271a06eea655ef51b4
MD5 4483a4bdd68579ba5c9e5bf875a162bf
BLAKE2b-256 60c0cce0ad7d488ba583a0b4905a63635565e93e8ccb25fda5197203600504bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1.tar.gz:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-win_arm64.whl.

File metadata

  • Download URL: xtbloom-0.1.1-py3-none-win_arm64.whl
  • Upload date:
  • Size: 5.9 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xtbloom-0.1.1-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 c93205ea28dd50048c3e8184a226981a92a348b39e935a3256a4eeb3a2b55b1c
MD5 18550fe972593fa33597b8ca7b578a48
BLAKE2b-256 ec1cc20d82208615bb6ff732e68e627003985cd2a390eb4475f458e70adda5a5

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-win_arm64.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-win_amd64.whl.

File metadata

  • Download URL: xtbloom-0.1.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 7.9 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for xtbloom-0.1.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 90576fc6a6096d07ab9edef2184e9d1499f83063da21a0322493ea6e8d9b7f0d
MD5 2f6664e07a2906e0c12ce4b635b5a838
BLAKE2b-256 b85288f80457c2e9421595e32efcfb91befa1db12433a2c0e113bb247da11761

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-win_amd64.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-pyemscripten_2026_0_wasm32.whl.

File metadata

File hashes

Hashes for xtbloom-0.1.1-py3-none-pyemscripten_2026_0_wasm32.whl
Algorithm Hash digest
SHA256 17d4a42649b7c28370a408d191836333a8a479f4072282dbdab41ebbbb1c0ec3
MD5 2ec5efa2fed0cc0f24e8db53209896c0
BLAKE2b-256 efad24796536851f1d91125df60d334ead6ab0c1e79fcead1988ac076f8dda8f

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-pyemscripten_2026_0_wasm32.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for xtbloom-0.1.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1c1c38eb8765d60a6c6f5c44bcb4d42d1ba1c6e8b4830db39f85a3d8985d302b
MD5 01fe445855810edc63bb9a5a11b2153f
BLAKE2b-256 a4f8f90bbcad46499479659aad1d3824d4783467b1ac06998574d8cb6ba101c2

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for xtbloom-0.1.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 d730c02855cd8f45434196779d1867278a3dbf70c1878e881e6425c693f7b214
MD5 616f845a3ea8f85ac2068ce5ed31fb9c
BLAKE2b-256 988ae458ec2fead3fa0c82d1d2d1f237bb1551a497684461113014c0572db6f6

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for xtbloom-0.1.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9dcb7fdf1cacb675bf329076b57f6cd894dc778b575a77190cfa5a3a00f42ae0
MD5 57894c0a4c79301ffc0a77d882a9d20c
BLAKE2b-256 f20cfcbb9280b8c1598ae60c6acf10dde27474212667f7bd3587b7e6d24a331b

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-macosx_11_0_arm64.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file xtbloom-0.1.1-py3-none-macosx_10_15_x86_64.whl.

File metadata

File hashes

Hashes for xtbloom-0.1.1-py3-none-macosx_10_15_x86_64.whl
Algorithm Hash digest
SHA256 dccc72b8a983c488a861f8c09261252d5d26d399ab054a0909aa7ea2b501b302
MD5 0607e51b975fce77ed087a3f5629e468
BLAKE2b-256 0dd93591c4d0538bb41287c1dc0e74d7da86899fe067f03e855c001848cccbf0

See more details on using hashes here.

Provenance

The following attestation bundles were made for xtbloom-0.1.1-py3-none-macosx_10_15_x86_64.whl:

Publisher: wheels.yml on jinzhezenggroup/xtbloom

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.2

8 files

0.2.1

8 files

0.2.0

8 files

This release

0.1.1 This release

8 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page