eriksen-lab/opentrustregion v3.0.0

on GitHub

OpenTrustRegion 3.0.0

Installation

• Wheels on PyPI: pip install pyopentrustregion, for Linux (x86_64, aarch64) and macOS (arm64, x86_64), built with 32-bit integers. Check an installation with python -m pyopentrustregion.verify_install.
• Building now requires CMake ≥ 3.24, and the Python package requires Python ≥ 3.10.
• Source builds of the Python package use scikit-build-core. Pass CMake options as -C cmake.define.<OPTION>=<VALUE>; the CMAKE_FLAGS environment variable is no longer read.
• The CMake package exports the library together with its Fortran modules. The shared library is versioned by major and minor version, and C and Fortran programs are rebuilt for every minor version.

Breaking changes

• Every callback function receives a host context as its last argument (void * in C, class(*), pointer in Fortran), set through settings%context. Python callbacks are unchanged.
• solver and stability_check take an optional state after the settings, which reports the progress and the final values of the optimization.
  • The settings are inputs only, are no longer modified and are optional in every language. In C, NULL selects the defaults and, for the state, no state.
  • The Fortran stability_check no longer takes n_param.
  • The C entry points take const settings and state pointers instead of settings by value.
• The Python solver takes update_orbs before obj_func, as documented and as in Fortran and C. Version 2.0.1 expected them the other way round.
• Python settings objects reject attributes that are not settings, so a misspelled setting raises an AttributeError.
• Fortran settings are default-initialized; settings%init() is removed.
• The Fortran module opentrustregion exports only the public interface.
• A custom conv_check now replaces the criterion on the RMS gradient.
• The subsystem solvers "davidson" and "jacobi-davidson" are renamed to "davidson_ls" and "jacobi-davidson_ls".
• The solver no longer limits steps to orbital rotations of π/4. A host that needs the limit returns an infinite objective function value for such steps.
• Callback outputs that are not finite are reported as errors; a NaN objective function value only rejects the step. Reaching the iteration limit has an error code of its own.
• New defaults:
  • solver: subsystem solver "davidson_ls", gradient perturbation (grad_noise) on, one extra trial vector and no random ones for the subsystem solvers;
  • stability check: conv_tol = 1e-9 and an automatic number of random trial vectors.
• Together with the trust radius, which now only expands when a step reaches its boundary, the new defaults change iteration counts from 2.0.1.

New features

• Escape from saddle points. With stability, the solver leaves an unstable converged point by a descent-checked step along the unstable mode instead of returning it. A converged starting point and an exactly vanishing gradient are always checked.
• Stability check.
  • New settings: the threshold stability_thresh and stop_on_instability.
  • Block Davidson with extra trial vectors (get_extra_trial_vectors) and a convergence check of its own.
  • The nested stability_settings configure the solver's internal check.
• Subsystem solvers. The augmented-Hessian variants "davidson_ah" and "jacobi-davidson_ah", and non-symmetric (approximate) Hessians with hess_symm = .false. (for "davidson_ls").
• Projection. A project callback for redundant parameterizations.
• Maximum precision. Points where no further progress can be resolved are detected from the resolution of the objective function and reported as max_precision_reached in the state, without an error.
• Builds. Nested and concurrent solves, LLVM Flang support, OpenTrustRegion_HOST_PROVIDES_BLAS for hosts that link BLAS/LAPACK themselves, and optional -march=native (OpenTrustRegion_ENABLE_XHOST, off by default).
• Python. An exception raised in a callback is attached as the cause of the resulting RuntimeError, and Ctrl+C interrupts a solve.

Fixes

• The Davidson hard case and the bisection of the level shift.
• Random trial vectors that already lie in the trial space.
• Early exits with unallocated arrays.
• Stricter validation of settings.
• A C header that compiles as C++.
• Booleans handed to C by the Intel compiler.