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} <: AbstractEstimatorNames 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 thetrialsof theJuMPResult. 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"".
solver: Theoptimizer_factoryargument ofset_optimizer.
settings: The solver attributes thatset_solver_attributessets withset_attributeafterJuMP.set_optimizerattaches the solver.nothingsets no attribute.
check_sol: The keyword arguments thatassert_is_solved_and_feasibletakes after each solve. They decide which solver statuses count as a solved model. The default(;)keeps the JuMP defaults,allow_local = trueandallow_almost = false. The termination status must then beOPTIMALorLOCALLY_SOLVED, and the primal status must beFEASIBLE_POINT. So the check refuses a solution that the solver itself reports as approximate, andoptimise_JuMP_model!tries the next solver of the vector.check_sol = (; allow_local = true, allow_almost = true)also acceptsALMOST_OPTIMAL,ALMOST_LOCALLY_SOLVEDandNEARLY_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. Setallow_local = falseto refuseLOCALLY_SOLVED, and adddual = trueto also require a feasible dual point.
add_bridges: Theadd_bridgeskeyword argument ofset_optimizer. Withfalse, JuMP adds no bridges, and a constraint that the solver does not support raises atJuMP.optimize!.
Constructors
Solver(; name::Sym_Str = "", solver::Any, settings::Option{<:SlvSettings} = nothing, check_sol::NamedTuple = (;), add_bridges::Bool = true) -> SolverKeywords correspond to the struct's fields.
Validation
- If
settingsis a collection,!isempty(settings), else anIsEmptyError. Ifsettingsis notnothing, each key is aSlvKeys, else anArgumentError.
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: trueThis 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: trueRelated
PortfolioOptimisers.JuMPResult — Type
struct JuMPResult{__T_trials, __T_success} <: AbstractJuMPResultRecords 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:truewhen one solver gives a solution that itscheck_solaccepts.
Constructors
JuMPResult(; trials::AbstractDict, success::Bool) -> JuMPResultKeywords 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: trueRelated