add examples description

docs/examples/bilevel-problem.rst

@@ -3,6 +3,9 @@
 MILP-MILP Example with MibS
 ===========================
 
+Problem Definition
+------------------
+
 This example is taken from :cite:`Moore1990` and is a bilevel optimization problem where the upper level is a mixed-integer linear program (MILP) and the lower level is a mixed-integer linear program (MILP).
 
 The problem is formulated as follows:
@@ -24,7 +27,10 @@ The problem is formulated as follows:
             \end{array}
     \end{align}
 
-Here is one possible implementation of the problem with idol and solved with MibS.
+Implementation with idol
+------------------------
+
+In this example, we show how to model this MILP-MILP bilevel problem and how to solve it using the MibS solver.
 
 .. literalinclude:: ../../examples/bilevel-optimization/bilevel.example.cpp
     :language: cpp

docs/examples/facility-location-problem.rst

@@ -1,3 +1,5 @@
+.. _example_flp:
+
 Facility Location Problem
 =========================
 
@@ -10,7 +12,7 @@ a subset of facility location to activate in order to serve all customers' deman
 
 Each facility :math:`i\in V_1` has an opening cost :math:`f_i` and a maximum capacity :math:`q_i`.
 Each customer :math:`j\in V_2` has a demand :math:`d_j`.
-The unitary cost of serving customer :math:`j` from facility :math:`i` is :math:`t_{ij}`.
+The unitary cost for serving customer :math:`j\in V_2` from facility :math:`i\in V_1` is :math:`t_{ij}`.
 
 We model the capacitated FLP with the MILP
 

docs/examples/generalized-assignment-problem.rst

@@ -1,5 +1,41 @@
 Generalized Assignment Problem
 ==============================
 
+Problem Definition
+------------------
+
+We consider the Generalized Assignment Problem (GAP).
+Given a set of :math:`m` agents and :math:`n` jobs, the goal is to assign each job to exactly one agent in such a
+way that the total cost is minimized, while respecting the capacity constraints of each agent.
+
+Each agent :math:`i\in\{1,\dotsc,m\}` has a capacity :math:`C_i`.
+Each job :math:`j\in\{1,\dotsc,n\}` has a resource consumption :math:`r_{ij}` and a cost :math:`c_{ij}` when assigned to agent :math:`i`.
+
+We model the GAP with the following binary linear program:
+
+.. math::
+
+    \begin{align*}
+        \min_{x} \ & \sum_{i=1}^m \sum_{j=1}^n c_{ij} x_{ij} \\
+        \text{s.t.} & \sum_{j=1}^n r_{ij} x_{ij} \le C_i && i=1,\dotsc,m \\
+                    & \sum_{i=1}^m x_{ij} = 1 && j=1,\dotsc,n \\
+                    & x_{ij} \in \{0,1\} && i=1,\dotsc,m, j=1,\dotsc,n.
+    \end{align*}
+
+Decomposition
+-------------
+
+In this example, we use Dantzig-Wolfe decomposition to break down the problem into a master problem and subproblems. The master problem coordinates the assignment of jobs to agents, while the subproblems handle the capacity constraints for each agent individually.
+
+1. **Master Problem:** The master problem is responsible for ensuring that each job is assigned to exactly one agent. It maintains the overall objective of minimizing the total cost.
+
+2. **Subproblems:** Each subproblem corresponds to an agent and ensures that the agent's capacity constraints are respected. The subproblems are solved independently and their solutions are used to update the master problem.
+
+Implementation with idol
+------------------------
+
+In this example, we show how to model the Generalized Assignment Problem with idol and how to solve it using a
+Dantzig-Wolfe decomposition within a branch-and-bound framework, i.e., a branch-and-price algorithm.
+
 .. literalinclude:: ../../examples/mixed-integer-optimization/assignment.example.cpp
     :language: cpp

docs/examples/knapsack-problem.rst

@@ -1,5 +1,30 @@
 Knapsack Problem
 ================
 
+Problem Definition
+------------------
+
+We consider the Knapsack Problem (KP).
+Given a set of :math:`n` items, each of which having a weight and a profit, the goal is to
+select of subset of items such that the total weight does not exceed a given capacity and the total profit is maximized.
+
+For each item :math:`j\in\{1,\dotsc,n\}`, we denote its weight by :math:`w_j` and its profit by :math:`p_j`.
+The maximum capacity of the knapsack is :math:`C`.
+
+We model the KP with the following binary linear program:
+
+.. math::
+
+    \begin{align*}
+        \max_{x} \ & \sum_{j=1}^n p_j x_j \\
+        \text{s.t.} & \sum_{j=1}^n w_j x_j \le C \\
+                    & x_j \in \{0,1\} && j=1,\dotsc,n.
+    \end{align*}
+
+Implementation with idol
+------------------------
+
+In this example, we show how to model the Knapsack Problem with idol and how to solve it using the HiGHS solver.
+
 .. literalinclude:: ../../examples/mixed-integer-optimization/knapsack.example.cpp
     :language: cpp

docs/examples/two-stage-robust-facility-location-problem.rst

@@ -3,26 +3,50 @@
 Two-Stage Robust Facility Location Problem (CCG)
 ================================================
 
+Problem Description
+-------------------
 
+We consider a robust version of the capacitated Facility Location Problem (FLP).
+Given a set of potential facility locations :math:`V_1` and a set of customers :math:`V_2`, the goal is to select a subset of facility locations
+to activate in order to serve all customers' demand, while minimizing the total cost.
+This version introduces uncertainty in the customers' demands.
+
+Note that there is also an example for the :ref:`deterministic version of the FLP using Column Generation <example_flp>`.
+
+Each facility :math:`i\in V_1` has an opening cost :math:`f_i` and a maximum capacity :math:`q_i`.
+Each customer :math:`j\in V_2` has a demand :math:`d_j`.
+The unitary cost for serving customer :math:`j\in V_2` from facility :math:`i\in V_1` is :math:`t_{ij}`.
+The uncertainty in customer demands is controlled by a parameter :math:`\Gamma`.
+
+In this robust variant, we consider that the demands are uncertain and can be expressed as :math:`d_j(\xi) = d_j(1 + p\xi_j)``
+with :math:`p` being the maximum increase in demand and :math:`\xi` being an unknown vector taken in the uncertainty set
+
+.. math::
+
+    \Xi := \left\{ \xi\in[ 0, 1 ]^{|V_2|} : \sum_{j\in V_2} \xi_j \le \Gamma \right\}.
+
+We model the two-stage robust FLP as
 
 .. math::
 
-    \begin{align}
-        \min_{x, y} \ & -x + -10 y \\
-        \text{s.t.} \ & x \in \mathbb Z_+ \\
-        & y\in
-            \begin{array}[t]{l}
-                \displaystyle \underset{y}{\text{arg min}} \ & y \\
-                \text{s.t.} \ & -25 x + 20 y \leq 30, \\
-                & x + 2 y \leq 10, \\
-                & 2 x - y \leq 15, \\
-                & 2 x + 10 y \geq 15, \\
-                & y \geq 0, \\
-                & y \in \mathbb Z_+.
-            \end{array}
-    \end{align}
-
-Here is one possible implementation of the problem with idol and solved with MibS.
-
-.. literalinclude:: ../../examples/bilevel-optimization/bilevel.example.cpp
+    \min_{x\in \{0,1\}^{|V_1|}} \ \left\{ \sum_{i\in V_1} f_i x_i + \max_{\xi\in \Xi} \ \min_{y\in Y(x,\xi)} \  \sum_{i\in V_1} \sum_{j\in V_2} t_{ij} y_{ij} \right\}
+
+where :math:`Y(x,\xi)` is the set of feasible solutions for the second stage problem, given the first stage solution :math:`x` and the realization :math:`\xi` of the uncertain demand vector.
+It is defined as the set of vectors :math:`y\in \mathbb{R}^{|V_1|\times|V_2|}` that satisfy the following constraints
+
+.. math::
+
+    \begin{align*}
+        & \sum_{i\in V_1} y_{ij} = d_j(\xi) && j\in V_2, \\
+        & \sum_{j\in V_2} y_{ij} \le q_i x_i && i\in V_1, \\
+        & y_{ij} \ge 0 && i\in V_1, j\in V_2.
+    \end{align*}
+
+Implementation with idol
+------------------------
+
+We now show how to implement the two-stage robust FLP with idol and how to solve it using a CCG algorithm.
+Here, the "adversarial problem" is solved by calling the bilevel solver MibS.
+
+.. literalinclude:: ../../examples/robust-optimization/robust_ccg.example.cpp
     :language: cpp