Merge pull request #53 from JuliaConstraints/revisions

minor revisions

Author: Azzaare

docs/src/constraints/constraint_commons.md

@@ -60,7 +60,7 @@ at_end
 
 ## Extensions
 
-We extended some operations for `Nothing` and `Symbol`.
+We extend some operations for `Nothing` and `Symbol`.
 
 ```@docs; canonical=false
 symcon
@@ -89,7 +89,7 @@ consisempty
 
 ## Sampling
 
-During our constraint learning processes, we use sampling to efficiently make partial exploration of search spaces. Follows some sampling utilities.
+During our constraint learning processes, we use sampling to efficiently make partial exploration of search spaces. The following are some examples of sampling utilities.
 
 ```@docs; canonical=false
 oversample
@@ -112,18 +112,18 @@ We need to compute the difference between extrema of various kind of collections
 δ_extrema
 ```
 
+### Performances
+
 ```@raw html
 <div style="display: flex; justify-content: space-between;">
   <img src="https://github.com/JuliaConstraints/Benchmarks/blob/main/ConstraintCommons/visuals/bench_evolution_extrema.png?raw=true" alt="Bench Evolution" style="width:48%;"/>
   <img src="https://github.com/JuliaConstraints/Benchmarks/blob/main/ConstraintCommons/visuals/chair_evolution_extrema.png?raw=true" alt="Chair Evolution" style="width:48%;"/>
 </div>
 ```
 
-### Performances
-
 ## Dictionaries
 
-We provide the everuseful `incsert!` function for dictionaries.
+We provide the ever-useful `incsert!` function for dictionaries.
 
 ```@docs; canonical=false
 incsert!
@@ -136,4 +136,4 @@ incsert!
   <img src="https://github.com/JuliaConstraints/Benchmarks/blob/main/ConstraintCommons/visuals/bench_evolution_dictionaries.png?raw=true" alt="Bench Evolution" style="width:48%;"/>
   <img src="https://github.com/JuliaConstraints/Benchmarks/blob/main/ConstraintCommons/visuals/chair_evolution_dictionaries.png?raw=true" alt="Chair Evolution" style="width:48%;"/>
 </div>
-```
+```

docs/src/constraints/generic_constraints.md

@@ -14,7 +14,7 @@ Note that the *intention* constraint is not directly available through the JC-AP
 
 We provide a straightforward example through the `:dist_different` constraint on how to define and add such a constraint in the `USUAL_CONSTRAINTS` collection.
 
-Higher level modeling language such as `JuMP` should provide a `Intention` interface.
+Higher level modeling languages such as `JuMP` should provide a `Intention` interface.
 
 ### Defining an intention constraint in JC-API
 
@@ -33,7 +33,7 @@ Ensures that the distances between marks on the ruler are unique.
 predicate_dist_different(x) = abs(x[1] - x[2]) ≠ abs(x[3] - x[4])
 
 # Add it to usual constraints
-@usual concept_dist_different(x) = xcsp_intension(
+@usual concept_dist_different(x) = xcsp_intention(
     list = x,
     predicate = predicate_dist_different
 )
@@ -44,11 +44,11 @@ Please check the section dedicated to the Golomb Ruler problem to see a use for
 
 ### APIs
 
-Note that the *intension* constraint is not directly available through the JC-API in Constraints.jl. It is designed as such since defining a constraint through a *predicate* is the natural way.
+Note that the *intention* constraint is not directly available through the JC-API in Constraints.jl. It is designed as such since defining a constraint through a *predicate* is the natural way.
 
 We provide here a usage example for the `:dist_different` constraint, previously added to the `USUAL_CONSTRAINTS` collection.
 
-Higher level modeling language such as `JuMP` should provide an `Intension` interface.
+Higher level modeling language such as `JuMP` should provide an `Intention` interface.
 
 ::: code-group
 
@@ -63,7 +63,7 @@ concept(:dist_different)(x)
 # Defines the DistDifferent constraint
 using Constraints
 
-c = x -> xcsp_intension(
+c = x -> xcsp_intention(
     list = x,
     predicate = y -> abs(y[1] - y[2]) ≠ abs(y[3] - y[4])
 )
@@ -76,35 +76,100 @@ c([1, 2, 3, 4]) # false
 using CBLS, JuMP
 
 model = Model(CBLS.Optimizer)
+
+# Using build-in DistDifferent
 @variable(model, 0 <= X[1:4] <= 10, Int)
 @constraint(model, X in DistDifferent())
+
+# Alternatively
+@variable(model, 0 <= Y[1:4] <= 10, Int)
+@constraint(model, Y in Intention(y -> abs(y[1] - y[2]) ≠ abs(y[3] - y[4])))
+
 optimize!(model)
 
 @info value.(X)
-
-# Note that this example gives a solution for the constraint within the interval 0:10
+@info value.(Y)
 ```
 
 ```julia [MOI]
-# TODO: How to handle intention in JuMP/MOI
-```
+using CBLS
+import MathOptInterface as MOI
 
-:::
+optimizer = CBLS.Optimizer()
 
-### Specific documentation
+x = MOI.add_variables(optimizer, 4)
+for xi in x
+    # Missing RangeDomain currently in CBLS
+    MOI.add_constraint(optimizer, xi, CBLS.DiscreteSet(collect[1:10]))
+end
+MOI.add_constraint(optimizer, x, CBLS.Intention(y -> abs(y[1] - y[2]) ≠ abs(y[3] - y[4])))
 
-```@docs; canonical=false
-xcsp_intension
+MOI.optimize!(optimizer)
 ```
 
+:::
+
 ## Extension Constraints
 
-These are constraints that are defined by explicitly listing all the tuples of values that satisfy the constraint. They are called extensional because they are defined by the set of values they allow. For example, a binary constraint that specifies that a variable X must be either 1 or 2 and a variable Y must be either 3 or 4 could be defined extensionally by the set of tuples {(1,3), (1,4), (2,3), (2,4)}.
+These are constraints that are defined by explicitly listing all the tuples of values that satisfy the constraint. They are called extensional because they are defined by the set of values they allow. For example, a binary constraint that specifies that a variable ``X`` must be either ``1`` or ``2`` and a variable ``Y`` must be either ``3`` or ``4`` could be defined extensionally by the set of tuples $${(1,3), (1,4), (2,3), (2,4)}.$$
 
 These two types of constraints provide a flexible way to define complex relationships between variables in constraint programming.
 
-### [XCSP](https://arxiv.org/abs/2009.00514) in Constraints.jl
+::: code-group
+
+```julia [JC-API]
+using Constraints
 
-```@docs; canonical=false
-xcsp_extension
+concept(:dist_different, x)
+concept(:dist_different)(x)
 ```
+
+```julia [XCSP]
+# Defines the DistDifferent constraint
+using Constraints
+
+c = x -> xcsp_intention(
+    list = x,
+    predicate = y -> abs(y[1] - y[2]) ≠ abs(y[3] - y[4])
+)
+
+c([1, 2, 3, 3]) # true
+c([1, 2, 3, 4]) # false
+```
+
+```julia [JuMP]
+using CBLS, JuMP
+
+model = Model(CBLS.Optimizer)
+
+# Using build-in DistDifferent
+@variable(model, 0 <= X[1:4] <= 10, Int)
+@constraint(model, X in DistDifferent())
+
+# Alternatively
+@variable(model, 0 <= Y[1:4] <= 10, Int)
+@constraint(model, Y in Intention(y -> abs(y[1] - y[2]) ≠ abs(y[3] - y[4])))
+
+optimize!(model)
+
+@info value.(X)
+@info value.(Y)
+```
+
+```julia [MOI]
+using CBLS
+import MathOptInterface as MOI
+
+optimizer = CBLS.Optimizer()
+
+x = MOI.add_variables(optimizer, 4)
+for xi in x
+    # Missing RangeDomain currently in CBLS
+    MOI.add_constraint(optimizer, xi, CBLS.DiscreteSet(collect[1:10]))
+end
+MOI.add_constraint(optimizer, x, CBLS.Intention(y -> abs(y[1] - y[2]) ≠ abs(y[3] - y[4])))
+
+MOI.optimize!(optimizer)
+```
+
+:::

docs/src/constraints/variables_and_domains.md

@@ -69,7 +69,7 @@ MOI.add_constraint(optimizer, v4, CBLS.DiscreteSet([1, 42, 3.14]))
 
 ### `RangeDomain`
 
-A range domain allows for minimal storage and more efficient operation on discrete sets defined as `Range` in Julia. It is not recommended for dynamic domains (it will be replaced with `SetDomain` as soon non-extremal element is removed).
+A range domain allows for minimal storage and more efficient operation on discrete sets defined as `Range` in Julia. It is not recommended for dynamic domains (it will be replaced with `SetDomain` as soon as a non-extremal element is removed).
 
 ::: code-group