nimOptimMethod {nimble}

Set or get an optimization function to be used by nimOptim

Description

Add, check, or remove an R optimization function to/from NIMBLE's set of registered optimization functions that can be called from nimOptim.

Usage

nimOptimMethod(name, value)

Arguments

name

character string, giving the name of optimization method that can be referred to by the method argument of nimOptim (aka optim in a nimbleFunction).

value

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.

Details

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".