git:20260810.e2c149b to git:20260810.6a7d139

15 added, 0 removed. Audit A to A.

---

name: xtbloom-run-python-inference

description: Write, review, and run high-level xTBloom Python GFN2-xTB inference with `Calculator`, `Structure`, and `BatchCalculator`, including single systems, repeated geometry updates, heterogeneous ragged batches, backend selection, units, finite-temperature meaning, and peer-local failure handling. Use for ordinary NumPy-based energy, force, and charge workflows; use a dedicated integration skill instead for Array API/DLPack/PyTorch zero-copy, ASE/dpdata, the native C API, or QM/MM coupling.

---

# Run xTBloom Python Inference

Build a calculation whose units, backend behavior, lifetime, and failure policy are explicit. Read [references/python-inference.md](references/python-inference.md) for the public API contract and complete examples.

+ ## Run Standalone Programs Ephemerally

+ Do not require xTBloom to be preinstalled for an agent-generated standalone

+ program. Add PEP 723 metadata at the top, then run it with `uv run --script calculation.py`:

+ ```python

+ # /// script

+ # requires-python = ">=3.10"

+ # dependencies = ["xtbloom>=0.1.1"]

+ # ///

+ ```

+ Respect an existing application environment when the user asks to modify one;

+ do not replace its dependency policy merely to make the example standalone.

## Select the Interface

- Use `Calculator` for one system and for repeated geometry updates on one topology.

- Use `Structure` plus `BatchCalculator` for differently sized systems in one native ragged request.

- Use context managers so native contexts and persistent backend resources are released deterministically.

- Keep this workflow on high-level NumPy-backed inputs. Route direct device arrays, caller-owned outputs, DLPack, and PyTorch autograd to the zero-copy integration workflow.

- Route ASE/dpdata unit conversion and adapter behavior, native C/C++ consumers, and QM/MM external operators to their dedicated workflows.

## Make Backend Intent Explicit

Choose `backend="cpu"` or `backend="cuda"` when that backend must execute. Choose `"auto"` only when preferring CUDA with CPU fallback is acceptable. Never infer a CUDA pass from an `auto` calculation without confirming the resolved backend; for a GPU acceptance check, require `"cuda"` and let an unavailable runtime fail clearly.

If import, native-library loading, CPU provider creation, or CUDA context creation fails, diagnose the installation before changing the scientific request.

## Preserve Numerical Meaning

Always state the following alongside generated input and output code:

| Quantity | High-level Python unit or meaning |

| ------------------------ | --------------------------------- |

| Positions | bohr |

| Energy | Hartree |

| Forces | Hartree/bohr |

| `gradient` | `-forces` |

| Charges | elementary-charge units |

| `electronic_temperature` | kelvin |

At finite electronic temperature, the reported variational energy is the electronic Helmholtz free energy. Do not label input coordinates as angstrom unless they were converted to bohr before constructing the high-level xTBloom object.

## Handle Results Honestly

`Calculator.singlepoint()` raises when its single system does not converge or its eigensolver fails. `BatchCalculator.compute()` instead preserves peer-local results by default:

1. Inspect `failed_indices`, `per_system_status`, `scc_converged`, and `scc_iterations`.

1. Use successful peer results normally.

1. Treat every requested floating-point slice for a failed system as invalid NaN output.

1. Call `result.raise_for_status()` after inspection when strict exception behavior is desired, or pass `raise_on_failure=True` only when losing direct access to the returned peer results is acceptable.

A successful batch function return does not mean every member converged.

## Reuse State Deliberately

The default `warm_start=False` makes each high-level calculation an independent fresh SCC solve. For iterative geometry work, reuse one `Calculator`, call `update(positions=...)`, and enable `warm_start=True` only when seeding from the previous compatible converged state is intended. The high-level wrapper transparently starts fresh on the first call or after an incompatible identity change.

For large CUDA batches, `auto_batch_size=True` may split and retry recoverable allocation failures while preserving order and peer diagnostics. Do not combine automatic slicing with `warm_start=True`, because one native context owns one whole-batch checkpoint.

## Keep Scope Accurate

Use only `GFN2-xTB`. Restricted and unrestricted calculations are supported on CPU and CUDA; specify `multiplicity` or `uhf = multiplicity - 1` consistently for open-shell systems. Do not claim support for GFN1-xTB, ROCm, lattice/PBC inputs, solvation, native geometry optimization, molecular dynamics, Hessians, or higher-order autograd.

Report the requested and resolved backend, input units, temperature, batch failure summary, and any unavailable runtime. Do not turn CPU fallback or an unexecuted backend into a pass.