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.0A 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 (setsnitmax). If set, the limit on the number of function evaluations isnfevalmaxif provided toSPGBoxOpt, and unlimited otherwise. If not set, the defaults ofspgbox!are used.maxtime: maximum time (in seconds), checked at the end of every iteration.callback: called ascallback(state, f)after every iteration. Thestate.originalfield is the currentSPGBoxResult. If the callback returnstruethe optimization stops.abstolandreltolare not used. Use theepsoption (tolerance on the projected gradient norm).
The gradient is computed by the automatic differentiation backend of the OptimizationFunction, or provided with its grad option.
Mapping of the common solve options
solve keyword | Effect |
|---|---|
maxiters | Maximum 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. |
maxtime | Checked at the end of every iteration (in seconds). |
callback | Called as callback(state, f) after every iteration. state.original holds the current SPGBoxResult. Returning true stops the optimization. |
abstol, reltol | Not 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.