GitHub

Basic Usage

This guide demonstrates how to use BipartiteFactorGraphs.jl effectively for different applications.

Creating a Graph

First, create a bipartite factor graph with the desired data types:

using BipartiteFactorGraphs

# Create a graph with Float64 for variable data, String for factor data,
# and Int for edge data
g = BipartiteFactorGraph(Float64, String, Int)

show(g)
BipartiteFactorGraph{Float64, String, Int64} with 0 variables, 0 factors, and 0 edges

The type parameters specify:

  1. The type for variable node data
  2. The type for factor node data
  3. The type for edge data

You can use any Julia type for these parameters, including custom types.

Adding Nodes

Add variable and factor nodes with their associated data using the add_variable! and add_factor! functions:

# Add variables
v1 = add_variable!(g, 1.0)  # returns vertex ID 1
v2 = add_variable!(g, 2.0)  # returns vertex ID 2

# Add factors
f1 = add_factor!(g, "sum")  # returns vertex ID 3
f2 = add_factor!(g, "product")  # returns vertex ID 4


show(g)
BipartiteFactorGraph{Float64, String, Int64} with 2 variables, 2 factors, and 0 edges

Connecting Nodes

Connect variable and factor nodes with edges containing data with the add_edge! function:

# Connect variables and factors
add_edge!(g, v1, f1, 10)  # Add edge between variable v1 and factor f1 with data 10
add_edge!(g, v2, f1, 20)
add_edge!(g, v2, f2, 30)


show(g)
BipartiteFactorGraph{Float64, String, Int64} with 2 variables, 2 factors, and 3 edges
Warning

You are responsible for maintaining the bipartite structure of the graph. The package does not prevent you from adding edges between two variables or two factors, but doing so violates the bipartite property. Always ensure that edges only connect variable nodes to factor nodes. You can use the Graphs.is_bipartite function to check if the graph is bipartite.

BipartiteFactorGraphs.is_bipartite(g)
true

Failing to ensure the bipartite property will most likely lead to wrong results or undefined behavior.

has_edge(g, v1, f1)
true
has_edge(g, v1, f2)
false

Querying the Graph

BipartiteFactorGraphs.jl provides several functions to query the graph structure and retrieve information about nodes and their connections:

Getting all variable and associated data

See variables and get_variable_data

# Get all variables
variables(g)
KeySet for a Dict{Int64, Float64} with 2 entries. Keys:
  2
  1
get_variable_data.(g, variables(g))
2-element Vector{Float64}:
 2.0
 1.0
get_variable_data(g, v1)
1.0

Getting all factor and associated data

See factors and get_factor_data

# Get all factors
factors(g)
KeySet for a Dict{Int64, String} with 2 entries. Keys:
  4
  3
get_factor_data.(g, factors(g))
2-element Vector{String}:
 "product"
 "sum"
get_factor_data(g, f1)
"sum"

Checking node types

See is_variable and is_factor

is_variable(g, v1), is_factor(g, v1)
(true, false)
is_factor(g, f1), is_variable(g, f1)
(true, false)

Getting neighbors

See neighbors, variable_neighbors, and factor_neighbors

variable_neighbors(g, f1)  # Get variable neighbors of factor f1
2-element Vector{Int64}:
 1
 2
factor_neighbors(g, v1)  # Get factor neighbors of variable v1
1-element Vector{Int64}:
 3

Getting the number of nodes

See nv, num_variables, and num_factors

nv(g)
4
num_variables(g)
2
num_factors(g)
2

Getting the number of edges

See ne and edges

ne(g)
3
length(edges(g))
3

Getting data of edges

See get_edge_data

get_edge_data(g, v1, f1)
10