Integrate xTBloom with ASE and dpdata

Use xTBloom’s public adapters instead of duplicating their unit conversion, charge/spin resolution, batching, or failure handling. Keep the surrounding framework responsible for its workflow: ASE owns optimizers and dynamics, while dpdata owns dataset containers and invokes xTBloom’s driver or minimizer plugin.

Run Standalone Programs Ephemerally

For an agent-generated standalone program, add PEP 723 metadata and run it with uv run --script workflow.py. Declare only the adapter being used:

# /// script
# requires-python = ">=3.10"
# dependencies = ["xtbloom[ase]>=0.1.1"]
# ///

Use xtbloom[dpdata]>=0.1.1 instead for dpdata. Add cuda12 to the same extra list only when the selected Linux CUDA environment needs those user-space libraries. Do not install ASE and dpdata together unless the program uses both.

Load the Relevant References

• Read integration-contract.md before changing an ASE or dpdata integration. It is the self-contained behavioral contract.
• Read recipes.md when writing or reviewing executable user code.

Choose the Integration Path

1. Use xtbloom.ase.XTBloom when the application already operates on ase.Atoms, uses an ASE optimizer or dynamics driver, or expects ASE properties.
2. Use dpdata’s driver="xtbloom" or XTBloomDriver when labeling every frame of a molecular dpdata.System with energies and forces.
3. Use dpdata’s minimizer="xtbloom" with XTBloomDriver when relaxing many molecular frames through the adapter’s batch-native L-BFGS workflow.
4. Use xTBloom’s lower-level Python interfaces instead when the task needs atomic-unit arrays, explicit point charges, charge-response operators, direct CUDA buffers, or per-system failure inspection not exposed by these adapters.

Do not route a periodic structure into either adapter. xTBloom has no lattice descriptor, and both integrations reject periodic inputs rather than treating them as isolated molecules.

Gather the Scientific Intent

Before editing code, determine:

• whether the input is one molecule, an ASE trajectory, or a multi-frame dpdata system;
• the total charge and spin multiplicity, including whether they are fixed or vary per frame;
• whether CPU fallback is acceptable (backend="auto") or the requested backend must be enforced ("cpu" or "cuda");
• whether consecutive calls should share a compatible SCC starting state or remain independent and reproducible;
• whether the caller expects only single-point properties or a framework-owned optimization/dynamics workflow.

Never infer a nonzero charge, multiplicity, or periodic interpretation from geometry alone. Require the user or existing data model to provide scientifically meaningful values.

Implement an ASE Workflow

1. Import XTBloom from xtbloom.ase and attach it to atoms.calc.
2. Pass method="GFN1-xTB" or method="GFN2-xTB" explicitly in generated examples. GFN1-xTB is CPU-only; GFN2-xTB supports CPU and CUDA.
3. Set backend explicitly when silently changing backend would violate the request.
4. Set charge and multiplicity explicitly when known. Otherwise document ASE’s fallback to initial charges and magnetic moments.
5. Choose warm_start=True for compatible geometry sequences such as optimization or dynamics. Choose warm_start=False for independent calls whose SCC initialization must not depend on an earlier step.
6. Let ASE consume and report positions in angstrom, energies in eV, and forces in eV/angstrom. Do not manually convert values around the adapter.
7. Close a long-lived calculator explicitly when the workflow ends so its native context and caches are released.

ASE optimizers and dynamics repeatedly call the calculator; they are not native xTBloom geometry optimization or molecular dynamics features. Preserve that distinction in code comments and user-facing explanations.

Implement a dpdata Workflow

For labeling:

1. Select the registered "xtbloom" driver or construct XTBloomDriver when an explicit reusable configuration is clearer.
2. Pass fixed charge, uhf, or multiplicity only when those values apply to every frame. Otherwise preserve valid per-frame dpdata fields.
3. Treat driver failure as an error for the whole labeling operation. The adapter deliberately avoids publishing silent NaN labels when any frame fails SCC or the eigensolver.
4. Keep dpdata coordinates in angstrom and accept returned energies in eV and forces in eV/angstrom.

For relaxation:

1. Select minimizer="xtbloom" and pass a configured XTBloomDriver for backend and electronic settings.
2. Interpret fmax in eV/angstrom and max_steps as geometry moves after the initial force evaluation.
3. Explain that the minimizer is an upper-level, batch-native L-BFGS adapter built from repeated xTBloom single-point calls.
4. Preserve its all-or-error behavior for SCC/eigensolver failure or a stalled line search. Do not convert those failures into apparently valid relaxed structures.

Do not describe the dpdata minimizer as a native C-ABI optimizer, assume support for periodic cells, or imply that it implements arbitrary ASE constraints.

Validate the Integration

Run the narrowest real workflow available and check all of the following:

• the input is explicitly molecular: atoms.pbc is false for ASE or dpdata marks the system nonperiodic;
• the requested backend is enforced when fallback is unacceptable;
• energy and force arrays are finite and have the expected framework shapes;
• reported units are eV and eV/angstrom at both adapter boundaries;
• charge and multiplicity reach the adapter through the intended fixed or per-frame path;
• a geometry update triggers a new calculation rather than reusing stale results;
• independent calculations use warm_start=False, while sequential workflows use warm start only intentionally;
• the calculator or driver-owned native resources are released when the host workflow ends.

When a requested feature lies outside these adapters, state the boundary and switch to the appropriate xTBloom interface instead of simulating unsupported behavior.