Skip to content

xtb

xtb: the semiempirical GFN-xTB, GFN-FF, and g-xTB program, run on the command line.

The codec writes structure.xyz and runs::

xtb structure.xyz --<runtype> --chrg <charge> --uhf <unpaired> <method flags> <keywords>

model.method selects the Hamiltonian: gfn0, gfn1, gfn2, gfnff, or gxtb. g-xTB needs the xtb build distributed with g-xTB (https://github.com/grimme-lab/g-xtb); point qccodec at it with QCCODEC_XTB_EXECUTABLE. GFN0 reads its parameter file from the directory named by XTBPATH. That build reports the version of upstream xtb 6.7.1, so results also name the build's commit from xtb's version line in provenance.program_commit (26dd68d for the g-xTB build, edcfbbe for upstream 6.7.1).

Keywords become command-line flags in xtb's own spelling: {"alpb": "water"} gives --alpb water, {"etemp": 1000} gives --etemp 1000, a list gives several values ({"alpb": ["water", "bar1M"]}), True gives a bare flag, and False or None leaves the flag out. For optimizations, {"opt": "tight"} sets the optimization level. A keyword that is not one of xtb's options is refused before xtb runs (kind input, code unknown_key) with the closest option named, and so are flags the codec sets itself (chrg, uhf, the method and run-type flags) and flags that would run something else or move the molecule (cma); xtb itself only warns about an unknown flag and runs without it. xtb runs on one thread unless the input asks for more (threads, or xtb's own parallel, not both): it nests OpenMP threads and slows down badly otherwise, so parallelize over calculations instead. Detailed input ($constrain, $fix, $wall, ...) goes in an xcontrol file supplied through files and named with {"input": "xcontrol"}; such files are passed through verbatim, so atom indices in them are 1-based as xtb expects.

Hessians are xtb's numerical second derivatives (central differences of gradients) at the input geometry, with nothing projected out. xtb projects translations and rotations out of the Hessian it writes to hessian, which is wrong away from a stationary point, where the gradient fixes the Hessian's rotational part; so the codec has xtb also write the Hessian before projection ($write hessian.out=true in the xcontrol file, appended to yours if you supply one) and returns that one. Hessians also fill frequencies and normal modes from g98.out (with translations and rotations projected out), where xtb writes mass-weighted vectors rounded to two decimals; the codec converts them to unit-length Cartesian displacements, as qcdata defines them. A Hessian also carries the energy and the gradient at the input geometry: the codec adds --grad to --hess, which costs one more gradient beside the Hessian's displaced ones.

One keyword is not an xtb flag: external_potentials, point charges for QM/MM electrostatic embedding, in the same form the Psi4 codec takes: [[charge, [x, y, z]], ...] in bohr. An optional third entry, [charge, [x, y, z], atomic_number], names the element whose chemical hardness xtb uses to damp that charge's interaction at short range. The codec writes them to pcharge and adds an $embedding group to the xcontrol file (appending to yours if you supply one); gradients then also fill point_charge_gradient from xtb's pcgrad. Only GFN1- and GFN2-xTB apply point charges: GFN0, GFN-FF, and g-xTB ignore them without a warning, so the codec rejects them there.

Failures and their kinds: an SCF that does not converge is convergence (code scf_not_converged), an optimization that runs out of cycles convergence (max_iter), with its trajectory attached; atoms on top of each other, a multiplicity the number of electrons cannot have, and a solvent xtb has no parameters for are input; an unknown option given in cmdline_args is input (unknown_key); gxtb on an xtb build without g-xTB is environment.

Examples

Each script runs as written. Copy it, delete the options you don't need, and run it with python script.py. They live in the repository's examples/ folder.

Single point: energy, gradient, Hessian

examples/xtb/single_point.py

"""xtb single point: energy, gradient, or Hessian with GFN-xTB, GFN-FF, or g-xTB.

Requires: ``pip install qccompute[qccodec]`` and xtb on PATH, e.g.
``conda install -c conda-forge xtb``. For g-xTB (``method="gxtb"``) use the xtb build
from https://github.com/grimme-lab/g-xtb instead; it also runs every other method.
GFN0-xTB reads its parameter file from the directory named by ``XTBPATH``.

How the codec talks to xtb (https://xtb-docs.readthedocs.io/):

- ``model.method`` picks the Hamiltonian: "gfn0", "gfn1", "gfn2", "gfnff", or "gxtb".
  There is no basis set.
- Charge and multiplicity come from ``structure`` (passed as ``--chrg`` and ``--uhf``).
- ``keywords`` become xtb command-line flags (``xtb --help``): ``{"alpb": "water"}``
  gives ``--alpb water``, ``True`` gives a bare flag, and ``False``/``None`` drop it.
  Flags the codec sets itself (``chrg``, ``uhf``, ``gfn``, ``sp``, ``hess``, ...)
  are rejected.
- xtb only warns about options it does not know and runs without them; the codec
  turns that warning into a failure, so a typo never silently changes the method.
- Detailed settings (``$scc``, ``$wall``, ``$constrain``, ...) go in an xcontrol file
  (``man 7 xcontrol``); see the commented example below. Atom indices in it are
  1-based, as xtb expects.
- ``external_potentials`` (point charges, as for Psi4) is the one keyword that is not
  an xtb flag: the codec writes it to ``pcharge`` and adds an ``$embedding`` group.
- g-xTB has no ALPB/GBSA parameters (xtb stops with "No ALPB/GBSA parameters found")
  and xtb 6.7.1 silently ignores ``cpcmx`` with g-xTB, so run g-xTB in the gas phase.
- xtb's Hessian is numerical (finite differences of analytic gradients) and comes
  with harmonic frequencies and normal modes. Do not pass ``cma``: it moves the
  molecule to its principal axes, so results would not match ``structure``.
"""

from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, Structure

calctype = CalcType.gradient  # or CalcType.energy, CalcType.hessian

# Coordinates are in bohr (Structure.from_xyz / Structure.open read angstrom files).
structure = Structure(
    symbols=["O", "H", "H"],
    geometry=[[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]],
    charge=0,
    multiplicity=1,  # open shells: xtb gets multiplicity - 1 unpaired electrons
)

prog_input = ProgramInput(
    program="xtb",
    calctype=calctype,
    structure=structure,
    model=Model(method="gfn2"),  # or "gfn1", "gfn0", "gfnff", "gxtb" (g-xTB build)
    keywords={
        # Any xtb command-line flag, without the leading dashes:
        "parallel": 1,  # threads
        "acc": 1.0,  # SCC accuracy; lower is tighter (0.0001 to 1000)
        "iterations": 250,  # maximum SCC iterations
        # "etemp": 300,  # electronic temperature (K); raise it for difficult SCCs
        #
        # Implicit solvent; pick one model (GFN1/GFN2/GFN-FF only, not g-xTB):
        "alpb": "water",  # ALPB; ["water", "bar1M"] also sets the reference state
        # "gbsa": "h2o",  # GBSA (its own solvent names)
        # "cpcmx": "water",  # CPCM-X
        #
        # Extra output, found in the logs or with collect_files=True:
        # "molden": True,  # orbitals in molden.input
        # "wbo": True,  # Wiberg bond orders in wbo
        # "json": True,  # xtbout.json
        #
        # Detailed settings from an xcontrol file (pass it in `files` below):
        # "input": "xcontrol",
        #
        # Point charges for QM/MM electrostatic embedding (GFN1/GFN2 only; xtb
        # ignores them for GFN0, GFN-FF, and g-xTB, so the codec refuses those):
        # [charge, [x, y, z]] in bohr, optionally followed by the atomic number
        # whose hardness damps the charge at short range. The gradient on the
        # charges comes back as point_charge_gradient.
        # "external_potentials": [[-0.834, [0.0, 0.0, 5.5], 8], [0.417, [1.4, 0.0, 6.4], 1]],
    },
    # files={"xcontrol": "$scc\n   temp=500\n$end\n"},
)

output = compute(
    prog_input,
    # timeout=600,  # seconds before xtb is killed
)

results = output.results
print("Energy (Hartree):", results.energy)
if results.gradient is not None:
    print("Gradient (Hartree/bohr):\n", results.gradient)
if results.hessian is not None:
    print("Frequencies (cm^-1):", results.vibrational_analysis.frequencies)
    print(
        "Normal modes (modes, atoms, xyz):",
        results.vibrational_analysis.vibrational_analysis.normal_modes_cartesian.shape,
    )
print("Partial charges:", results.atomic_charges)
if results.point_charge_gradient is not None:
    print("Gradient on point charges:\n", results.point_charge_gradient)
print("xtb version:", results.provenance.program_version)

Optimization

examples/xtb/optimization.py

"""xtb geometry optimization with its built-in optimizer, ANCopt.

Requires: ``pip install qccompute[qccodec]`` and xtb on PATH, e.g.
``conda install -c conda-forge xtb`` (or the g-xTB build of xtb for ``method="gxtb"``,
https://github.com/grimme-lab/g-xtb).

Notes for xtb optimizations (https://xtb-docs.readthedocs.io/en/latest/optimization.html):

- ``{"opt": "tight"}`` sets the convergence level: "crude", "sloppy", "loose",
  "normal" (default), "tight", "verytight", or "extreme". ``cycles`` caps the steps.
- xtb exits normally when it runs out of cycles; the codec reports that as a failure
  ("failed to converge geometry optimization").
- Each step in ``results.frames`` has its structure and energy but no gradient:
  xtb's log records only those.
- Constraints go in an xcontrol file (``$fix``, ``$constrain``, ``$wall``; see
  https://xtb-docs.readthedocs.io/en/latest/xcontrol.html). Its atom indices are
  1-based, unlike the 0-based indices used elsewhere in qcdata.
- Other keywords become xtb command-line flags, as in single_point.py: solvent,
  accuracy, electronic temperature, threads.
- For transition states, or an optimizer that records gradients at every step, drive
  xtb gradients with geomeTRIC (examples/geometric/).
"""

from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, Structure

# Coordinates are in bohr.
structure = Structure(
    symbols=["O", "H", "H"],
    geometry=[[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]],
    charge=0,
    multiplicity=1,
)

prog_input = ProgramInput(
    program="xtb",
    calctype=CalcType.optimization,
    structure=structure,
    model=Model(method="gfn2"),  # or "gfn1", "gfnff", "gxtb" (g-xTB build)
    keywords={
        # ANCopt settings:
        "opt": "tight",  # convergence level
        "cycles": 100,  # maximum optimization steps
        #
        "parallel": 1,  # threads
        "alpb": "water",  # implicit solvent; or "gbsa": "h2o"
        # "etemp": 300,  # electronic temperature (K)
        #
        # Constraints from an xcontrol file (pass it in `files` below):
        # "input": "xcontrol",
    },
    # Keep the first O-H bond at its starting length and freeze the oxygen atom.
    # xcontrol atom indices are 1-based: atom 1 is structure.symbols[0].
    # files={
    #     "xcontrol": (
    #         "$constrain\n"
    #         "   force constant=1.0\n"
    #         "   distance: 1, 2, auto\n"
    #         "$fix\n"
    #         "   atoms: 1\n"
    #         "$end\n"
    #     )
    # },
)

output = compute(
    prog_input,
    # timeout=600,  # seconds before xtb is killed
)

results = output.results
print("Frames (structures evaluated):", len(results.frames))
print("Energies (Hartree):", results.energies)
print("Final structure (bohr):\n", results.final_structure.geometry)
# Save the trajectory, e.g. to view in a molecule viewer:
# results.save("optimization.json"); results.final_structure.save("final.xyz")

Many calculations at once

examples/xtb/many_calculations.py

"""xtb for many structures at once: calculations run side by side.

Requires: what examples/xtb/single_point.py requires.

How lists work (the same for every program that runs as its own process: ORCA,
Psi4, CREST, DFTB+, TeraChem, ...):

- Pass ``compute`` a list of inputs to get a list of outputs in the same order. Each
  calculation runs in its own process and directory, so several run at once in
  threads; no ``if __name__ == "__main__":`` guard is needed.
- A list shares the runner's threads (all the cores this process may use for
  ``qccompute.compute``, or ``qccompute.Runner(threads=...)``): each calculation gets
  its ``threads`` keyword, else its part of them, and never more run at once. With 16
  cores and ``threads`` 2, eight xtb calculations run at once (xtb itself runs on one
  thread unless asked). GPU programs (TeraChem) get their own GPUs through
  ``CUDA_VISIBLE_DEVICES``.
- The inputs may mix programs, methods, and calculation types.
- Every calculation runs first. Then, if any failed, ``qcdata.ProgramErrors`` (an
  ``ExceptionGroup``) is raised: each error is a ``qcdata.ProgramError`` whose
  ``output`` is the failed output, and ``.results`` holds every output in input
  order. With ``raise_exc=False`` the outputs are returned as they are; check
  ``output.success``. For outputs as they finish, ``runner.submit`` each input (with
  ``threads``) and use ``concurrent.futures.as_completed``.
"""

import math
import time

from qccompute import Runner, compute
from qcdata import CalcType, Model, ProgramErrors, ProgramInput, Structure


def water(r: float) -> Structure:
    """Water with one O-H bond stretched to r bohr, the other at 1.81 bohr."""
    angle = math.radians(104.5)
    return Structure(
        symbols=["O", "H", "H"],
        geometry=[
            [0.0, 0.0, 0.0],
            [r, 0.0, 0.0],
            [1.81 * math.cos(angle), 1.81 * math.sin(angle), 0.0],
        ],
    )


distances = [1.4 + 0.1 * i for i in range(20)]  # bohr
inputs = [
    ProgramInput(
        program="xtb",
        calctype=CalcType.gradient,
        structure=water(r),
        model=Model(method="gfn2"),
        keywords={"threads": 2},  # each xtb's threads, out of the runner's
    )
    for r in distances
]

start = time.perf_counter()
try:
    outputs = compute(
        inputs,
        # timeout=600,  # seconds each calculation may run
    )
except ProgramErrors as errors:
    outputs = errors.results  # every output, failed ones with success=False
    for i, output in enumerate(outputs):
        if not output.success:
            print(f"Input {i} failed: {output.error}")
parallel = time.perf_counter() - start

start = time.perf_counter()
with Runner(threads=2) as runner:  # one at a time, for comparison
    runner.compute(inputs)
serial = time.perf_counter() - start

print("r (bohr)  energy (Hartree)")
for r, output in zip(distances, outputs, strict=True):
    print(f"{r:8.2f}  {output.results.energy:16.8f}")
print(f"Side by side: {parallel:.2f} s; one at a time: {serial:.2f} s")