JuMP model optimisation

PortfolioOptimisers.jl builds its optimisation models with JuMP, so a solver that JuMP supports can solve them.

A Solver names one solver, its settings and the solution statuses it must reach. An optimiser takes one Solver or a vector of them, and tries them in order until one returns an accepted solution. A JuMPResult records which solvers failed, at which stage, and whether any of them succeeded.

PortfolioOptimisers.Solver — Type
struct Solver{__T_name, __T_solver, __T_settings, __T_check_sol, __T_add_bridges} <: AbstractEstimator

Names one JuMP solver, the attributes to set on it, and the solution statuses to accept.

An estimator that solves a JuMP model takes one Solver or a vector of them. optimise_JuMP_model! tries the solvers of a vector in order, and stops at the first solution that the check_sol of its solver accepts.

Fields

  • name: The symbol or string that names the solver. optimise_JuMP_model! records a failure of the solver under this key in the trials of the JuMPResult. Two solvers that share a name share one entry, and the later failure overwrites the earlier one. Give each solver of a vector its own name, because every solver has the default name "".
  • check_sol: The keyword arguments that assert_is_solved_and_feasible takes after each solve. They decide which solver statuses count as a solved model. The default (;) keeps the JuMP defaults, allow_local = true and allow_almost = false. The termination status must then be OPTIMAL or LOCALLY_SOLVED, and the primal status must be FEASIBLE_POINT. So the check refuses a solution that the solver itself reports as approximate, and optimise_JuMP_model! tries the next solver of the vector. check_sol = (; allow_local = true, allow_almost = true) also accepts ALMOST_OPTIMAL, ALMOST_LOCALLY_SOLVED and NEARLY_FEASIBLE_POINT. The examples, the user guide and the tests pass it, because a first-order solver that reaches its tolerance on a well-posed portfolio problem gives a usable solution. Set allow_local = false to refuse LOCALLY_SOLVED, and add dual = true to also require a feasible dual point.
  • add_bridges: The add_bridges keyword argument of set_optimizer. With false, JuMP adds no bridges, and a constraint that the solver does not support raises at JuMP.optimize!.

Constructors

Solver(;    name::Sym_Str = "",    solver::Any,    settings::Option{<:SlvSettings} = nothing,    check_sol::NamedTuple = (;),    add_bridges::Bool = true) -> Solver

Keywords correspond to the struct's fields.

Validation

  • If settings is a collection, !isempty(settings), else an IsEmptyError. If settings is not nothing, each key is a SlvKeys, else an ArgumentError.

Examples

The default check_sol accepts a solution only when the solver reports OPTIMAL or LOCALLY_SOLVED, and a FEASIBLE_POINT.

julia> Solver(; solver = nothing)Solver         name ┼ String: ""       solver ┼ nothing     settings ┼ nothing    check_sol ┼ @NamedTuple{}: NamedTuple()  add_bridges ┴ Bool: true

This check_sol also accepts an approximate solution. The examples, the user guide and the tests use it.

julia> Solver(; solver = nothing, check_sol = (; allow_local = true, allow_almost = true))Solver         name ┼ String: ""       solver ┼ nothing     settings ┼ nothing    check_sol ┼ @NamedTuple{allow_local::Bool, allow_almost::Bool}: (allow_local = true, allow_almost = true)  add_bridges ┴ Bool: true

Related

source
PortfolioOptimisers.JuMPResult — Type
struct JuMPResult{__T_trials, __T_success} <: AbstractJuMPResult

Records which solvers failed, at which stage, and whether one of them succeeded.

The constructor warns when success is false. failed_solve_msg writes the warning, with one line for each failed stage of each solver. A line holds the name of the solver, the stage and the first line of the error. The warning holds no settings and no full exception, and trials keeps them.

trials records failures only. A solver that succeeds adds no entry, so an empty trials with success = true means that the first solver succeeded. The key of an entry is the name of the solver. The value is a dictionary from the failed stage, :set_optimizer, :optimize! or :assert_is_solved_and_feasible, to its exception. An entry of the last stage also holds the termination status of the solver under :termination_status, so the warning can state that the problem is infeasible or unbounded, and the settings of the solver under :settings.

Two solvers that share a name share one entry. Every solver has the default name "", so a vector of unnamed solvers keeps only its last failure.

Fields

  • trials: The failures of the solvers. The key of an entry is the name of a solver, and the value maps each failed stage to its exception.
  • success: true when one solver gives a solution that its check_sol accepts.

Constructors

JuMPResult(;    trials::AbstractDict,    success::Bool) -> JuMPResult

Keywords correspond to the struct's fields.

Examples

julia> JuMPResult(; trials = Dict(:HiGHS => Dict(:optimize! => "error")), success = true)JuMPResult   trials ┼ Dict{Symbol, Dict{Symbol, String}}: Dict(:HiGHS => Dict(:optimize! => "error"))  success ┴ Bool: true

Related

source