Doc up

Project.toml

@@ -1,7 +1,7 @@
 name = "CompositionalNetworks"
 uuid = "4b67e4b5-442d-4ef5-b760-3f5df3a57537"
 authors = ["Jean-François Baffier"]
-version = "0.1.2"
+version = "0.1.3"
 
 [deps]
 ConstraintDomains = "5800fd60-8556-4464-8d61-84ebf7a0bedb"
@@ -11,7 +11,7 @@ OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
 [compat]
-ConstraintDomains = "0.1"
+ConstraintDomains = "0.1.2"
 Dictionaries = "0.3"
 Evolutionary = "0.7, 0.8"
 OrderedCollections = "1.3"

README.md

@@ -4,3 +4,60 @@
 [![Build Status](https://github.com/JuliaConstraints/CompositionalNetworks.jl/workflows/CI/badge.svg)](https://github.com/JuliaConstraints/CompositionalNetworks.jl/actions)
 [![codecov](https://codecov.io/gh/JuliaConstraints/CompositionalNetworks.jl/branch/main/graph/badge.svg?token=m5Y2106hdi)](https://codecov.io/gh/JuliaConstraints/CompositionalNetworks.jl)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
+
+`CompositionalNetworks.jl`, a Julia package for Interpretable Compositional Networks (ICN), a variant of neural networks, allowing the user to get interpretable results, unlike regular artificial neural networks.
+
+The current state of our ICN focuses on the composition of error functions for `LocalSearchSolvers.jl`, but produces results independently of it and export it to either/both Julia functions or/and human readable output.
+
+### How does it work?
+
+The package comes with a basic ICN for learning global constraints. The ICN is composed of 4 layers: `transformation`, `arithmetic`, `aggregation`, and `comparison`. Each contains several operations that can be composed in various ways.
+Given a `concept` (a predicate over the variables' domains), a metric (`hamming` by default), and the variables' domains, we learn the binary weights of the ICN. 
+
+## Installation
+
+```julia
+] add CompositionalNetworks
+```
+
+As the package is in a beta version, some changes in the syntax and features are likely to occur. However, those changes should be minimal between minor versions. Please update with caution.
+
+## Quickstart
+
+```julia
+# 4 variables in 1:4
+doms = [domain([1,2,3,4]) for i in 1:4]
+
+# allunique concept (that is used to define the :all_different constraint)
+err = explore_learn_compose(allunique, domains=doms)
+# > interpretation: identity ∘ count_positive ∘ sum ∘ count_eq_left
+
+# test our new error function
+@assert err([1,2,3,3], dom_size = 4) > 0.0
+
+# export an all_different function to file "current/path/test_dummy.jl" 
+compose_to_file!(icn, "all_different", "test_dummy.jl")
+```
+
+The output file should produces a function that can be used as follows (assuming the maximum domain size is `7`)
+
+```julia
+import CompositionalNetworks
+
+all_different([1,2,3,4,5,6,7]; dom_size = 7)
+# > 0.0 (which means true, no errors)
+```
+
+Please see `JuliaConstraints/Constraints.jl/learn.jl` for an extensive example of ICN learning and compositions.
+
+## Contributing
+
+Contributions to this package are more than welcome and can be arbitrarily, and not exhaustively, split as follows:
+- Adding (useful) operations in one of the $4$ existing layers
+- Creating other ICNs from scratch or with only some of the original operations
+- Creating an ICN with a layer structure
+- Creating other compositional networks which target other problems
+- Just making stuff better, faster, user-friendlier, etc.
+
+### Contact
+Do not hesitate to contact me (@azzaare) or other members of JuliaConstraints on GitHub (file an issue), the julialang discourse forum, the julialang slack channel, the julialang zulip server, or the Human of Julia (HoJ) discord server.

docs/Project.toml

@@ -1,3 +1,4 @@
 [deps]
 CompositionalNetworks = "4b67e4b5-442d-4ef5-b760-3f5df3a57537"
+ConstraintDomains = "5800fd60-8556-4464-8d61-84ebf7a0bedb"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -1,8 +1,9 @@
 using CompositionalNetworks
+using ConstraintDomains
 using Documenter
 
 makedocs(;
-    modules=[CompositionalNetworks],
+    modules=[CompositionalNetworks, ConstraintDomains],
     authors="Jean-François Baffier",
     repo="https://github.com/JuliaConstraints/CompositionalNetworks.jl/blob/{commit}{path}#L{line}",
     sitename="CompositionalNetworks.jl",
@@ -13,12 +14,18 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "ICNs" => "icn.md",
         "Layers" => [
             "Transformation" => "transformation.md",
             "Arithmetic" => "arithmetic.md",
             "Aggregation" => "aggregation.md",
             "Comparison" => "comparison.md",
         ],
+        "Domains" => "domain.md",
+        "Library" => [
+            "public.md",
+            "internal.md",
+        ],
     ],
 )
 

docs/src/aggregation.md

@@ -0,0 +1,17 @@
+# Aggregation Layer
+
+The aggregation layer of our basic ICN can be constructed using `aggregation_layer()`.
+
+
+```@docs
+CompositionalNetworks.aggregation_layer
+```
+
+## List of Aggregations
+
+Follows a list of the current operations available in any aggregation layer. Those operations are mutually exclusive.
+
+```@docs
+CompositionalNetworks._ag_sum
+CompositionalNetworks._ag_count_positive
+```

docs/src/arithmetic.md

@@ -0,0 +1,17 @@
+# Arithmetic Layer
+
+The arithmetic layer of our basic ICN can be constructed using `arithmetic_layer()`.
+
+
+```@docs
+CompositionalNetworks.arithmetic_layer
+```
+
+## List of Arithmetic operations 
+
+Follows a list of the current operations available in any arithmetic layer. Those operations are mutually exclusive.
+
+```@docs
+CompositionalNetworks._ar_sum
+CompositionalNetworks._ar_prod
+```

docs/src/comparison.md

@@ -0,0 +1,30 @@
+# Comparison Layer
+
+The comparison layer of our basic ICN can be constructed using `comparison_layer(param=false)`. All operations are mutually exclusive.
+
+```@docs
+CompositionalNetworks.comparison_layer
+```
+
+## Non-parametric comparisons
+
+Follows a list of the current non-parametric operations available in any comparison layer.
+
+```@docs
+CompositionalNetworks._co_identity
+CompositionalNetworks._co_euclidian
+CompositionalNetworks._co_abs_diff_val_vars
+CompositionalNetworks._co_val_minus_vars
+CompositionalNetworks._co_vars_minus_val
+```
+
+## Parametric comparisons
+
+And finally a list of the parametric ones.
+
+```@docs
+CompositionalNetworks._co_abs_diff_val_param
+CompositionalNetworks._co_val_minus_param
+CompositionalNetworks._co_param_minus_val
+CompositionalNetworks._co_euclidian_param
+```

docs/src/domain.md

@@ -0,0 +1,7 @@
+# ConstraintDomains.jl (dependency)
+
+Currently only discrete domains are supported using the following function. 
+
+```@docs
+ConstraintDomains.domain
+```

docs/src/icn.md

@@ -0,0 +1,7 @@
+# ICNs
+
+Currently only construct a generic ICN with all available operations.
+
+```@docs
+CompositionalNetworks.ICN
+```

docs/src/index.md

@@ -2,11 +2,61 @@
 CurrentModule = CompositionalNetworks
 ```
 
-# Compositional Networks
+# CompositionalNetworks.jl
 
-```@index
+`CompositionalNetworks.jl`, a Julia package for Interpretable Compositional Networks (ICN), a variant of neural networks, allowing the user to get interpretable results, unlike regular artificial neural networks.
+
+The current state of our ICN focuses on the composition of error functions for `LocalSearchSolvers.jl`, but produces results independently of it and export it to either/both Julia functions or/and human readable output.
+
+### How does it work?
+
+The package comes with a basic ICN for learning global constraints. The ICN is composed of 4 layers: `transformation`, `arithmetic`, `aggregation`, and `comparison`. Each contains several operations that can be composed in various ways.
+Given a `concept` (a predicate over the variables' domains), a metric (`hamming` by default), and the variables' domains, we learn the binary weights of the ICN. 
+
+## Installation
+
+```julia
+] add CompositionalNetworks
+```
+
+As the package is in a beta version, some changes in the syntax and features are likely to occur. However, those changes should be minimal between minor versions. Please update with caution.
+
+## Quickstart
+
+```julia
+# 4 variables in 1:4
+doms = [domain([1,2,3,4]) for i in 1:4]
+
+# allunique concept (that is used to define the :all_different constraint)
+err = explore_learn_compose(allunique, domains=doms)
+# > interpretation: identity ∘ count_positive ∘ sum ∘ count_eq_left
+
+# test our new error function
+@assert err([1,2,3,3], dom_size = 4) > 0.0
+
+# export an all_different function to file "current/path/test_dummy.jl" 
+compose_to_file!(icn, "all_different", "test_dummy.jl")
 ```
 
-```@autodocs
-Modules = [CompositionalNetworks]
+The output file should produces a function that can be used as follows (assuming the maximum domain size is `7`)
+
+```julia
+import CompositionalNetworks
+
+all_different([1,2,3,4,5,6,7]; dom_size = 7)
+# > 0.0 (which means true, no errors)
 ```
+
+Please see `JuliaConstraints/Constraints.jl/learn.jl` for an extensive example of ICN learning and compositions.
+
+## Contributing
+
+Contributions to this package are more than welcome and can be arbitrarily, and not exhaustively, split as follows:
+- Adding (useful) operations in one of the $4$ existing layers
+- Creating other ICNs from scratch or with only some of the original operations
+- Creating an ICN with a layer structure
+- Creating other compositional networks which target other problems
+- Just making stuff better, faster, user-friendlier, etc.
+
+### Contact
+Do not hesitate to contact me (@azzaare) or other members of JuliaConstraints on GitHub (file an issue), the julialang discourse forum, the julialang slack channel, the julialang zulip server, or the Human of Julia (HoJ) discord server.

docs/src/internal.md

@@ -0,0 +1,11 @@
+# Internals
+
+```@contents
+Pages = ["internal.md"]
+Depth = 5
+```
+
+```@autodocs
+Modules = [CompositionalNetworks]
+Public = false
+```

docs/src/public.md

@@ -0,0 +1,11 @@
+# Public
+
+```@contents
+Pages = ["public.md"]
+Depth = 5
+```
+
+```@autodocs
+Modules = [CompositionalNetworks]
+Private = false
+```

docs/src/transformation.md

@@ -0,0 +1,52 @@
+# Transformation Layer
+
+The transformation layer of our basic ICN can be constructed using `transformation_layer(param=false)`.
+
+
+```@docs
+CompositionalNetworks.transformation_layer
+```
+
+## Non-parametric transformations
+
+Follows a list of the current non-parametric operations available in any transformation layer.
+
+```@docs
+CompositionalNetworks._tr_identity
+CompositionalNetworks._tr_count_eq
+CompositionalNetworks._tr_count_eq_left
+CompositionalNetworks._tr_count_eq_right
+CompositionalNetworks._tr_count_greater
+CompositionalNetworks._tr_count_lesser
+CompositionalNetworks._tr_count_g_left
+CompositionalNetworks._tr_count_l_left
+CompositionalNetworks._tr_count_g_right
+CompositionalNetworks._tr_count_l_right
+CompositionalNetworks._tr_contiguous_vals_minus
+CompositionalNetworks._tr_contiguous_vals_minus_rev
+```
+
+Note that all functions are extended to a vectorized version with the `lazy` function.
+
+```@docs
+CompositionalNetworks.lazy
+```
+
+## Parametric transformations
+
+And finally a list of the parametric ones.
+
+```@docs
+CompositionalNetworks._tr_count_eq_param
+CompositionalNetworks._tr_count_l_param
+CompositionalNetworks._tr_count_g_param
+CompositionalNetworks._tr_count_bounding_param
+CompositionalNetworks._tr_val_minus_param
+CompositionalNetworks._tr_param_minus_val
+```
+
+Note that all functions are extended to a vectorized version with the `lazy_param` function.
+
+```@docs
+CompositionalNetworks.lazy_param
+```

src/CompositionalNetworks.jl

@@ -10,11 +10,12 @@ import ConstraintDomains: _get_domain, _length
 
 # Exports utilities
 export lazy, lazy_param, csv2space
-export hamming
+export hamming, regularization
 
 # Export ICN
 export ICN, compose, show_layers, show_composition, optimize!
 export explore_learn_compose, learn_compose, compose_to_file!
+export transformation_layer, arithmetic_layer, aggregation_layer, comparison_layer
 
 # Include utils
 include("utils.jl")

src/aggregation.jl

@@ -12,7 +12,7 @@ _ag_count_positive(x) = count(y -> y > 0.0, x)
 
 """
     aggregation_layer()
-Generate the layer of aggregation functions of the ICN.
+Generate the layer of aggregations of the ICN. The operations are mutually exclusive, that is only one will be selected.
 """
 function aggregation_layer()
     aggregations = LittleDict{Symbol, Function}(

src/arithmetic.jl

@@ -1,14 +1,18 @@
 """
     _ar_sum(x)
-    _ar_prod(x)
-Reduce `k = length(x)` vectors through sum/product to a single vector.
+Reduce `k = length(x)` vectors through sum to a single vector.
 """
 _ar_sum(x) = reduce((y, z) -> y .+ z, x)
+
+"""
+    _ar_prod(x)
+Reduce `k = length(x)` vectors through product to a single vector.
+"""
 _ar_prod(x) = reduce((y, z) -> y .* z, x)
 
 """
     arithmetic_layer()
-Generate the layer of arithmetic functions of the ICN.
+Generate the layer of arithmetic operations of the ICN. The operations are mutually exclusive, that is only one will be selected.
 """
 function arithmetic_layer()
     arithmetics = LittleDict{Symbol, Function}(