Interface to OpenTrustRegion by J. Greiner

Code author: Jonas Greiner

Section author: Lori A. Burns

https://img.shields.io/badge/home-OpenTrustRegion-5077AB.svg

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

  • https://img.shields.io/github/tag/eriksen-lab/OpenTrustRegion.svg?maxAge=2592000
  • 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?

SOSCF_START_CONVERGENCE

When to start second-order SCF iterations based on gradient RMS. Both this and SOSCF_START must be satisfied.

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.

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

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?.

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_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.

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.h

  • OpenTrustRegion_DIR — CMake variable to specify where pre-built OpenTrustRegion can be found. Set to installation directory containing lib/cmake/OpenTrustRegion/OpenTrustRegionConfig.cmake

  • CMAKE_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

  1. Build bundled

>>> cmake -DENABLE_OpenTrustRegion=ON
  1. Build without OpenTrustRegion

>>> cmake
  1. 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
  1. 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