diff --git a/docs/examples/bilevel-problem.rst b/docs/examples/bilevel-problem.rst index 1ba4a8a8..2e65def7 100644 --- a/docs/examples/bilevel-problem.rst +++ b/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 diff --git a/docs/examples/facility-location-problem.rst b/docs/examples/facility-location-problem.rst index b69a5762..e4f3cd06 100644 --- a/docs/examples/facility-location-problem.rst +++ b/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 diff --git a/docs/examples/generalized-assignment-problem.rst b/docs/examples/generalized-assignment-problem.rst index 2ba4163f..ff62c20e 100644 --- a/docs/examples/generalized-assignment-problem.rst +++ b/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 diff --git a/docs/examples/knapsack-problem.rst b/docs/examples/knapsack-problem.rst index 531383b8..c8dd6c3e 100644 --- a/docs/examples/knapsack-problem.rst +++ b/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 diff --git a/docs/examples/two-stage-robust-facility-location-problem.rst b/docs/examples/two-stage-robust-facility-location-problem.rst index 80c61cef..edbbcada 100644 --- a/docs/examples/two-stage-robust-facility-location-problem.rst +++ b/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 `. + +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