From c37b236396472ba977c08cafac7136972576db0e Mon Sep 17 00:00:00 2001 From: odow Date: Fri, 28 May 2021 09:26:00 +1200 Subject: [PATCH 1/4] Document order of multiple solutions --- src/attributes.jl | 75 +++++++++++++++++++++++++++++++---------------- 1 file changed, 49 insertions(+), 26 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index 8036b90217..fd888fb91c 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -924,24 +924,32 @@ struct ObjectiveFunctionType <: AbstractModelAttribute end ## Optimizer attributes """ - ObjectiveValue(resultidx::Int=1) + ObjectiveValue(result_index::Int = 1) -A model attribute for the objective value of the `result_index`th primal result. +A model attribute for the objective value of the primal solution `result_index`. + +If multiple results are present, the first result (i.e., `result_index=1`) must +be an optimal solution. Other results may be alternative optimal solutions; use +`ObjectiveValue` to compare their objective values. """ struct ObjectiveValue <: AbstractModelAttribute result_index::Int - (::Type{ObjectiveValue})(result_index = 1) = new(result_index) + ObjectiveValue(result_index::Int = 1) = new(result_index) end """ - DualObjectiveValue(result_index::Int=1) + DualObjectiveValue(result_index::Int = 1) A model attribute for the value of the objective function of the dual problem for the `result_index`th dual result. + +If multiple results are present, the first result (i.e., `result_index=1`) must +be an optimal solution. Other results may be alternative optimal solutions; use +[`ObjectiveValue`](@ref) to compare their objective values. """ struct DualObjectiveValue <: AbstractModelAttribute result_index::Int - (::Type{DualObjectiveValue})(result_index = 1) = new(result_index) + DualObjectiveValue(result_index::Int = 1) = new(result_index) end """ @@ -1062,15 +1070,18 @@ struct VariablePrimalStart <: AbstractVariableAttribute end """ VariablePrimal(result_index::Int = 1) - VariablePrimal() A variable attribute for the assignment to some primal variable's value in result `result_index`. If `result_index` is omitted, it is 1 by default. + +If multiple results are present, the first result (i.e., `result_index=1`) must +be an optimal solution. Other results may be alternative optimal solutions; use +[`ObjectiveValue`](@ref) to compare their objective values. """ struct VariablePrimal <: AbstractVariableAttribute result_index::Int + VariablePrimal(result_index::Int = 1) = new(result_index) end -VariablePrimal() = VariablePrimal(1) """ CallbackVariablePrimal(callback_data) @@ -1188,50 +1199,64 @@ A constraint attribute for the initial assignment to some constraint's dual valu struct ConstraintDualStart <: AbstractConstraintAttribute end """ - ConstraintPrimal(result_index::Int) - ConstraintPrimal() + ConstraintPrimal(result_index::Int = 1) A constraint attribute for the assignment to some constraint's primal value(s) in result `result_index`. If `result_index` is omitted, it is 1 by default. +If multiple results are present, the first result (i.e., `result_index=1`) must +be an optimal solution. Other results may be alternative optimal solutions; use +[`ObjectiveValue`](@ref) to compare their objective values. + +## Example + Given a constraint `function-in-set`, the `ConstraintPrimal` is the value of the -function evaluated at the primal solution of the variables. For example, given -the constraint `ScalarAffineFunction([x,y], [1, 2], 3)`-in-`Interval(0, 20)` and -a primal solution of `(x,y) = (4,5)`, the `ConstraintPrimal` solution of the -constraint is `1 * 4 + 2 * 5 + 3 = 17`. +function evaluated at the primal solution of the variables. + +For example, given the constraint +`ScalarAffineFunction([x,y], [1, 2], 3)`-in-`Interval(0, 20)` and a primal +solution of `(x,y) = (4,5)`, the `ConstraintPrimal` solution of the constraint +is `1 * 4 + 2 * 5 + 3 = 17`. """ struct ConstraintPrimal <: AbstractConstraintAttribute result_index::Int + ConstraintPrimal(result_index::Int = 1) = new(result_index) end -ConstraintPrimal() = ConstraintPrimal(1) """ - ConstraintDual(result_index::Int) - ConstraintDual() + ConstraintDual(result_index::Int = 1) A constraint attribute for the assignment to some constraint's dual value(s) in result `result_index`. If `result_index` is omitted, it is 1 by default. + +If multiple results are present, the first result (i.e., `result_index=1`) must +be an optimal solution. Other results may be alternative optimal solutions; use +[`ObjectiveValue`](@ref) to compare their objective values. """ struct ConstraintDual <: AbstractConstraintAttribute result_index::Int + ConstraintDual(result_index::Int = 1) = new(result_index) end -ConstraintDual() = ConstraintDual(1) """ - ConstraintBasisStatus(result_index) + ConstraintBasisStatus(result_index::Int = 1) ConstraintBasisStatus() A constraint attribute for the `BasisStatusCode` of some constraint in result `result_index`, with respect to an available optimal solution basis. If `result_index` is omitted, it is 1 by default. +If multiple results are present, the first result (i.e., `result_index=1`) must +be an optimal solution. Other results may be alternative optimal solutions; use +[`ObjectiveValue`](@ref) to compare their objective values. + **For the basis status of a variable, query the corresponding `SingleVariable` constraint that enforces the variable's bounds.** """ struct ConstraintBasisStatus <: AbstractConstraintAttribute result_index::Int + ConstraintBasisStatus(result_index::Int = 1) = new(result_index) end -ConstraintBasisStatus() = ConstraintBasisStatus(1) """ CanonicalConstraintFunction() @@ -1541,10 +1566,9 @@ The values indicate how to interpret the result vector. ) """ - PrimalStatus(result_index) - PrimalStatus() + PrimalStatus(result_index::Int = 1) -A model attribute for the `ResultStatusCode` of the primal result +A model attribute for the [`ResultStatusCode`](@ref) of the primal result `result_index`. If `result_index` is omitted, it defaults to 1. If `result_index` is larger than the value of [`ResultCount`](@ref) then @@ -1552,12 +1576,11 @@ If `result_index` is larger than the value of [`ResultCount`](@ref) then """ struct PrimalStatus <: AbstractModelAttribute result_index::Int + PrimalStatus(result_index::Int = 1) = new(result_index) end -PrimalStatus() = PrimalStatus(1) """ - DualStatus(result_index) - DualStatus() + DualStatus(result_index::Int = 1) A model attribute for the `ResultStatusCode` of the dual result `result_index`. If `result_index` is omitted, it defaults to 1. @@ -1567,8 +1590,8 @@ If `result_index` is larger than the value of [`ResultCount`](@ref) then """ struct DualStatus <: AbstractModelAttribute result_index::Int + DualStatus(result_index::Int = 1) = new(result_index) end -DualStatus() = DualStatus(1) # Cost of bridging constrained variable in S struct VariableBridgingCost{S<:AbstractSet} <: AbstractModelAttribute end From 64c4d9a153818ffc86c66c72f16c91f91fda2c65 Mon Sep 17 00:00:00 2001 From: odow Date: Sat, 29 May 2021 11:20:15 +1200 Subject: [PATCH 2/4] Consolidate docs in ResultCount --- src/attributes.jl | 47 +++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index fd888fb91c..3cd6f7975d 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -928,9 +928,7 @@ struct ObjectiveFunctionType <: AbstractModelAttribute end A model attribute for the objective value of the primal solution `result_index`. -If multiple results are present, the first result (i.e., `result_index=1`) must -be an optimal solution. Other results may be alternative optimal solutions; use -`ObjectiveValue` to compare their objective values. +See [`ResultCount`](@ref) for information on how the results are ordered. """ struct ObjectiveValue <: AbstractModelAttribute result_index::Int @@ -943,9 +941,7 @@ end A model attribute for the value of the objective function of the dual problem for the `result_index`th dual result. -If multiple results are present, the first result (i.e., `result_index=1`) must -be an optimal solution. Other results may be alternative optimal solutions; use -[`ObjectiveValue`](@ref) to compare their objective values. +See [`ResultCount`](@ref) for information on how the results are ordered. """ struct DualObjectiveValue <: AbstractModelAttribute result_index::Int @@ -1008,6 +1004,29 @@ struct RawSolver <: AbstractModelAttribute end ResultCount() A model attribute for the number of results available. + +## Order of solutions + +A number of attributes contain an index, `result_index`, which is used to refer +to on of the available results. `result_index` must be an integer between `1` +and the number of available results. + +As a general rule, the first result (`result_index=1`) is the most important +result (e.g., an optimal solution or an infeasibility certificate). Other +results will typically be alternate solutions that the solver found during the +search for the first result. + +If a (local) optimal solution is available, i.e., [`TerminationStatus`](@ref) is +`OPTIMAL` or `LOCALLY_SOLVED`, the first result must correspond to the (locally) +optimal solution. Other results may be alternative optimal solutions, or they +may be other suboptimal solutions. Use [`ObjectiveValue`](@ref) to distingiush +between them. + +If a primal or dual infeasibility certificate is available, i.e., +[`TerminationStatus`](@ref) is `INFEASIBLE` or `DUAL_INFEASIBLE` and the +corresponding [`PrimalStatus`](@ref) or [`DualStatus`](@ref) is +`INFEASIBILITY_CERTIFICATE`, then the first result must be a certificate. Other +results may be alternate certificates, or infeasible points. """ struct ResultCount <: AbstractModelAttribute end @@ -1074,9 +1093,7 @@ struct VariablePrimalStart <: AbstractVariableAttribute end A variable attribute for the assignment to some primal variable's value in result `result_index`. If `result_index` is omitted, it is 1 by default. -If multiple results are present, the first result (i.e., `result_index=1`) must -be an optimal solution. Other results may be alternative optimal solutions; use -[`ObjectiveValue`](@ref) to compare their objective values. +See [`ResultCount`](@ref) for information on how the results are ordered. """ struct VariablePrimal <: AbstractVariableAttribute result_index::Int @@ -1204,9 +1221,7 @@ struct ConstraintDualStart <: AbstractConstraintAttribute end A constraint attribute for the assignment to some constraint's primal value(s) in result `result_index`. If `result_index` is omitted, it is 1 by default. -If multiple results are present, the first result (i.e., `result_index=1`) must -be an optimal solution. Other results may be alternative optimal solutions; use -[`ObjectiveValue`](@ref) to compare their objective values. +See [`ResultCount`](@ref) for information on how the results are ordered. ## Example @@ -1229,9 +1244,7 @@ end A constraint attribute for the assignment to some constraint's dual value(s) in result `result_index`. If `result_index` is omitted, it is 1 by default. -If multiple results are present, the first result (i.e., `result_index=1`) must -be an optimal solution. Other results may be alternative optimal solutions; use -[`ObjectiveValue`](@ref) to compare their objective values. +See [`ResultCount`](@ref) for information on how the results are ordered. """ struct ConstraintDual <: AbstractConstraintAttribute result_index::Int @@ -1246,9 +1259,7 @@ A constraint attribute for the `BasisStatusCode` of some constraint in result `result_index`, with respect to an available optimal solution basis. If `result_index` is omitted, it is 1 by default. -If multiple results are present, the first result (i.e., `result_index=1`) must -be an optimal solution. Other results may be alternative optimal solutions; use -[`ObjectiveValue`](@ref) to compare their objective values. +See [`ResultCount`](@ref) for information on how the results are ordered. **For the basis status of a variable, query the corresponding `SingleVariable` constraint that enforces the variable's bounds.** From a8c1e16a9c363a3cda766f9381241618f1643364 Mon Sep 17 00:00:00 2001 From: odow Date: Sat, 29 May 2021 11:22:02 +1200 Subject: [PATCH 3/4] Update docs --- src/attributes.jl | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/attributes.jl b/src/attributes.jl index 3cd6f7975d..7ad5aef6a8 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -1253,7 +1253,6 @@ end """ ConstraintBasisStatus(result_index::Int = 1) - ConstraintBasisStatus() A constraint attribute for the `BasisStatusCode` of some constraint in result `result_index`, with respect to an available optimal solution basis. If @@ -1582,6 +1581,8 @@ The values indicate how to interpret the result vector. A model attribute for the [`ResultStatusCode`](@ref) of the primal result `result_index`. If `result_index` is omitted, it defaults to 1. +See [`ResultCount`](@ref) for information on how the results are ordered. + If `result_index` is larger than the value of [`ResultCount`](@ref) then `NO_SOLUTION` is returned. """ @@ -1596,6 +1597,8 @@ end A model attribute for the `ResultStatusCode` of the dual result `result_index`. If `result_index` is omitted, it defaults to 1. +See [`ResultCount`](@ref) for information on how the results are ordered. + If `result_index` is larger than the value of [`ResultCount`](@ref) then `NO_SOLUTION` is returned. """ From 84da34eea423628b0cfa1ee32570404ba94b6f20 Mon Sep 17 00:00:00 2001 From: Oscar Dowson Date: Sun, 30 May 2021 12:24:47 +1200 Subject: [PATCH 4/4] Update attributes.jl --- src/attributes.jl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index 7ad5aef6a8..f86ad5ffe8 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -1008,8 +1008,8 @@ A model attribute for the number of results available. ## Order of solutions A number of attributes contain an index, `result_index`, which is used to refer -to on of the available results. `result_index` must be an integer between `1` -and the number of available results. +to one of the available results. Thus, `result_index` must be an integer between +`1` and the number of available results. As a general rule, the first result (`result_index=1`) is the most important result (e.g., an optimal solution or an infeasibility certificate). Other @@ -1019,7 +1019,7 @@ search for the first result. If a (local) optimal solution is available, i.e., [`TerminationStatus`](@ref) is `OPTIMAL` or `LOCALLY_SOLVED`, the first result must correspond to the (locally) optimal solution. Other results may be alternative optimal solutions, or they -may be other suboptimal solutions. Use [`ObjectiveValue`](@ref) to distingiush +may be other suboptimal solutions; use [`ObjectiveValue`](@ref) to distingiush between them. If a primal or dual infeasibility certificate is available, i.e.,