Optimization.jl interface

SPGBox can be called through the common Optimization.jl interface, using the SPGBoxOpt algorithm. This allows SPGBox to be used interchangeably with other Optimization.jl solvers, and to be compared with them on the same problems.

The interface is provided by a package extension, loaded automatically when SPGBox and Optimization (or OptimizationBase and SciMLBase) are both loaded. No extra dependency is added to SPGBox for users who do not need this interface.

Installation

Install SPGBox and Optimization, plus an automatic-differentiation backend if the gradient is not supplied explicitly. The example below uses ForwardDiff (AutoForwardDiff is re-exported by Optimization):

julia> using Pkg

julia> Pkg.add(["SPGBox", "Optimization", "ForwardDiff"])

If the gradient is provided directly, an AD package is not required.

Basic usage

The objective function must be of the Optimization.jl form f(x,p), where p are optional fixed parameters, and the gradient is computed with an automatic-differentiation backend (here, ForwardDiff):

julia> using SPGBox, Optimization, ForwardDiff

julia> f(x, p) = (x[1] - p[1])^2 + (x[2] - 1)^2
f (generic function with 1 method)

julia> optf = OptimizationFunction(f, AutoForwardDiff())
OptimizationFunction{...}

julia> prob = OptimizationProblem(optf, [10.0, 18.0], [1.0]; lb = [2.0, -Inf], ub = [Inf, Inf])
OptimizationProblem{...}

julia> sol = solve(prob, SPGBoxOpt())
retcode: Success
u: [2.0, 1.0]
Final objective value:     1.0

A gradient function can be provided instead of an AD backend, with the grad keyword of OptimizationFunction (see the Optimization.jl documentation).

SPGBoxOpt options

SPGBox.SPGBoxOpt — Type
SPGBoxOpt(; eps, nfevalmax, m, project_x0, step_nc, iprint)

Algorithm to use SPGBox through the Optimization.jl interface.

The solver is available once Optimization (or OptimizationBase and SciMLBase) is loaded:

using SPGBox, Optimization, ForwardDiff
f(x, p) = (x[1] - p[1])^2 + (x[2] - 1)^2
optf = OptimizationFunction(f, AutoForwardDiff())
prob = OptimizationProblem(optf, [10.0, 18.0], [1.0]; lb = [2.0, -Inf], ub = [Inf, Inf])
sol = solve(prob, SPGBoxOpt())

The keyword arguments are the options of spgbox! of the same name, and are the only ones that can be set in the constructor. The common solve options are interpreted as:

  • maxiters: maximum number of iterations (sets nitmax). If set, the limit on the number of function evaluations is nfevalmax if provided to SPGBoxOpt, and unlimited otherwise. If not set, the defaults of spgbox! are used.
  • maxtime: maximum time (in seconds), checked at the end of every iteration.
  • callback: called as callback(state, f) after every iteration. The state.original field is the current SPGBoxResult. If the callback returns true the optimization stops.
  • abstol and reltol are not used. Use the eps option (tolerance on the projected gradient norm).

The gradient is computed by the automatic differentiation backend of the OptimizationFunction, or provided with its grad option.

source

Mapping of the common solve options

solve keywordEffect
maxitersMaximum number of iterations (sets nitmax). If given, the evaluation limit is the nfevalmax passed to SPGBoxOpt (or unlimited, if none was passed). If not given, the spgbox! defaults are used.
maxtimeChecked at the end of every iteration (in seconds).
callbackCalled as callback(state, f) after every iteration. state.original holds the current SPGBoxResult. Returning true stops the optimization.
abstol, reltolNot used. Use the eps option of SPGBoxOpt (tolerance on the projected gradient norm) instead.

The lb and ub bounds of the OptimizationProblem are passed directly to spgbox!.

Benchmark against other box-constrained solvers

A script comparing SPGBoxOpt against other gradient-based, box-constrained Optimization.jl solvers (L-BFGS-B, Fminbox(LBFGS()) and NLopt.LD_LBFGS()) is available in benchmark/optimization/. See its README for setup and run instructions.