Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

qcopt

Minimizations, transition-state searches, and IRCs for the qc* stack. Inputs and outputs are qcdata objects; gradients and Hessians come from any program qccompute runs, such as axtb (g-xTB and GFN2-xTB) or a DFT code, through its sessions, which warm-start from step to step.

A qcopt calculation is a qcdata ProgramInput: the calculation type, the starting structure, qcopt's settings as keywords, and the programs that compute gradients (and Hessians) as subprograms. qcopt.compute runs it:

import qcopt
from qcdata import ProgramInput, Structure

# accuracy_scale 0.01: at axtb's default SCF accuracy, g-xTB gradients carry ~1e-5
# Eh/bohr of noise, the size of qcopt's convergence threshold (12% more time per gradient).
gxtb = {"program": "axtb", "model": {"method": "gxtb-v2.0.1"}, "keywords": {"accuracy_scale": 0.01}}

ts = qcopt.compute(
    ProgramInput(
        program="qcopt",
        calctype="transition_state",   # or "optimization", "irc"
        structure=Structure.open("ts_guess.xyz"),
        keywords={"freq": {"check": True}},
        subprograms=[{**gxtb, "calctype": "gradient"}, {**gxtb, "calctype": "hessian"}],
    )
)
ts.results.final_structure      # the saddle point: one imaginary mode

The hessian subprogram is optional. Without it, minimizations start from Lindh's model Hessian and transition states from finite differences of gradients. It may be another program than the gradients', often a cheaper method: the frames keep the gradient program's energies and gradients.

gfn2 = {"program": "axtb", "model": {"method": "gfn2"}, "keywords": {"accuracy_scale": 0.01}}
subprograms = [{**gxtb, "calctype": "gradient"}, {**gfn2, "calctype": "hessian"}]

Any calculation can start from results already known at its structure (ProgramInput.given): their Hessian becomes the starting one, from any program. An IRC from a search with freq.check starts from the search's transition-state Hessian, and computes only the gradient there:

last = ts.results.frames[-1]
path = qcopt.compute(
    ProgramInput(
        program="qcopt",
        calctype="irc",
        structure=last.structure,
        given=last.results,              # its Hessian: the IRC's at the transition state
        keywords={"ends": {"minimize": True}},
        subprograms=[{**gxtb, "calctype": "gradient"}, {**gxtb, "calctype": "hessian"}],
    )
)                                        # a ProgramOutput holding PathData

A calculation that fails or does not converge raises qcdata.ProgramError, which carries the failed output, frames included, as output (see Results).

Many calculations at once go through qccompute, the runner of AFH programs: qccompute.compute([inp1, inp2, ...]). They advance in lockstep, and each round's gradients from all of them are computed together. qcopt computes its gradients and Hessians through sessions of the child programs, one per calculation and program, warm-started from geometry to geometry (each IRC branch its own lineage), under the runner's resources. Called directly, qcopt.compute hands itself to qccompute's default runner, which runs it on this machine.

A qcopt calculation asks the runner for the threads its children's plans ask for, and the runner gives them to the children: qcopt's own steps run on one BLAS thread. A child that names no number (axtb without threads) asks for all of them, which a lone search uses well. Many calculations submitted one by one (qccompute.submit) then run one at a time: give the child's spec threads (often 1 for small molecules), or pass them as one list, which runs them together.

Settings

Settings come in groups, under keywords:

keywords={"convergence": {"g_tol": 1e-5, "max_iter": 200},
          "constraints": {"frozen": [0, 1], "distance": [[2, 3, 2.9]]}}
keywords={"hessian": {"recompute_every": 5}, "mode": {"guide": tangent},
          "coordinate_system": "cartesian"}            # a transition state
keywords={"irc": {"step": 0.2}, "ends": {"minimize": True}}   # an IRC

The common settings (docs/settings.md documents every one, with its default and unit):

group settings calculation types
coordinate_system auto (TRIC; Cartesians with frozen atoms), tric, dlc, cartesian min, TS
convergence max_iter, g_tol (largest atomic gradient, Eh/bohr), g_rms_tol, d_tol, e_tol all (IRC: per branch)
trust radius, min, max (bohr) min, TS
hessian initial (auto, exact, model, ...), update, recompute_every, step all
constraints frozen, distance, angle, dihedral (degrees) min, TS (IRC: frozen)
mode guide (a direction to climb), follow TS
freq check (frequencies at the end decide), imaginary_cutoff (cm⁻¹) min, TS
escape attempts, step: step off saddle points a minimization stops on min
irc direction, step (bohr amu^1/2), method (gs2, lqa) IRC
ends minimize (the IRC's ends), coordinate_system, max_iter, g_tol IRC

The rules, shared with AFH's other programs (axtb, linus):

  • Atomic units (bohr, Hartree) unless a setting says otherwise.
  • "auto" means qcopt decides, and every result records what it decided and why.
  • A misspelled or unknown setting is an error that says what was meant. So is a setting of another calculation type, and one given that cannot affect the calculation (such as escape.step without escape.attempts): you always know what is computed. Settings that act only if a condition arises during the run are allowed.
  • qcopt.program.program.settings_schema(calctype) is the JSON Schema of each calculation type's settings.

docs/choosing-settings.md has the benchmark evidence behind the defaults and when to change them.

Results

A ProgramOutput holding OptimizationData (minima, transition states) or PathData (IRCs). Every frame is a qcdata Frame with the energy and gradient computed there. A run that fails or does not converge raises ProgramError; its output has success=False and keeps its frames (qccompute.compute(..., raise_exc=False) returns it in place). The output's standard slots, the same in every AFH program:

  • resolved: settings, the settings with every auto replaced (pass them back as keywords to reproduce the run), and reasons;
  • record: what happened: gradients and Hessians computed, coordinate rebuilds, rejected steps, IRC branch ends, the step log;
  • error, on failure: kind (input, program: a gradient or Hessian calculation failed, with its program and its own error as cause, and a message that starts with the program and calculation type, axtb (gradient): ...; convergence, with code such as max_iter or not_first_order_saddle; numerical; internal), message and code. traceback holds the message, then the failed calculation's own traceback;
  • execution.timings: subprograms (in the gradient and Hessian programs), optimizer (qcopt's own), total.

What it does

Calculation Method
optimization RS-RFO in TRIC coordinates (Wang and Song, 2016: each molecule's internal coordinates plus its translation and rotation), or delocalized internals, or Cartesians; Lindh model Hessian or the program's exact one; BFGS updates (Bofill while the Hessian is indefinite); optional frequency check that steps off saddle points
transition_state RS-P-RFO climbing the lowest mode (or, in Cartesians, one following a guide direction); exact (or a cheaper method's) or finite-difference starting Hessian; TS-BFGS updates; recomputed when the negative mode is lost; fails when it ends without negative curvature
irc Mass-weighted steepest descent by Gonzalez-Schlegel steps (or the local quadratic approximation), both branches together, frames in the input's frame; overshoots retried at half the step; optionally both ends minimized together

How it is built, and where to extend it: ARCHITECTURE.md.

Benchmarks

benchmarks/ compares qcopt with Sella, geomeTRIC and OptKing on the same axtb gradients; results are summarized in AFH's findings.

Install

pip install --pre "qcopt==0.3.0a7"         # on the stack's alpha 7 (qcdata 0.24.0a8, qccompute 0.23.0a7)
pip install --pre "qcopt[axtb]==0.3.0a7"   # with axtb: g-xTB and GFN2-xTB, analytic Hessians

This README describes the 0.3 alphas. Without --pre, pip installs qcopt 0.2, whose interface differs.

The axtb extra installs axtb 0.2 or newer, the first with sessions. Its wheels are for x86-64 Linux; elsewhere pip builds it from source, which needs Rust.

Status

0.x: the API may still change between minor versions.

License

MIT.

Metadata

Release files for qcopt 0.3.0a7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qcopt 0.3.0a7
File Size Uploaded Provenance Actions
qcopt-0.3.0a7.tar.gz 232.7 kB With provenance Details for qcopt-0.3.0a7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qcopt 0.3.0a7
File Interpreter ABI Platform Actions
qcopt-0.3.0a7-py3-none-any.whl Python 3 none any Details for qcopt-0.3.0a7-py3-none-any.whl

Total release size: 321.6 kB

Release files / qcopt-0.3.0a7.tar.gz

Download URL qcopt-0.3.0a7.tar.gz
Size 232.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9dde78ff7ed45365e3800e5bc840bc3b11ac942a28a81955070dc3d723795424
BLAKE2b-256 checksum
How to use checksums
f84ec0f89318cb3a0cc6a0dab3db8f3394f49aa20fb93f434e26920d47869b67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / qcopt-0.3.0a7-py3-none-any.whl

Download URL qcopt-0.3.0a7-py3-none-any.whl
Size 89.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
38882eb124cbec9ba55a8dc500fc867a6c552e4f1b19f090749d7c9ddcdfb8f9
BLAKE2b-256 checksum
How to use checksums
b442dd8591437c97a30e65c091eaf8ced53f3f3a996a4e667d10cf3101cbb1ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for qcopt 0.3.0a7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for qcopt-0.3.0a7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page