Metadata-Version: 2.4
Name: xtbloom
Version: 0.1.1
Summary: Batched CPU and GPU inference for GFN2-xTB through the public C ABI
Keywords: xtb,tight-binding,semiempirical,qm,gpu
Author: xTBloom developers
Maintainer-Email: Jinzhe Zeng <jinzhe.zeng@ustc.edu.cn>
License-Expression: GPL-3.0-or-later
License-File: CUDA_MKL_LINKING_EXCEPTION
License-File: LICENSE
License-File: LICENSES/3Dmol.js-BSD-3-Clause.txt
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/BSD-3-Clause.txt
License-File: LICENSES/CLAPACK-3.2.1-BSD-3-Clause.txt
License-File: LICENSES/LAPACK-OpenBLAS-0.3.28-BSD-3-Clause.txt
License-File: LICENSES/LGPL-3.0-or-later.txt
License-File: LICENSES/MIT.txt
License-File: LICENSES/OpenBLAS-0.3.28-BSD-3-Clause.txt
License-File: LICENSES/array-api-compat-MIT.txt
License-File: LICENSES/iobuffer-MIT.txt
License-File: LICENSES/libf2c-AT&T-Lucent-Bellcore.txt
License-File: LICENSES/netcdfjs-MIT.txt
License-File: LICENSES/openchemlib-BSD-3-Clause.txt
License-File: LICENSES/pako-MIT.txt
License-File: LICENSES/pako-Zlib.txt
License-File: LICENSES/pyodide-MPL-2.0.txt
License-File: LICENSES/scipy-openblas32-0.3.34.0.0-macos.txt
License-File: LICENSES/scipy-openblas32-0.3.34.0.0-windows-amd64.txt
License-File: LICENSES/scipy-openblas32-0.3.34.0.0-windows-arm64.txt
License-File: LICENSES/scipy-openblas32-0.3.34.0.0.txt
License-File: LICENSES/scipy-openblas32-tools-LICENSE_win32.txt
License-File: LICENSES/upng-js-MIT.txt
License-File: THIRD_PARTY_NOTICES.md
License-File: data/parameters/d4.NOTICE
License-File: data/parameters/licenses/dftd4-COPYING
License-File: data/parameters/licenses/dftd4-COPYING.LESSER
License-File: data/parameters/licenses/mctc-lib-LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Homepage, https://xtbloom.jinzhezeng.group
Project-URL: Documentation, https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/index.md
Project-URL: Repository, https://github.com/jinzhezenggroup/xtbloom
Project-URL: Issues, https://github.com/jinzhezenggroup/xtbloom/issues
Project-URL: Web demo, https://xtbloom.jinzhezeng.group
Requires-Python: >=3.10
Requires-Dist: numpy>=1.20
Requires-Dist: array-api-compat<2,>=1.15
Provides-Extra: ase
Requires-Dist: ase; extra == "ase"
Provides-Extra: dpdata
Requires-Dist: dpdata; extra == "dpdata"
Provides-Extra: cuda12
Requires-Dist: nvidia-cublas-cu12>=12.9.1.4; sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64") and extra == "cuda12"
Requires-Dist: nvidia-cusolver-cu12>=11.7.5.82; sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64") and extra == "cuda12"
Requires-Dist: nvidia-cusparse-cu12>=12.5.10.65; sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64") and extra == "cuda12"
Requires-Dist: nvidia-cuda-runtime-cu12>=12.9.79; sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64") and extra == "cuda12"
Requires-Dist: nvidia-nvjitlink-cu12>=12.9.86; sys_platform == "linux" and (platform_machine == "x86_64" or platform_machine == "aarch64") and extra == "cuda12"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: ase; extra == "test"
Requires-Dist: dpdata; extra == "test"
Description-Content-Type: text/markdown

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

```console
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:

```console
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](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/user-guide/index.md#prerequisites).

Source-build and package-boundary details are in the
[developer guide](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/developer-guide/packaging.md).

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

```python
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.

```python
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](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/user-guide/python.md#array-api-and-dlpack-input-arrays).

`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](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/user-guide/qmmm.md)
for the complete contract.

## ASE and dpdata

ASE exposes xTBloom through its usual eV and angstrom conventions:

```python
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:

```python
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

- [Documentation home](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/index.md)
- [Python API guide](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/user-guide/python.md)
- [Units and result meaning](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/user-guide/index.md#units-and-result-meaning)
- [QM/MM theory](https://github.com/jinzhezenggroup/xtbloom/blob/main/docs/theory/qmmm.md)
- [Browser demo](https://xtbloom.jinzhezeng.group)
- [Source repository](https://github.com/jinzhezenggroup/xtbloom)
- [Issue tracker](https://github.com/jinzhezenggroup/xtbloom/issues)
- [License and notices](https://github.com/jinzhezenggroup/xtbloom/blob/main/THIRD_PARTY_NOTICES.md)
