oqp.library.oqp_engine

Step-determination engine for the oqp OpenQP optimizer.

Backend-agnostic (NumPy only).  The :class:`OQPEngine` owns the optimization
loop and drives an energy/gradient callback supplied by the caller, so it can be
exercised on analytic test potentials without the compiled OQP core.

Algorithm (v1):

* working coordinates from :mod:`oqp.library.oqp_coords` (redundant internals
  with Cartesian fall-back);
* restricted-step Rational Function Optimization (RFO) for minima and
  partitioned-RFO (P-RFO, eigenvector following) for transition states;
* Schlegel-type diagonal model Hessian, or an optional supplied Cartesian
  Hessian transformed into working coordinates, updated with BFGS (minima) or
  the Bofill SR1/PSB mixture (TS);
* a predictive trust region in Cartesian RMSD, grown/shrunk on the ratio of
  actual to predicted energy change.

References: Banerjee, Adams, Simons, Shepard, J. Phys. Chem. 89, 52 (1985);
Bofill, J. Comput. Chem. 15, 1 (1994); Peng, Ayala, Schlegel, Frisch,
J. Comput. Chem. 17, 49 (1996).

Exceptions

ConvergenceSignal

Classes

OQPEngine

Functions

parse_frozen_distance_spec(value)

Module Contents

exception ConvergenceSignal

Bases: Exception

Raised by the convergence callback to stop the loop cleanly.

parse_frozen_distance_spec(value)

Return one-based atom pairs from ``distance(i,j);...`` syntax.

class OQPEngine(atoms, x0, mode='min', trust=0.2, trust_min=0.005, trust_max=0.5, maxiter=100, follow_mode=0, coordsys='auto', logger=None, initial_hessian=None, initial_gradient=None, masses=None, project_global_rigid_modes=False, frozen_distances=None)

atoms

x

sqrt_cartesian_mass

project_global_rigid_modes = False

frozen_distances = []

mode = 'min'

trust

trust_min

trust_max

maxiter = 100

follow_mode = 0

logger = None

coords

coordsys

nonfinite_step_rejections = 0

run(energy_gradient, on_converged=None)

Optimize until ``on_converged`` raises or ``maxiter`` is reached.

``energy_gradient(x_flat) -> (E, g_flat)`` returns energy (Hartree) and
Cartesian gradient (Hartree/Bohr).  ``on_converged()`` is called after
every evaluation and may raise to stop (mirrors OQP's ``StopIteration``
convergence protocol).

rebase_previous_objective(energy, gradient)

Re-evaluate the stored previous point for a changed objective.

Adaptive objectives may change a scalar parameter between two geometry
evaluations.  Their caller can recombine the previous geometry's
parameter-independent energy and Cartesian gradient at the new
parameter, then use this helper to keep the BFGS secant and trust-ratio
comparison on one objective.  The previous geometry is retained with
the accepted step so the rebased gradient is transformed in the same
coordinate frame in which it was evaluated.

Returns ``False`` before the first step, when no previous point exists.