Interface to OpenOrbitalOptimizer by S. Lehtola

Code author: Susi Lehtola

Section author: Lori A. Burns

https://img.shields.io/badge/home-OpenOrbitalOptimizer-5077AB.svg
https://img.shields.io/badge/docs-latest-5077AB.svg

This is a collection of SCF optimization techniques (DIIS, EDIIS, ADIIS, ODA) developed by S. Lehtola and interfaced to PSI4 . Enabling OOO and adding set orbital_optimizer_package openorbitaloptimizer or set orbital_optimizer_package ooo runs the SCF iterations steps from OOO. Set to internal to revoke.

Installation

Binary

  • https://anaconda.org/SusiLehtola/OpenOrbitalOptimizer/badges/version.svg

  • OpenOrbitalOptimizer is available as a conda package for Linux, macOS, and Windows.

  • The conda package is (for the C++ interface) a header-only library.

  • If using the PSI4 binary, OpenOrbitalOptimizer has already been compiled in (except Windows).

  • If using PSI4 built from source, and anaconda or miniconda has already been installed (instructions at Quick Installation), OpenOrbitalOptimizer can be obtained through conda install openorbitaloptimizer -c conda-forge. Then enable it as a feature with ENABLE_OpenOrbitalOptimizer, hint its location with CMAKE_PREFIX_PATH, and rebuild PSI4 to detect OpenOrbitalOptimizer and activate dependent code.

  • To remove a conda installation, conda remove openorbitaloptimizer.

Source

  • https://img.shields.io/github/tag/SusiLehtola/OpenOrbitalOptimizer.svg?maxAge=2592000

  • If using PSI4 built from source and you want OpenOrbitalOptimizer built from from source also, enable it as a feature with ENABLE_OpenOrbitalOptimizer, and let the build system fetch and build it and activate dependent code.

OpenOrbitalOptimizer Options

OpenOrbitalOptimizer is ready to use for RHF and UHF SCF iterations. (Other references will fall back on the internal optimizer.) Note that you may need to back off on convergence criteria. OpenOrbitalOptimizer for the SAD guess is available for experimentation only.

ORBITAL_OPTIMIZER_PACKAGE

Orbital optimizer package to use for SCF.

  • Type: string

  • Possible Values: INTERNAL

  • Default: INTERNAL

MAXITER

Maximum number of iterations. Cfour Interface: Keyword translates into CFOUR_SCF_MAXCYC

  • Type: integer

  • Default: 100

OOO_PRINT

For ORBITAL_OPTIMIZER_PACKAGE = OOO, verbosity of printing to screen. 0 prints nothing. 1 prints one line per iter (note that RHF rms(density) printed differs by half from convergence criterion. 5 is common and adds occupancy printing. 12 is max.

  • Type: integer

  • Default: 0

DIIS_MAX_VECS

Maximum number of error vectors stored for DIIS extrapolation. For ORBITAL_OPTIMIZER_PACKAGE = OOO, sets maximum_history_length.

  • Type: integer

  • Default: 10

SCF_INITIAL_START_DIIS_TRANSITION

SCF error at which to start the linear interpolation between DIIS steps and steps of the initial SCF accelerator. Value taken from Garza and Scuseria, DOI: 10.1063/1.4740249 For ORBITAL_OPTIMIZER_PACKAGE = OOO, sets diis_epsilon.

  • Type: double

  • Default: 1.0e-1

SCF_INITIAL_FINISH_DIIS_TRANSITION

SCF error at which to complete the linear interpolation between DIIS steps and steps of the initial SCF accelerator Value taken from Garza and Scuseria, DOI: 10.1063/1.4740249 For ORBITAL_OPTIMIZER_PACKAGE = OOO, sets diis_threshold.

  • Type: double

  • Default: 1.0e-4

OOO_DIIS_RESTART_FACTOR

For ORBITAL_OPTIMIZER_PACKAGE = OOO, the DIIS restart criterion (Chupin et al, 2021)

  • Type: double

  • Default: 1.0e-4

OOO_OPTIMAL_DAMPING_THRESHOLD

For ORBITAL_OPTIMIZER_PACKAGE = OOO, use optimal damping when max error bigger than this.

  • Type: double

  • Default: 1.0

SAD_ORBITAL_OPTIMIZER_PACKAGE

Orbital optimizer package to use for SAD guess.

  • Type: string

  • Possible Values: INTERNAL

  • Default: INTERNAL

How to configure OpenOrbitalOptimizer for building Psi4

Role and Dependencies

  • Role — In PSI4, OpenOrbitalOptimizer is a library that provides alternate orbital optimization.

  • Downstream Dependencies — PSI4 (\(\Leftarrow\) optional) OpenOrbitalOptimizer

  • Upstream Dependencies — OpenOrbitalOptimizer \(\Leftarrow\) Armadillo

CMake Variables

  • ENABLE_OpenOrbitalOptimizer — CMake variable toggling whether PSI4 builds with OpenOrbitalOptimizer

  • CMAKE_PREFIX_PATH — CMake list variable to specify where pre-built dependencies can be found. For OOO, set to an installation directory containing include/openorbitaloptimizer/scfsolver.hpp

  • OpenOrbitalOptimizer_DIR — CMake variable to specify where pre-built OpenOrbitalOptimizer can be found. Set to installation directory containing share/cmake/OpenOrbitalOptimizer/OpenOrbitalOptimizer/OpenOrbitalOptimizerConfig.cmake

  • CMAKE_DISABLE_FIND_PACKAGE_OpenOrbitalOptimizer — CMake variable to force internal build of OpenOrbitalOptimizer instead of detecting pre-built

  • CMAKE_INSIST_FIND_PACKAGE_OpenOrbitalOptimizer — CMake variable to force detecting pre-built OpenOrbitalOptimizerand not falling back on internal build

Examples

  1. Build bundled

>>> cmake -DENABLE_OpenOrbitalOptimizer=ON

  1. Build without OpenOrbitalOptimizer

>>> cmake

  1. Link against pre-built

>>> cmake -DENABLE_OpenOrbitalOptimizer=ON -DCMAKE_PREFIX_PATH=/path/to/OpenOrbitalOptimizer/root

>>> cmake -DENABLE_OpenOrbitalOptimizer=ON -DOpenOrbitalOptimizer_DIR=/path/to/ooo/configdir

  1. Build bundled despite pre-built being detectable

>>> cmake -DENABLE_OpenOrbitalOptimizer=ON -DCMAKE_PREFIX_PATH=/path/to/unwanted/OpenOrbitalOptimizer/root/and/wanted/other/dependencies/root -DCMAKE_DISABLE_FIND_PACKAGE_OpenOrbitalOptimizer=ON