optimize controls in .oqp¶
.oqp control reference
Use canonical routes and controls in input files. Raw names
identify implementation storage. A control without an accepted canonical
spelling is not available in .oqp files.
The optimize section selects the optimization backend, target states, and
convergence thresholds for geometry and reaction-path workflows.
Two input surfaces
Concise .oqp geometry drivers always use the native OpenQP engine and do
not accept lib, optimizer, step_size, step_tol, or mep_maxit.
Those five raw keys are not .oqp controls; their remaining API meanings are documented for implementers.
In Python scripts, use job.workflow.optimize(...) for the optimization runtype, common
optimization options, and backend options. For example,
job.workflow.optimize(istate=0) uses the native backend and its automatic DLC
coordinates. Supplying coordsys routes an explicit coordinate-system override
to the native optimizer while keeping state and convergence options in
optimize. The lower-level job.optimize(...) section helper remains
available for existing scripts.
QM/MM geometry optimisation¶
With input.qmmm_flag = true, runtype = optimize
minimises the QM/MM energy: the embedded QM energy in the ESPF field of
the MM charges, the link-atom terms, and the classical MM energy, exactly the
quantity the QM/MM dynamics drivers integrate. The gas-phase optimiser is not
used, because it would move the QM fragment in vacuum while the environment
sat still. The movable atoms are chosen with the qmmm active-atom keys —
the QM region plus the MM residues within
qmmm.active_radius, plus
active_atoms and minus
frozen_atoms — and the rest is fixed. The native trust-radius
RFO/BFGS engine drives the search, in Cartesian coordinates by default (trust radius from
oqp.trust / trust_max), orbitals are reused between steps,
and convergence is the same five-part test as the all-QM optimiser:
energy_shift, rmsd_step,
max_step, rmsd_grad and
max_grad. Only method = hf (HF and DFT), tdhf
(TDHF/MRSF) and the tight-binding methods dftb and xtb are accepted.
Options the QM/MM force does not carry are rejected rather than ignored:
frozen-distance constraints (freeze or frozen_distances in oqp or
optimize), D4 dispersion (input.d4), the MD driver's QM-coordinate
override (qmmm.qm_atoms_xyz / qm_list), guess.swapmo, and
guess.continue_geom (to continue, use the optimised full-system PDB as the
new qmmm.pdb_file).
init_scf is honoured: by default the converged orbitals of
the previous step seed the next SCF; init_scf = true restarts it at every
geometry. oqp.coordsys accepts auto, cartesian and tric; auto
means Cartesian here because the movable set can be several disconnected
fragments, and DLC/RIC are rejected because they remove the collective
translations and rotations of the movable atoms relative to the fixed MM
atoms. Relative
qmmm.pdb_file and forcefield_files entries not found in the working
directory are looked up next to the input deck. After the run,
Runner.results()["energy"] holds the QM/MM total energy of the reported
geometry at index istate, and mol.qmmm_optimization records convergence,
the number of evaluations, the final gradient measures and the movable atoms.
The result is written
as a full-system PDB (qmmm_output). Only plain
minimisation is connected; MECI, MECP, TS, IRC, MEP and NEB refuse
qmmm_flag.
rhf/6-31g opt qmmm(forcefield_files="amber14-all.xml",qm_atoms="8,9,16,17,18",active_radius=3.0,frozen_atoms="6 name:CA")
geom="ala.pdb 9 10 17 18 19"
This optimises the alanine dipeptide of the repository example
examples/QMMM/ala-dipeptide_RHF-QMMM-OPT-active with the MM residues within
3 Å of the QM region free to move, except the backbone N (index 6) and the
CA atom, which are held. The geom indices are 1-based and qm_atoms lists the
same atoms 0-based; qmmm(...) sets qmmm_flag, and qmmm.pdb_file is
taken from geom. For an excited state, use an MRSF route and name the state,
for example opt(S1).
The selection keys are documented with the rest of the qmmm section under
Active atoms; they use ORCA's
%qmmm ActiveAtoms syntax and are shared with the QM/MM dynamics drivers.
Keywords¶
lib¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | string |
| Default | oqp |
| Values | oqp, geometric, scipy |
| Used by | optimizer backend selection |
Python API backend selector; not an .oqp option. The native oqp backend
supports optimize, ts, meci, mecp, tci, neb, irc, and mep.
geomeTRIC supports optimize, meci, mecp, ts, irc, and neb; it is
retained as an optional compatibility path for advanced constraints beyond
native frozen distances. SciPy is a legacy backend for optimize, meci,
mecp, and mep.
DL-FIND is not a current user-facing optimizer backend.
optimizer¶
| Field | Value |
|---|---|
| Type | string |
| Default | bfgs |
| Values | bfgs, cg, l-bfgs-b, newton-cg |
| Used by | SciPy backend |
Selects the SciPy optimizer when lib=scipy.
maxit¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | integer |
| Default | 30 |
| Used by | optimization iterations |
Maximum number of geometry steps. The shipped multistate MECI regression uses
maxit=1 only as a short continuous-integration smoke; production searches
normally require a substantially larger limit.
states¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | integer array |
| Default | empty |
| Used by | BaekA multistate MECI |
Ordered internal response roots for optimize.meci_search=baeka. Supply at
least two distinct, ascending, consecutive values. In concise .oqp, users
write physical labels directly, for example
meci(S0,S1,S2,S3,algorithm=baeka); OpenQP creates this internal list.
istate, jstate, kstate¶
| Field | Value |
|---|---|
| Type | integer |
| Defaults | 1, 2, 3 |
| Used by | state-specific and crossing searches |
Target state indices. HF/DFT ground-state optimization uses istate=0.
TDHF/MRSF state-specific workflows use positive state indices. A QM/MM
optimisation (qmmm_flag = true) uses istate the same way and differentiates
that root of the embedded QM fragment. MECI uses
istate and jstate for the established two-state algorithms. The legacy TCI
compatibility route uses all three and requires istate < jstate < kstate;
new multistate inputs use states with meci_search=baeka.
qmmm_radius¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | float (Å) |
| Default | 0.0 |
| Used by | QM/MM optimisation (qmmm_flag = true) |
Radius of the movable shell around the QM region in a QM/MM geometry
optimisation. Every MM residue with an atom within this distance of a QM atom
moves with the QM atoms; everything else is held fixed. 0 moves the QM
atoms alone. Whole residues are selected so that waters and side chains stay
intact; in a periodic box the distance is the minimum-image distance.
This key is an alias of qmmm.active_radius,
which is the spelling the QM/MM dynamics drivers share; qmmm wins if both
are given. The companion aliases qmmm_active and qmmm_freeze are
qmmm.active_atoms and
frozen_atoms. New decks should use the qmmm
names — see Active atoms.
qmmm_output¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | string |
| Default | <project>_opt.pdb |
| Used by | QM/MM optimisation (qmmm_flag = true) |
File that receives the optimised full-system geometry (QM and MM atoms,
in the topology of qmmm.pdb_file), ready to be used
as the starting structure of a QM/MM dynamics run.
imult, jmult¶
| Field | Value |
|---|---|
| Type | integer |
| Defaults | 1, 3 |
| Used by | MECP multiplicities |
Multiplicity labels for MECP-style crossing searches. MECP requires different
values.
The MECP driver switches the response multiplicity to each value in turn, so
the response method must resolve both spin manifolds. Use tdhf.type=mrsf, or
type=umrsf where its analytic gradient is available (HF, LDA/GGA and global
hybrids; imult and jmult from {1, 3}); conventional RPA/TDA (one spin manifold per run)
and SF-TDDFT are rejected for MECP.
energy_shift¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | float |
| Default | 1.0e-6 |
| Used by | optimization convergence |
Energy-change convergence threshold. BaekA evaluates this as a same-current-
sigma objective change: the previous geometry's mean-energy and penalty
terms are recombined using the current penalty weight before delta_F is
formed.
energy_gap¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | float |
| Default | 1.0e-5 |
| Used by | crossing-point convergence |
Target energy-gap threshold for crossing searches. For BaekA, OpenQP tests the
outer span E_last - E_first, not the largest individual adjacent gap. The
canonical algorithm=baeka default is 1.0e-4 Hartree. Traditional sectioned
inputs retain the longstanding global 1.0e-5 default unless they explicitly
set energy_gap=1.0e-4. See the
BaekA multistate MECI workflow.
meci_search¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | string |
| Default | auto |
| Values | auto, auglag, penalty, ubp, hybrid, baeka |
| Used by | MECI search algorithm |
Selects the MECI search strategy. auglag, penalty, ubp, and hybrid use
the traditional istate/jstate pair. baeka accepts the two-or-more-root
states list and selects the additive BaekA independent-gap
objective. Each maps to algorithm=<name> inside meci(...), so BaekA is
algorithm=baeka and the augmented Lagrangian is algorithm=auglag.
auto resolves to auglag for two states and to baeka for three or more.
With the native optimizer, BaekA is also held back as a rescue on the recovery
budget if auglag does not meet the convergence criteria.
auglag is an augmented Lagrangian on top of the usual branching-plane update,
so it needs no derivative coupling. A least-squares multiplier removes the
mean-gradient component along the gap direction, leaving a gap term and a
projected mean gradient that are orthogonal. Because orthogonal terms cannot
cancel, a vanishing total gradient forces the energy gap to zero rather than
balancing it against the descent. penalty has no such multiplier: its
stationary point sits at a finite gap, so on its own it stalls above
energy_gap. The strength of the gap term is set by
gap_sigma.
mecp_search¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | string |
| Default | auto |
| Values | auto, sqp, auglag, penalty, quad |
| Used by | MECP (spin-crossing) search algorithm |
Selects the MECP search strategy. The two states differ in spin multiplicity, so the derivative coupling vanishes and the branching space is the single gradient-difference direction.
auto selects sqp with the native optimizer and auglag on the backends
that supply their own, since SQP replaces the optimizer rather than providing
an objective to it.
sqp solves the KKT equations of the constrained problem
minimise 0.5 (E_i + E_j) subject to E_j - E_i = 0
for the step and the multiplier together, using a damped BFGS approximation to
the Hessian of the Lagrangian started from the native model Hessian. The
multiplier is therefore a result rather than a formula, and there is no penalty
parameter: gap_sigma is not read. It works in delocalized
internal coordinates, so coordsys applies to the native optimizer
and not to this search, and it requires lib=oqp.
auglag is the same augmented Lagrangian described above; with gap_sigma=1
its converged form is the plain Bearpark gradient projection. It is what auto
selects on the scipy and geomeTRIC backends. penalty is the Levine-Martinez
smooth penalty.
quad is the legacy fixed-weight quadratic penalty
0.5 (E_i + E_j) + gap_weight (E_j - E_i)^2. Its stationary condition balances
the mean gradient against the gap term, and because the two are not orthogonal
they cancel at a residual gap of order 1/gap_weight. It therefore cannot
satisfy a tight energy_gap and is retained only to reproduce
runs made before the converging objectives were added.
gap_sigma¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | float |
| Default | 10.0 |
| Used by | auglag crossing searches |
Scales the gap term of the auglag objective relative to the projected mean
gradient. 1.0 reproduces the plain Bearpark gradient projection; the larger
default reaches the seam faster and keeps the quasi-Newton history better
conditioned. Must be positive: zero removes the gap term entirely, and a
negative value drives the search away from the seam.
pen_sigma, pen_alpha¶
| Field | Value |
|---|---|
| Type | float |
| Global schema defaults | 1.0, 0.0 |
| BaekA method defaults | 1.0, 0.02 Hartree |
| Used by | penalty-function crossing searches |
For meci_search=baeka, pen_sigma is the initial current dimensionless
penalty weight and pen_alpha is a positive energy-valued smoothing parameter.
Canonical algorithm=baeka injects alpha=0.02 Hartree and rejects explicit
alpha=0. A traditional BaekA input inherits the global pen_alpha=0.0
sentinel when the key is omitted; BaekA interprets that sentinel as the fixed
0.02 Hartree method default. It does not derive alpha from a gradient RMS,
whose units are incompatible.
pen_incre¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | float |
| Default | 1.0 |
| Used by | legacy penalty-function multiplier update |
Historical multiplicative update control used by the established tci
workflow and older penalty implementation:
sigma_next = sigma_current * pen_incre
BaekA does not use this key. Its additive controls are pen_delta and
pen_jump.
pen_delta, pen_jump¶
| Field | Value |
|---|---|
| Types | float; float array |
| Defaults | 0.025; 10,10,25,25,100,100,1000,1000,3000 |
| Used by | BaekA adaptive sigma updates |
pen_delta is the small dimensionless additive increment after an ordinary
nonstationary BaekA macro-step:
sigma_next = sigma_current + pen_delta
pen_jump is an ordered schedule of larger additive increments. OpenQP
consumes one entry only when the same-sigma projected stationary tests pass but
the outer energy span remains above energy_gap. Schedule entries are neither
multipliers nor thresholds. In concise .oqp, use the public names
delta_beta and beta_schedule. See the
BaekA workflow.
gap_weight¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | float |
| Default | 1.0 |
| Used by | crossing-search objective |
Weight applied to a crossing-search penalty objective. The public BaekA route
uses sigma, alpha, delta_beta, beta_schedule, and gap; for BaekA this
lower-level key is fixed at 1.0, and sigma is the published penalty
multiplier. Other legacy crossing algorithms retain their established use of
gap_weight.
rmsd_grad, max_grad¶
| Field | Value |
|---|---|
| Type | float |
| Defaults | 1.0e-4, 3.0e-4 |
| Used by | gradient convergence |
RMS and maximum gradient convergence thresholds for the established
optimizers. BaekA reuses the legacy-named rmsd_grad value as the threshold
for the Euclidean norms ||g_parallel||_2 / sigma and
||g_perpendicular||_2; those BaekA quantities are not RMS values. max_grad
remains a logged generic diagnostic and is not a BaekA termination test.
Concise BaekA input rejects an explicitly supplied max_grad to avoid
implying otherwise.
rmsd_step, max_step¶
| Field | Value |
|---|---|
| Type | float |
| Defaults | 1.0e-3, 2.0e-3 |
| Used by | step convergence |
RMS and maximum geometry-step convergence thresholds. They remain available
as generic optimization diagnostics but are not BaekA termination tests;
concise BaekA input rejects explicit rmsd_step and max_step controls.
step_size, step_tol¶
| Field | Value |
|---|---|
| Type | float |
| Defaults | 0.1, 1.0e-2 |
| Used by | SciPy/lightweight optimization paths |
Step-size controls used by legacy optimization paths.
These are SciPy-backend Python API compatibility keys. They are not accepted in concise .oqp geometry drivers.
mep_maxit¶
| Field | Value |
|---|---|
| Type | integer |
| Default | 10 |
| Used by | MEP workflow |
Maximum number of MEP iterations.
This is a legacy SciPy MEP key and is not accepted in concise .oqp. Use
mep(points=N,step=...); points lowers to the native maxit limit and
step lowers to oqp.mep_step.
init_scf¶
Use the physical route or primary calculation for this control; see the canonical spelling and ownership. Do not write this raw storage key as a separate input section.
| Field | Value |
|---|---|
| Type | boolean |
| Default | False |
| Used by | geometry-step SCF handling |
Requests initial SCF cycles during geometry steps.
Scientific references¶
Geometry optimization and reaction paths; BaekA Multistate MECI.