Common Solver Options (Solve Keyword Arguments)

OptimizationBase

Core types, defaults, and solver interface extensions shared by the Optimization.jl solver packages.

solve(prob::OptimizationProblem, alg, args...; kwargs...)

Solve an OptimizationProblem with alg and return an AbstractOptimizationSolution.

solve validates the problem against the algorithm's capability traits and dispatches to the solver package that implements alg. Solver-specific keywords are forwarded unchanged.

Arguments

• prob: the problem to optimize.
• alg: an algorithm provided by an Optimization.jl solver package.
• args...: positional arguments accepted by the solver implementation.

Keyword Arguments

• sensealg: sensitivity algorithm used by differentiation integrations.
• u0: replacement initial value for the problem.
• p: replacement parameter value for the problem.
• wrap: whether to return the standard Optimization solution wrapper.
• kwargs...: common and solver-specific options.

Returns

An AbstractOptimizationSolution containing the final variables, objective value, return code, and OptimizationStats.

Callbacks

When supported by alg, callback is called after an optimization step as callback(state, objective). state is an OptimizationState, and returning true stops the optimization. The default callback returns false.

Examples

using Optimization, OptimizationOptimJL

f(u, p) = sum(abs2, u)
prob = OptimizationProblem(OptimizationFunction(f), [1.0, -2.0])
sol = solve(prob, Optim.BFGS(); maxiters = 100)

OptimizationCache(prob::OptimizationProblem, opt; kwargs...)

Prepared optimization problem state used by cache-based solvers.

OptimizationCache stores the selected optimizer, instantiated objective and constraint functions, bounds, constraint limits, callbacks, verbosity settings, and solver keyword arguments. Use init to construct caches through the public solver interface.

Arguments

• prob: the optimization problem to prepare.
• opt: the selected optimization algorithm.

Keyword Arguments

• callback: callback invoked after an optimization step.
• maxiters: maximum number of iterations.
• maxtime: maximum runtime in seconds.
• abstol: absolute tolerance.
• reltol: relative tolerance.
• progress: whether to display progress information.
• structural_analysis: whether to perform structural analysis of the objective.
• manifold: manifold used for the optimization variables.
• verbose: verbosity setting or solver-specific verbosity value.
• kwargs...: solver-specific options.

Fields

The fields store the instantiated objective, bounds, constraints, callback, solver options, and progress state. Concrete solver caches may add fields, so solver implementations should expose their supported state through methods rather than requiring callers to access fields directly.

Examples

cache = OptimizationCache(prob, alg; maxiters = 100)
sol = solve!(cache)

DEFAULT_CALLBACK

Default callback for solve and init. It ignores all callback arguments and returns false, so optimization continues until the solver stops.

DEFAULT_DATA

Default data iterator for optimization problems that are not minibatched.

IncompatibleOptimizerError(msg)

Error thrown when an optimizer cannot solve the supplied OptimizationProblem because required features, such as bounds, constraints, callbacks, gradients, or hessians, are unsupported or missing.

OptimizerMissingError(alg)

Error thrown when solve or init cannot find an Optimization.jl solver implementation for alg. Load the package that provides the selected optimizer before solving the problem.

OptimizationVerbosity <: AbstractVerbositySpecifier

Verbosity configuration for Optimization.jl solvers, providing fine-grained control over diagnostic messages and warnings during optimization.

Fields

Convergence and Numerical Issues Group

• convergence_failure: Messages when algorithm fails to converge
• nan_inf_gradients: Messages when NaN or Inf values appear in gradients
• singularity_at_bounds: Messages when function has singularities at bounds
• unrecognized_stop_reason: Messages when stop reason is not recognized

Constraints and Bounds Group

• unsupported_bounds: Messages when bounds are not supported by the algorithm
• equality_constraints_ignored: Messages when equality constraints are not passed to the algorithm
• inequality_constraints_ignored: Messages when inequality constraints are not passed to the algorithm

Automatic Differentiation Group

• missing_second_order_ad: Messages when second-order AD is required but not provided
• incompatible_ad_backend: Messages when AD backend is incompatible with algorithm requirements

Feature Support Group

• unsupported_callbacks: Messages when callbacks are not supported by the algorithm
• unsupported_kwargs: Messages when common optimization parameters (abstol, reltol, maxtime, maxiters) are not supported by the algorithm

Solver Verbosity Group

• ipopt_verbosity: Controls Ipopt solver output verbosity (0=silent, 5=default, 12=maximum). Use SciMLLogging.MessageLevel(n) to specify an integer verbosity level.

Constructors

OptimizationVerbosity(preset::AbstractVerbosityPreset)

Create an OptimizationVerbosity using a preset configuration:

• SciMLLogging.None(): All messages disabled

• SciMLLogging.Minimal(): Only critical convergence issues and AD warnings

• SciMLLogging.Standard(): Balanced verbosity (default)

• SciMLLogging.Detailed(): Comprehensive information

• SciMLLogging.All(): Maximum verbosity

  OptimizationVerbosity(; preset=nothing, convergencenumerical=nothing, constraintsbounds=nothing, automaticdifferentiation=nothing, featuresupport=nothing, kwargs...)

Create an OptimizationVerbosity with group level or individual toggle level control.

Examples

# Use a preset
verbose = OptimizationVerbosity(SciMLLogging.Standard())

# Set entire groups
verbose = OptimizationVerbosity(
    convergence_numerical = SciMLLogging.WarnLevel(),
    feature_support = SciMLLogging.InfoLevel()
)

# Set individual fields
verbose = OptimizationVerbosity(
    convergence_failure = SciMLLogging.ErrorLevel(),
    unsupported_kwargs = SciMLLogging.Silent()
)

# Mix group and individual settings
verbose = OptimizationVerbosity(
    feature_support = SciMLLogging.InfoLevel(),  # Set all feature warnings to InfoLevel
    unsupported_callbacks = SciMLLogging.Silent()  # Override specific field
)

init(prob::OptimizationProblem, alg, args...; kwargs...)

Prepare prob and alg for an incremental optimization run by constructing an AbstractOptimizationCache.

Arguments

• prob: the problem to optimize.
• alg: an algorithm provided by an Optimization.jl solver package.
• args...: positional arguments accepted by the solver implementation.

Keyword Arguments

The common options are the same as for solve, including maxiters, maxtime, abstol, reltol, and callback. Solver-specific options are forwarded to the implementation.

Returns

An AbstractOptimizationCache ready for solve!.

Interface

Solver packages implement SciMLBase.__init(prob, alg; kwargs...) when they support the cache interface. The returned cache must implement SciMLBase.__solve(cache).

Examples

cache = init(prob, alg; maxiters = 100)
sol = solve!(cache)

solve!(cache::AbstractOptimizationCache)

Continue an optimization represented by cache and return its solution.

Arguments

• cache: a cache returned by init.

Returns

An AbstractOptimizationSolution containing the final optimization state.

Interface

Solver packages implement SciMLBase.__solve(cache) for their concrete cache type. The cache is a developer-facing extension point; callers should use documented constructors and methods rather than relying on concrete fields.

Examples

cache = init(prob, alg)
sol = solve!(cache)