Add thread-safe Steihaug, BOBYQA and NEWUOA trust-region optimizers

DESCRIPTION

@@ -1,29 +1,50 @@
 Package: RcppTrust
 Type: Package
-Title: Thread-Safe C++ Port of the 'trust' Trust Region Optimizer
-Version: 0.1.0
+Title: Thread-Safe C++ Trust Region Optimizers
+Version: 0.2.0
 Authors@R: c(
-    person(given = c("Charles", "J."), family = "Geyer", role = "aut",
+    person(given = c("Charles", "J."), family = "Geyer", role = c("aut", "cph"),
         email = "geyer@umn.edu", comment = c(ORCID = "0000-0003-1471-1703")),
     person(given = "Matthew", family = "Fidler", role = c("aut", "cre"),
-        email = "matthew.fidler@gmail.com", comment = c(ORCID = "0000-0001-8538-6691")))
-Description: Does local optimization using two derivatives and trust
-    regions. Guaranteed to converge to a local minimum of the objective
-    function. This is a thread-safe C++ port of the algorithm in the
-    'trust' package by Charles J. Geyer, exposed both as a drop-in R
-    function and as a C-callable, thread-safe entry point (with function
+        email = "matthew.fidler@gmail.com", comment = c(ORCID = "0000-0001-8538-6691")),
+    person(given = c("Michael", "J.", "D."), family = "Powell", role = "aut",
+        comment = "BOBYQA and NEWUOA algorithms and original Fortran 77 code"),
+    person(given = "Douglas", family = "Bates", role = c("ctb", "cph"),
+        comment = "minqa"),
+    person(given = c("Katharine", "M."), family = "Mullen", role = c("ctb", "cph"),
+        comment = "minqa"),
+    person(given = c("John", "C."), family = "Nash", role = c("ctb", "cph"),
+        comment = "minqa"),
+    person(given = "Ravi", family = "Varadhan", role = c("ctb", "cph"),
+        comment = "minqa"),
+    person(given = "Johan", family = "Larsson", role = c("ctb", "cph"),
+        comment = "basin trust-region / Steihaug implementation"))
+Description: Thread-safe C++ trust region optimizers, each exposed
+    both as an R function and as a C-callable entry point (with function
     pointers registered for other packages to call without linking
-    against this package's shared library) so it can be used from
-    parallel C++ code such as in 'nlmixr2est'.
-License: MIT + file LICENSE
+    against this package's shared library) so they can be used from
+    parallel C++ code such as in 'nlmixr2est'. Includes a port of the
+    two-derivative trust region algorithm in the 'trust' package by
+    Charles J. Geyer; a port of the Steihaug truncated conjugate-gradient
+    trust region method from the 'basin' Rust crate (Steihaug (1983)
+    <doi:10.1137/0720042>); and ports of M. J. D. Powell's
+    derivative-free BOBYQA (Powell (2009), Report DAMTP 2009/NA06) and
+    NEWUOA (Powell (2006) <doi:10.1007/0-387-30065-1_16>) Fortran 77
+    code <https://github.com/libprima/prima/tree/main/fortran/original>,
+    as modified and distributed in the 'minqa' package, whose R
+    interface is reproduced.
+License: GPL-2
+Copyright: See inst/COPYRIGHTS for the sources, copyright holders and
+    licenses of code ported from 'trust', 'basin', 'minqa' and Powell's
+    Fortran.
 URL: https://github.com/nlmixr2/RcppTrust/,
     https://nlmixr2.github.io/RcppTrust/,
     http://www.stat.umn.edu/geyer/trust/
 Encoding: UTF-8
 Depends: R (>= 4.2.0)
 Imports: Rcpp
 LinkingTo: Rcpp, RcppArmadillo, BH
-Suggests: testthat (>= 3.0.0), stats, knitr, rmarkdown, trust,
+Suggests: testthat (>= 3.0.0), stats, knitr, rmarkdown, trust, minqa,
     microbenchmark
 Config/testthat/edition: 3
 SystemRequirements: C++17

NAMESPACE

@@ -1,4 +1,10 @@
-useDynLib(RcppTrust, .registration = TRUE)
-importFrom(Rcpp, sourceCpp)
-export(trust)
+# Generated by roxygen2: do not edit by hand
+
+S3method(print,minqa)
 export(.RcppTrustPtr)
+export(bobyqa)
+export(newuoa)
+export(steihaug)
+export(trust)
+importFrom(Rcpp,sourceCpp)
+useDynLib(RcppTrust, .registration = TRUE)

NEWS.md

@@ -0,0 +1,29 @@
+# RcppTrust 0.2.0
+
+* The package license is now GPL-2, because the BOBYQA/NEWUOA ports and
+  their R wrappers derive from the GPL-2 package 'minqa'.
+
+* M. J. D. Powell is added as an author for the BOBYQA/NEWUOA algorithms
+  and original Fortran code; sources and notices for all ported code
+  ('trust', 'basin', 'minqa', Powell's Fortran) are listed in `inst/COPYRIGHTS`.
+
+* New `steihaug()`: a Steihaug truncated conjugate-gradient trust-region
+  Newton minimizer ported from the Rust crate 'basin', with exact-Hessian
+  and matrix-free (Hessian-vector product) modes, and a thread-safe C
+  entry point `steihaug_solve_c()`.
+
+* New `bobyqa()` and `newuoa()`: thread-safe C++ ports of Powell's
+  derivative-free BOBYQA and NEWUOA from 'minqa' 1.2.8, drop-in
+  replacements for `minqa::bobyqa()`/`minqa::newuoa()`, with C entry points
+  `bobyqa_solve_c()`/`newuoa_solve_c()`. BOBYQA's `RESCUE` step evaluates
+  the intended point rather than minqa's uninitialized one.
+
+* `.RcppTrustPtr()` and `RcppTrust.h` gain appended slots for the new C
+  entry points and their result-free functions.
+
+* New vignette `vignette("trust-region-methods")`.
+
+
+# RcppTrust 0.1.0
+
+* Original release of RcppTRust only containing the port of trust::trust()

R/RcppExports.R

@@ -1,6 +1,26 @@
 # Generated by using Rcpp::compileAttributes() -> do not edit by hand
 # Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
 
+minqa_bobyqa_r <- function(par, lower, upper, ctrl, fn) {
+    .Call(`_RcppTrust_minqa_bobyqa_r`, par, lower, upper, ctrl, fn)
+}
+
+minqa_newuoa_r <- function(par, ctrl, fn) {
+    .Call(`_RcppTrust_minqa_newuoa_r`, par, ctrl, fn)
+}
+
+solver_openmp_stress_test <- function(solver, n, nStarts, nThreadsRequested) {
+    .Call(`_RcppTrust_solver_openmp_stress_test`, solver, n, nStarts, nThreadsRequested)
+}
+
+solver_c_api_edge_test <- function() {
+    .Call(`_RcppTrust_solver_c_api_edge_test`)
+}
+
+steihaug_solve_r <- function(par, fn, gr, hess, hessvec, control) {
+    .Call(`_RcppTrust_steihaug_solve_r`, par, fn, gr, hess, hessvec, control)
+}
+
 trust_solve_r <- function(objfun1, tryEval, parinit, rinit, rmax, parscale, iterlim, fterm, mterm, minimize, blather) {
     .Call(`_RcppTrust_trust_solve_r`, objfun1, tryEval, parinit, rinit, rmax, parscale, iterlim, fterm, mterm, minimize, blather)
 }

R/c-api.R

@@ -0,0 +1,28 @@
+#' Thread-safe C interfaces
+#'
+#' Every optimizer in this package is implemented as a C-callable core with
+#' no R API calls and no global state, so each can run concurrently from
+#' OpenMP/parallel C++ code (e.g. as an inner or outer optimizer in
+#' \code{nlmixr2est}). The R functions [trust()], [steihaug()], [bobyqa()]
+#' and [newuoa()] are thin wrappers around these same cores.
+#'
+#' \tabular{lll}{
+#'   \strong{Solver} \tab \strong{Header} \tab \strong{Entry point / free} \cr
+#'   trust \tab \code{trust_types.h} \tab \code{trust_solve_c} / \code{trust_result_free} \cr
+#'   BOBYQA \tab \code{minqa_types.h} \tab \code{bobyqa_solve_c} / \code{minqa_result_free} \cr
+#'   NEWUOA \tab \code{minqa_types.h} \tab \code{newuoa_solve_c} / \code{minqa_result_free} \cr
+#'   Steihaug \tab \code{steihaug_types.h} \tab \code{steihaug_solve_c} / \code{steihaug_result_free} \cr
+#' }
+#'
+#' A consuming package adds \code{RcppTrust} to \code{LinkingTo} and
+#' \code{Imports}, includes \code{RcppTrust.h}, and resolves the pointers at
+#' load time from [.RcppTrustPtr()] (slots, in order: \code{trust_solve_c},
+#' \code{trust_result_free}, \code{bobyqa_solve_c}, \code{newuoa_solve_c},
+#' \code{minqa_result_free}, \code{steihaug_solve_c},
+#' \code{steihaug_result_free}). See \code{vignette("RcppTrust")} for a
+#' worked example.
+#'
+#' @name minqa_c_api
+#' @aliases steihaug_c_api trust_c_api
+#' @keywords internal
+NULL