xTB MDI engine – drive LAMMPS MD with tblite over MDI#

Author:

Paul Saxe (with Claude)

Date:

2026-06-25

Status:

Implemented – guard tests pass; end-to-end run pending

Campaign:

LAMMPS + MOPAC/xTB QM-MD via MDI

Scope#

This is the xTB side of the QM-MD-over-MDI campaign – the engine-side mirror of MOPAC’s Phase A. It lets a driver (lammps_step) run MD with energies and forces from xTB (via the tblite library) over MDI, with no xTB-specific knowledge in the driver.

The model-chemistry grammar and the LAMMPS consumer (Phase C) are program-agnostic – LAMMPS resolves the owning step from the stored _model_chemistry and calls get_mdi_engine_command on it – so nothing in those needed to change. xTB slots in purely by exposing the same contract MOPAC does and shipping an engine script.

Delivered:

  • xTBStep (the Stevedore entry-point helper) gains the MDI contract, mirroring MOPACStep: _MDI_CAPABLE_METHODS, _MDI_PERIODIC_VALIDATED, get_model_chemistry_options, get_executor_config, get_mdi_engine_command.

  • data/tblite_mdi.py – the engine, wrapping tblite.interface.Calculator (shipped in the wheel, Option C, like mopac_mdi.py).

  • data/seamm-xtb.yml gains tblite-python + pymdi.

  • A method-set guard test (tests/test_mdi_methods.py).

What xTB advertises#

xTBStep.get_model_chemistry_options() returns level specs keyed by bare method name, e.g. xTB:SQM@GFN2-xTB (xTB is semiempirical QM -> type SQM; owner xTB). The MDI-drivable subset:

  • _MDI_CAPABLE_METHODS = {GFN1-xTB, GFN2-xTB}

  • _MDI_PERIODIC_VALIDATED = {GFN1-xTB, GFN2-xTB} (both run periodic – tblite returns the virial, from which the engine forms the stress).

GFN0-xTB and GFN-FF remain reachable only through the ordinary xtb-binary path, not via MDI (the tblite Python Calculator does not cover them). The composed result label a LAMMPS MD run records is therefore LAMMPS:MD|xTB:SQM@GFN2-xTB.

How it differs from the MOPAC engine#

Like MOPAC, the engine needs no input file – atom count, atomic numbers, coordinates and cell all arrive over the MDI handshake (>NATOMS, >ELEMENTS, >COORDS, >CELL), and the tblite Calculator is built lazily on the first energy/force request. The remaining differences from mopac_mdi.py are small and all handled here:

Aspect

MOPAC (mopac_mdi.py)

xTB (tblite_mdi.py)

Spin input

--multiplicity (2S+1)

--uhf (unpaired electrons = multiplicity - 1)

Units

kcal/mol, Angstrom -> convert

Bohr / Hartree natively = MDI units; no conversion

Method set

engine == advertised set

engine also accepts IPEA1-xTB (not advertised)

Note

The engine originally bootstrapped from structure.dat (parsing the LAMMPS data file) and the elements line in input.dat, because tblite’s Calculator wants numbers/positions/lattice at construction. That was refactored away (2026-06-26): the driver already sends all of it over MDI to any engine, so the wrapper now defers construction to the first compute and reads the handshake – matching MOPAC, and removing the data-file parser, the --structure/--elements/--atom-style flags, and a whole class of atom_style-mismatch bugs.

Engine launch#

get_mdi_engine_command builds (rendered into the driver’s launch script with shlex.join):

OMP_NUM_THREADS=<n> MKL_NUM_THREADS=<n> \
<conda> run --live-stream -n seamm-xtb python <abs>/tblite_mdi.py
    -mdi "-role ENGINE -name TBLITE -method TCP -port <port> -hostname <host>"
    --method GFN2-xTB --charge <q> --uhf <2S>

The engine runs in seamm-xtb (tblite-python + pymdi added to seamm-xtb.yml); conda run keeps it in its own environment while the LAMMPS driver stays in seamm-lammps, meeting over TCP – exactly the MOPAC split. Non-conda installations raise NotImplementedError for now.

Open / to verify#

  • End-to-end run through the SEAMM GUI (Model Chemistry -> LAMMPS) once seamm-xtb has tblite-python/pymdi installed; the standalone engine is already validated (NVT/NPT/stress decks in ~/Work/tblite-mdi).

  • Package name tblite-python is what provides from tblite.interface import Calculator on conda-forge; adjust if your channel differs.

  • IPEA1-xTB could be advertised too (add it to metadata.py and _MDI_CAPABLE_METHODS); left out for now as it is not in xtb_step’s computational-models metadata.

References#

  • MOPAC engine (the template): mopac_step/data/mopac_mdi.py and mopac_step.py (get_mdi_engine_command etc.).

  • Model-chemistry grammar / naming: molssi-seamm.github.io :: background/model_chemistry_naming.rst.

  • LAMMPS consumer (Phase C): lammps_step :: campaigns/2026-06-22/NOTES_C.rst.

  • Working standalone engine + test decks: ~/Work/tblite-mdi/.