mutable struct BipartiteGraph{I<:Integer, M} <: Graphs.AbstractGraph{I<:Integer}

A bipartite graph representation between two, possibly distinct, sets of vertices (source and dependencies). Maps source vertices, labelled 1:N₁, to vertices on which they depend (labelled 1:N₂).

Fields

• ne

• fadjlist

• badjlist

• metadata

Example

using ModelingToolkit

ne = 4
srcverts = 1:4
depverts = 1:2

# six source vertices
fadjlist = [[1],[1],[2],[2],[1],[1,2]]

# two vertices they depend on
badjlist = [[1,2,5,6],[3,4,6]]

bg = BipartiteGraph(7, fadjlist, badjlist)

Base.isequal(bg1::BipartiteGraph{T}, bg2::BipartiteGraph{T}) where {T <: Integer}

Test whether two BipartiteGraphs are equal.

equation_dependencies(sys::AbstractSystem; variables = unknowns(sys))

Given an AbstractSystem calculate for each equation the variables it depends on.

Notes:

• Variables that are not in variables are filtered out.
• get_variables! is used to determine the variables within a given equation.
• returns a Vector{Vector{Variable}}() mapping the index of an equation to the variables it depends on.

Example:

using ModelingToolkit
using ModelingToolkit: t_nounits as t
@parameters β γ κ η
@variables S(t) I(t) R(t)

rate₁ = β * S * I
rate₂ = γ * I + t
affect₁ = [S ~ S - 1, I ~ I + 1]
affect₂ = [I ~ I - 1, R ~ R + 1]
j₁ = ModelingToolkit.ConstantRateJump(rate₁, affect₁)
j₂ = ModelingToolkit.VariableRateJump(rate₂, affect₂)

# create a JumpSystem using these jumps
@named jumpsys = JumpSystem([j₁, j₂], t, [S, I, R], [β, γ])

# dependency of each jump rate function on unknown variables
equation_dependencies(jumpsys)

# dependency of each jump rate function on parameters
equation_dependencies(jumpsys, variables = parameters(jumpsys))

asgraph(eqdeps, vtois)

Convert a collection of equation dependencies, for example as returned by equation_dependencies, to a BipartiteGraph.

Notes:

• vtois should provide a Dict like mapping from each Variable dependency in eqdeps to the integer idx of the variable to use in the graph.

Example: Continuing the example started in equation_dependencies

digr = asgraph(equation_dependencies(jumpsys),
               Dict(s => i for (i, s) in enumerate(unknowns(jumpsys))))

asgraph(sys::AbstractSystem; variables = unknowns(sys),
        variablestoids = Dict(convert(Variable, v) => i for (i, v) in enumerate(variables)))

Convert an AbstractSystem to a BipartiteGraph mapping the index of equations to the indices of variables they depend on.

Notes:

• Defaults for kwargs creating a mapping from equations(sys) to unknowns(sys) they depend on.
• variables should provide the list of variables to use for generating the dependency graph.
• variablestoids should provide Dict like mapping from a Variable to its Int index within variables.

Example: Continuing the example started in equation_dependencies

digr = asgraph(jumpsys)

variable_dependencies(sys::AbstractSystem; variables = unknowns(sys),
                      variablestoids = nothing)

For each variable, determine the equations that modify it and return as a BipartiteGraph.

Notes:

• Dependencies are returned as a BipartiteGraph mapping variable indices to the indices of equations that modify them.
• variables denotes the list of variables to determine dependencies for.
• variablestoids denotes a Dict mapping Variables to their Int index in variables.

Example: Continuing the example of equation_dependencies

variable_dependencies(jumpsys)

asdigraph(g::BipartiteGraph, sys::AbstractSystem; variables = unknowns(sys),
          equationsfirst = true)

Convert a BipartiteGraph to a LightGraph.SimpleDiGraph.

Notes:

• The resulting SimpleDiGraph unifies the two sets of vertices (equations and then unknowns in the case it comes from asgraph), producing one ordered set of integer vertices (SimpleDiGraph does not support two distinct collections of vertices, so they must be merged).
• variables gives the variables that g are associated with (usually the unknowns of a system).
• equationsfirst (default is true) gives whether the BipartiteGraph gives a mapping from equations to variables they depend on (true), as calculated by asgraph, or whether it gives a mapping from variables to the equations that modify them, as calculated by variable_dependencies.

Example: Continuing the example in asgraph

dg = asdigraph(digr, jumpsys)

eqeq_dependencies(eqdeps::BipartiteGraph{T},
                  vardeps::BipartiteGraph{T}) where {T <: Integer}

Calculate a LightGraph.SimpleDiGraph that maps each equation to equations they depend on.

Notes:

• The fadjlist of the SimpleDiGraph maps from an equation to the equations that modify variables it depends on.
• The badjlist of the SimpleDiGraph maps from an equation to equations that depend on variables it modifies.

Example: Continuing the example of equation_dependencies

eqeqdep = eqeq_dependencies(asgraph(jumpsys), variable_dependencies(jumpsys))

function varvar_dependencies(eqdeps::BipartiteGraph{T},
                             vardeps::BipartiteGraph{T}) where {T <: Integer}
    eqeq_dependencies(vardeps, eqdeps)
end

Calculate a LightGraph.SimpleDiGraph that maps each variable to variables they depend on.

Notes:

• The fadjlist of the SimpleDiGraph maps from a variable to the variables that depend on it.
• The badjlist of the SimpleDiGraph maps from a variable to variables on which it depends.

Example: Continuing the example of equation_dependencies

varvardep = varvar_dependencies(asgraph(jumpsys), variable_dependencies(jumpsys))

map_variables_to_equations(
    sys::ModelingToolkit.AbstractSystem;
    rename_dummy_derivatives
) -> Dict{Union{Num, SymbolicUtils.BasicSymbolic}, Equation}

Given a system that has been simplified via mtkcompile, return a Dict mapping variables of the system to equations that are used to solve for them. This includes observed variables.

Keyword Arguments

• rename_dummy_derivatives: Whether to rename dummy derivative variable keys into their Differential forms. For example, this would turn the key yˍt(t) into Differential(t)(y(t)).