Update getting started

Author: Azzaare

docs/src/cp/getting_started.md

@@ -5,7 +5,122 @@
 - Discuss the advantages of Julia for computational science and optimization, highlighting its performance and ease of use.
 
 ## Setting Up Your Julia Environment
-- Guide on setting up Julia and essential packages for CP and optimization.
+
+We encourage users to install Julia through `juliaup`, a version manager for the Julia language. Please look at the official Julia language download page for further information. Once installed, Julia can be used through various editors (`Visual Studio Code`), notebooks (`Pluto.jl`), or command-line (`REPL`).
+
+Although a part of the CP solvers available within the Julia ecosystem have their own interface, we encourage users to use the JuMP modeling language if possible.
+
+Julia Constraints host several solvers(' interfaces). Due to its flexibility in modeling and solving, we will use LocalSearchSolvers.jl through its JuMP interface CBLS.jl as the basic example. Note that depending on the targeted instances, available hardware, and expectations, it is not necessarily the best choice.
+
+All along the documentation, we will try to provide syntax examples for different setup.
+
+::: code-group
+
+```julia [LocalSearchSolvers]
+using LocalSearchSolvers
+```
+
+```julia [CBLS]
+using JuMP, CBLS
+```
+
+```julia [TODO]
+# TODO: Add other solvers
+```
+
+:::
 
 ## Your First Julia CP Model
-- A simple tutorial to build and solve a basic CP model using Julia.
+
+We will start with a classic puzzle game and some of its not that simple variants: the Sudoku.
+
+(From Wikipedia) In classic Sudoku, the objective is to fill a 9 × 9 grid with digits so that each column, each row, and each of the nine 3 × 3 subgrids that compose the grid (also called "boxes", "blocks", or "regions") contains all of the digits from 1 to 9. The puzzle setter provides a partially completed grid, which for a well-posed puzzle has a single solution.
+
+Constraint Programming follows the *model-and-solve* approach. We first need to model our Sudoku problem.
+
+::: code-group
+
+```julia [CBLS]
+m = JuMP.Model(CBLS.Optimizer)
+```
+
+```julia [TODO]
+# TODO: Add other solvers
+```
+
+:::
+
+But what are the basis of CP models? It is quite simple:
+
+1. A collection ``X = X_1, \cdots, X_n`` of variables with each an associated domain.
+::: code-group
+
+```julia [CBLS]
+@variable(m, 1 ≤ X[1:9, 1:9] ≤ 9, Int)
+```
+
+```julia [TODO]
+# TODO: Add other solvers
+```
+
+:::
+
+1. A collection of predicates (called constraints) ``C = C_1, \cdots, C_n`` over (subsets of) ``X``.
+
+When modeling problems as CP, one might define and use their own predicates. However, a large collection of already defined constraints exists. One, if not the most, iconic global constraint is called AllDifferent. It ensures that all variables take distinct values.
+
+Sudoku puzzles can be defined using only this one constraint applied to different subsets of variables.
+
+::: code-group
+
+```julia [CBLS]
+for i in 1:9
+        @constraint(m, X[i,:] in AllDifferent()) # rows
+        @constraint(m, X[:,i] in AllDifferent()) # columns
+end
+```
+
+```julia [TODO]
+# TODO: Add other solvers
+```
+
+:::
+
+The last series of AllDifferent constraint is less straight forward. We need to ensure that each 3 × 3 subgrid (block) is filled with distinct values.
+
+::: code-group
+
+```julia [CBLS]
+for i in 0:2, j in 0:2 # blocks
+    @constraint(
+        m,
+        vec(X[(3i+1):(3(i+1)), (3j+1):(3(j+1))]) in AllDifferent(),
+    )
+end
+```
+
+```julia [TODO]
+# TODO: Add other solvers
+```
+
+:::
+
+We can now simply run our solver to look for a feasible solution.
+
+::: code-group
+
+```julia [CBLS]
+optimize!(m)
+```
+
+:::
+
+Note that this is heuristic solver, we might not get a feasible solution! Let's check it out. The value function print the value of a JuMP variable. We can cast it over a collection with the `value.` syntax.
+
+::: code-group
+
+```julia [CBLS]
+value.(X)
+```
+
+:::

notebooks/sudoku.jl

@@ -808,16 +808,16 @@ version = "17.4.0+2"
 # ╠═0165319a-0082-11ef-3870-c156b946632d
 # ╟─f3cf35b7-3768-4e81-960b-0de664f11bbb
 # ╠═f1469f7b-7015-44e6-9d65-6e20c3b6060f
-# ╟─941b4622-f1d6-45ef-a278-1a774cbeb5be
+# ╠═941b4622-f1d6-45ef-a278-1a774cbeb5be
 # ╠═3e44aa50-2bdb-4ae4-9f49-c5e48b5ee86a
 # ╟─9ed0dc54-6193-4533-9b14-3e6436148f96
-# ╟─d07690f7-6e64-4ff3-af7f-54a89d3fda86
+# ╠═d07690f7-6e64-4ff3-af7f-54a89d3fda86
 # ╠═0bd29769-32e6-4e74-8b94-509b650651ed
 # ╠═e4fc6f6b-2818-4cb4-a425-67f0bd49d3d5
 # ╟─5df218df-b615-47eb-88bc-8b17a38e5cd9
 # ╠═009c7898-d203-475a-b005-71ab92ecd7eb
 # ╠═76cbf784-df24-4e38-a71e-38618e235ddc
-# ╟─a1d3e36c-0151-4e35-83b6-c9b801194178
+# ╠═a1d3e36c-0151-4e35-83b6-c9b801194178
 # ╠═6d9e9d0d-f95b-4965-97cc-fc2eaae81c49
 # ╠═94e11c4a-c558-47a8-8635-c1da1c4187c1
 # ╟─96ce8df9-6316-4cfb-891d-7db10f2655fd