Xtbloom Integrate Ase Dpdata

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.