Merge pull request #374 from stephane-caron/fix/qplayer_docs

Expose QPFunction in the documentation

Author: ManifoldFR

bindings/python/proxsuite/torch/qplayer.py

@@ -18,73 +18,72 @@ def QPFunction(
     omp_parallel=False,
     structural_feasibility=True,
 ):
-    """
+    """!
     Solve a batch of Quadratic Programming (QP) problems.
 
     This function solves QP problems of the form:
-        min 0.5*z'*Q*z + p'*z
-        s.t. l <= G*z <= h
-             A*z = b
+
+    $$
+    \begin{align}
+    \min_{z} &  ~\frac{1}{2}z^{T} Q (\theta) z +p(\theta)^{T}z \\\
+    \text{s.t.} & ~A(\theta) z = b(\theta) \\\
+    & ~l(\theta) \leq G(\theta) z \leq u(\theta)
+    \end{align}
+    $$
 
     The QP can be infeasible - in this case the solver will return a solution to
     the closest feasible QP.
 
-    Args:
-        eps (float, optional): Tolerance for the primal infeasibility. Defaults to 1e-9.
-        maxIter (int, optional): Maximum number of iterations. Defaults to 1000.
-        eps_backward (float, optional): Tolerance for the backward pass. Defaults to 1e-4.
-        rho_backward (float, optional): The new value for the primal proximal parameter. Defaults to 1e-6.
-        mu_backward (float, optional): The new dual proximal parameter used for both equality and inequality. Defaults to 1e-6.
-        omp_parallel (bool, optional): Whether to solve the QP in parallel. Requires that proxsuite is compiled with openmp support. Defaults to False.
-        structural_feasibility (bool, optional): Whether to solve the QP with structural feasibility. Defaults to True.
-
-    Returns:
-        QPFunctionFn or QPFunctionFn_infeas: A callable object that represents the QP problem solver.
+    \param[in] eps Tolerance for the primal infeasibility. Defaults to 1e-9.
+    \param[in] maxIter Maximum number of iterations. Defaults to 1000.
+    \param[in] eps_backward Tolerance for the backward pass. Defaults to 1e-4.
+    \param[in] rho_backward The new value for the primal proximal parameter. Defaults to 1e-6.
+    \param[in] mu_backward The new dual proximal parameter used for both equality and inequality. Defaults to 1e-6.
+    \param[in] omp_parallel Whether to solve the QP in parallel. Requires that proxsuite is compiled with openmp support. Defaults to False.
+    \param[in] structural_feasibility Whether to solve the QP with structural feasibility. Defaults to True.
+
+    \returns QPFunctionFn or QPFunctionFn_infeas: A callable object that represents the QP problem solver.
         We disinguish two cases:
             1. The QP is feasible. In this case, we solve the QP problem.
             2. The QP is infeasible. In this case, we solve the closest feasible QP problem.
 
     The callable object has two main methods:
 
-    Forward:
-        Solve the QP problem.
-
-        Args:
-            Q (torch.Tensor): Batch of quadratic cost matrices of size (nBatch, n, n) or (n, n).
-            p (torch.Tensor): Batch of linear cost vectors of size (nBatch, n) or (n).
-            A (torch.Tensor, optional): Batch of eq. constraint matrices of size (nBatch, p, n) or (p, n).
-            b (torch.Tensor, optional): Batch of eq. constraint vectors of size (nBatch, p) or (p).
-            G (torch.Tensor): Batch of ineq. constraint matrices of size (nBatch, m, n) or (m, n).
-            l (torch.Tensor): Batch of ineq. lower bound vectors of size (nBatch, m) or (m).
-            u (torch.Tensor): Batch of ineq. upper bound vectors of size (nBatch, m) or (m).
-
-        Returns:
-            zhats (torch.Tensor): Batch of optimal primal solutions of size (nBatch, n).
-            lams (torch.Tensor): Batch of dual variables for eq. constraint of size (nBatch, m).
-            nus (torch.Tensor): Batch of dual variables  for ineq. constraints of size (nBatch, p).
-            Only for infeasible case:
-                s_e (torch.Tensor): Batch of slack variables for eq. constraints of size (nBatch, m).
-                s_i (torch.Tensor): Batch of slack variables for ineq. constraints of size (nBatch, p).
-
-    Backward:
-        Compute the gradients of the QP problem wrt its parameters.
-
-        Args:
-            dl_dzhat (torch.Tensor): Batch of gradients of size (nBatch, n).
-            dl_dlams (torch.Tensor, optional): Batch of gradients of size (nBatch, p).
-            dl_dnus (torch.Tensor, optional): Batch of gradients of size (nBatch, m).
-            Only for infeasible case:
-                dl_ds_e (torch.Tensor, optional): Batch of gradients of size (nBatch, m).
-                dl_ds_i (torch.Tensor, optional): Batch of gradients of size (nBatch, m).
-
-        Returns:
-            dQs (torch.Tensor): Batch of gradients of size (nBatch, n, n).
-            dps (torch.Tensor): Batch of gradients of size (nBatch, n).
-            dAs (torch.Tensor): Batch of gradients of size (nBatch, p, n).
-            dbs (torch.Tensor): Batch of gradients of size (nBatch, p).
-            dGs (torch.Tensor): Batch of gradients of size (nBatch, m, n).
-            dls (torch.Tensor): Batch of gradients of size (nBatch, m).
-            dus (torch.Tensor): Batch of gradients of size (nBatch, m).
+    \section qpfunction-forward Forward method
+
+    Solve the QP problem.
+
+    \param[in] Q Batch of quadratic cost matrices of size (nBatch, n, n) or (n, n).
+    \param[in] p Batch of linear cost vectors of size (nBatch, n) or (n).
+    \param[in] A Optional batch of eq. constraint matrices of size (nBatch, p, n) or (p, n).
+    \param[in] b Optional batch of eq. constraint vectors of size (nBatch, p) or (p).
+    \param[in] G Batch of ineq. constraint matrices of size (nBatch, m, n) or (m, n).
+    \param[in] l Batch of ineq. lower bound vectors of size (nBatch, m) or (m).
+    \param[in] u Batch of ineq. upper bound vectors of size (nBatch, m) or (m).
+
+    \returns \p zhats Batch of optimal primal solutions of size (nBatch, n).
+    \returns \p lams Batch of dual variables for eq. constraint of size (nBatch, m).
+    \returns \p nus Batch of dual variables  for ineq. constraints of size (nBatch, p).
+    \returns \p s_e Only returned in the infeasible case: batch of slack variables for eq. constraints of size (nBatch, m).
+    \returns \p s_i Only returned in the infeasible case: batch of slack variables for ineq. constraints of size (nBatch, p).
+
+    \section qpfunction-backward Backward method
+
+    Compute the gradients of the QP problem with respect to its parameters.
+
+    \param[in] dl_dzhat Batch of gradients of size (nBatch, n).
+    \param[in] dl_dlams Optional batch of gradients of size (nBatch, p).
+    \param[in] dl_dnus Optional batch of gradients of size (nBatch, m).
+    \param[in] dl_ds_e Only applicable in the infeasible case: optional batch of gradients of size (nBatch, m).
+    \param[in] dl_ds_i Only applicable in the infeasible case: optional batch of gradients of size (nBatch, m).
+
+    \returns \p dQs Batch of gradients of size (nBatch, n, n).
+    \returns \p dps Batch of gradients of size (nBatch, n).
+    \returns \p dAs Batch of gradients of size (nBatch, p, n).
+    \returns \p dbs Batch of gradients of size (nBatch, p).
+    \returns \p dGs Batch of gradients of size (nBatch, m, n).
+    \returns \p dls Batch of gradients of size (nBatch, m).
+    \returns \p dus Batch of gradients of size (nBatch, m).
     """
     global proxqp_parallel
     proxqp_parallel = omp_parallel

doc/4-qplayer.md

@@ -4,15 +4,17 @@
 
 $$
 \begin{align}
-\min_{x} &  ~\frac{1}{2}x^{T}H(\theta)x+g(\theta)^{T}x \\
-\text{s.t.} & ~A(\theta) x = b(\theta) \\
+\min_{x} &  ~\frac{1}{2}x^{T}H(\theta)x+g(\theta)^{T}x \\\
+\text{s.t.} & ~A(\theta) x = b(\theta) \\\
 & ~l(\theta) \leq C(\theta) x \leq u(\theta)
 \end{align}
 $$
 
 where \f$x \in \mathbb{R}^n\f$ is the optimization variable. The objective function is defined by a positive semidefinite matrix \f$H(\theta) \in \mathcal{S}^n_+\f$ and a vector \f$g(\theta) \in \mathbb{R}^n\f$. The linear constraints are defined by the equality-contraint matrix \f$A(\theta) \in \mathbb{R}^{n_\text{eq} \times n}\f$ and the inequality-constraint matrix \f$C(\theta) \in \mathbb{R}^{n_\text{in} \times n}\f$ and the vectors \f$b \in \mathbb{R}^{n_\text{eq}}\f$, \f$l(\theta) \in \mathbb{R}^{n_\text{in}}\f$ and \f$u(\theta) \in \mathbb{R}^{n_\text{in}}\f$ so that \f$b_i \in \mathbb{R},~ \forall i = 1,...,n_\text{eq}\f$ and \f$l_i \in \mathbb{R} \cup \{ -\infty \}\f$ and \f$u_i \in \mathbb{R} \cup \{ +\infty \}, ~\forall i = 1,...,n_\text{in}\f$.
 
-We provide in the file qplayer_sudoku.py an example which enables training LP layer in two different settings: (i) either we learn only the equality constraint matrix \f$A\f$, or (ii) we learn on the same time \f$A\f$ and \f$b\f$, such that \f$b\f$ is structurally in the range space of \f$A\f$. The procedure (i) is harder since a priori the fixed right hand side does not ensure the QP to be feasible. Yet, this learning procedure is more structured, and for some problem can produce better prediction quicker (i.e., in fewer epochs).
+We provide in the file `qplayer_sudoku.py` an example which enables training LP layer in two different settings: (i) either we learn only the equality constraint matrix \f$A\f$, or (ii) we learn on the same time \f$A\f$ and \f$b\f$, such that \f$b\f$ is structurally in the range space of \f$A\f$. The procedure (i) is harder since a priori the fixed right hand side does not ensure the QP to be feasible. Yet, this learning procedure is more structured, and for some problem can produce better prediction quicker (i.e., in fewer epochs).
+
+The differentiable QP layer is implemented in \ref proxsuite.torch.qplayer.QPFunction.
 
 \section QPLayerCite How to cite QPLayer ?
 
@@ -32,4 +34,4 @@ If you are using QPLayer for your work, we encourage you to cite the related pap
 }
 \endcode
 
-The paper is publicly available in HAL ([ref 04133055](https://inria.hal.science/hal-04133055/file/QPLayer_Preprint.pdf)).
+The paper is publicly available in HAL ([ref 04133055](https://inria.hal.science/hal-04133055/file/QPLayer_Preprint.pdf)).

doc/Doxyfile.extra.in

@@ -1,5 +1,6 @@
 INPUT                   = @PROJECT_SOURCE_DIR@/doc \
                           @PROJECT_SOURCE_DIR@/include \
+                          @PROJECT_SOURCE_DIR@/bindings/python/proxsuite \
 
 RECURSIVE               = YES