[Bridges] fix various docstrings for CSP (#1931)

Author: odow

src/Bridges/Constraint/bridges/bin_packing.jl

@@ -9,15 +9,27 @@
 
 `BinPackingToMILPBridge` implements the following reformulation:
 
-  * ``x \\in BinPacking(c, w)`` into
-    ```math
-    \\begin{aligned}
-    z_{ij} \\in \\{0, 1\\}              & \\forall i, j \\\\
-    \\sum\\limits_{j} z_{ij} = 1        & \\forall i \\\\
-    \\sum\\limits_{i} w_i z_{ij} \\le c & \\forall j \\\\
-    \\sum\\limits_{j} j z_{ij} == x_i   & \\forall i
-    \\end{aligned}
-    ```
+  * ``x \\in BinPacking(c, w)`` into a mixed-integer linear program.
+
+## Reformulation
+
+The reformulation is non-trivial, and it depends on the finite domain of each
+variable ``x_i``, which we as define ``S_i = \\{l_i,\\ldots,u_i\\}``.
+
+First, we introduce new binary variables ``z_{ij}``, which are ``1`` if variable
+``x_i`` takes the value ``j`` in the optimal solution and ``0`` otherwise:
+```math
+\\begin{aligned}
+z_{ij} \\in \\{0, 1\\}                              & \\;\\; \\forall i \\in 1\\ldots d, j \\in S_i  \\\\
+x_i - \\sum\\limits_{j\\in S_i} j \\cdot z_{ij} = 0 & \\;\\; \\forall i \\in 1\\ldots d              \\\\
+\\sum\\limits_{j\\in S_i} z_{ij} = 1                & \\;\\; \\forall i \\in 1\\ldots d              \\\\
+\\end{aligned}
+```
+
+Then, we add the capacity constraint for all possible bins ``j``:
+```math
+\\sum\\limits_{i} w_i z_{ij} \\le c \\forall j \\in \\bigcup_{i=1,\\ldots,d} S_i
+```
 
 ## Source node
 

src/Bridges/Constraint/bridges/count_at_least.jl

@@ -9,9 +9,9 @@
 
 `CountAtLeastToCountBelongsBridge` implements the following reformulation:
 
-  * ``x \\in \\textsf{CountAtLeast}(n, d, set)`` to
-    ``(n_i, x_{d_i}) \\in \\textsf{CountBelongs}(1+d)``
-    and ``n_i \\ge n``
+  * ``x \\in \\textsf{CountAtLeast}(n, d, \\mathcal{S})`` to
+    ``(n_i, x_{d_i}) \\in \\textsf{CountBelongs}(1+d, \\mathcal{S})``
+    and ``n_i \\ge n`` for all ``i``.
 
 ## Source node
 

src/Bridges/Constraint/bridges/count_belongs.jl

@@ -30,7 +30,7 @@ x_i - \\sum\\limits_{j\\in S_i} j \\cdot z_{ij} = 0 & \\;\\; \\forall i \\in 1\\
 Finally, ``n`` is constrained to be the number of ``z_{ij}`` elements that are
 in ``\\mathcal{S}``:
 ```math
-n - \\sum\\limits_{j \\in \\mathcal{S}} y_{j} = 0
+n - \\sum\\limits_{i\\in 1\\ldots d, j \\in \\mathcal{S}} z_{ij} = 0
 ```
 
 ## Source node

src/Bridges/Constraint/bridges/table.jl

@@ -12,9 +12,9 @@
   * ``x \\in Table(t)`` into
     ```math
     \\begin{aligned}
-    z_{j} \\in \\{0, 1\\}                     & \\forall i, j \\\\
+    z_{j} \\in \\{0, 1\\}                     & \\quad \\forall i, j \\\\
     \\sum\\limits_{j=1}^n z_{j} = 1                           \\\\
-    \\sum\\limits_{j=1}^n t_{ij} z_{j} == x_i & \\forall i
+    \\sum\\limits_{j=1}^n t_{ij} z_{j} = x_i & \\quad \\forall i
     \\end{aligned}
     ```
 
@@ -30,7 +30,6 @@
 
   * [`MOI.VariableIndex`](@ref) in [`MOI.ZeroOne`](@ref)
   * [`MOI.ScalarAffineFunction{T}`](@ref) in [`MOI.EqualTo{T}`](@ref)
-  * [`MOI.ScalarAffineFunction{T}`](@ref) in [`MOI.LessThan{T}`](@ref)
 """
 struct TableToMILPBridge{T,F<:MOI.AbstractVectorFunction} <: AbstractBridge
     z::Vector{MOI.VariableIndex}

src/sets.jl

@@ -1163,7 +1163,7 @@ end
 """
     BinPacking(c::T, w::Vector{T}) where {T}
 
-The set ``\\{x \\in \\mathbb{R}^d\\}`` where `d = length(w)`, such that each
+The set ``\\{x \\in \\mathbb{Z}^d\\}`` where `d = length(w)`, such that each
 item `i` in `1:d` of weight `w[i]` is put into bin `x[i]`, and the total weight
 of each bin does not exceed `c`.
 
@@ -1225,7 +1225,8 @@ Graphs with multiple independent circuits, such as `[2, 1, 3]` and
 
 ## Also known as
 
-This constraint is called `circuit` in MiniZinc.
+This constraint is called `circuit` in MiniZinc, and it is equivalent to forming
+a (potentially sub-optimal) tour in the travelling salesperson problem.
 
 ## Example
 
@@ -1417,8 +1418,8 @@ end
 """
     Cumulative(dimension::Int)
 
-The set ``\\{(s, d, r, b) \\in \\mathbb{R}^{3n+1}\\}``, representing the
-`cumulative`` global constraint, where
+The set ``\\{(s, d, r, b) \\in \\mathbb{Z}^{3n+1}\\}``, representing the
+`cumulative` global constraint, where
 `n == length(s) == length(r) == length(b)` and `dimension = 3n + 1`.
 
 `Cumulative` requires that a set of tasks given by start times ``s``, durations
@@ -1456,7 +1457,7 @@ end
 Given a graph comprised of a set of nodes `1..N` and a set of arcs `1..E`
 represented by an edge from node `from[i]` to node `to[i]`, `Path` constrains
 the set
-``(s, t, ns, es) \\in (1..N)\\times(1..N)\\times\\{0,1\\}^N\\times\\{0,1\\}^E``,
+``(s, t, ns, es) \\in (1..N)\\times(1..E)\\times\\{0,1\\}^N\\times\\{0,1\\}^E``,
 to form subgraph that is a path from node `s` to node `t`, where node `n` is in
 the path if `ns[n]` is `1`, and edge `e` is in the path if `es[e]` is `1`.