Interface to OpenTrustRegion by J. Greiner¶
Code author: Jonas Greiner
Section author: Lori A. Burns
OpenTrustRegion is a collection of second-order orbital optimization algorithms developed by J. Greiner in the Eriksen lab and interfaced to PSI4. Rather than iterating the Fock matrix to self-consistency, it minimizes the SCF energy directly with respect to the orbital rotation parameters, using a trust-region method with the orbital Hessian applied on the fly.
Enabling OTR by adding set second_order_orbital_optimizer_package
opentrustregion or set second_order_orbital_optimizer_package otr, together
with SOSCF, runs the second-order SCF iterations through OTR. Set to
internal to revoke.
Installation¶
Binary
A conda package for OpenTrustRegion is available. Obtain it through
conda install opentrustregion -c conda-forge, then enable it as a feature with ENABLE_OpenTrustRegion, hint its location with CMAKE_PREFIX_PATH, and rebuild PSI4 to detect OpenTrustRegion and activate dependent code. When v1.12 is released, OpenTrustRegion will be built into the PSI4 conda package.
Source
If using PSI4 built from source and you want OpenTrustRegion built from source also, enable it as a feature with ENABLE_OpenTrustRegion=ON, and let the build system fetch and build it and activate dependent code. Note that OpenTrustRegion is written in Fortran, so a Fortran compiler is required for the source build.
OpenTrustRegion Options¶
OpenTrustRegion is ready to use for RHF, UHF, ROHF and the corresponding KS references. It is an external second-order optimizer, so it engages only once SOSCF turns second-order iterations on, taking over from the first-order package once both SOSCF_START_CONVERGENCE and SOSCF_START are met. See Second-order Convergence for how it contrasts with the internal second-order code, which computations fall back on that code, and how the first- and second-order packages combine.
Settings with a genuine PSI4 counterpart reuse that keyword; the rest are
exposed as OTR_* keywords, each defaulting to OpenTrustRegion’s own default.
Each OpenTrustRegion macro-iteration prints as an ordinary SCF iteration row,
labelled OTR, nmicro=N as the internal second-order code labels its own.
OpenTrustRegion’s table follows those rows, carrying the trust radius, level
shift and step size; its gradient RMS is taken over the orbital rotation
parameters and so does not match the \(\mathrm{RMS}\ |[F,P]|\) of the rows
above. OTR_PRINT 0 suppresses that table.
SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE¶
Package driving the second-order SCF iterations once SOSCF turns them on.
Type: string
Possible Values: INTERNAL
Default: INTERNAL
ORBITAL_OPTIMIZER_PACKAGE¶
Package driving the first-order SCF iterations.
Type: string
Possible Values: INTERNAL
Default: INTERNAL
SOSCF¶
Do use second-order SCF convergence methods?
Type: boolean
Default: false
SOSCF_START_CONVERGENCE¶
When to start second-order SCF iterations based on gradient RMS. Both this and SOSCF_START must be satisfied.
Type: conv double
Default: 1.0e-2
SOSCF_START¶
The earliest iteration on which second-order SCF may start. Both this and SOSCF_START_CONVERGENCE must be satisfied. Starting earlier than the default gives the first-order iterations less room to settle the occupation, which a second-order step may (true for OTR) hold fixed.
Type: integer
Default: 3
E_CONVERGENCE¶
Convergence criterion for SCF energy. See Table SCF Convergence & Algorithm for default convergence criteria for different calculation types.
Type: conv double
Default: 1e-6
D_CONVERGENCE¶
Convergence criterion for SCF density, defined as the RMS or maximum absolute value of the orbital gradient. See Table SCF Convergence & Algorithm for default convergence criteria for different calculation types. Cfour Interface: Keyword translates into CFOUR_SCF_CONV
Type: conv double
Default: 1e-6
MAXITER¶
Maximum number of iterations. Cfour Interface: Keyword translates into CFOUR_SCF_MAXCYC
Type: integer
Default: 100
SOSCF_PRINT¶
Do we print the SOSCF microiterations?.
Type: boolean
Default: false
OTR_SUBSYSTEM_SOLVER¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, solver used for the trust-region subproblem. The Davidson family comes in a linear-system (_LS) and an augmented-Hessian (_AH) formulation; _LS is OpenTrustRegion’s own default. TCG is often faster, markedly so with diffuse basis sets, but is less robust: it can stall before reaching the convergence threshold.
Type: string
Default: DAVIDSON_LS
OTR_N_RANDOM_TRIAL_VECTORS¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, number of random trial vectors seeding each microiteration space. Raising it is OpenTrustRegion’s suggested remedy when it reports a trial subspace that is too small, at the cost of one Hessian application per vector.
Type: integer
Default: 0
OTR_JACOBI_DAVIDSON_START¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, microiteration at which to switch from Davidson to Jacobi-Davidson.
Type: integer
Default: 30
OTR_LINE_SEARCH¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, do a line search along the trust-region step.
Type: boolean
Default: false
OTR_GRAD_NOISE¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, whether to perturb the orbital gradient. The perturbation helps the solver leave a stationary point, which is wanted when seeking a minimum and not when a calculation means to sit at a saddle point, and it moves the converged orbitals within D_CONVERGENCE enough to show in a sensitive response property.
Type: boolean
Default: true
OTR_START_TRUST_RADIUS¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, initial trust radius.
Type: double
Default: 0.4
OTR_GLOBAL_RED_FACTOR¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, relative residual reduction demanded of the microiterations far from convergence.
Type: double
Default: 1.0e-3
OTR_LOCAL_RED_FACTOR¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, relative residual reduction demanded of the microiterations near convergence.
Type: double
Default: 1.0e-4
OTR_SEED¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, seed for the random trial vectors. Fixed so runs are reproducible.
Type: integer
Default: 42
OTR_MAX_PRECISION_REACHED_HANDLING¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, what to do when OpenTrustRegion stops at its floating-point precision floor short of E_CONVERGENCE and D_CONVERGENCE Its trust-region step is accepted on the measured against the predicted energy change, so once neither can be resolved it cannot verify further progress and stops, reporting success. DIIS finishes the job with first-order iterations, which converge on the orbital gradient instead and are not subject to that limit, and fails if they cannot reach the thresholds within MAXITER either. FAIL treats the shortfall as non-convergence at once. WARN accepts the orbitals, reporting the shortfall in the output.
Type: string
Possible Values: DIIS, FAIL, WARN
Default: DIIS
OTR_PRINT¶
For SECOND_ORDER_ORBITAL_OPTIMIZER_PACKAGE = OTR, verbosity of the solver’s own printing: 0 only warnings and errors, 1 its macro-iteration table, 2 or more adds debug messages (only for OTR_SUBSYSTEM_SOLVER = TCG). The table follows the SCF iteration rows, which report the same macro iterations in Psi4’s format. Unset, this follows SOSCF_PRINT ; setting it overrides that.
Type: integer
Default: 1
How to configure OpenTrustRegion for building Psi4¶
Role and Dependencies
Role — In PSI4, OpenTrustRegion is a library that provides alternate orbital optimization.
Downstream Dependencies — PSI4 (\(\Leftarrow\) optional) OpenTrustRegion
Upstream Dependencies — OpenTrustRegion \(\Leftarrow\) LAPACK, Fortran
CMake Variables
ENABLE_OpenTrustRegion — CMake variable toggling whether PSI4 builds with OpenTrustRegion
CMAKE_PREFIX_PATH — CMake list variable to specify where pre-built dependencies can be found. For OTR, set to an installation directory containing
include/opentrustregion.hOpenTrustRegion_DIR — CMake variable to specify where pre-built OpenTrustRegion can be found. Set to installation directory containing
lib/cmake/OpenTrustRegion/OpenTrustRegionConfig.cmakeCMAKE_DISABLE_FIND_PACKAGE_OpenTrustRegion — CMake variable to force internal build of OpenTrustRegion instead of detecting pre-built
CMAKE_INSIST_FIND_PACKAGE_OpenTrustRegion — CMake variable to force detecting pre-built OpenTrustRegion and not falling back on internal build
Examples
Build bundled
>>> cmake -DENABLE_OpenTrustRegion=ON
Build without OpenTrustRegion
>>> cmake
Link against pre-built
>>> cmake -DENABLE_OpenTrustRegion=ON -DCMAKE_PREFIX_PATH=/path/to/OpenTrustRegion/root>>> cmake -DENABLE_OpenTrustRegion=ON -DOpenTrustRegion_DIR=/path/to/otr/cmakeconfigdir
Build bundled despite pre-built being detectable
>>> cmake -DENABLE_OpenTrustRegion=ON -DCMAKE_PREFIX_PATH=/path/to/unwanted/OpenTrustRegion/root/and/wanted/other/dependencies/root -DCMAKE_DISABLE_FIND_PACKAGE_OpenTrustRegion=ON