Document and Test Dual Sign Convention

doc/OnlineDocs/explanation/experimental/solvers.rst

@@ -357,3 +357,92 @@ implemented. For example, for ``ipopt``:
    :members:
    :show-inheritance:
    :inherited-members:
+
+
+Dual Sign Convention
+--------------------
+For all future solver interfaces, Pyomo adopts the following sign convention. Given the problem
+
+.. math::
+
+   \begin{align}
+   \min & f(x) \\
+   \text{s.t.} \\
+   & c_i(x) = 0 && \forall i \in \mathcal{E} \\
+   & g_i(x) \leq 0 && \forall i \in \mathcal{U} \\
+   & h_i(x) \geq 0 && \forall i \in \mathcal{L}
+   \end{align}
+
+We define the Lagrangian as
+
+.. math::
+
+   \begin{align}
+   L(x, \lambda, \nu, \delta) = f(x) - \sum_{i \in \mathcal{E}} \lambda_i c_i(x) - \sum_{i \in \mathcal{U}} \nu_i g_i(x) - \sum_{i \in \mathcal{L}} \delta_i h_i(x)
+   \end{align}
+
+Then, the KKT conditions are [NW99]_
+
+.. math::
+
+   \begin{align}
+   \nabla_x L(x, \lambda, \nu, \delta) = 0 \\
+   c(x) = 0 \\
+   g(x) \leq 0 \\
+   h(x) \geq 0 \\
+   \nu \leq 0 \\
+   \delta \geq 0 \\
+   \nu_i g_i(x) = 0 \\
+   \delta_i h_i(x) = 0
+   \end{align}
+
+Note that this sign convention is based on the ``(lower, body, upper)``
+representation of constraints rather than the expression provided by a
+user. Users can specify constraints with variables on both the left- and
+right-hand sides of equalities and inequalities. However, the
+``(lower, body, upper)`` representation ensures that all variables
+appear in the ``body``, matching the form of the problem above.
+
+For maximization problems of the form
+
+.. math::
+
+   \begin{align}
+   \max & f(x) \\
+   \text{s.t.} \\
+   & c_i(x) = 0 && \forall i \in \mathcal{E} \\
+   & g_i(x) \leq 0 && \forall i \in \mathcal{U} \\
+   & h_i(x) \geq 0 && \forall i \in \mathcal{L}
+   \end{align}
+
+we define the Lagrangian to be the same as above:
+
+.. math::
+
+   \begin{align}
+   L(x, \lambda, \nu, \delta) = f(x) - \sum_{i \in \mathcal{E}} \lambda_i c_i(x) - \sum_{i \in \mathcal{U}} \nu_i g_i(x) - \sum_{i \in \mathcal{L}} \delta_i h_i(x)
+   \end{align}
+
+As a result, the signs of the duals change. The KKT conditions are 
+
+.. math::
+
+   \begin{align}
+   \nabla_x L(x, \lambda, \nu, \delta) = 0 \\
+   c(x) = 0 \\
+   g(x) \leq 0 \\
+   h(x) \geq 0 \\
+   \nu \geq 0 \\
+   \delta \leq 0 \\
+   \nu_i g_i(x) = 0 \\
+   \delta_i h_i(x) = 0
+   \end{align}
+
+
+Pyomo also supports "range constraints" which are inequalities with both upper and lower bounds, where the bounds are not equal. For example,
+
+.. math::
+
+   -1 \leq x + y \leq 1
+
+These are handled very similarly to variable bounds in terms of dual sign conventions. For these, at most one "side" of the inequality can be active at a time. If neither side is active, then the dual will be zero. If the dual is nonzero, then the dual corresponds to the side of the constraint that is active. The dual for the other side will be implicitly zero. When accessing duals, the keys are the constraints. As a result, there is only one key for a range constraint, even though it is really two constraints. Therefore, the dual for the inactive side will not be reported explicitly. Again, the sign convention is based on the ``(lower, body, upper)`` representation of the constraint. Therefore, the left side of this inequality belongs to :math:`\mathcal{L}` and the right side belongs to :math:`\mathcal{U}`.

doc/OnlineDocs/reference/bibliography.rst

@@ -149,3 +149,6 @@ Bibliography
 .. [VAN10] J. P. Vielma, S. Ahmed, and G. Nemhauser. "Mixed-Integer
    Models for Non-separable Piecewise Linear Optimization: Unifying
    framework and Extensions", *Operations Research* 58(2), 303-315. 2010.
+
+.. [NW99] Nocedal, Jorge, and Stephen J. Wright, eds. Numerical
+   optimization. New York, NY: Springer New York, 1999.