nimOptimAdd, check, or remove an R optimization function to/from NIMBLE's set of
registered optimization functions that can be called from nimOptim.
nimOptimMethod(name, value)character string, giving the name of optimization method that
can be referred to by the method argument of nimOptim
(aka optim in a nimbleFunction).
An optimization function with specifications described below and
in nimOptim. If value is NULL, then name
will be found in NIMBLE's set of registered optimizer names. If
value is missing, the registered optimizer for name will be
returned.
When programming in nimbleFunctions, optim, which is converted
automatically to nimOptim, provides a generalization of R's
optim methods for optimization. If one of the supported original
optim methods is not chosen with the method argument to
nimOptim, an arbitrary method name can be given. If that name has been
registered as a name by a call to nimOptimMethod, then the
corresponding function (value) will be called for optimization.
The function value must perform minimization. If the call to
nimOptim includes a control list with either fnscale (which, if
negative, turns the problem into a maximization) or parscale, these
will be managed by nimOptim outside of the optimizer such that the
optimization should be minimization.
The function value must take named arguments par (initial
parameter vector), fn (objective function), gr (optional
gradient function), he (optional Hessian function), lower
(vector of lower bounds), upper (vector of upper bounds),
control (arbitrary control list), and hessian (logical
indicating whether a Hessian at the optimum is requested). It must return a
list with elements elements par (parameter values of the optimium,
i.e., "arg min"), value (function value at the minimum),
convergence (should be 0 if convergence occurred), counts
(optional vector of counts of calls to fn, gr, and he),
evaluations (optional total function evaluations), message
(optional character message), and hessian (optional Hessian matrix,
which may be NULL).
If the call to nimOptim has hessian=TRUE, that will be passed
as hessian=TRUE to the optimizer. However, if the optimizer returns a
NULL in the hessian element of the return list, then
nimOptim will calculate the Hessian by finite element differences.
Hence, an optimizer need not provide a Hessian capability.
The control list passed from nimOptim to the optimizer will
have only a limited set of the optim control list options. These will
include abstol, reltol, maxit, and trace. The
optimizer may use these as it wishes. Other control options for a particular
optimizer must be managed in some other way.
Note that it is possible to use browser() inside of value, or
to set debug(value), to enter a browser when the optimizer
(value) is called and then inspect its arguments to make sense of the
situation.
This whole feature is particularly helpful when the nimbleFunction using
nimOptim has been compiled by compileNimble. Many optimizers
are available through R, so nimOptim arranges to call a named
(registered) optimizer in R, while providing fn and optionally
gr or he as functions that will call the compiled (by nimble)
versions of the corresponding functions provided in the call to
nimOptim.
R's optimizer nlminb is automatically registered under the name
"nlminb".