diff --git a/doc/rst/features-guide.rst b/doc/rst/features-guide.rst index 3c120fac7..d0b7aa073 100644 --- a/doc/rst/features-guide.rst +++ b/doc/rst/features-guide.rst @@ -20,7 +20,8 @@ Solver options ================= Solver options are key-value pairs controlling a solver's behavior. -Many of them are standardized across AMPL solvers. +Many of them are standardized across AMPL solvers +(for solver's native options see :ref:`further `.) List all available options diff --git a/doc/rst/modeling-expressions.rst b/doc/rst/modeling-expressions.rst index d8ba0f696..0e748e3c5 100644 --- a/doc/rst/modeling-expressions.rst +++ b/doc/rst/modeling-expressions.rst @@ -62,7 +62,8 @@ use of a small tolerance. For example, if x is minimized subject to x > 5, then x value greater than 5 is not minimal, and any x value less than or equal to 5 is not feasible. Thus, to insure that a minimum is well defined, the constraint must be changed to x >= 5 + eps for some small constant eps. Each solver has its own -default value of the eps constant, which can be adjusted through an option setting. +default value of the eps constant, which can be adjusted through +an :ref:`option setting `. Conditional operators @@ -495,7 +496,7 @@ MP library provides additional conversion into solver-specific conic forms. Exam *Note:* Mosek cannot mix SOCP and general quadratic constraints. -Option ``cvt:socp=0`` results in second-order conic +:ref:`Option ` ``cvt:socp=0`` results in second-order conic constraints being passed to the solver as quadratics, even if the solver has native SOCP API. diff --git a/doc/rst/modeling-numerics.rst b/doc/rst/modeling-numerics.rst index ef922faea..395873177 100644 --- a/doc/rst/modeling-numerics.rst +++ b/doc/rst/modeling-numerics.rst @@ -6,6 +6,9 @@ Numerical accuracy Mathematical Programming solvers typically work with finite-precision numbers, which leads to concerns on numerical stability. +While general numerical stability is a well-established topic, below +we highlight some common points for non-smooth models. + Importance of tight bounds: "big-M" constraints ************************************************** @@ -30,7 +33,7 @@ with the big-M constant taken as the upper bound on :math:`x`. Thus, big-M constraints require finite bounds on participating variables. They should be as tight as possible, ideally between :math:`\pm10^4`. In any case, for numerical stability these bounds should -not exceed the reciprocal of the integrality tolerance (option *inttol*). A default +not exceed the reciprocal of the integrality tolerance (:ref:`option ` *inttol*). A default big-M value can be set with the option *cvt:bigM* (use with caution). In some cases, a different formulation can help automatic detection diff --git a/doc/rst/solution-check.rst b/doc/rst/solution-check.rst index e6eb771c7..3e5355e51 100644 --- a/doc/rst/solution-check.rst +++ b/doc/rst/solution-check.rst @@ -8,6 +8,15 @@ Solutions obtained from the solver are automatically checked for correctness with given tolerances (see :ref:`solver-options` ``sol:chk:...``.) +There are two checking modes: "realistic" and "idealistic". +For linear and quadratic models they are equivalent. +Differences can arise for models with other non-linear expressions. + +In "realistic" mode, any expressions computed by the solver +and reported via an auxiliary variable, are trusted with +a tolerance. In "idealistic" mode, all expression trees +are recomputed. + "Realistic" solution check ****************************** @@ -27,6 +36,10 @@ In this mode, variable values are taken as they were reported by the solver - 1 original expression(s) of type ':quadrange', up to 1E+00 (item 'socp[13]') +In this example, realistic check reports a constraint violation +of 1, which can mean a significant violation if the constraint's +right-hand side is of moderate magnitude. + "Idealistic" solution check ****************************** @@ -127,3 +140,17 @@ set ``option (solver_)auxfiles rc;`` as follows: Objective value violations: - 1 objective value(s) violated, up to 1E+01 (item 'Total') + + +Remedies +********************* + +For "realistic" solution violations, the reason is most probably +:ref:`numerical_accuracy`. + +For "idealistic" warnings, to make sure AMPL can access the true +objective value, see a +`Colab example `_ +detailing +a more common case and a remedy consisting of an explicit +variable for the objective value. diff --git a/test/end2end/cases/categorized/fast/logical/ifthen_var.mod b/test/end2end/cases/categorized/fast/logical/ifthen_var.mod index e8857ee86..d1b69dcb0 100644 --- a/test/end2end/cases/categorized/fast/logical/ifthen_var.mod +++ b/test/end2end/cases/categorized/fast/logical/ifthen_var.mod @@ -1,14 +1,15 @@ -/** + /** * Test expression map as well as if-then. - * Requires cvt:cmp:eps > feastol - * for AMPL to correctly compute obj value, see #102. + * Test solution check and cap:eps. + * Used in a Colab notebook on solution check. */ -var x >=-100, <= 200; -var y >=-300, <= 460; - +var x >=0, <= 1; +var y >=0, <= 1; var b: binary; -subj to ConImpl: b ==> 2*x + 3*y <= 5; +s.t. ConImpl: + b ==> 2*x + 3*y <= 5; -minimize TotalIf: if 2*x+3*y<=5 then b else -b-5; +minimize TotalIf: + if 2*x+3*y>5 then 2*x+3*y-3*b-25 else 2*x+3*y-3*b; \ No newline at end of file diff --git a/test/end2end/cases/categorized/fast/logical/modellist.json b/test/end2end/cases/categorized/fast/logical/modellist.json index 700f2df79..79b1cd700 100644 --- a/test/end2end/cases/categorized/fast/logical/modellist.json +++ b/test/end2end/cases/categorized/fast/logical/modellist.json @@ -14,16 +14,41 @@ }, { "name" : "ifthen_var", - "objective" : -5, + "objective" : -3, "tags" : ["logical"], "options": { "ANYSOLVER_options": "cvt:cmp:eps=1e-4" }, + "valies": { + "2*x+3*y": 0 + }, "comment": [ "For AMPL to correctly compute obj value, ", - "need strict inequality for the opposite case" + "need strict inequality", + "obeyed in the reformulation with a significant tolerance" ] }, + { + "name" : "ifthen_var", + "objective" : 2, + "tags" : ["logical"], + "options": { + "ANYSOLVER_options": "cvt:cmp:eps=0" + }, + "valies": { + "2*x+3*y": 5 + } + }, + { + "name" : "ifthen_var", + "tags" : ["logical"], + "options": { + "ANYSOLVER_options": "cvt:cmp:eps=0 chk:fail" + }, + "values": { + "solve_result_num": 520 + } + }, { "name" : "test_int_non_int", "objective" : 0,