add examples on how initializing QP model in the documentation

Author: Antoine Bambade

doc/2-PROXQP_API/2-ProxQP_api.md

@@ -97,7 +97,7 @@ For loading ProxQP with dense backend it is as simple as the following code belo
   </tr>
 </table>
 
-The dimensions of the problem (i.e., n is the dimension of primal variable x, n_eq the number of equality constraints, and n_in the number of inequality constraints) are used for allocating the space needed for the Qp object. The dense Qp object is templated by the floatting precision of the QP model (in the example above in C++ a double precision).
+The dimensions of the problem (i.e., n is the dimension of primal variable x, n_eq the number of equality constraints, and n_in the number of inequality constraints) are used for allocating the space needed for the Qp object. The dense Qp object is templated by the floatting precision of the QP model (in the example above in C++ a double precision). Note that for model to be valid, the primal dimension (i.e., n) must be strictly positive. If it is not the case an assertion will be raised precising this issue.
 
 For loading ProxQP with sparse backend they are two possibilities:
 * one can use as before the dimensions of the QP problem (i.e., n, n_eq and n_in)
@@ -139,7 +139,22 @@ Once you have defined a Qp object, the init method enables you setting up the QP
   </tr>
 </table>
 
-Note that with its dense backend, ProxQP solver can manipulate both matrices in dense and sparse representations (in the example above the matrices are in sparse format).
+Note that with its dense backend, ProxQP solver can manipulate both matrices in dense and sparse representations (in the example above the matrices are in sparse format). Note that if some elements of your QP model are not defined (for example a QP without linear cost or inequality constraints), you can either pass a None argument, or a matrix with zero shape for specifying it. We provide an example below in cpp and python (for the dense case, it is similar with sparse backend).
+
+<table class="manual">
+  <tr>
+    <th>examples/cpp/initializing_with_none.cpp</th>
+    <th>examples/python/initializing_with_none.py</th>
+  </tr>
+  <tr>
+    <td valign="top">
+      \include initializing_with_none.cpp
+    </td>
+    <td valign="top">
+      \include initializing_with_none.py
+    </td>
+  </tr>
+</table>
 
 With the init method, you can also setting-up on the same time some other parameters in the following order:
 * compute_preconditioner: a boolean parameter for executing or not the preconditioner. The preconditioner is an algorithm used (for the moment we use [Ruiz equilibrator](https://cds.cern.ch/record/585592/files/CM-P00040415.pdf)) for reducing the ill-conditioning of the QP problem, and hence speeding-up the solver and increasing its accuracy. It consists mostly of an heuristic involving linear scalings. Note that for very ill-conditioned QP problem, when one asks for a very accurate solution, the unscaling procedure can become less precise (we provide some remarks about this subject in section 6.D of the [following paper](https://hal.inria.fr/hal-03683733/file/Yet_another_QP_solver_for_robotics_and_beyond.pdf)). By default its value is set to true.

doc/3-ProxQP_solve.md

@@ -130,3 +130,20 @@ Finally, note that in C++, if you want to change one option, the order described
     </td>
   </tr>
 </table>
+
+Note that if some elements of your QP model are not defined (for example a QP without linear cost or inequality constraints), you can either pass a None argument, or a matrix with zero shape for specifying it. We provide an example below in cpp and python (for the dense case, it is similar with sparse backend).
+
+<table class="manual">
+  <tr>
+    <th>examples/cpp/initializing_with_none_without_api.cpp</th>
+    <th>examples/python/initializing_with_none_without_api.py</th>
+  </tr>
+  <tr>
+    <td valign="top">
+      \include initializing_with_none_without_api.cpp
+    </td>
+    <td valign="top">
+      \include initializing_with_none_without_api.py
+    </td>
+  </tr>
+</table>

examples/cpp/initializing_with_none.cpp

@@ -0,0 +1,28 @@
+#include "proxsuite/proxqp/dense/dense.hpp"
+#include <proxsuite/proxqp/utils/random_qp_problems.hpp> // used for generating a random convex Qp
+
+using namespace proxsuite::proxqp;
+using T = double;
+int
+main()
+{
+  dense::isize dim = 10;
+  dense::isize n_eq(0);
+  dense::isize n_in(0);
+  dense::QP<T> Qp(dim, n_eq, n_in);
+  T strong_convexity_factor(0.1);
+  T sparsity_factor(0.15);
+  // we generate a qp, so the function used from helpers.hpp is
+  // in proxqp namespace. The qp is in dense eigen format and
+  // you can control its sparsity ratio and strong convexity factor.
+  dense::Model<T> qp = utils::dense_strongly_convex_qp(
+    dim, n_eq, n_in, sparsity_factor, strong_convexity_factor);
+
+  Qp.init(qp.H, qp.g,qp.A,qp.b,qp.C,qp.u,qp.l); // initialization with zero shape matrices
+  //it is equivalent to do Qp.init(qp.H, qp.g, std::nullopt,std::nullopt,std::nullopt,std::nullopt,std::nullopt);
+  Qp.solve();
+  // print an optimal solution x,y and z
+  std::cout << "optimal x: " << Qp.results.x << std::endl;
+  std::cout << "optimal y: " << Qp.results.y << std::endl;
+  std::cout << "optimal z: " << Qp.results.z << std::endl;
+}

examples/cpp/initializing_with_none_without_api.cpp

@@ -0,0 +1,27 @@
+#include "proxsuite/proxqp/dense/dense.hpp"
+#include <proxsuite/proxqp/utils/random_qp_problems.hpp> // used for generating a random convex Qp
+
+using namespace proxsuite::proxqp;
+using T = double;
+int
+main()
+{
+  dense::isize dim = 10;
+  dense::isize n_eq(0);
+  dense::isize n_in(0);
+  T strong_convexity_factor(0.1);
+  T sparsity_factor(0.15);
+  // we generate a qp, so the function used from helpers.hpp is
+  // in proxqp namespace. The qp is in dense eigen format and
+  // you can control its sparsity ratio and strong convexity factor.
+  dense::Model<T> qp = utils::dense_strongly_convex_qp(
+    dim, n_eq, n_in, sparsity_factor, strong_convexity_factor);
+
+  Results<T> results =
+    dense::solve<T>(qp.H, qp.g,qp.A,qp.b,qp.C,qp.u,qp.l); // initialization with zero shape matrices
+  //it is equivalent to do dense::solve<T>(qp.H, qp.g, std::nullopt,std::nullopt,std::nullopt,std::nullopt,std::nullopt);
+  // print an optimal solution x,y and z
+  std::cout << "optimal x: " << results.x << std::endl;
+  std::cout << "optimal y: " << results.y << std::endl;
+  std::cout << "optimal z: " << results.z << std::endl;
+}

examples/python/initializing_with_none.py

@@ -0,0 +1,15 @@
+import numpy as np
+import proxsuite
+
+H = np.array([[65.0, -22.0, -16.0], [-22.0, 14.0, 7.0], [-16.0, 7.0, 5.0]])
+g = np.array([-13.0, 15.0, 7.0])
+A = None
+b = None
+C = None
+u = None
+l = None
+
+Qp = proxsuite.proxqp.dense.QP(3,0,0)
+Qp.init(H, g, A, b, C, u, l) # it is equivalent to do as well Qp.init(H, g)
+Qp.solve()
+print("optimal x: {}".format(Qp.results.x))

examples/python/initializing_with_none_without_api.py

@@ -0,0 +1,13 @@
+import numpy as np
+import proxsuite
+
+H = np.array([[65.0, -22.0, -16.0], [-22.0, 14.0, 7.0], [-16.0, 7.0, 5.0]])
+g = np.array([-13.0, 15.0, 7.0])
+A = None
+b = None
+C = None
+u = None
+l = None
+
+results = proxsuite.proxqp.dense.solve(H, g, A, b, C, u, l) # it is equivalent to do as well proxsuite.proxqp.dense.solve(H, g)
+print("optimal x: {}".format(results.x))