Callbacks

NLSolvers.jl supports user-defined callbacks that are invoked after every iteration of any optimization solver. Callbacks let you monitor progress, log intermediate state, build a convergence trace, or stop the solver early based on custom criteria.

Basic usage

A callback is any function (or callable object) that takes a single info argument and returns a Bool:

using NLSolvers

callback = info -> begin
    println("iter=$(info.iter), f=$(info.state.fz)")
    return false   # continue optimization
end

solve(prob, x0, LineSearch(BFGS()),
      OptimizationOptions(callback = callback))

Returning true stops the solver early; returning false lets it continue. The default callback = nothing disables the mechanism with zero overhead.

What the callback receives

The info argument is a NamedTuple with three fields:

Field	Type	Description
`iter`	`Int`	Current iteration count (1-based)
`time`	`Float64`	Elapsed seconds since `solve` started
`state`	`NamedTuple`	Solver-specific state (see below)

Solver-specific `state`

The contents of info.state depend on which solver is running. Use haskey if you write generic callbacks.

Line search solvers (BFGS, DBFGS, DFP, SR1, L-BFGS, CG, Gradient Descent, Newton)

state is the internal objvars named tuple:

Field	Description
`x`	Previous iterate
`fx`	Objective value at `x`
`∇fx`	Gradient at `x`
`z`	New iterate (after line search)
`fz`	Objective value at `z`
`∇fz`	Gradient at `z`
`B`	Current Hessian (or inverse) approximation; `nothing` for L-BFGS/CG
`Pg`	Preconditioned gradient if using a preconditioner; otherwise `nothing`

Trust region solvers

Same fields as line search, plus:

Field	Description
`Δ`	Current trust region radius
`rejected`	`true` if the previous step was rejected by the trust region rule

Nelder-Mead

Field	Description
`simplex_vector`	Vector of simplex vertices
`simplex_value`	Function values at each vertex
`x_centroid`	Centroid of the simplex (excluding the worst vertex)
`nm_obj`	Convergence metric — standard deviation of `simplex_value`

Simulated Annealing

Field	Description
`x_best`	Best point found so far
`f_best`	Best objective value found so far
`x_now`	Current state of the chain
`f_now`	Objective value at `x_now`
`temperature`	Current temperature

Particle Swarm

Field	Description
`X`	Current particle positions
`X_best`	Each particle's personal best
`Fs`	Function values at `X`
`Fs_best`	Function values at `X_best`
`x`	Global best particle
`best_f`	Global best objective value
`swarm_f`	Convergence metric for the swarm

Brent's method (univariate)

Field	Description
`x`	Current best point
`fx`	Function value at `x`
`a`, `b`	Current bracketing interval `[a, b]`
`v`, `w`	Two previous iterates
`fv`, `fw`	Function values at `v` and `w`

Active Box (projected Newton)

Field	Description
`x`	Previous iterate
`z`	New iterate
`fz`	Objective value at `z`
`∇fz`	Gradient at `z`
`B`	Hessian approximation
`activeset`	Boolean vector indicating active bound constraints

Examples

Build a convergence trace

trace = Float64[]
solve(prob, x0, LineSearch(BFGS()),
      OptimizationOptions(
          callback = info -> (push!(trace, info.state.fz); false),
          maxiter = 100,
      ))

Stop when the gradient is sufficiently small

gtol = 1e-6
solve(prob, x0, LineSearch(BFGS()),
      OptimizationOptions(
          callback = info -> norm(info.state.∇fz, Inf) < gtol,
          g_abstol = 0.0,  # disable built-in g-tolerance so callback wins
      ))

Time-limited optimization

time_limit = 5.0  # seconds
solve(prob, x0, LineSearch(BFGS()),
      OptimizationOptions(callback = info -> info.time > time_limit))

Save iterates for plotting later

Arrays in info.state (such as z, ∇fz, simplex_vector) are aliases of live solver buffers — they will be overwritten on the next iteration. Copy them if you need to retain them past the callback call.

history = Vector{Vector{Float64}}()
solve(prob, x0, LineSearch(BFGS()),
      OptimizationOptions(
          callback = info -> (push!(history, copy(info.state.z)); false),
      ))

Scalar fields like info.iter, info.time, info.state.fz are values and do not need copying.

Performance

The callback machinery has zero runtime overhead when callback === nothing (the default). The callback type is captured as a type parameter on OptimizationOptions, so the compiler eliminates the dispatch entirely. Passing a concrete callback function adds only the cost of calling that function once per iteration.