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¶
"""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¶
"""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")