diff --git a/src/attributes.jl b/src/attributes.jl index f8b3d4b0ce..33e00b1126 100644 --- a/src/attributes.jl +++ b/src/attributes.jl @@ -692,34 +692,74 @@ 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. +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 -* `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 primal or dual result to return. +* `UnboundedNoResult`: the algorithm stopped because it decided that the problem + 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 primal or dual 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 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 the norm of an iterate became too + large. +* `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 +769,26 @@ 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` -* `NearlyInfeasibilityCertificate` -* `ReductionCertificate` -* `NearlyReductionCertificate` -* `UnknownResultStatus` -* `OtherResultStatus` -""" -@enum ResultStatusCode NoSolution FeasiblePoint NearlyFeasiblePoint InfeasiblePoint InfeasibilityCertificate NearlyInfeasibilityCertificate ReductionCertificate NearlyReductionCertificate UnknownResultStatus OtherResultStatus +* `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. + 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 + 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, + UnknownResultStatus, OtherResultStatus) """ PrimalStatus(N)