Reference

Abstract type from which JSO solvers derive.

GenericExecutionStats(nlp; ...)
GenericExecutionStats{T, S, V, Tsp}(;...)

A GenericExecutionStats is a struct for storing the output information of solvers. It contains the following fields:

• status: Indicates the output of the solver. Use show_statuses() for the full list;
• solution: The final approximation returned by the solver (default: an uninitialized vector like nlp.meta.x0);
• objective: The objective value at solution (default: Inf);
• dual_feas: The dual feasibility norm at solution (default: Inf);
• primal_feas: The primal feasibility norm at solution (default: 0.0 if unconstrained, Inf otherwise);
• multipliers: The Lagrange multipliers wrt to the constraints (default: an uninitialized vector like nlp.meta.y0);
• multipliers_L: The Lagrange multipliers wrt to the lower bounds on the variables (default: an uninitialized vector like nlp.meta.x0 if there are bounds, or a zero-length vector if not);
• multipliers_U: The Lagrange multipliers wrt to the upper bounds on the variables (default: an uninitialized vector like nlp.meta.x0 if there are bounds, or a zero-length vector if not);
• iter: The number of iterations computed by the solver (default: -1);
• elapsed_time: The elapsed time computed by the solver (default: Inf);
• solver_specific::Dict{Symbol,Any}: A solver specific dictionary.

The constructor preallocates storage for the fields above. Special storage may be used for multipliers_L and multipliers_U by passing them to the constructor. For instance, if a problem has few bound constraints, those multipliers could be held in sparse vectors.

The following fields indicate whether the information above has been updated and is reliable:

• solution_reliable
• objective_reliable
• residuals_reliable (for dual_feas and primal_feas)
• multipliers_reliable (for multipliers)
• bounds_multipliers_reliable (for multipliers_L and multipliers_U)
• iter_reliable
• time_reliable
• solver_specific_reliable.

Setting fields using one of the methods set_solution!(), set_objective!(), etc., also marks the field value as reliable.

The reset!() method marks all fields as unreliable.

nlp is highly recommended to set default optional fields. If it is not provided, the function reset!(stats, nlp) should be called before solve!.

All other variables can be input as keyword arguments.

Notice that GenericExecutionStats does not compute anything, it simply stores.

reset!(solver::AbstractOptimizationSolver, model::AbstractNLPModel)

Use in the context of restarting or reusing the solver structure. Reset the internal fields of solver for the model before calling solve! on the same structure. model must have the same number of variables, bounds and constraints as that used to instantiate solver.

reset!(stats::GenericExecutionStats)
reset!(stats::GenericExecutionStats, nlp::AbstractNLPModel)

Reset the internal flags of stats to false to Indicate that the contents should not be trusted. If an AbstractNLPModel is also provided, the pre-allocated vectors are adjusted to the problem size.

broadcast_solver_specific!(stats::GenericExecutionStats, field::Symbol, value)

Broadcast value as a solver-specific value identified by field in stats and mark it as reliable.

get_status(nlp, kwargs...)

Return the output of the solver based on the information in the keyword arguments. Use show_statuses() for the full list.

The keyword arguments may contain:

• elapsed_time::Float64 = 0.0: current elapsed time (default: 0.0);
• iter::Integer = 0: current number of iterations (default: 0);
• optimal::Bool = false: true if the problem reached an optimal solution (default: false);
• small_residual::Bool = false: true if the nonlinear least squares problem reached a solution with small residual (default: false);
• infeasible::Bool = false: true if the problem is infeasible (default: false);
• parameter_too_large::Bool = false: true if the parameters are loo large (default: false);
• unbounded::Bool = false: true if the problem is unbounded (default: false);
• stalled::Bool = false: true if the algorithm is stalling (default: false);
• max_eval::Integer: limit on the number of evaluations defined by eval_fun (default: typemax(Int));
• max_time::Float64 = Inf: limit on the time (default: Inf);
• max_iter::Integer: limit on the number of iterations (default: typemax(Int)).

log_header(colnames, coltypes)

Creates a header using the names in colnames formatted according to the types in coltypes. Uses internal formatting specification given by SolverCore.formats and default header translation given by SolverCore.default_headers.

Input:

• colnames::Vector{Symbol}: Column names.
• coltypes::Vector{DataType}: Column types.

Keyword arguments:

• hdr_override::Dict{Symbol,String}: Overrides the default headers.
• colsep::Int: Number of spaces between columns (Default: 2)

See also log_row.

log_row(vals)

Creates a table row from the values on vals according to their types. Pass the names and types of vals to log_header for a logging table. Uses internal formatting specification given by SolverCore.formats.

To handle a missing value, add the type instead of the number:

@info log_row(Any[1.0, 1])
@info log_row(Any[Float64, Int])

Prints

[ Info:  1.0e+00       1
[ Info:        -       -

Keyword arguments:

• colsep::Int: Number of spaces between columns (Default: 2)

set_bounds_multipliers!(stats::GenericExecutionStats{T, S, V}, zL::V, zU::V)

Register zL and zU as optimal multipliers associated to lower-bounded and upper-bounded constraints, respectively, in stats and mark them as reliable.

set_constraint_multipliers!(stats::GenericExecutionStats{T, S, V}, y::S, zL::V, zU::V)

Register y as optimal multipliers associated to general constraints in stats and mark them as reliable.

set_dual_residual!(stats::GenericExecutionStats{T, S, V}, dual::T)

Register dual as optimal dual feasibility residuals in stats and mark it as reliable.

set_iter!(stats::GenericExecutionStats, iter::Int)

Register iter as optimal iteration number in stats and mark it as reliable.

set_multipliers!(stats::GenericExecutionStats{T, S, V}, y::S, zL::V, zU::V)

Register y, zL and zU as optimal multipliers associated to general constraints, lower-bounded and upper-bounded constraints, respectively, in stats and mark them as reliable.

set_objective!(stats::GenericExecutionStats{T, S, V}, val::T)

Register val as optimal objective value in stats and mark it as reliable.

set_primal_residual!(stats::GenericExecutionStats{T, S, V}, primal::T)

Register primal as optimal primal residuals in stats and mark it as reliable.

set_residuals!(stats::GenericExecutionStats{T, S, V}, primal::T, dual::T)

Register primal and dual as optimal primal and dual feasibility residuals, respectively, in stats and mark them as reliable.

set_solution!(stats::GenericExecutionStats, x::AbstractVector)

Register x as optimal solution in stats and mark it as reliable.

set_solver_specific!(stats::GenericExecutionStats, field::Symbol, value)

Register value as a solver-specific value identified by field in stats and mark it as reliable.

set_status!(stats::GenericExecutionStats, status::Symbol)

Register status as final status in stats and mark it as reliable.

set_time!(stats::GenericExecutionStats, time::Float64)

Register time as optimal solution time in stats and mark it as reliable.

show_statuses()

Show the list of available statuses to use with GenericExecutionStats.

solve!(solver, model; kwargs...)
solve!(solver, model, stats; kwargs...)

Apply solver to model.

Arguments

• solver::AbstractOptimizationSolver: solver structure to hold all storage necessary for a solve
• model::AbstractNLPModel: the model solved, see NLPModels.jl
• stats::GenericExecutionStats: stats structure to hold solution information.

The first invocation allocates and returns a new GenericExecutionStats. The second one fills out a preallocated stats structure and allows for efficient re-solves.

The kwargs are passed to the solver.

Return Value

• stats::GenericExecutionStats: stats structure holding solution information.