Package 'nloptr' reference manual

Title:	R Interface to NLopt
Description:	Solve optimization problems using an R interface to NLopt. NLopt is a free/open-source library for nonlinear optimization, providing a common interface for a number of different free optimization routines available online as well as original implementations of various other algorithms. See <https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/> for more information on the available algorithms. Building from included sources requires 'CMake'. On Linux and 'macOS', if a suitable system build of NLopt (2.7.0 or later) is found, it is used; otherwise, it is built from included sources via 'CMake'. On Windows, NLopt is obtained through 'rwinlib' for 'R <= 4.1.x' or grabbed from the 'Rtools42 toolchain' for 'R >= 4.2.0'.
Authors:	Jelmer Ypma [aut], Steven G. Johnson [aut] (author of the NLopt C library), Hans W. Borchers [ctb], Dirk Eddelbuettel [ctb], Brian Ripley [ctb] (build process on multiple OS), Kurt Hornik [ctb] (build process on multiple OS), Julien Chiquet [ctb], Avraham Adler [ctb] (removal deprecated calls from tests, <https://orcid.org/0000-0002-3039-0703>), Xiongtao Dai [ctb], Aymeric Stamm [ctb, cre] , Jeroen Ooms [ctb]
Maintainer:	Aymeric Stamm <[email protected]>
License:	LGPL (>= 3)
Version:	2.0.3
Built:	2024-05-03 08:27:25 UTC
Source:	CRAN

Augmented Lagrangian Algorithm

Description

The Augmented Lagrangian method adds additional terms to the unconstrained objective function, designed to emulate a Lagrangian multiplier.

Usage

auglag(
  x0,
  fn,
  gr = NULL,
  lower = NULL,
  upper = NULL,
  hin = NULL,
  hinjac = NULL,
  heq = NULL,
  heqjac = NULL,
  localsolver = c("COBYLA"),
  localtol = 1e-06,
  ineq2local = FALSE,
  nl.info = FALSE,
  control = list(),
  ...
)

Arguments

`x0`	starting point for searching the optimum.
`fn`	objective function that is to be minimized.
`gr`	gradient of the objective function; will be provided provided is `NULL` and the solver requires derivatives.
`lower`, `upper`	lower and upper bound constraints.
`hin`, `hinjac`	defines the inequality constraints, `hin(x) >= 0`
`heq`, `heqjac`	defines the equality constraints, `heq(x) = 0`.
`localsolver`	available local solvers: COBYLA, LBFGS, MMA, or SLSQP.
`localtol`	tolerance applied in the selected local solver.
`ineq2local`	logical; shall the inequality constraints be treated by the local solver?; not possible at the moment.
`nl.info`	logical; shall the original NLopt info been shown.
`control`	list of options, see `nl.opts` for help.
`...`	additional arguments passed to the function.

Details

This method combines the objective function and the nonlinear inequality/equality constraints (if any) in to a single function: essentially, the objective plus a ‘penalty’ for any violated constraints.

This modified objective function is then passed to another optimization algorithm with no nonlinear constraints. If the constraints are violated by the solution of this sub-problem, then the size of the penalties is increased and the process is repeated; eventually, the process must converge to the desired solution (if it exists).

Since all of the actual optimization is performed in this subsidiary optimizer, the subsidiary algorithm that you specify determines whether the optimization is gradient-based or derivative-free.

The local solvers available at the moment are ⁠COBYLA'' (for the derivative-free approach) and ⁠LBFGS”, ⁠MMA'', or ⁠SLSQP” (for smooth functions). The tolerance for the local solver has to be provided.

There is a variant that only uses penalty functions for equality constraints while inequality constraints are passed through to the subsidiary algorithm to be handled directly; in this case, the subsidiary algorithm must handle inequality constraints. (At the moment, this variant has been turned off because of problems with the NLOPT library.)

Value

List with components:

`par`	the optimal solution found so far.
`value`	the function value corresponding to `par`.
`iter`	number of (outer) iterations, see `maxeval`.
`global_solver`	the global NLOPT solver used.
`local_solver`	the local NLOPT solver used, LBFGS or COBYLA.
`convergence`	integer code indicating successful completion (> 0) or a possible error number (< 0).
`message`	character string produced by NLopt and giving additional information.

Note

Birgin and Martinez provide their own free implementation of the method as part of the TANGO project; other implementations can be found in semi-free packages like LANCELOT.

Author(s)

Hans W. Borchers

References

Andrew R. Conn, Nicholas I. M. Gould, and Philippe L. Toint, “A globally convergent augmented Lagrangian algorithm for optimization with general constraints and simple bounds,” SIAM J. Numer. Anal. vol. 28, no. 2, p. 545-572 (1991).

E. G. Birgin and J. M. Martinez, “Improving ultimate convergence of an augmented Lagrangian method," Optimization Methods and Software vol. 23, no. 2, p. 177-195 (2008).

Examples

x0 <- c(1, 1)
fn <- function(x) (x[1]-2)^2 + (x[2]-1)^2
hin <- function(x) -0.25*x[1]^2 - x[2]^2 + 1    # hin >= 0
heq <- function(x) x[1] - 2*x[2] + 1            # heq == 0
gr <- function(x) nl.grad(x, fn)
hinjac <- function(x) nl.jacobian(x, hin)
heqjac <- function(x) nl.jacobian(x, heq)

auglag(x0, fn, gr = NULL, hin = hin, heq = heq) # with COBYLA
# $par:     0.8228761 0.9114382
# $value:   1.393464
# $iter:    1001

auglag(x0, fn, gr = NULL, hin = hin, heq = heq, localsolver = "SLSQP")
# $par:     0.8228757 0.9114378
# $value:   1.393465
# $iter     173

##  Example from the alabama::auglag help page
fn <- function(x) (x[1] + 3*x[2] + x[3])^2 + 4 * (x[1] - x[2])^2
heq <- function(x) x[1] + x[2] + x[3] - 1
hin <- function(x) c(6*x[2] + 4*x[3] - x[1]^3 - 3, x[1], x[2], x[3])

auglag(runif(3), fn, hin = hin, heq = heq, localsolver="lbfgs")
# $par:     2.380000e-09 1.086082e-14 1.000000e+00
# $value:   1
# $iter:    289

##  Powell problem from the Rsolnp::solnp help page
x0 <- c(-2, 2, 2, -1, -1)
fn1  <- function(x) exp(x[1]*x[2]*x[3]*x[4]*x[5])
eqn1 <-function(x)
	c(x[1]*x[1]+x[2]*x[2]+x[3]*x[3]+x[4]*x[4]+x[5]*x[5],
	  x[2]*x[3]-5*x[4]*x[5],
	  x[1]*x[1]*x[1]+x[2]*x[2]*x[2])

auglag(x0, fn1, heq = eqn1, localsolver = "mma")
# $par: -3.988458e-10 -1.654201e-08 -3.752028e-10  8.904445e-10  8.926336e-10
# $value:   1
# $iter:    1001

R interface to NLopt

Description

nloptr is an R interface to NLopt, a free/open-source library for nonlinear optimization started by Steven G. Johnson, providing a common interface for a number of different free optimization routines available online as well as original implementations of various other algorithms. The NLopt library is available under the GNU Lesser General Public License (LGPL), and the copyrights are owned by a variety of authors. Most of the information here has been taken from the NLopt website, where more details are available.

Usage

nloptr(
  x0,
  eval_f,
  eval_grad_f = NULL,
  lb = NULL,
  ub = NULL,
  eval_g_ineq = NULL,
  eval_jac_g_ineq = NULL,
  eval_g_eq = NULL,
  eval_jac_g_eq = NULL,
  opts = list(),
  ...
)

Arguments

x0

vector with starting values for the optimization.

eval_f

function that returns the value of the objective function. It can also return gradient information at the same time in a list with elements "objective" and "gradient" (see below for an example).

eval_grad_f

function that returns the value of the gradient of the objective function. Not all of the algorithms require a gradient.

lb

vector with lower bounds of the controls (use -Inf for controls without lower bound), by default there are no lower bounds for any of the controls.

ub

vector with upper bounds of the controls (use Inf for controls without upper bound), by default there are no upper bounds for any of the controls.

eval_g_ineq

function to evaluate (non-)linear inequality constraints that should hold in the solution. It can also return gradient information at the same time in a list with elements "constraints" and "jacobian" (see below for an example).

eval_jac_g_ineq

function to evaluate the jacobian of the (non-)linear inequality constraints that should hold in the solution.

eval_g_eq

function to evaluate (non-)linear equality constraints that should hold in the solution. It can also return gradient information at the same time in a list with elements "constraints" and "jacobian" (see below for an example).

eval_jac_g_eq

function to evaluate the jacobian of the (non-)linear equality constraints that should hold in the solution.

opts

list with options. The option "algorithm" is required. Check the NLopt website for a full list of available algorithms. Other options control the termination conditions (minf_max, ftol_rel, ftol_abs, xtol_rel, xtol_abs, maxeval, maxtime). Default is xtol_rel = 1e-4. More information here. A full description of all options is shown by the function nloptr.print.options().

Some algorithms with equality constraints require the option local_opts, which contains a list with an algorithm and a termination condition for the local algorithm. See ?nloptr-package for an example.

The option print_level controls how much output is shown during the optimization process. Possible values:

0 (default)	no output
1	show iteration number and value of objective function
2	1 + show value of (in)equalities
3	2 + show value of controls

The option check_derivatives (default = FALSE) can be used to run to compare the analytic gradients with finite difference approximations. The option check_derivatives_print ('all' (default), 'errors', 'none') controls the output of the derivative checker, if it is run, showing all comparisons, only those that resulted in an error, or none. The option check_derivatives_tol (default = 1e-04), determines when a difference between an analytic gradient and its finite difference approximation is flagged as an error.

...

arguments that will be passed to the user-defined objective and constraints functions.

Details

NLopt addresses general nonlinear optimization problems of the form:

min f(x) x in R^n

s.t. g(x) <= 0 h(x) = 0 lb <= x <= ub

where f is the objective function to be minimized and x represents the n optimization parameters. This problem may optionally be subject to the bound constraints (also called box constraints), lb and ub. For partially or totally unconstrained problems the bounds can take -Inf or Inf. One may also optionally have m nonlinear inequality constraints (sometimes called a nonlinear programming problem), which can be specified in g(x), and equality constraints that can be specified in h(x). Note that not all of the algorithms in NLopt can handle constraints.

Value

The return value contains a list with the inputs, and additional elements

`call`	the call that was made to solve
`status`	integer value with the status of the optimization (0 is success)
`message`	more informative message with the status of the optimization
`iterations`	number of iterations that were executed
`objective`	value if the objective function in the solution
`solution`	optimal value of the controls
`version`	version of NLopt that was used

Note

See ?nloptr-package for an extended example.

Author(s)

Steven G. Johnson and others (C code)
Jelmer Ypma (R interface)

References

Steven G. Johnson, The NLopt nonlinear-optimization package, https://nlopt.readthedocs.io/en/latest/

Examples

library('nloptr')

## Rosenbrock Banana function and gradient in separate functions
eval_f <- function(x) {
    return( 100 * (x[2] - x[1] * x[1])^2 + (1 - x[1])^2 )
}

eval_grad_f <- function(x) {
    return( c( -400 * x[1] * (x[2] - x[1] * x[1]) - 2 * (1 - x[1]),
                200 * (x[2] - x[1] * x[1])) )
}


# initial values
x0 <- c( -1.2, 1 )

opts <- list("algorithm"="NLOPT_LD_LBFGS",
             "xtol_rel"=1.0e-8)

# solve Rosenbrock Banana function
res <- nloptr( x0=x0,
               eval_f=eval_f,
               eval_grad_f=eval_grad_f,
               opts=opts)
print( res )


## Rosenbrock Banana function and gradient in one function
# this can be used to economize on calculations
eval_f_list <- function(x) {
    return( list( "objective" = 100 * (x[2] - x[1] * x[1])^2 + (1 - x[1])^2,
                  "gradient"  = c( -400 * x[1] * (x[2] - x[1] * x[1]) - 2 * (1 - x[1]),
                                    200 * (x[2] - x[1] * x[1])) ) )
}

# solve Rosenbrock Banana function using an objective function that
# returns a list with the objective value and its gradient
res <- nloptr( x0=x0,
               eval_f=eval_f_list,
               opts=opts)
print( res )



# Example showing how to solve the problem from the NLopt tutorial.
#
# min sqrt( x2 )
# s.t. x2 >= 0
#      x2 >= ( a1*x1 + b1 )^3
#      x2 >= ( a2*x1 + b2 )^3
# where
# a1 = 2, b1 = 0, a2 = -1, b2 = 1
#
# re-formulate constraints to be of form g(x) <= 0
#      ( a1*x1 + b1 )^3 - x2 <= 0
#      ( a2*x1 + b2 )^3 - x2 <= 0

library('nloptr')


# objective function
eval_f0 <- function( x, a, b ){
    return( sqrt(x[2]) )
}

# constraint function
eval_g0 <- function( x, a, b ) {
    return( (a*x[1] + b)^3 - x[2] )
}

# gradient of objective function
eval_grad_f0 <- function( x, a, b ){
    return( c( 0, .5/sqrt(x[2]) ) )
}

# jacobian of constraint
eval_jac_g0 <- function( x, a, b ) {
    return( rbind( c( 3*a[1]*(a[1]*x[1] + b[1])^2, -1.0 ),
                   c( 3*a[2]*(a[2]*x[1] + b[2])^2, -1.0 ) ) )
}


# functions with gradients in objective and constraint function
# this can be useful if the same calculations are needed for
# the function value and the gradient
eval_f1 <- function( x, a, b ){
    return( list("objective"=sqrt(x[2]),
                 "gradient"=c(0,.5/sqrt(x[2])) ) )
}

eval_g1 <- function( x, a, b ) {
    return( list( "constraints"=(a*x[1] + b)^3 - x[2],
                  "jacobian"=rbind( c( 3*a[1]*(a[1]*x[1] + b[1])^2, -1.0 ),
                                    c( 3*a[2]*(a[2]*x[1] + b[2])^2, -1.0 ) ) ) )
}


# define parameters
a <- c(2,-1)
b <- c(0, 1)

# Solve using NLOPT_LD_MMA with gradient information supplied in separate function
res0 <- nloptr( x0=c(1.234,5.678),
                eval_f=eval_f0,
                eval_grad_f=eval_grad_f0,
                lb = c(-Inf,0),
                ub = c(Inf,Inf),
                eval_g_ineq = eval_g0,
                eval_jac_g_ineq = eval_jac_g0,
                opts = list("algorithm"="NLOPT_LD_MMA"),
                a = a,
                b = b )
print( res0 )

# Solve using NLOPT_LN_COBYLA without gradient information
res1 <- nloptr( x0=c(1.234,5.678),
                eval_f=eval_f0,
                lb = c(-Inf,0),
                ub = c(Inf,Inf),
                eval_g_ineq = eval_g0,
                opts = list("algorithm"="NLOPT_LN_COBYLA"),
                a = a,
                b = b )
print( res1 )


# Solve using NLOPT_LD_MMA with gradient information in objective function
res2 <- nloptr( x0=c(1.234,5.678),
                eval_f=eval_f1,
                lb = c(-Inf,0),
                ub = c(Inf,Inf),
                eval_g_ineq = eval_g1,
                opts = list("algorithm"="NLOPT_LD_MMA", "check_derivatives"=TRUE),
                a = a,
                b = b )
print( res2 )

Package:	nloptr
Type:	Package
Version:	0.9.9
Date:	2013-11-22
License:	L-GPL
LazyLoad:	yes

`.x`	point at which the comparison is done.
`func`	function to be evaluated.
`func_grad`	function calculating the analytic gradients.
`check_derivatives_tol`	option determining when differences between the analytic gradient and its finite difference approximation are flagged as an error.
`check_derivatives_print`	option related to the amount of output. 'all' means that all comparisons are shown, 'errors' only shows comparisons that are flagged as an error, and 'none' shows the number of errors only.
`func_grad_name`	option to change the name of the gradient function that shows up in the output.
`...`	further arguments passed to the functions func and func_grad.

`name`	name of the option
`type`	type (numeric, logical, integer, character)
`possible_values`	string explaining the values the option can take
`default`	default value of the option (as a string)
`is_termination_condition`	is this option part of the termination conditions?
`description`	description of the option (taken from NLopt website if it's an option that is passed on to NLopt).

`opts.show`	list or vector with names of options. A description will be shown for the options in this list. By default, a description of all options is shown.
`opts.user`	object containing user supplied options. This argument is optional. It is used when `nloptr.print.options` is called from `nloptr`. In that case options are listed if `print_options_doc` is set to `TRUE` when passing a minimization problem to `nloptr`.

`x`	object containing result from minimization.
`show.controls`	Logical or vector with indices. Should we show the value of the control variables in the solution? If `show.controls` is a vector with indices, it is used to select which control variables should be shown. This can be useful if the model contains a set of parameters of interest and a set of nuisance parameters that are not of immediate interest.
`...`	further arguments passed to or from other methods.

`x0`	initial point for searching the optimum.
`fn`	objective function that is to be minimized.
`lower`, `upper`	lower and upper bound constraints.
`maxeval`	maximum number of function evaluations.
`pop.size`	population size.
`ranseed`	prescribe seed for random number generator.
`xtol_rel`	stopping criterion for relative change reached.
`nl.info`	logical; shall the original NLopt info been shown.
`...`	additional arguments passed to the function.

`x0`	point as a vector where the gradient is to be calculated.
`fn`	scalar function of one or several variables.
`heps`	step size to be used.
`...`	additional arguments passed to the function.

Package 'nloptr'

Help Index

R interface to NLopt

Description

Details

Note

Author(s)

References

See Also

Examples

Augmented Lagrangian Algorithm

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Bound Optimization by Quadratic Approximation

Description

Usage

Arguments

Details

Value

Note

References

See Also

Examples

Conservative Convex Separable Approximation with Affine Approximation plus Quadratic Penalty

Description

Usage

Arguments

Value

Note

References

See Also

Examples

Check analytic gradients of a function using finite difference approximations

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Constrained Optimization by Linear Approximations

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Controlled Random Search

Description

Usage

Arguments

Details

Value

Note

References

Examples

DIviding RECTangles Algorithm for Global Optimization

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

R interface to NLopt