diff --git a/Project.toml b/Project.toml index 40d3057..dfa8301 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "FactorGraph" uuid = "528f6532-2a0d-4856-bb42-8bcefd89a10f" authors = ["Mirsad Cosovic "] -version = "0.1.0" +version = "0.1.1" [deps] Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b" diff --git a/README.md b/README.md index 24c458c..b05760a 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,40 @@ -# GaussBP +# FactorGraph [![Documentation][documentation-badge]][documentation] ![Build][build-badge] -GaussBP is an open-source, easy-to-use simulation tool/solver for researchers and educators provided as a Julia package, with source code released under MIT License. The GaussBP package provides the set of different functions to perform inference over the factor graph in a static or dynamic framework using the linear Gaussian belief propagation (GBP) algorithm. The linear GBP model requires the set of linear equations and provides the minimum mean squared error (MMSE) estimate of the state variables. +FactorGraph is an open-source, easy-to-use simulation tool/solver for researchers and educators provided as a Julia package, with source code released under MIT License. The FactorGraph package provides the set of different functions to perform inference over the factor graph in a static or dynamic framework using the linear Gaussian belief propagation (GBP) algorithm. The linear GBP model requires the set of linear equations and provides the minimum mean squared error (MMSE) estimate of the state variables. We have tested and verified simulation tool using different scenarios to the best of our ability. As a user of this simulation tool, you can help us to improve future versions, we highly appreciate your feedback about any errors, inaccuracies, and bugs. For more information, please visit [documentation][documentation] site. --- #### Requirement -GaussBP requires Julia 1.6 and higher. +FactorGraph requires Julia 1.6 and higher. --- #### Installation -To install the GaussBP package, run the following command: +To install the FactorGraph package, run the following command: ```julia-repl -pkg> add GaussBP +pkg> add FactorGraph ``` -To use GaussBP package, add the following code to your script, or alternatively run the same command in Julia REPL: +To use FactorGraph package, add the following code to your script, or alternatively run the same command in Julia REPL: ```julia-repl -using GaussBP +using FactorGraph ``` --- #### Quick start -Following examples are intended for a quick introduction to GaussBP package. +Following examples are intended for a quick introduction to FactorGraph package. - Synchronous message passing schedule using the native GBP algorithm. ```julia-repl -using GaussBP +using FactorGraph gbp = graphicalModel("data33_14.h5") # initialize the graphical model using HDF5 input for iteration = 1:200 # the GBP inference @@ -47,7 +47,7 @@ displayData(gbp) # show results - Synchronous message passing schedule using the efficient GBP algorithm. ```julia-repl -using GaussBP +using FactorGraph H = [1.0 0.0 0.0; 1.5 0.0 2.0; 0.0 3.1 4.6] # jacobian matrix z = [0.5; 0.8; 4.1] # observation vector diff --git a/docs/src/index.md b/docs/src/index.md index de54b3f..b158212 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,7 +1,7 @@ -GaussBP +FactorGraph ============= -The GaussBP package provides the set of different functions to perform inference over the factor graph in a static or dynamic framework using the linear Gaussian belief propagation (GBP) algorithm. The linear GBP model requires the set of linear equations and provides the minimum mean squared error (MMSE) estimate of the state variables. +The FactorGraph package provides the set of different functions to perform inference over the factor graph in a static or dynamic framework using the linear Gaussian belief propagation (GBP) algorithm. The linear GBP model requires the set of linear equations and provides the minimum mean squared error (MMSE) estimate of the state variables. The software package includes algorithms based on the [synchronous message passing schedule] (@ref synchronous): - [vanilla GBP algorithm] (@ref vanillaGBP); @@ -16,28 +16,28 @@ The software package also includes a message passing algorithm that allows exact --- #### Requirement -GaussBP requires Julia 1.6 and higher. +FactorGraph requires Julia 1.6 and higher. --- #### Installation -To install the GaussBP package, run the following command: +To install the FactorGraph package, run the following command: ```julia-repl -pkg> add GaussBP +pkg> add FactorGraph ``` -To use GaussBP package, add the following code to your script, or alternatively run the same command in Julia REPL: +To use FactorGraph package, add the following code to your script, or alternatively run the same command in Julia REPL: ```julia-repl -using GaussBP +using FactorGraph ``` --- #### Quick start -Following examples are intended for a quick introduction to GaussBP package. +Following examples are intended for a quick introduction to FactorGraph package. - Synchronous message passing schedule using the native GBP algorithm. ```julia-repl -using GaussBP +using FactorGraph gbp = graphicalModel("data33_14.h5") # initialize the graphical model using HDF5 input for iteration = 1:200 # the GBP inference @@ -50,7 +50,7 @@ displayData(gbp) # show results - Synchronous message passing schedule using the efficient GBP algorithm. ```julia-repl -using GaussBP +using FactorGraph H = [1.0 0.0 0.0; 1.5 0.0 2.0; 0.0 3.1 4.6] # jacobian matrix z = [0.5; 0.8; 4.1] # observation vector @@ -66,7 +66,7 @@ marginal(gbp) # compute marginals - Synchronous message passing schedule using the GBP and Kahan-Babuska algorithm with the plotting of the marginal mean through iteration. ```julia-repl -using GaussBP +using FactorGraph using Plots gbp = graphicalModel("data33_14.h5") # initialize the graphical model @@ -82,7 +82,7 @@ plot(collect(1:50), x6) # show plot - Synchronous message passing schedule using the native GBP algorithm in the dynamic framework. ```julia-repl -using GaussBP +using FactorGraph H = [1.0 0.0 0.0; 1.5 0.0 2.0; 0.0 3.1 4.6] # jacobian matrix z = [0.5; 0.8; 4.1] # observation vector @@ -108,7 +108,7 @@ displayData(gbp) # show results - Synchronous message passing schedule using the native GBP algorithm in the dynamic ageing framework. ```julia-repl -using GaussBP +using FactorGraph H = [1.0 0.0 0.0; 1.5 0.0 2.0; 0.0 3.1 4.6] # jacobian matrix z = [0.5; 0.8; 4.1] # observation vector @@ -137,7 +137,7 @@ displayData(gbp) # show results - Forward–backward algorithm over the tree factor graph. ```julia-repl -using GaussBP +using FactorGraph H = [1 0 0 0 0; 6 8 2 0 0; 0 5 0 0 0; # jacobian matrix 0 0 2 0 0; 0 0 3 8 2] diff --git a/docs/src/man/graphicalmodel.md b/docs/src/man/graphicalmodel.md index 4978d47..fb50be6 100644 --- a/docs/src/man/graphicalmodel.md +++ b/docs/src/man/graphicalmodel.md @@ -1,11 +1,11 @@ # [Graphical Model](@id graphicalModel) -The GaussBP supports the composite type `GraphicalModel` related with the [synchronous message passing schedule] (@ref synchronous), with three fields: +The FactorGraph supports the composite type `GraphicalModel` related with the [synchronous message passing schedule] (@ref synchronous), with three fields: - `FactorGraph`; - `Inference`; - `SystemModel`. -The subtype `FactorGraph` describes the factor graph obtained based on the input data. The GBP inference and marginal values are kept in the subtype `Inference`. The system of the linear equations being solved is preserved in the subtype `SystemModel`. Note that the function `graphicalModel()` returns the main GaussBP composite type `GraphicalModel` with all subtypes. +The subtype `FactorGraph` describes the factor graph obtained based on the input data. The GBP inference and marginal values are kept in the subtype `Inference`. The system of the linear equations being solved is preserved in the subtype `SystemModel`. Note that the function `graphicalModel()` returns the main FactorGraph composite type `GraphicalModel` with all subtypes. In addition, we also provide several functions for factor graph manipulation. diff --git a/docs/src/man/graphicalmodeltree.md b/docs/src/man/graphicalmodeltree.md index d6653f6..778e333 100644 --- a/docs/src/man/graphicalmodeltree.md +++ b/docs/src/man/graphicalmodeltree.md @@ -1,6 +1,6 @@ # [Graphical Model Tree](@id graphicalModelTree) -The GaussBP supports the composite type `GraphicalModelTree` related with the [forward–backward message passing] (@ref treeGBP), with three fields: +The FactorGraph supports the composite type `GraphicalModelTree` related with the [forward–backward message passing] (@ref treeGBP), with three fields: - `FactorGraphTree`; - `Inference`; - `SystemModel`. diff --git a/docs/src/man/inference.md b/docs/src/man/inference.md index 0430252..5e728ef 100644 --- a/docs/src/man/inference.md +++ b/docs/src/man/inference.md @@ -1,6 +1,6 @@ # [Inference](@id vanilla) -We advise the reader to read the [theoretical background] (@ref theoretical) which provides a detailed description of the inference algorithms. To exchange information over the factor graph, the GaussBP provides three inference approaches: +We advise the reader to read the [theoretical background] (@ref theoretical) which provides a detailed description of the inference algorithms. To exchange information over the factor graph, the FactorGraph provides three inference approaches: - [vanilla GBP algorithm] (@ref vanillaGBP), - [computation-efficient GBP algorithm] (@ref efficientGBP), - [computation-efficient kahan–babuška GBP algorithm] (@ref kahanGBP). @@ -47,7 +47,7 @@ messageDampFactorVariableKahan(gbp); meanDampFactorVariableKahan(gbp) --- #### Marginal inference -To compute marginals the GaussBP provides the function: +To compute marginals the FactorGraph provides the function: ```julia-repl marginal(gbp) ``` diff --git a/docs/src/man/inferencetree.md b/docs/src/man/inferencetree.md index b8427fc..93cb477 100644 --- a/docs/src/man/inferencetree.md +++ b/docs/src/man/inferencetree.md @@ -1,6 +1,6 @@ # [Inference](@id inferenceTree) -To exchange information over the tree factor graph, the GaussBP provides forward–backward algorithm. We advise the reader to read the [forward–backward algorithm] (@ref treeGBP) which provides a detailed description of the inference algorithm. +To exchange information over the tree factor graph, the FactorGraph provides forward–backward algorithm. We advise the reader to read the [forward–backward algorithm] (@ref treeGBP) which provides a detailed description of the inference algorithm. Each of the inference functions accepts only the composite type `GraphicalModelTree`, i.e., an output variable of the function `gbp = graphicalModelTree()`. @@ -23,7 +23,7 @@ backwardFactorVariable(gbp) --- #### Marginal inference -To compute marginals the GaussBP provides the function: +To compute marginals the FactorGraph provides the function: ```julia-repl marginal(gbp) ``` diff --git a/docs/src/man/input.md b/docs/src/man/input.md index 229372d..070d955 100644 --- a/docs/src/man/input.md +++ b/docs/src/man/input.md @@ -1,6 +1,6 @@ # [Input Data](@id inputdata) -The GaussBP package supports HDF5 and XLSX input files or passing data directly via command-line arguments. The basic input data structure describing a linear system of equations includes the `jacobian` matrix containing coefficients of the equations, while vectors `observation` and `variance` represent measurement values and measurement variances, respectively. The functions `graphicalModel()` and `graphicalModelTree()` accept `jacobian`, `observation` and `variance` variables to form appropriate probabilistic graphical model. Note that, with large-scale systems, we strongly recommend using the HDF5 file data format. +The FactorGraph package supports HDF5 and XLSX input files or passing data directly via command-line arguments. The basic input data structure describing a linear system of equations includes the `jacobian` matrix containing coefficients of the equations, while vectors `observation` and `variance` represent measurement values and measurement variances, respectively. The functions `graphicalModel()` and `graphicalModelTree()` accept `jacobian`, `observation` and `variance` variables to form appropriate probabilistic graphical model. Note that, with large-scale systems, we strongly recommend using the HDF5 file data format. @@ -41,13 +41,13 @@ The type and structure of the arguments must be: --- #### Data structure -The GaussBP package uses `jacobian` input data format for all analyses. Jacobian input data contains coefficients of the linear system of the equations. The structure of the `jacobian` variable being loaded from HDF5 or XLSX input files is given below: +The FactorGraph package uses `jacobian` input data format for all analyses. Jacobian input data contains coefficients of the linear system of the equations. The structure of the `jacobian` variable being loaded from HDF5 or XLSX input files is given below: - column 1: row indices of the corresponding jacobian matrix; - column 2: column indices of the corresponding jacobian matrix; - column 3: coefficient values of the corresponding jacobian matrix. Passing data directly via command-line arguments allows the use of a sparse or full matrix to describe the `jacobian` variable. -The `observation` and `variance` input data are used for all analyses available in the GaussBP package and contains measurement mean and variance values. +The `observation` and `variance` input data are used for all analyses available in the FactorGraph package and contains measurement mean and variance values. --- diff --git a/docs/src/man/output.md b/docs/src/man/output.md index 2dc36a7..fe554b7 100644 --- a/docs/src/man/output.md +++ b/docs/src/man/output.md @@ -20,7 +20,7 @@ Fields `mean` and `variance` define state variable marginal distributions. The `Inference` field contains the GBP algorithm results. To describe the outputs, we will use the example shown below. ```julia-repl -using GaussBP +using FactorGraph # x1 x2 x3 H = [1.0 0.0 0.0; # f1 diff --git a/docs/src/man/outputtree.md b/docs/src/man/outputtree.md index a15058c..c95b926 100644 --- a/docs/src/man/outputtree.md +++ b/docs/src/man/outputtree.md @@ -20,7 +20,7 @@ Fields `mean` and `variance` define state variable marginal distributions. The `Inference` field contains the GBP algorithm results. To describe the outputs, we will use the example shown below. ```julia-repl -using GaussBP +using FactorGraph # x1 x2 x3 x4 H = [1.0 0.0 0.0 0.0; # f1 @@ -95,7 +95,7 @@ julia> [T.fromFactor T.toVariable T.meanFactorVariable T.varianceFactorVariable] ``` The first row defines the message from factor node ``f_3`` to variable node ``x_1``. Zero rows are initialized for messages to be calculated in the next forward and backward steps. -The message passing steps from variable nodes to factor nodes and from factor nodes to variable nodes are then applied recursively until messages have been propagated along every link, and the root node has received messages from all of its neighbours. The GaussBP keeps flag `gbp.graph.forward` to signal that moment. Therefore, a complete forward step can be done using: +The message passing steps from variable nodes to factor nodes and from factor nodes to variable nodes are then applied recursively until messages have been propagated along every link, and the root node has received messages from all of its neighbours. The FactorGraph keeps flag `gbp.graph.forward` to signal that moment. Therefore, a complete forward step can be done using: ```julia-repl while gbp.graph.forward forwardVariableFactor(gbp) @@ -135,7 +135,7 @@ julia> [T.fromFactor T.toVariable T.meanFactorVariable T.varianceFactorVariable] ``` The first two rows are obtained using forward steps. The third row defines the message from factor node ``f_2`` to variable node ``x_1``, the fourth row keeps the message from factor node ``f_2`` to variable node ``x_2``. -Thus, the backward recursion starts when the root node received messages from all of its neighbours. It can therefore send out messages to all of its neighbours. These in turn will then have received messages from all of their neighbours and so can send out messages along the links going away from the root, and so on. In this way, messages are passed outwards from the root all the way to the leaves. The GaussBP keeps flag `gbp.graph.backward` to signal that moment. Therefore, a complete backward step can be done using: +Thus, the backward recursion starts when the root node received messages from all of its neighbours. It can therefore send out messages to all of its neighbours. These in turn will then have received messages from all of their neighbours and so can send out messages along the links going away from the root, and so on. In this way, messages are passed outwards from the root all the way to the leaves. The FactorGraph keeps flag `gbp.graph.backward` to signal that moment. Therefore, a complete backward step can be done using: ```julia-repl while gbp.graph.backward backwardVariableFactor(gbp) diff --git a/docs/src/man/utility.md b/docs/src/man/utility.md index d0c6a44..76e6f73 100644 --- a/docs/src/man/utility.md +++ b/docs/src/man/utility.md @@ -1,6 +1,6 @@ # [Utility Functions](@id utilityfunction) -The GaussBP provides several utility functions to evaluate and compare obtained results. +The FactorGraph provides several utility functions to evaluate and compare obtained results. --- #### The WLS results