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.
One qcopt calculation needs nothing set: it runs on its caller's threads (the runner's,
at top level), its gradient and Hessian calculations use them, and qcopt's own steps take
one. For many calculations at once, set threads: 1 on each qcopt input, or pass them as
one list, which divides the threads among them. qccompute's
Threads page has the rules.
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: minimize both ways off saddle points a minimization stops on, and keep the lower |
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 |
threads |
CPU threads the calculation asks the runner for (AFH's shared resource key) | all |
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.stepwithoutescape.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, with each setting'sx-tier,x-concern,x-unitandx-applies-toas qcdata's conventions define them.
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 everyautoreplaced (pass them back askeywordsto reproduce the run), andreasons;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 itsprogramand its own error ascause, and a message that starts with the program and calculation type,axtb (gradient): ...;convergence, withcodesuch asmax_iterornot_first_order_saddle;numerical;stopped:qccompute.stop(future)ended it before its next step;timeout: the caller's time ran out;internal),messageandcode.tracebackholds 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 minimizes both ways off saddle points and keeps the lower |
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 qcopt # on qccompute 0.23 (qcdata 0.24)
pip install "qcopt[axtb]" # with axtb: g-xTB and GFN2-xTB, analytic Hessians
The axtb extra installs axtb 0.2 or newer. 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qcopt-0.3.0.tar.gz | 240.4 kB | With provenance | Details for qcopt-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qcopt-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for qcopt-0.3.0-py3-none-any.whl |
Total release size: 333.1 kB
Release files / qcopt-0.3.0.tar.gz
| Download URL | qcopt-0.3.0.tar.gz |
|---|---|
| Size | 240.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aa617a73cb106287c944408ed3becaa83777795a8da57c59c993e4ed048e3164
|
|
BLAKE2b-256 checksum How to use checksums |
bff669a980d1486d4606a9f0315c46b6a58d5819272d46e54050ace9fcdb1998
|
| 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 20, 2026.
Transparency logRelease files / qcopt-0.3.0-py3-none-any.whl
| Download URL | qcopt-0.3.0-py3-none-any.whl |
|---|---|
| Size | 92.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7c6bdf583576ce1810e5993f653d388df737c0b6bd3fd2f3aac12208e5917f5
|
|
BLAKE2b-256 checksum How to use checksums |
8ce779ff196c80eef9bca20ed10f315cdb12ae47924a345e0933f0a9e4e96d73
|
| 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 20, 2026.
Transparency logSecurity for qcopt 0.3.0
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.
Attestation for qcopt-0.3.0.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 20, 2026.
Transparency logA 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.