update starting guide (#199)

Following BlockDecomposition release.

docs/src/start.md

@@ -3,10 +3,8 @@
 This quick start guide introduces main features of Coluna.jl package through an
 example.
 
-## Instantiation of solver and model
 
-Coluna requires `JuMP` and `BlockDecomposition` to write the model and apply a 
-decomposition. In this example, we use `GLPK` as the underlying solver.
+## Start
 
 ```julia
 using JuMP, BlockDecomposition, GLPK, Coluna
@@ -18,40 +16,54 @@ We instantiate the solver and define how we want to solve the decomposed formula
 coluna = JuMP.with_optimizer(
     Coluna.Optimizer,
     params = Coluna.Params(
-        global_strategy = Coluna.GlobalStrategy(Coluna.SimpleBnP, Coluna.SimpleBranching, Coluna.DepthFirst)
-    ),
+        global_strategy = Coluna.GlobalStrategy(
+                Coluna.SimpleBnP(), Coluna.SimpleBranching(), Coluna.DepthFirst())
+        ),
     default_optimizer = with_optimizer(GLPK.Optimizer)
 )
 ```
 
 Then, we instanciate the model
 
 ```julia
-model = BlockModel(coluna, bridge_constraints = false)
+model = BlockModel(coluna)
 ```  
 
-!!! note
-    Argument `bridge_constraints = false` is mandatory until the fix we made 
-    in MathOptInterface.jl is available on the stable version.
+## Generalized Assignment Problem
 
-## Generalized Assignment problem
+Assume we want to solve the following instance :
 
-The model is written as a JuMP model. If you are not familiar with JuMP syntax,
-you may want to check its [documentation]
-(http://www.juliaopt.org/JuMP.jl/stable/).
+```julia
+M = 4
+J = 30
+Cost = [12.7 22.5 8.9 20.8 13.6 12.4 24.8 19.1 11.5 17.4 24.7 6.8 21.7 14.3 10.5 15.2 14.3 12.6 9.2 20.8 11.7 17.3 9.2 20.3 11.4 6.2 13.8 10.0 20.9 20.6;  19.1 24.8 24.4 23.6 16.1 20.6 15.0 9.5 7.9 11.3 22.6 8.0 21.5 14.7 23.2 19.7 19.5 7.2 6.4 23.2 8.1 13.6 24.6 15.6 22.3 8.8 19.1 18.4 22.9 8.0;  18.6 14.1 22.7 9.9 24.2 24.5 20.8 12.9 17.7 11.9 18.7 10.1 9.1 8.9 7.7 16.6 8.3 15.9 24.3 18.6 21.1 7.5 16.8 20.9 8.9 15.2 15.7 12.7 20.8 10.4;  13.1 16.2 16.8 16.7 9.0 16.9 17.9 12.1 17.5 22.0 19.9 14.6 18.2 19.6 24.2 12.9 11.3 7.5 6.5 11.3 7.8 13.8 20.7 16.8 23.6 19.1 16.8 19.3 12.5 11.0]
+Weight = [61 70 57 82 51 74 98 64 86 80 69 79 60 76 78 71 50 99 92 83 53 91 68 61 63 97 91 77 68 80; 50 57 61 83 81 79 63 99 82 59 83 91 59 99 91 75 66 100 69 60 87 98 78 62 90 89 67 87 65 100; 91 81 66 63 59 81 87 90 65 55 57 68 92 91 86 74 80 89 95 57 55 96 77 60 55 57 56 67 81 52;  62 79 73 60 75 66 68 99 69 60 56 100 67 68 54 66 50 56 70 56 72 62 85 70 100 57 96 69 65 50]
+Capacity = [1020 1460 1530 1190]
+```
 
-Consider a set of machines `Machines = 1:M` and a set of jobs `Jobs = 1:J`.
+We have a set of machines `Machines = 1:M` and a set of jobs `Jobs = 1:J`.
 A machine `m` has a resource capacity `Capacity[m]`. When we assign a job
 `j` to a machine `m`, the job has a cost `Cost[m,j]` and consumes
-`Weight[m,j]` resources of the machine `m`. The goal is to minimize the jobs
+`Weight[m,j]` resource units of the machine `m`. The goal is to minimize the jobs
 cost sum by assigning each job to a machine while not exceeding the capacity of
 each machine.
 
-Since the knapsack problem is tractable, we decompose the problem 
-over machines to obtain one knapsack subproblem per machine. 
+Let $x_{mj}$ equal to one if job $j$ is assigned to machine $m$; $0$ otherwise.
+
+```math
+\begin{alignat}{4} 
+[GAP] \equiv \min \rlap{\sum_{m \in \text{Machines}} c_{mj} x_{mj}} \label{obj} \\
+\text{s.t.} && \sum_{m \in \text{Machines}} x_{mj} &= 1  \quad& j \in \text{Jobs} \label{mast} \\
+&& \sum_{j \in \text{Jobs}} x_{mj} &\leq C_m  \quad  \quad& m \in \text{Machines}   \label{knp} \\
+&& x_{mj}  &\in \{0,1\}  &m \in \text{Machines},\; j \in \text{Jobs}
+\end{alignat}
+```
+
+Since the knapsack problem is tractable, we want to apply a Dantzig-Wolfe 
+decomposition to the model $[GAP]$ to get one knapsack subproblem per machine. 
+Let $(Q^m)_{m \in \text{Machines}}$ be the set of knapsack subproblems.
 
-The decomposition is described through an axis. 
-Each index of the axis represents a subproblem.
+The axis is the index set of subproblems. First, we define the axis `Machines`.
 
 ```julia
 @axis(Machines, 1:M)
@@ -76,25 +88,24 @@ Then, we write the model
 Afterward, we apply the Dantzig-Wolfe decomposition according to axis `Machines`.
 
 ```julia
-@dantzig_wolfe_decomposition(model, dec, Machines)
+@dantzig_wolfe_decomposition(model, decomposition, Machines)
 ```
 
-Now, we can solve the problem.
-
+We retrieve the master and the subproblems.
 ```julia
-optimize!(model)
+master = getmaster(decomposition)
+subproblems = getsubproblems(decomposition)
+```
+We specify that the lower multiplicity of subproblems is 0.
+```julia
+specify!(subproblems, lower_multiplicity = 0, upper_multiplicity = 1)
 ```
 
-## Example
-
-Try yourself by copying the following data and the example above in your julia terminal :
+Now, we can solve the problem.
 
 ```julia
-M = 4
-J = 30
-Cost = [12.7 22.5 8.9 20.8 13.6 12.4 24.8 19.1 11.5 17.4 24.7 6.8 21.7 14.3 10.5 15.2 14.3 12.6 9.2 20.8 11.7 17.3 9.2 20.3 11.4 6.2 13.8 10.0 20.9 20.6;  19.1 24.8 24.4 23.6 16.1 20.6 15.0 9.5 7.9 11.3 22.6 8.0 21.5 14.7 23.2 19.7 19.5 7.2 6.4 23.2 8.1 13.6 24.6 15.6 22.3 8.8 19.1 18.4 22.9 8.0;  18.6 14.1 22.7 9.9 24.2 24.5 20.8 12.9 17.7 11.9 18.7 10.1 9.1 8.9 7.7 16.6 8.3 15.9 24.3 18.6 21.1 7.5 16.8 20.9 8.9 15.2 15.7 12.7 20.8 10.4;  13.1 16.2 16.8 16.7 9.0 16.9 17.9 12.1 17.5 22.0 19.9 14.6 18.2 19.6 24.2 12.9 11.3 7.5 6.5 11.3 7.8 13.8 20.7 16.8 23.6 19.1 16.8 19.3 12.5 11.0]
-Weight = [61 70 57 82 51 74 98 64 86 80 69 79 60 76 78 71 50 99 92 83 53 91 68 61 63 97 91 77 68 80; 50 57 61 83 81 79 63 99 82 59 83 91 59 99 91 75 66 100 69 60 87 98 78 62 90 89 67 87 65 100; 91 81 66 63 59 81 87 90 65 55 57 68 92 91 86 74 80 89 95 57 55 96 77 60 55 57 56 67 81 52;  62 79 73 60 75 66 68 99 69 60 56 100 67 68 54 66 50 56 70 56 72 62 85 70 100 57 96 69 65 50]
-Capacity = [1020 1460 1530 1190]
+optimize!(model)
+```
 ```
 
 ## Logs