Merge pull request #390 from ReactiveBayes/dev-4.0.0-examples

Changes for GraphPPL v4
ReactiveBayes · Apr 11, 2024 · d1a5c6a · d1a5c6a
2 parents a8de9c0 + 56aed30
commit d1a5c6a
Show file tree

Hide file tree

Showing 177 changed files with 3,665 additions and 5,524 deletions.
diff --git a/Makefile b/Makefile
@@ -23,7 +23,7 @@ benchmark: benchmark_init ## Runs simple benchmark
 .PHONY: docs
 
 doc_init:
-	julia --project=docs -e 'ENV["PYTHON"]=""; using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate();'
+	julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate();'
 
 docs: doc_init ## Generate documentation
 	julia --project=docs/ docs/make.jl

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "ReactiveMP"
 uuid = "a194aa59-28ba-4574-a09c-4a745416d6e3"
 authors = ["Dmitry Bagaev <d.v.bagaev@tue.nl>", "Albert Podusenko <a.podusenko@tue.nl>", "Bart van Erp <b.v.erp@tue.nl>", "Ismail Senoz <i.senoz@tue.nl>"]
-version = "3.14.0"
+version = "4.0.0"
 
 [deps]
 BayesBase = "b4ee3484-f114-42fe-b91c-797d54a0c67e"
@@ -65,7 +65,7 @@ Optimisers = "0.2"
 PositiveFactorizations = "0.2"
 Random = "1.9"
 Requires = "1"
-Rocket = "1.7.0"
+Rocket = "1.8.0"
 SpecialFunctions = "1.4, 2"
 StaticArrays = "1.2"
 StatsBase = "0.33, 0.34"

diff --git a/README.md b/README.md
@@ -24,11 +24,12 @@
 
 # Reactive message passing engine
 
-ReactiveMP.jl is a Julia package that provides an efficient reactive message passing based Bayesian inference engine on a factor graph. The package is a part of the bigger and user-friendly ecosystem for automatic Bayesian inference called [RxInfer](https://github.com/reactivebayes/RxInfer.jl). While ReactiveMP.jl exports only the inference engine, RxInfer provides convenient tools for model and inference constraints specification as well as routines for running efficient inference both for static and real-time datasets. 
+ReactiveMP.jl is a Julia package that provides an efficient reactive message passing based Bayesian inference engine on a factor graph. The package is a part of the bigger and user-friendly ecosystem for automatic Bayesian inference called [RxInfer](https://github.com/reactivebayes/RxInfer.jl). While ReactiveMP.jl exports only the inference engine, RxInfer provides convenient tools for model and inference constraints specification as well as routines for running efficient inference both for static and dynamic datasets. 
 
-# Examples 
+## Examples and tutorials
 
-Tutorials and examples are available in the [RxInfer documentation](https://reactivebayes.github.io/RxInfer.jl/stable/).
+The ReactiveMP.jl package is intended for advanced users with a deep understanding of message passing principles.
+Accesible tutorials and examples are available in the [RxInfer documentation](https://reactivebayes.github.io/RxInfer.jl/stable/).
 
 # License
 

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -15,6 +15,7 @@ ReactiveMP = "a194aa59-28ba-4574-a09c-4a745416d6e3"
 Rocket = "df971d30-c9d6-4b37-b8ff-e965b2cb3a40"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"
+StatsPlots = "f3b207a7-027a-5e70-b257-86293d7955fd"
 
 [compat]
 Documenter = "1.0.0"
diff --git a/docs/make.jl b/docs/make.jl
@@ -8,30 +8,41 @@ DocMeta.setdocmeta!(ReactiveMP, :DocTestSetup, :(using ReactiveMP, Distributions
 
 makedocs(
     modules  = [ ReactiveMP ],
-    warnonly = Documenter.except(:doctest, :eval_block, :example_block, :meta_block, :parse_error, :setup_block),
     clean    = true,
     sitename = "ReactiveMP.jl",
     pages    = [
         "Introduction"    => "index.md",
+        "Library" => [
+            "Factor nodes"         => "lib/nodes.md",
+            "Messages"             => "lib/message.md",
+            "Marginals"            => "lib/marginal.md",
+            "Message update rules" => "lib/rules.md",
+            "Helper utils"         => "lib/helpers.md",
+            "Algebra utils"        => "lib/algebra.md",
+            "Specific factor nodes" => [
+                "Delta" => "lib/nodes/delta.md",
+                "Flow" => "lib/nodes/flow.md",
+                "BIFM" => "lib/nodes/bifm.md",
+                "Logical" => "lib/nodes/logical.md",
+                "Continuous transition" => "lib/nodes/ctransition.md",
+                "Autoregressive" => "lib/nodes/ar.md",
+            ]
+        ],
         "Custom functionality" => [
             "Custom functional form" => "custom/custom-functional-form.md",
-            "Custom addons" => "custom/custom-addons.md"
-        ],
-        "Library" => [
-            "Messages"     => "lib/message.md",
-            "Factor nodes" => [ 
-                "Overview" => "lib/nodes/nodes.md",
-                "Flow"     => "lib/nodes/flow.md"
-            ],
-            "Message update rules" => "lib/rules/rules.md",
-            "Helper utils"        => "lib/helpers.md",
-            "Algebra utils"       => "lib/algebra/common.md",
-            "Exported methods"    => "lib/methods.md"
+            "Custom addons"          => "custom/custom-addons.md"
         ],
-        "Contributing" => "extra/contributing.md",
+        "Extra" => [
+            "Contributing"     => "extra/contributing.md",
+            "Extensions"       => "extra/extensions.md",
+            "Exported methods" => "extra/methods.md"
+        ]
+
     ],
     format   = Documenter.HTML(
-        prettyurls = get(ENV, "CI", nothing) == "true"
+        prettyurls = get(ENV, "CI", nothing) == "true",
+        example_size_threshold = 200 * 1024,
+        size_threshold_warn = 200 * 1024,
     )
 )
 

diff --git a/docs/src/custom/custom-addons.md b/docs/src/custom/custom-addons.md
@@ -62,3 +62,9 @@ here we add the number of operations from the addons that are being multiplied a
 ### More information
 
 For more advanced information check the implementation of the log-scale or memory addons.
+
+### Built-in addons
+
+```@docs 
+ReactiveMP.AddonDebug
+```
diff --git a/docs/src/custom/custom-functional-form.md b/docs/src/custom/custom-functional-form.md
@@ -14,6 +14,7 @@ q(x) = f\left(\frac{\overrightarrow{\mu}(x)\overleftarrow{\mu}(x)}{\int \overrig
 
 ```@docs 
 AbstractFormConstraint
+UnspecifiedFormConstraint
 CompositeFormConstraint
 ```
 
@@ -28,6 +29,7 @@ Every custom functional form must implement a new method for the [`default_form_
 default_form_check_strategy
 FormConstraintCheckEach
 FormConstraintCheckLast
+FormConstraintCheckPickDefault
 ```
 
 ### Prod constraint 
@@ -46,22 +48,6 @@ The main function that a custom functional form must implement, which we referre
 constrain_form
 ```
 
-### Is point mass form constraint (optional)
-
-Every custom functional form may implement a new method for the [`is_point_mass_form_constraint`](@ref) function that returns either `true` or `false`. This is an utility function that simplifes computation of the Bethe Free Energy and is not strictly necessary.
-
-```@docs 
-is_point_mass_form_constraint
-```
-
-### Compatibility with `@constraints` macro (optional)
-
-To make custom functional form constraint compatible with the `@constraints` macro, it must implement a new method for the [`make_form_constraint`](@ref) function.
-
-```@docs 
-make_form_constraint
-```
-
 ## [Custom Functional Form Example](@id custom-functional-form-example)
 
 In this demo we show how to build a custom functional form constraint that is compatible with the `ReactiveMP.jl` inference backend. An important part of the functional forms constraint implementation is the `prod` function in the [`BayesBase`](https://reactivebayes.github.io/BayesBase.jl/stable/) package. We show a relatively simple use-case, which might not be very useful in practice, but serves as a simple step-by-step guide. Assume that we want a specific posterior marginal of some random variable in our model to have a specific Gaussian parametrisation, for example mean-precision. We can use built-in `NormalMeanPrecision` distribution, but we still need to define our custom functional form constraint:
@@ -76,7 +62,6 @@ struct MeanPrecisionFormConstraint <: AbstractFormConstraint end
 Next we define the behaviour of our functional form constraint:
 
 ```@example custom-functional-form-example
-ReactiveMP.is_point_mass_form_constraint(::MeanPrecisionFormConstraint) = false
 ReactiveMP.default_form_check_strategy(::MeanPrecisionFormConstraint)   = FormConstraintCheckLast()
 ReactiveMP.default_prod_constraint(::MeanPrecisionFormConstraint)       = GenericProd()
 

diff --git a/docs/src/extra/contributing.md b/docs/src/extra/contributing.md
@@ -46,7 +46,7 @@ We use default [Julia style guide](https://docs.julialang.org/en/v1/manual/style
 
 - Use 4 spaces for indentation
 - Type names use `UpperCamelCase`. For example: `AbstractFactorNode`, `RandomVariable`, etc..
-- Function names are `lowercase` with underscores, when necessary. For example: `activate!`, `randomvar`, `as_variable`, etc..
+- Function names are `lowercase` with underscores, when necessary. For example: `activate!`, `randomvar`, etc..
 - Variable names and function arguments use `snake_case`
 - The name of a method that modifies its argument(s) must end in `!`
 

diff --git a/docs/src/lib/methods.md → docs/src/extra/methods.md b/docs/src/lib/methods.md → docs/src/extra/methods.md
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -6,18 +6,29 @@ ReactiveMP.jl
 !!! note
     This package exports only an inference engine, for the full ecosystem with convenient model and constraints specification we refer user to the [`RxInfer.jl`](https://github.com/reactivebayes/RxInfer.jl) package and its [documentation](https://reactivebayes.github.io/RxInfer.jl/stable/).
 
+## Ideas and principles behind `ReactiveMP.jl`
+
+`ReactiveMP.jl` is a particular implementation of message passing on factor graphs, which does not create any specific message passing schedule in advance, but rather _reacts_ on changes in the data source (hence _reactive_ in the name of the package). The detailed explanation of the ideas and principles behind the _Reactive Message Passing_ can be found in PhD disseration of _Dmitry Bagaev_ titled [__Reactive Probabilistic Programming for Scalable Bayesian Inference__](https://pure.tue.nl/ws/portalfiles/portal/313860204/20231219_Bagaev_hf.pdf) ([link2](https://research.tue.nl/nl/publications/reactive-probabilistic-programming-for-scalable-bayesian-inferenc), [link3](https://github.com/bvdmitri/phdthesis)).
+
 ## Examples and tutorials
 
-Tutorials and examples are available in the [RxInfer documentation](https://reactivebayes.github.io/RxInfer.jl/stable/).
+The `ReactiveMP.jl` package is intended for advanced users with a deep understanding of message passing principles. 
+Accesible tutorials and examples are available in the [RxInfer documentation](https://reactivebayes.github.io/RxInfer.jl/stable/).
 
 ## Table of Contents
 
 ```@contents
 Pages = [
+  "lib/nodes.md",
   "lib/message.md",
-  "lib/node.md",
-  "lib/math.md",
-  "extra/contributing.md"
+  "lib/marginal.md",
+  "lib/rules.md",
+  "lib/nodes.md",
+  "lib/helpers.md",
+  "lib/algebra.md",
+  "extra/contributing.md",
+  "extra/extensions.md",
+  "extra/methods.md",
 ]
 Depth = 2
 ```

diff --git a/docs/src/lib/algebra.md b/docs/src/lib/algebra.md
@@ -0,0 +1,19 @@
+# [Algebra common utilities](@id lib-helpers-algebra-common)
+
+## [diageye](@id lib-helpers-algebra-diageye)
+
+```@docs
+diageye
+ReactiveMP.CompanionMatrix
+ReactiveMP.PermutationMatrix
+ReactiveMP.StandardBasisVector
+ReactiveMP.GammaShapeLikelihood
+ReactiveMP.ImportanceSamplingApproximation
+ReactiveMP.mul_inplace!
+ReactiveMP.negate_inplace!
+ReactiveMP.mul_trace
+ReactiveMP.rank1update
+ReactiveMP.v_a_vT
+ReactiveMP.powerset
+ReactiveMP.besselmod
+```
diff --git a/docs/src/lib/algebra/common.md b/docs/src/lib/algebra/common.md
diff --git a/docs/src/lib/helpers.md b/docs/src/lib/helpers.md
@@ -3,15 +3,12 @@
 
 `ReactiveMP` implements various structures/functions/methods as "helper" structures that might be useful in various contexts.
 
-## [SkipIndexIterator](@id lib-helpers-skip-index-iterator)
-
 ```@docs
 ReactiveMP.SkipIndexIterator
 ReactiveMP.skipindex
-```
-
-## [FunctionalIndex](@id lib-helpers-functional-index)
-
-```@docs
-ReactiveMP.FunctionalIndex
+ReactiveMP.MacroHelpers.proxy_type
+ReactiveMP.MacroHelpers.ensure_symbol
+ReactiveMP.MacroHelpers.@proxy_methods
+ReactiveMP.MacroHelpers.upper_type
+ReactiveMP.MacroHelpers.bottom_type
 ```
diff --git a/docs/src/lib/marginal.md b/docs/src/lib/marginal.md
@@ -0,0 +1,39 @@
+# [Marginal implementation](@id lib-marginal)
+
+## Marginal type
+
+All marginals are encoded with the type `Marginal`. 
+
+```@docs
+Marginal
+```
+
+From an implementation point a view the `Marginal` structure does nothing but hold some `data` object and redirects most of the statistical related functions to that `data` object. However, this object is used extensively in Julia's multiple dispatch. 
+
+```@docs
+ReactiveMP.getdata(marginal::Marginal)
+ReactiveMP.is_clamped(marginal::Marginal)
+ReactiveMP.is_initial(marginal::Marginal)
+ReactiveMP.getaddons(marginal::Marginal)
+ReactiveMP.as_marginal
+ReactiveMP.to_marginal
+```
+
+```@example marginal
+using ReactiveMP, BayesBase, ExponentialFamily
+
+distribution  = ExponentialFamily.NormalMeanPrecision(0.0, 1.0)
+marginal      = Marginal(distribution, false, true, nothing)
+```
+
+```@example marginal
+mean(marginal), precision(marginal)
+```
+
+```@example marginal
+logpdf(marginal, 1.0)
+```
+
+```@example marginal
+is_clamped(marginal), is_initial(marginal)
+```