Skip to content

tblite

tblite: GFN1-xTB, GFN2-xTB, and IPEA1-xTB through tblite's Python API.

tblite (https://tblite.readthedocs.io) is the library implementation of the extended tight-binding methods. The codec calls tblite.interface.Calculator in the calling process, so there is no program to find on PATH: install it next to qccompute with pip install tblite (or conda install -c conda-forge tblite-python).

Inputs map to tblite as follows:

  • model.method selects the parametrization: gfn2 (GFN2-xTB), gfn1 (GFN1-xTB), or ipea1 (IPEA1-xTB); tblite's own names work too. Models have no basis set.
  • structure.charge is the total charge and structure.multiplicity - 1 the number of unpaired electrons (tblite's uhf).
  • keywords use tblite's own names. Calculator settings go to Calculator.set: acc (the accuracy factor, accuracy in tblite's Python API and --acc on its command line: the shared keyword accuracy is an accuracy target, which tblite cannot honour, kind unsupported), guess, max-iter, mixer-damping, mixer-memory, temperature (electronic temperature in Hartree, as tblite takes it; multiply kelvin by 3.166808578545117e-6), annealing, and verbosity. Interactions go to Calculator.add, with a single value or a list of arguments: alpb-solvation and gbsa-solvation (a solvent name, or [solvent, state] with state gsolv, bar1mol, or reference), ddX-solvation, gbe-solvation, gb-solvation, electric-field (a vector in atomic units), and spin-polarization (a scaling factor, usually 1.0).
  • cmdline_args and files are not accepted.

Calculation types: energy and gradient. tblite has no analytic Hessian; use program="xtb" for GFN2-xTB Hessians, or geomeTRIC with tblite gradients for optimizations. Every result records Mulliken partial charges in atomic_charges and the dipole moment (e bohr) in dipole_moment.

tblite never moves or reorients the molecule, so gradients are in the input's frame. No input field carries atom indices.

A keyword that is not a tblite setting or interaction is refused before tblite runs (kind input, code unknown_key) with the closest name. Failures and their kinds: an SCF that does not converge is convergence (scf_not_converged); atoms on top of each other, a multiplicity the number of electrons cannot have, and an unknown solvent are input; elements beyond radon are unsupported.

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

examples/tblite/single_point.py

"""tblite single point: GFN2-xTB, GFN1-xTB, or IPEA1-xTB energy or gradient.

Requires: ``pip install qccompute[qccodec] tblite`` (or ``conda install -c conda-forge
tblite-python``). tblite is a Python library, so nothing has to be on PATH: the
calculation runs in a qccompute worker process of this Python environment.

How the codec talks to tblite (https://tblite.readthedocs.io/):

- ``model.method`` picks the parametrization: "gfn2", "gfn1", or "ipea1". There is no
  basis set.
- Charge and multiplicity come from ``structure``; tblite gets multiplicity - 1
  unpaired electrons.
- ``keywords`` use tblite's own names. Settings go to ``Calculator.set`` and
  interactions (implicit solvent, electric field, spin polarization) to
  ``Calculator.add``; anything else is rejected, so a typo fails loudly.
- ``temperature`` is the electronic temperature in Hartree, not kelvin (multiply
  kelvin by 3.166808578545117e-6).
- tblite has no Hessian. Use ``program="xtb"`` for GFN2-xTB Hessians, and geomeTRIC
  with tblite gradients for optimizations (examples/geometric/).
- An SCF that does not converge raises with tblite's message.
"""

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

calctype = CalcType.gradient  # or CalcType.energy

# 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,
)

prog_input = ProgramInput(
    program="tblite",
    calctype=calctype,
    structure=structure,
    model=Model(method="gfn2"),  # or "gfn1", "ipea1"
    keywords={
        # Calculator settings:
        "acc": 1.0,  # SCC accuracy factor; lower is tighter
        "max-iter": 250,  # maximum SCC iterations
        # "temperature": 300 * 3.166808578545117e-6,  # electronic temperature (Hartree)
        # "verbosity": 0,  # silence the SCC printout
        #
        # Implicit solvent; pick one model. A solvent name, or [solvent, state]
        # with state "gsolv" (default), "bar1mol", or "reference":
        "alpb-solvation": "water",
        # "gbsa-solvation": "water",
        # "ddX-solvation": ["water", "cosmo"],
        #
        # "spin-polarization": 1.0,  # spin-polarized xTB for open shells
        # "electric-field": [0.0, 0.0, 0.001],  # uniform field (atomic units)
    },
)

output = compute(prog_input)

results = output.results
print("Energy (Hartree):", results.energy)
if results.gradient is not None:
    print("Gradient (Hartree/bohr):\n", results.gradient)
print("Partial charges:", results.atomic_charges)
print("Dipole (e*bohr):", results.dipole_moment)
print("tblite version:", results.provenance.program_version)