Skip to content

geomeTRIC

geomeTRIC: optimizations, transition-state searches, and IRCs driving another program.

geomeTRIC runs in Python and asks for gradients through a callback: every step is a full gradient calculation of the program named in subprograms, run by qccompute like any other calculation and kept in the trajectory. Any codec with gradients works as the child, including ones registered with qccodec.register.

Inputs map to geomeTRIC as follows:

  • subprograms must hold one ProgramSpec with calctype="gradient": the child program, its model, and its own keywords (passed to that program unchanged).
  • keywords are geomeTRIC's optimizer parameters (geometric.params.OptParams): maxiter, convergence_set, convergence_energy, trust, hessian, enforce, ... Two are handled by the codec: coordsys (tric by default, or cart, prim, dlc, hdlc) and constraints (geomeTRIC's constraint dictionary, e.g. {"freeze": [{"type": "xyz", "indices": [0]}]}, with set distances in bohr; scans are not supported). geomeTRIC itself ignores parameters it does not know, so the codec refuses them first (kind input, code unknown_key, with the closest parameter named), as it refuses those it sets itself (transition, irc, xyzout), those that only write files it does not return (qdata, write_cart_hess, wigner), meci and bigchem; irc_direction outside an IRC is not_applicable.
  • cmdline_args are not accepted.

Calculation types: optimization, transition_state (transition=True; geomeTRIC computes a starting Hessian from finite differences of child gradients), and irc (irc=True, from the transition state in structure; geomeTRIC computes its Hessian the same way). An IRC returns a PathData: the path geomeTRIC accepted, from the end of its backward branch, through the transition state (ts_index), to the end of its forward branch, each frame the child calculation at that point. Its frames are the accepted points only; rejected trial steps are left out. geomeTRIC finishes each branch by optimizing to the minimum once the IRC has converged, so the ends are minima (its irc_direction keyword can limit the IRC to one branch).

The trajectory holds one frame per structure the optimizer evaluated, the starting structure first, so n steps give n + 1 frames. Gradients at the displaced geometries of a finite-difference Hessian are not steps, so they are left out, unless one fails. Each Hessian geomeTRIC computes is attached to the frame at its geometry (frame.results.hessian): the first frame for hessian="first", the default for transition states, and also the last frame for "first+last" or "last". Atom indices in constraints are 0-based, as in geomeTRIC's Python interface.

Each step is a calculation of the subprogram through the runner (ctx.compute), so the step's program runs wherever the runner places it. Called directly, the program hands itself to qccompute.compute. Its subprogram runs on the optimization's thread count (unless the subprogram sets threads), and the optimization plans the GPUs its subprogram's plan asks for; its own Python holds its thread pools at one thread.

geomeTRIC runs in the caller's process: it writes its files in the calculation directory, its log (the geometric.nifty logger) goes to the output's logs rather than the caller's handlers, and several optimizations run side by side in threads. Its subprograms are therefore found as any calculation in that process finds them, including programs registered there with qccompute.register_program. A timeout stops its subprograms, not geomeTRIC's own Python.

Failures and their kinds: running out of iterations (maxiter) is convergence (code max_iter); an IRC started from a structure that is not a first-order saddle point is input (not_first_order_saddle); parameters geomeTRIC rejects are input; non-finite gradients are numerical; a failed subprogram is program, with its error as the cause. The trajectory so far is attached to every failure, and geomeTRIC's traceback is in the output's traceback.

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.

Optimization

examples/geometric/optimization.py

"""geomeTRIC geometry optimization driving another program's gradients.

Requires: ``pip install qccompute[qccodec] qccodec[geometric]`` (geomeTRIC itself) and the
gradient program on PATH. This example uses CREST for fast GFN2-xTB gradients:
https://github.com/crest-lab/crest/releases (official static build).

How it works (https://geometric.readthedocs.io/):

- geomeTRIC runs in Python and asks for a gradient at every step. Each one is a full
  ``gradient`` calculation of the program in ``subprograms``, with that program's own
  model and keywords, so any program with gradients works: CREST, xtb, Psi4, ORCA,
  TeraChem, ... Swap the ``ProgramSpec`` below for one of the commented alternatives.
- ``keywords`` are geomeTRIC's optimizer parameters (``geometric.params.OptParams``,
  the long ``geometric-optimize --help`` names). geomeTRIC ignores names it does not
  know, so check spelling against its documentation.
- ``coordsys``: "tric" (default, translation-rotation internal coordinates, good for
  several molecules), "dlc", "prim", or "cart".
- ``constraints`` use geomeTRIC's dictionary format with 0-based atom indices,
  distances in bohr, and angles in degrees. Scans are not supported.
- Each step in ``results.frames`` is a frame: its structure and the child's
  results (energy, gradient, charges, ...), whichever program it is.
- QM/MM: this is the way to optimize a QM region in point charges with Psi4, since
  Psi4 1.11's own optimizer cannot (see the Psi4 child below). The charges stay fixed.
"""

from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, ProgramSpec, 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,
)

# The program that computes energies and gradients: CREST with GFN2-xTB.
gradient_program = ProgramSpec(
    program="crest",
    calctype=CalcType.gradient,
    model=Model(method="gfn2"),
    keywords={"threads": 1, "calculation": {"level": [{"alpb": "water"}]}},
)

# xtb instead (examples/xtb/single_point.py lists its keywords):
# gradient_program = ProgramSpec(
#     program="xtb",
#     calctype=CalcType.gradient,
#     model=Model(method="gfn2"),
#     keywords={"alpb": "water"},
# )

# Psi4 instead, here with QM/MM point charges [charge, [x, y, z]] in bohr:
# gradient_program = ProgramSpec(
#     program="psi4",
#     calctype=CalcType.gradient,
#     model=Model(method="wb97x-d", basis="def2-svp"),
#     keywords={
#         "external_potentials": [[-0.2, [0.0, 0.0, 8.0]], [0.2, [2.0, 2.0, 9.0]]],
#     },
#     cmdline_args=["-n", "1", "--memory", "2GB"],
# )

# TeraChem instead (GPU); pass propagate_wfn=True to compute() below:
# gradient_program = ProgramSpec(
#     program="terachem",
#     calctype=CalcType.gradient,
#     model=Model(method="wb97xd3", basis="def2-svp"),
#     keywords={"dftd": "d3"},
# )

prog_input = ProgramInput(
    program="geometric",
    calctype=CalcType.optimization,
    structure=structure,
    subprograms=[gradient_program],
    keywords={
        "coordsys": "tric",  # or "dlc", "prim", "cart"
        "maxiter": 100,  # maximum optimization steps
        "convergence_set": "gau",  # or "gau_loose", "gau_tight", "gau_verytight", ...
        # Individual criteria override the set (Hartree, Hartree/bohr, angstrom):
        # "convergence_energy": 1e-6,
        # "convergence_grms": 3e-4,
        # "convergence_gmax": 4.5e-4,
        # "convergence_drms": 1.2e-3,
        # "convergence_dmax": 1.8e-3,
        # "trust": 0.1,  # starting trust radius (angstrom)
        # "tmax": 0.3,  # largest trust radius (angstrom)
        #
        # Constraints (0-based atom indices; distances in bohr, angles in degrees):
        # "constraints": {
        #     "freeze": [{"type": "xyz", "indices": [0]}],  # fix the oxygen in place
        #     "set": [{"type": "angle", "indices": [1, 0, 2], "value": 104.5}],
        # },
    },
)

output = compute(
    prog_input,
    # timeout=3600,  # seconds before the whole optimization is stopped
)

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

Transition state

examples/geometric/transition_state.py

"""geomeTRIC transition-state search driving another program's gradients.

Requires: ``pip install qccompute[qccodec] qccodec[geometric]`` (geomeTRIC itself) and the
gradient program on PATH. This example uses CREST for fast GFN2-xTB gradients:
https://github.com/crest-lab/crest/releases (official static build).

Notes for geomeTRIC transition-state searches (https://geometric.readthedocs.io/):

- ``CalcType.transition_state`` turns on geomeTRIC's saddle-point optimizer.
  geomeTRIC needs a starting Hessian, which it builds by finite differences of child
  gradients (two per Cartesian coordinate). Those displaced gradients are not
  optimizer steps, so ``results.frames`` leaves them out: it holds one frame per
  structure the optimizer evaluated, the starting structure first, and each Hessian geomeTRIC computes is attached to the frame at its
  geometry (``frame.results.hessian``).
- ``"hessian"`` chooses when: ``"first"`` (the default) at the start,
  ``"first+last"`` also at the end, which is how this example checks its result,
  ``"each"`` at every step (costly).
- Start close to the saddle point. This example starts from nearly planar ammonia;
  its inversion transition state is planar, with one imaginary frequency.
- A transition state has exactly one negative Hessian eigenvalue (one imaginary
  frequency). The final frame's Hessian shows it, whatever the child program.
- The child program, coordinate systems, constraints, and QM/MM point charges work
  as in optimization.py; swap the ``ProgramSpec`` for xtb, Psi4, TeraChem, ...
- Transition-state steps use a small trust radius by default (``trust`` 0.01,
  ``tmax`` 0.03 angstrom), so expect more steps than for a minimum.
"""

import numpy as np
from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, ProgramSpec, Structure

# Ammonia near its planar inversion saddle point, coordinates in bohr.
structure = Structure(
    symbols=["N", "H", "H", "H"],
    geometry=[
        [0.0, 0.0, 0.01],
        [1.88, 0.0, 0.01],
        [-0.94, 1.62, 0.01],
        [-0.94, -1.62, 0.01],
    ],
    charge=0,
    multiplicity=1,
)

# The program that computes energies and gradients: CREST with GFN2-xTB.
gradient_program = ProgramSpec(
    program="crest",
    calctype=CalcType.gradient,
    model=Model(method="gfn2"),
    keywords={"threads": 1},  # add "calculation": {"level": [{"alpb": "water"}]}
)

# Psi4 instead (any gradient program works; see optimization.py for more):
# gradient_program = ProgramSpec(
#     program="psi4",
#     calctype=CalcType.gradient,
#     model=Model(method="wb97x-d", basis="def2-svp"),
#     cmdline_args=["-n", "1", "--memory", "2GB"],
# )

prog_input = ProgramInput(
    program="geometric",
    calctype=CalcType.transition_state,
    structure=structure,
    subprograms=[gradient_program],
    keywords={
        "coordsys": "tric",  # or "dlc", "prim", "cart"
        "maxiter": 100,
        "convergence_set": "gau",  # or "gau_tight", ...
        "hessian": "first+last",  # exact Hessians at the start and the end
        # "trust": 0.01,  # starting trust radius (angstrom)
        # "tmax": 0.03,  # largest trust radius (angstrom)
    },
)

output = compute(
    prog_input,
    # timeout=3600,
)

results = output.results
print("Frames (structures evaluated):", len(results.frames))
print("Transition-state energy (Hartree):", results.energies[-1])
print("Transition-state structure (bohr):\n", results.final_structure.geometry)

# Confirm the saddle point: exactly one negative eigenvalue of the final Hessian.
final_hessian = results.frames[-1].results.hessian
eigenvalues = np.linalg.eigvalsh(final_hessian)
print("Negative Hessian eigenvalues:", int((eigenvalues < -1e-3).sum()), "(1 for a TS)")

Many calculations at once

examples/geometric/many_calculations.py

"""geomeTRIC for many structures at once: optimizations run side by side.

Requires: what examples/geometric/optimization.py requires (geomeTRIC and CREST).

How lists of Python calculations work (geomeTRIC, tblite, the ML potentials):

- geomeTRIC runs in this process: it writes only in its calculation directory and
  logs through one logger, so a list's optimizations run side by side in threads, and
  a program registered in this script can be its gradient program. tblite and the ML
  potentials run in worker processes instead (``python -m qccompute.serve``), which
  stay alive between calls until the runner closes; this script is never imported
  again there and needs no ``if __name__ == "__main__":`` guard.
- A list is packed into the runner's threads (all the cores this process may use, or
  ``qccompute.Runner(threads=...)``): an optimization counts the threads of its
  gradient program (CREST ``threads`` here). A worker sets each call's threads for
  PyTorch and the BLAS and OpenMP runtimes, so numpy does not start a thread per core.
- The gradient calculations run inside each optimization, through the runner.
- Failures are reported as for any list: see examples/xtb/many_calculations.py.
"""

import random
import time

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

random.seed(0)
start_geometry = [[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]]


def jiggled() -> Structure:
    """The starting water with every coordinate moved by up to 0.2 bohr."""
    return Structure(
        symbols=["O", "H", "H"],
        geometry=[
            [x + random.uniform(-0.2, 0.2) for x in atom] for atom in start_geometry
        ],
    )


gradient_program = ProgramSpec(
    program="crest",
    calctype=CalcType.gradient,
    model=Model(method="gfn2"),
    keywords={"threads": 1},  # threads for each gradient, packed into the runner's
)
inputs = [
    ProgramInput(
        program="geometric",
        calctype=CalcType.optimization,
        structure=jiggled(),
        subprograms=[gradient_program],
        keywords={"maxiter": 100},
    )
    for _ in range(4)
]

start = time.perf_counter()
outputs = compute(inputs)  # four optimizations side by side
# with qccompute.Runner(threads=2) as runner:  # at most two at a time
#     outputs = runner.compute(inputs)
elapsed = time.perf_counter() - start

for i, output in enumerate(outputs):
    results = output.results
    print(
        f"Optimization {i}: {len(results.frames)} frames, final energy "
        f"{results.energies[-1]:.8f} Hartree"
    )
print(f"Four optimizations side by side: {elapsed:.2f} s")

IRC

examples/geometric/irc.py

"""geomeTRIC intrinsic reaction coordinate (IRC) driving another program's gradients.

Requires: ``pip install qccompute[qccodec] qccodec[geometric]`` (geomeTRIC itself) and the
gradient program on PATH. This example uses CREST for fast GFN2-xTB gradients:
https://github.com/crest-lab/crest/releases (official static build).

Notes for geomeTRIC IRCs (https://geometric.readthedocs.io/):

- ``CalcType.irc`` follows the IRC down both sides of the transition state in
  ``structure``, forward first, then backward. geomeTRIC needs the saddle's Hessian,
  which it computes by finite differences of child gradients (6N of them) and which is
  attached to the transition-state frame.
- ``results`` is a ``PathData``: ``frames`` are the points geomeTRIC accepted, from
  the end of its backward branch, through the transition state (``ts_index``), to the
  end of its forward branch. Each frame is the child's calculation at that point;
  rejected trial steps are left out. ``forward_barrier`` and ``reverse_barrier`` are
  the transition state's energy above the first and last frames, in Hartree.
- Once a branch's IRC has converged, geomeTRIC switches to minimizing, so the ends are
  minima. ``"irc_direction": "forward"`` (or ``"backward"``) runs one branch only.
- ``trust`` sets the IRC step size (angstrom); ``maxiter`` limits each direction.
- The codec keeps the path in the input's frame, removing the small rigid drift of
  geomeTRIC's internal-coordinate steps.
- Any program with gradients works as the child (examples/geometric/optimization.py
  shows xtb, Psi4, and TeraChem).
"""

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

# The HCN <-> HNC transition state (GFN2-xTB), coordinates in bohr.
transition_state = Structure(
    symbols=["C", "N", "H"],
    geometry=[[0.017, 0.036, 0.0], [2.283, -0.137, 0.0], [1.0, 2.0, 0.0]],
    charge=0,
    multiplicity=1,
)

prog_input = ProgramInput(
    program="geometric",
    calctype=CalcType.irc,
    structure=transition_state,
    subprograms=[
        ProgramSpec(
            program="crest",
            calctype=CalcType.gradient,
            model=Model(method="gfn2"),
            keywords={"threads": 1},
        )
    ],
    keywords={
        "maxiter": 300,  # maximum steps per direction
        # "trust": 0.05,  # IRC step size (angstrom)
        # "irc_direction": "forward",  # or "backward"; both by default
    },
)

output = compute(prog_input)
path = output.results
print("Frames:", len(path.frames), "transition state at", path.ts_index)
print(f"Forward barrier: {path.forward_barrier * 627.5095:.1f} kcal/mol")
print(f"Reverse barrier: {path.reverse_barrier * 627.5095:.1f} kcal/mol")
print("Backward end (bohr):\n", path.frames[0].structure.geometry)
print("Forward end (bohr):\n", path.frames[-1].structure.geometry)
# Save the path, e.g. to view in a molecule viewer: path.save("irc.xyz")