First complete draft of variables and domains

JuliaConstraints · Jul 29, 2024 · ff4c7ff · ff4c7ff
1 parent 0400fad
commit ff4c7ff
Show file tree

Hide file tree

Showing 4 changed files with 132 additions and 101 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -66,10 +66,10 @@ uuid = "0dad84c5-d112-42e6-8d28-ef12dabb789f"
 version = "1.1.1"
 
 [[deps.ArrayInterface]]
-deps = ["Adapt", "LinearAlgebra", "SparseArrays", "SuiteSparse"]
-git-tree-sha1 = "5c9b74c973181571deb6442d41e5c902e6b9f38e"
+deps = ["Adapt", "LinearAlgebra"]
+git-tree-sha1 = "8c5b39db37c1d0340bf3b14895fba160c2d6cbb5"
 uuid = "4fba245c-0d91-5ea0-9b3e-6abc04ee57a9"
-version = "7.12.0"
+version = "7.14.0"
 
     [deps.ArrayInterface.extensions]
     ArrayInterfaceBandedMatricesExt = "BandedMatrices"
@@ -79,7 +79,8 @@ version = "7.12.0"
     ArrayInterfaceChainRulesExt = "ChainRules"
     ArrayInterfaceGPUArraysCoreExt = "GPUArraysCore"
     ArrayInterfaceReverseDiffExt = "ReverseDiff"
-    ArrayInterfaceStaticArraysCoreExt = "StaticArraysCore"
+    ArrayInterfaceSparseArraysExt = "SparseArrays"
+    ArrayInterfaceStaticArraysExt = "StaticArrays"
     ArrayInterfaceTrackerExt = "Tracker"
 
     [deps.ArrayInterface.weakdeps]
@@ -90,7 +91,8 @@ version = "7.12.0"
     ChainRules = "082447d4-558c-5d27-93f4-14fc19e9eca2"
     GPUArraysCore = "46192b85-c4d5-4398-a991-12ede77f4527"
     ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267"
-    StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
+    SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+    StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
     Tracker = "9f7883ad-71c0-57eb-9f7f-b5c9e6d3789c"
 
 [[deps.Artifacts]]
@@ -103,10 +105,10 @@ uuid = "a9b6321e-bd34-4604-b9c9-b65b8de01458"
 version = "0.1.0"
 
 [[deps.BangBang]]
-deps = ["Accessors", "Compat", "ConstructionBase", "InitialValues", "LinearAlgebra", "Requires"]
-git-tree-sha1 = "08e5fc6620a8d83534bf6149795054f1b1e8370a"
+deps = ["Accessors", "ConstructionBase", "InitialValues", "LinearAlgebra", "Requires"]
+git-tree-sha1 = "e2144b631226d9eeab2d746ca8880b7ccff504ae"
 uuid = "198e06fe-97b7-11e9-32a5-e1d131e6ad66"
-version = "0.4.2"
+version = "0.4.3"
 weakdeps = ["ChainRulesCore", "DataFrames", "StaticArrays", "StructArrays", "Tables", "TypedTables"]
 
     [deps.BangBang.extensions]
@@ -244,7 +246,7 @@ version = "0.2.2"
 
 [[deps.ConstraintDomains]]
 deps = ["ConstraintCommons", "Dictionaries", "Intervals", "PatternFolds", "StatsBase", "TestItems"]
-git-tree-sha1 = "9d56c60c941375702545d21a05381d2f5e872ea0"
+git-tree-sha1 = "20000526022d536c3c9fcbb3e9d92b6d9eef16c2"
 repo-rev = "main"
 repo-url = "https://github.com/JuliaConstraints/ConstraintDomains.jl.git"
 uuid = "5800fd60-8556-4464-8d61-84ebf7a0bedb"
@@ -642,9 +644,9 @@ version = "1.22.2"
 
 [[deps.JuliaFormatter]]
 deps = ["CSTParser", "CommonMark", "DataStructures", "Glob", "Pkg", "PrecompileTools", "Tokenize"]
-git-tree-sha1 = "0b50446cd3e52a51a7d48b52d49ec1a875aaf6e8"
+git-tree-sha1 = "4b0b04fe63e02eed776181e14ebc1f48d787ceec"
 uuid = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
-version = "1.0.58"
+version = "1.0.59"
 
 [[deps.JuliaVariables]]
 deps = ["MLStyle", "NameResolution"]

diff --git a/docs/src/constraints/variables_and_domains.md b/docs/src/constraints/variables_and_domains.md
@@ -4,128 +4,135 @@
 CurrentModule = ConstraintDomains
 ```
 
-*ConstraintDomains.jl* stands as a critical package within the *Julia Constraints* ecosystem, focusing on the definition and manipulation of variable domains that underpin the search spaces of constraint programming problems. This package provides the infrastructure necessary for specifying both discrete and continuous domains, thereby enabling a broad range of constraint programming applications.
+*ConstraintDomains.jl* stands as the standard way to define variables and explore domains within the *Julia Constraints* ecosystem. This package provides the infrastructure necessary for specifying both discrete and continuous domains. Explorations features are mainly related to the *learning about constraints* aspect and will be detailed in that chapter.
 
-## Key Features and Functionalities
+Variables and their domains can also be defined through `MOI` and `JuMP` syntaxes in their respective models.
 
-- **AbstractDomain Super Type**: At the foundation of ConstraintDomains.jl is the AbstractDomain type, an abstract supertype for all domain types. Implementations of AbstractDomain must provide methods for checking membership (∈), generating random elements (rand), and determining the domain's size or range (length). These functionalities are essential for defining the behavior and properties of variable domains within constraint models.
+## Implementing the `AbstractDomain` Interface
 
-- **Domain Types**: The package distinguishes between various domain types to cater to different needs:
+At the foundation of *ConstraintDomains.jl* is the `AbstractDomain` type, an abstract supertype for all domain types. Implementations of `AbstractDomain` must provide methods for checking membership (``\in``), generating random elements (`rand`), and determining the domain's size or range (`length`). These functionalities are essential for defining the behavior and properties of variable domains within constraint models.
 
-  - *ContinuousDomain*: A supertype for domains representing continuous ranges of real numbers.
-  - *DiscreteDomain*: Serves as a supertype for domains defined by discrete sets or ranges of numbers.
-  - *EmptyDomain*: Handles yet-to-be-defined domains, facilitating dynamic problem formulation.
-  - *Intervals and RangeDomain*: Represent continuous intervals and discrete ranges, respectively, providing flexible domain specification options.
-- **Dynamic Domain Manipulation**: ConstraintDomains.jl supports dynamic changes to domains, allowing for the addition (add!) and deletion (delete!) of elements, crucial for problems where domain definitions evolve based on the search process or external inputs.
+```@docs; canonical=false
+AbstractDomain
+```
 
-- **Exploration Settings and Methods**: The package offers ExploreSettings to configure the exploration of search spaces, including parameters for complete searches, maximum samplings, and solution limits. This feature is pivotal for tailoring the search process to the problem's characteristics and the computational resources available.
+## Discrete Domains
 
-- **Support for Advanced Modeling**: Beyond basic domain definition and manipulation, ConstraintDomains.jl integrates with learning and parameter exploration tools. For instance, FakeAutomaton facilitates the generation of pseudo-automata for parameter exploration, while the package also provides functions for generating random parameters (generate_parameters), accessing domain internals (get_domain), and merging or intersecting domains (merge_domains, intersect_domains).
+Optimization in discrete spaces has been the core of Constraint Programming since its inception. We provide three kinds of discrete domains.
 
-## Empowering Constraint Programming in Julia
+### `SetDomain`
 
-ConstraintDomains.jl embodies the versatility and power of the JuliaConstraints ecosystem, offering users a comprehensive toolkit for defining and exploring variable domains. By abstracting complex domain manipulations and providing a rich set of functionalities, ConstraintDomains.jl enhances the ease and efficiency of modeling constraint programming problems. Whether for educational purposes, research, or practical applications, this package lays the groundwork for advanced problem-solving strategies in the realm of constraint programming.
+A `SetDomain` is simply a `Set` of unordered numerical values.
 
-## Commons
+::: code-group
 
-```@docs; canonical=false
-AbstractDomain
-EmptyDomain
-domain
-domain_size
-get_domain
-to_domains
+```julia [JC-API]
+using ConstraintDomains
+
+d1 = domain([53.69, 89.2, 0.12])
+d2 = domain([2//3, 89//123])
+d3 = domain(4.3)
+d4 = domain(1, 42, 3.14)
 ```
 
-### Extension to Base module
+```julia [CBLS-JuMP]
+using CBLS, JuMP
 
-```@docs; canonical=false
-Base.in
-Base.rand
-Base.isempty
-Base.rand
-Base.string
+m = JuMP.Model(CBLS.Optimizer)
+
+@variable(m, x1 in DiscreteSet([53.69, 89.2, 0.12]))
+@variable(m, x2 in DiscreteSet([2//3, 89//123]))
+@variable(m, x3 in DiscreteSet(4.3))
+@variable(m, x4 in DiscreteSet([1, 42, 3.14]))
 ```
 
-### Performances
+```julia [CBLS-MOI]
+using CBLS
+import MathOptInterface as MOI
 
-## Continuous
+optimizer = CBLS.Optimizer()
 
-```@docs; canonical=false
-ContinuousDomain
-Intervals
-domain
-domain_size
-merge_domains
-intersect_domains
-intersect_domains!
-size
-```
+v1 = MOI.add_variable(optimizer)
+MOI.add_constraint(optimizer, v1, CBLS.DiscreteSet([53.69, 89.2, 0.12]))
 
-### Extension to Base module
+v2 = MOI.add_variable(optimizer)
+MOI.add_constraint(optimizer, v2, CBLS.DiscreteSet([2//3, 89//123]))
 
-```@docs; canonical=false
-Base.length
-Base.rand
-Base.in
-Base.string
+v3 = MOI.add_variable(optimizer)
+MOI.add_constraint(optimizer, v3, CBLS.DiscreteSet(4.3))
+
+v4 = MOI.add_variable(optimizer)
+MOI.add_constraint(optimizer, v4, CBLS.DiscreteSet([1, 42, 3.14]))
 ```
 
-## Discrete
+:::
 
-```@docs; canonical=false
-DiscreteDomain
-SetDomain
-RangeDomain
-ArbitraryDomain
-domain
-domain_size
-add!
-merge_domains
-intersect_domains
-size
+### `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).
+
+::: code-group
+
+```julia [JC-API]
+using ConstraintDomains
+
+d1 = domain(1:5)
+d2 = domain(0.4:0.1:1.3)
 ```
 
-### Extension to Base module
+```julia [CBLS-JuMP]
+## To be implemented
+# using CBLS, JuMP
 
+# m = JuMP.Model(CBLS.Optimizer)
 
-```@docs; canonical=false
-Base.delete!
-Base.length
-Base.rand
-Base.in
-Base.string
+# @variable(m, 1 ≤ x1 ≤ 5, Int) # Consecutive integers are interpreted as range
+# @variable(m, x2 in RangeSet(0.4:0.1:1.3))
 ```
 
-## General
+```julia [CBLS-MOI]
+## To be implemented
+# using CBLS
+# import MathOptInterface as MOI
 
-```@docs; canonical=false
-Base.eltype
-Base.convert
+# optimizer = CBLS.Optimizer()
+
+# v1 = MOI.add_variable(optimizer)
+# MOI.add_constraint(optimizer, v1, MOI.RangeSet(1:5))
+
+# v2 = MOI.add_variable(optimizer)
+
+# MOI.add_constraint(optimizer, v1, MOI.RangeSet(0.4:0.1:1.3))
 ```
 
-## Exploration
+:::
 
-```@docs; canonical=false
-ExploreSettings
-_explore
-explore
+### Arbitrary Domains
+
+As odd as it may sound, we provide a constructor for sets of elements making up arbitrary, possibly non-numerical, domains.
+
+Until some practical examples are implemented, this structure will mainly be a placeholder with default behavior.
+
+## Continuous Domains
+
+Numerous problems cannot be challenged without expressing at least part of their domains as continuous variables. In *Julia Constraints* we provide such domains as (set of) intervals.
+
+::: code-group
+
+```julia [JC-API]
+using ConstraintDomains, Intervals
+
+d1 = domain(Interval{Open,Closed}(3.2, true), (42, false))
+d2 = domain(3.2..42)
+d3 = domain([3.2..42, 63.2..324.1])
 ```
 
-## Parameters
+```julia [CBLS-JuMP]
+## see MOI.Interval
+```
 
-```@docs; canonical=false
-BoolParameterDomain
-DimParameterDomain
-IdParameterDomain
-FakeAutomaton
-ConstraintCommons.accept
-fake_automaton
-LanguageParameterDomain
-OpParameterDomain
-PairVarsParameterDomain
-ValParameterDomain
-ValsParameterDomain
-Base.rand
-generate_parameters
+```julia [CBLS-MOI]
+## see MOI.Interval
 ```
+
+:::
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -23,7 +23,7 @@ features:
     title: JuMP.jl
     details: Model optimization problems via JuMP.jl!
     link: "https://jump.dev/"
-  - icon: <img width="64" height="64" src="/logo.png" alt="PerfChecker.jl"/>
+  - icon: <img width="64" height="64" src="logo.png" alt="PerfChecker.jl"/>
     title: PerfChecker.jl
     details: Cross-version performance checking tool
     link: "https://github.com/JuliaConstraints/PerfChecker.jl"

diff --git a/docs/src/learning/intro.md b/docs/src/learning/intro.md
@@ -1,3 +1,25 @@
 # Learning about Constraints
 
 About learning constraints related matters.
+
+## Parameters
+
+<!-- To be moved -->
+
+One major challenge of learning the features of constraints is exploring the domains of parameters. To tackle this issue, we provide some way to generate parameters from variables' domains.
+
+```@docs; canonical=false
+BoolParameterDomain
+DimParameterDomain
+IdParameterDomain
+FakeAutomaton
+ConstraintCommons.accept
+fake_automaton
+LanguageParameterDomain
+OpParameterDomain
+PairVarsParameterDomain
+ValParameterDomain
+ValsParameterDomain
+Base.rand
+generate_parameters
+```