From b6067fc757380b5907ce5e41be73a7f59824c058 Mon Sep 17 00:00:00 2001
From: Gleb Belov <gleb@ampl.com>
Date: Tue, 5 Sep 2023 13:56:58 +1000
Subject: [PATCH] Solution check docu #200

---
 doc/rst/model-guide.rst          |   1 +
 doc/rst/modeling-expressions.rst |   2 +-
 doc/rst/solution-check.rst       | 120 +++++++++++++++++++++++++++++++
 3 files changed, 122 insertions(+), 1 deletion(-)
 create mode 100644 doc/rst/solution-check.rst

diff --git a/doc/rst/model-guide.rst b/doc/rst/model-guide.rst
index 36f1ea210..ab9c75e27 100644
--- a/doc/rst/model-guide.rst
+++ b/doc/rst/model-guide.rst
@@ -26,4 +26,5 @@ while below follows a comprehensive guide.
    modeling-expressions
    modeling-efficiency
    modeling-numerics
+   solution-check
 
diff --git a/doc/rst/modeling-expressions.rst b/doc/rst/modeling-expressions.rst
index e70d415bd..d8ba0f696 100644
--- a/doc/rst/modeling-expressions.rst
+++ b/doc/rst/modeling-expressions.rst
@@ -495,7 +495,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
+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/solution-check.rst b/doc/rst/solution-check.rst
new file mode 100644
index 000000000..7ed933bf0
--- /dev/null
+++ b/doc/rst/solution-check.rst
@@ -0,0 +1,120 @@
+.. _solution-check:
+
+
+Solution check
+---------------------
+
+Solutions obtained from the solver are automatically checked
+for correctness with given tolerances
+(see driver options ``sol:chk:...``.)
+
+
+"Realistic" solution check
+******************************
+
+In this mode, variable values are taken as they were reported by the solver
+(with possible modifications using AMPL's options
+``solution_round`` and ``solution_precision``, see driver options
+``sol:chk:no...``.). This check is enough for most practical situations.
+
+.. code-block:: ampl
+
+		------------ WARNINGS ------------
+		WARNING:  "Solution Check"
+				 [ sol:chk:feastol=1e-06, sol:chk:inttol=1e-05,
+				 solution_round='', solution_precision='' ]
+		Algebraic expression violations:
+			- 1 original expression(s) of type ':quadrange',
+					up to 1E+00 (item 'socp[13]')
+
+
+"Idealistic" solution check
+******************************
+
+In this mode, expressions are recomputed. Consider the following example.
+
+.. code-block:: ampl
+
+		var x >=0, <=100;
+		maximize Total: if x<=5 and x>=5.00000000001 then 10;
+
+Most solvers apply a constraint feasibility tolerance of the order :math:`10^{-6}`.
+
+.. code-block:: ampl
+
+		ampl: option solver gurobi;
+		ampl: solve;
+		Gurobi 10.0.2: optimal solution; objective 10
+		0 simplex iterations
+
+		------------ WARNINGS ------------
+		WARNING:  "Solution Check (Idealistic)"
+				 [ sol:chk:feastol=1e-06, sol:chk:inttol=1e-05,
+				 solution_round='', solution_precision='' ]
+		Objective value violations:
+			- 1 objective value(s) violated,
+					up to 1E+01
+
+		ampl: display x;
+		x = 5
+
+We see that ``x=5`` satisfies the ``if`` with that tolerance.
+Thus, our realistic check passes, but the idealistic check complains.
+Indeed, if we ask AMPL to recompute the objective value:
+
+.. code-block:: ampl
+
+		ampl: display Total;
+		Total = 0
+
+we see that AMPL does it "idealistically"
+(it does not know about solver tolerances.)
+
+To see which expressions cause the violation,
+use driver option ``chk:mode``:
+
+.. code-block:: ampl
+
+		ampl: option gurobi_options 'chk:mode=1023';
+		ampl: solve;
+		Gurobi 10.0.2:   sol:chk:mode = 1023
+		Gurobi 10.0.2: optimal solution; objective 10
+		0 simplex iterations
+
+		------------ WARNINGS ------------
+		WARNING:  "Solution Check (Idealistic)"
+				 [ sol:chk:feastol=1e-06, sol:chk:inttol=1e-05,
+				 solution_round='', solution_precision='' ]
+		Algebraic expression violations:
+			- 1 original expression(s) of type ':ifthen',
+					up to 1E+01
+		Logical expression violations:
+			- 1 original expression(s) of type ':and'
+		Objective value violations:
+			- 1 objective value(s) violated,
+					up to 1E+01
+
+*Hint*: to display AMPL model names,
+set ``option (solver_)auxfiles rc;`` as follows:
+
+.. code-block:: ampl
+
+		ampl: option gurobi_auxfiles rc;
+		ampl: solve;
+		Gurobi 10.0.2:   sol:chk:mode = 1023
+		Gurobi 10.0.2: optimal solution; objective 10
+		0 simplex iterations
+
+		------------ WARNINGS ------------
+		WARNING:  "Solution Check (Idealistic)"
+				 [ sol:chk:feastol=1e-06, sol:chk:inttol=1e-05,
+				 solution_round='', solution_precision='' ]
+		Algebraic expression violations:
+			- 1 original expression(s) of type ':ifthen',
+					up to 1E+01 (item 'Total_11_')
+		Logical expression violations:
+			- 1 original expression(s) of type ':and'
+					(item 'Total_7_')
+		Objective value violations:
+			- 1 objective value(s) violated,
+					up to 1E+01 (item 'Total')