nimOptim
Add, 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"
.