From 84dc94dfeb34aad471c73691d21cb9ef1a59af18 Mon Sep 17 00:00:00 2001 From: odow Date: Fri, 16 Nov 2018 15:37:01 -0600 Subject: [PATCH 1/4] Document status enums. --- src/attributes.jl | 96 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 23 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index f8b3d4b0ce..7099fb1e4b 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -692,34 +692,75 @@ struct TerminationStatus <: AbstractModelAttribute end """ TerminationStatusCode -An Enum of possible values for the `TerminationStatus` attribute. -This attribute is meant to explain the reason why the optimizer stopped executing. +An Enum of possible values for the `TerminationStatus` attribute. This attribute +is meant to explain the reason why the optimizer stopped executing. ## OK These are generally OK statuses. -* `Success`: the algorithm ran successfully and has a result; this includes cases where the algorithm converges to an infeasible point (NLP) or converges to a solution of a homogeneous self-dual problem and has a certificate of primal/dual infeasibility -* `InfeasibleNoResult`: the algorithm stopped because it decided that the problem is infeasible but does not have a result to return -* `UnboundedNoResult`: the algorithm stopped because it decided that the problem is unbounded but does not have a result to return -* `InfeasibleOrUnbounded`: the algorithm stopped because it decided that the problem is infeasible or unbounded (no result is available); this occasionally happens during MIP presolve +* `Success`: the algorithm ran successfully and has a result; this includes + cases where the algorithm converges to an infeasible point (NLP) or converges + to a solution of a homogeneous self-dual problem and has a certificate of + primal/dual infeasibility. +* `InfeasibleNoResult`: the algorithm stopped because it decided that the + problem is infeasible but does not have a result to return. +* `UnboundedNoResult`: the algorithm stopped because it decided that the problem + is unbounded but does not have a result to return. +* `InfeasibleOrUnbounded`: the algorithm stopped because it decided that the + problem is infeasible or unbounded (no result is available); this occasionally + happens during MIP presolve. ## Limits The optimizer stopped because of some user-defined limit. -To be documented: `IterationLimit`, `TimeLimit`, `NodeLimit`, `SolutionLimit`, `MemoryLimit`, `ObjectiveLimit`, `NormLimit`, `OtherLimit`. + +* `IterationLimit`: an iterative algorithm stopped after conducting the maximum + number of iterations. +* `TimeLimit`: the algorithm stopped after a user-specified computation time. +* `NodeLimit`: a branch-and-bound algorithm stopped because it explored a + maximum number of nodes in the branch-and-bound tree. +* `SolutionLimit`: the algorithm stopped because it found the required number of + solutions. This is often used in MIP's to get the solver to return the first + feasible solution it encounters. +* `MemoryLimit`: the algorithm stopped because it ran out of memory. +* `ObjectiveLimit`: the algorthm stopped because it found a solution better than + a minimum limit set by the user. +* `NormLimit`: the algorithm stopped because of a criteria involving a norm. + This is typically used to terminate an algorithm once successive iterations + result in a solution that is within some distance of the previous solution. +* `OtherLimit`: the algorithm stopped due to a limit not covered by one of the + above. ## Problematic This group of statuses means that something unexpected or problematic happened. -* `SlowProgress`: the algorithm stopped because it was unable to continue making progress towards the solution -* `AlmostSuccess` should be used if there is additional information that relaxed convergence tolerances are satisfied - -To be documented: `NumericalError`, `InvalidModel`, `InvalidOption`, `Interrupted`, `OtherError`. - -""" -@enum TerminationStatusCode Success AlmostSuccess InfeasibleNoResult UnboundedNoResult InfeasibleOrUnbounded IterationLimit TimeLimit NodeLimit SolutionLimit MemoryLimit ObjectiveLimit NormLimit OtherLimit SlowProgress NumericalError InvalidModel InvalidOption Interrupted OtherError +* `SlowProgress`: the algorithm stopped because it was unable to continue making + progress towards the solution. +* `AlmostSuccess` should be used if there is additional information that relaxed + convergence tolerances are satisfied +* `NumericalError`: the algorithm stopped because it encountered unrecoverable + numerical error. +* `InvalidModel`: the algorithm stopped because the model is invalid. +* `InvalidOption`: the algorithm stopped because it was provided an invalid + option. +* `Interrupted`: the algorithm stopped because of an interrupt signal. +* `OtherError`: the algorithm stopped because of an error not covered by one of + the statuses defined above. + +""" +@enum(TerminationStatusCode, + # OK + Success, AlmostSuccess, InfeasibleNoResult, UnboundedNoResult, + InfeasibleOrUnbounded, + # Limits + IterationLimit, TimeLimit, NodeLimit, SolutionLimit, MemoryLimit, + ObjectiveLimit, NormLimit, OtherLimit, + # Problematic + SlowProgress, NumericalError, InvalidModel, InvalidOption, Interrupted, + OtherError +) ## Result status @@ -729,18 +770,27 @@ To be documented: `NumericalError`, `InvalidModel`, `InvalidOption`, `Interrupte An Enum of possible values for the `PrimalStatus` and `DualStatus` attributes. The values indicate how to interpret the result vector. -* `NoSolution` -* `FeasiblePoint` -* `NearlyFeasiblePoint` -* `InfeasiblePoint` -* `InfeasibilityCertificate` +* `NoSolution`: the result vector is empty. +* `FeasiblePoint`: the result vector is a feasible point. +* `NearlyFeasiblePoint`: the result vector is feasible if some constraint + tolerances are relaxed. +* `InfeasiblePoint`: the result vector is an infeasible point. +* `InfeasibilityCertificate`: the result vector is an infeasibility certificate. + Given a dual feasible solution, an infeasibility certificate in the primal + implies that the dual is unbounded, given a primal feasible solution, an + infeasibility certificate in the dual implies that the primal is unbounded. * `NearlyInfeasibilityCertificate` * `ReductionCertificate` * `NearlyReductionCertificate` -* `UnknownResultStatus` -* `OtherResultStatus` -""" -@enum ResultStatusCode NoSolution FeasiblePoint NearlyFeasiblePoint InfeasiblePoint InfeasibilityCertificate NearlyInfeasibilityCertificate ReductionCertificate NearlyReductionCertificate UnknownResultStatus OtherResultStatus +* `UnknownResultStatus`: the result vector contains a solution with an unknown + interpretation. +* `OtherResultStatus`: the result vector contains a solution with an + interpretation not covered by one of the statuses defined above. +""" +@enum(ResultStatusCode, NoSolution, FeasiblePoint, NearlyFeasiblePoint, + InfeasiblePoint, InfeasibilityCertificate, NearlyInfeasibilityCertificate, + ReductionCertificate, NearlyReductionCertificate, UnknownResultStatus, + OtherResultStatus) """ PrimalStatus(N) From 68a3af99c8bb0444cdcb8acb4be60026b9999b1a Mon Sep 17 00:00:00 2001 From: odow Date: Fri, 16 Nov 2018 20:39:27 -0600 Subject: [PATCH 2/4] Address comments. --- src/attributes.jl | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index 7099fb1e4b..6f4ff7260e 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -697,19 +697,19 @@ is meant to explain the reason why the optimizer stopped executing. ## OK -These are generally OK statuses. +These are generally OK statuses, i.e., the algorithm ran to completion normally. * `Success`: the algorithm ran successfully and has a result; this includes cases where the algorithm converges to an infeasible point (NLP) or converges to a solution of a homogeneous self-dual problem and has a certificate of primal/dual infeasibility. * `InfeasibleNoResult`: the algorithm stopped because it decided that the - problem is infeasible but does not have a result to return. + problem is infeasible but does not have a primal or dual result to return. * `UnboundedNoResult`: the algorithm stopped because it decided that the problem - is unbounded but does not have a result to return. + is unbounded but does not have a primal or dual result to return. * `InfeasibleOrUnbounded`: the algorithm stopped because it decided that the - problem is infeasible or unbounded (no result is available); this occasionally - happens during MIP presolve. + problem is infeasible or unbounded (no primal or dual result is available); + this occasionally happens during MIP presolve. ## Limits @@ -721,14 +721,14 @@ The optimizer stopped because of some user-defined limit. * `NodeLimit`: a branch-and-bound algorithm stopped because it explored a maximum number of nodes in the branch-and-bound tree. * `SolutionLimit`: the algorithm stopped because it found the required number of - solutions. This is often used in MIP's to get the solver to return the first + solutions. This is often used in MIPs to get the solver to return the first feasible solution it encounters. * `MemoryLimit`: the algorithm stopped because it ran out of memory. * `ObjectiveLimit`: the algorthm stopped because it found a solution better than a minimum limit set by the user. * `NormLimit`: the algorithm stopped because of a criteria involving a norm. - This is typically used to terminate an algorithm once successive iterations - result in a solution that is within some distance of the previous solution. + This is typically used to indicate that an algorithm stopped after + encountering a sequence of diverging iterations. * `OtherLimit`: the algorithm stopped due to a limit not covered by one of the above. @@ -779,9 +779,8 @@ The values indicate how to interpret the result vector. Given a dual feasible solution, an infeasibility certificate in the primal implies that the dual is unbounded, given a primal feasible solution, an infeasibility certificate in the dual implies that the primal is unbounded. -* `NearlyInfeasibilityCertificate` -* `ReductionCertificate` -* `NearlyReductionCertificate` +* `NearlyInfeasibilityCertificate`: the result satisfies a relaxed criterion for + a certificate of infeasibility. * `UnknownResultStatus`: the result vector contains a solution with an unknown interpretation. * `OtherResultStatus`: the result vector contains a solution with an From 52aa2ea09fa141d9e41b7b752853e9d6a113549b Mon Sep 17 00:00:00 2001 From: odow Date: Fri, 16 Nov 2018 20:47:25 -0600 Subject: [PATCH 3/4] Address comments - II --- src/attributes.jl | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index 6f4ff7260e..46acdbf0bd 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -726,9 +726,8 @@ The optimizer stopped because of some user-defined limit. * `MemoryLimit`: the algorithm stopped because it ran out of memory. * `ObjectiveLimit`: the algorthm stopped because it found a solution better than a minimum limit set by the user. -* `NormLimit`: the algorithm stopped because of a criteria involving a norm. - This is typically used to indicate that an algorithm stopped after - encountering a sequence of diverging iterations. +* `NormLimit`: the algorithm stopped because the norm of an iterate became too + large. * `OtherLimit`: the algorithm stopped due to a limit not covered by one of the above. @@ -788,8 +787,7 @@ The values indicate how to interpret the result vector. """ @enum(ResultStatusCode, NoSolution, FeasiblePoint, NearlyFeasiblePoint, InfeasiblePoint, InfeasibilityCertificate, NearlyInfeasibilityCertificate, - ReductionCertificate, NearlyReductionCertificate, UnknownResultStatus, - OtherResultStatus) + UnknownResultStatus, OtherResultStatus) """ PrimalStatus(N) From b55ccd3c3623e01e7373b0c33b98fed89c25a28b Mon Sep 17 00:00:00 2001 From: Oscar Dowson Date: Sat, 17 Nov 2018 11:31:09 -0600 Subject: [PATCH 4/4] Update attributes.jl --- src/attributes.jl | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/attributes.jl b/src/attributes.jl index 46acdbf0bd..33e00b1126 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -775,9 +775,10 @@ The values indicate how to interpret the result vector. tolerances are relaxed. * `InfeasiblePoint`: the result vector is an infeasible point. * `InfeasibilityCertificate`: the result vector is an infeasibility certificate. - Given a dual feasible solution, an infeasibility certificate in the primal - implies that the dual is unbounded, given a primal feasible solution, an - infeasibility certificate in the dual implies that the primal is unbounded. + If the `PrimalStatus` is `InfeasibilityCertificate`, then the primal result + vector is a certificate of dual infeasibility. If the `DualStatus` is + `InfeasibilityCertificate`, then the dual result vector is a proof of primal + infeasibility. * `NearlyInfeasibilityCertificate`: the result satisfies a relaxed criterion for a certificate of infeasibility. * `UnknownResultStatus`: the result vector contains a solution with an unknown