Document checking the duality gap

Author: stephane-caron

doc/2-PROXQP_API/2-ProxQP_api.md

@@ -63,6 +63,20 @@ $$\begin{equation}\label{eq:approx_qp_sol_relative_criterion}
 \end{aligned}
 \end{equation}$$
 
+This stopping criterion on primal and dual residuals is not enough to guarantee that the returned solution satisfies all \eqref{qp:kkt} conditions. If the problem is *strictly* convex, that is, if it's Hessian $H$ is positive definite, then strong duality holds and to satisfy all optimality conditions we need to add a third criterion on the *duality gap* $r_g$:
+
+$$\begin{equation}\label{eq:approx_qp_sol}
+\begin{aligned}
+    &\left\{
+    \begin{array}{ll}
+        r_g := | x^T H x + g^T x + b^T y + u^T z^+ + l^T z^- | \leq \epsilon_{\text{abs}} + \epsilon_{\text{rel}} \max(\|x^T H x\|, \|g^T x\|, \|b^T y\|, \|u^T z^+\|, \|l^T z^-\|) \\
+    \end{array}
+    \right.
+\end{aligned}
+\end{equation}$$
+
+ProxQP provides the ``check_duality_gap`` option to include this duality gap in the stopping criterion. Note that it is disabled by default, as ProxQP is also designed to work with problems that are not strictly convex where strong duality doesn't hold; that is, where the duality gap can be non-zero at an optimal solution. Enable this option if you know that your problem is strictly convex and want a strong guarantee that the returned solution is optimal. ProxQP will then check the same termination condition as SCS (for more details see, e.g., SCS's [optimality conditions checks](https://www.cvxgrp.org/scs/algorithm/index.html#optimality-conditions) as well as [section 7.2](https://doi.org/10.1137/20M1366307) in the corresponding paper).
+
 \section OverviewAPIstructure ProxQP unified API for dense and sparse backends
 
 ProxQP algorithm is implemented in two versions specialized for dense and sparse matrices. One simple and unified API has been designed for loading the dense and sparse backends. Concretely, it contains three methods: