API

Network([g,] vertexf, edgef; kwarg...)

Construct a Network object from a graph g and edge and component models vertexf and edgef.

Arguments:

• g::AbstractGraph: The graph on which the network is defined. Optional, can be ommittet if all component models have a defined graphelement. See vidx and src/dst keywors for VertexModel and EdgeModel constructors respectively.

• vertexm: A single VertexModel or a vector of VertexModel objects. The order of the vertex models must mirror the order of the vertices(g) iterator.

• edgem: A single EdgeModel or a vector of EdgeModel objects. The order of the edge models must mirror the order of the edges(g) iterator.

Optional keyword arguments:

• execution=SequentialExecution{true}(): Execution model of the network. E.g. SequentialExecution, KAExecution, PolyesterExecution or ThreadedExecution.
• aggregator=execution isa SequentialExecution ? SequentialAggregator(+) : PolyesterAggregator(+): Aggregation function applied to the edge models. E.g. SequentialAggregator, PolyesterAggregator, ThreadedAggregator, SparseAggregator.
• check_graphelement=true: Check if the graphelement metadata is consistent with the graph.
• dealias=false Check if the components alias eachother and create copies if necessary. This is necessary if the same component model is referenced in multiple places in the Network but you want to dynamicially asign metadata, such as initialization information to specific instances.
• verbose=false: Show additional information during construction.

Network(nw::Network; g, vertexm, edgem, kwargs...)

Rebuild the Network with same graph and vertex/edge models but possibly different kwargs.

dim(nw::Network)

Returns the number of dynamic states in the network, corresponts to the length of the flat state vector.

pdim(nw::Network)

Returns the number of parameters in the network, corresponts to the length of the flat parameter vector.

VertexModel(; kwargs...)

Build a VertexModel according to the keyword arguments.

Main Arguments:

• f=nothing: Dynamic function of the component. Can be nothing if dim is 0.
• g: Output function of the component. Usefull helpers: StateMask
• sym/dim: Symbolic names of the states. If dim is provided, sym is set automaticially.
• outsym/outdim: Symbolic names of the outputs. If outdim is provided, outsym is set automaticially. Can be infered automaticially if g isa StateMask.
• psym/pdim=0: Symbolic names of the parameters. Ifpdimis provided,psym` is set automaticially.
• mass_matrix=I: Mass matrix of component. Can be a vector v and is then interpreted as Diagonal(v).
• name=dim>0 ? :VertexM : :StaticVertexM: Name of the component.

Optional Arguments:

• insym/indim: Symbolic names of the inputs. If indim is provided, insym is set automaticially.
• vidx: Index of the vertex in the graph, enables graphless constructor.
• ff: FeedForwardType of component. Will be typically infered from g automaticially.
• obssym/obsf: Define additional "observable" states.
• symmetadata/metadata: Provide prefilled metadata dictionaries.
• extin=nothing: Define "external" inputs for the model with Network indices, i.e. extin=[VIndex(7,:x), ..]. Those inputs will be provided as another input vector f(x, in, extin, p, t) and g(y, x, in, extin, p, t).

All Symbol arguments can be used to set default values, i.e. psym=[:K=>1, :p].

EdgeModel(; kwargs...)

Build a EdgeModel according to the keyword arguments.

Main Arguments:

• f=nothing: Dynamic function of the component. Can be nothing if dim is 0.
• g: Output function of the component. Usefull helpers: AntiSymmetric, Symmetric, Fiducial, Directed and StateMask.
• sym/dim: Symbolic names of the states. If dim is provided, sym is set automaticially.
• outsym/outdim: Symbolic names of the outputs. If outdim is provided, outsym is set automaticially. In general, outsym for edges isa named tuple (; src, dst). However, depending on the g function, it might be enough to provide a single vector or even nothing (e.g. AntiSymmetric(StateMask(1:2))). See Building EdgeModels for examples.
• psym/pdim=0: Symbolic names of the parameters. Ifpdimis provided,psym` is set automaticially.
• mass_matrix=I: Mass matrix of component. Can be a vector v and is then interpreted as Diagonal(v).
• name=dim>0 ? :EdgeM : :StaticEdgeM: Name of the component.

Optional Arguments:

• insym/indim: Symbolic names of the inputs. If indim is provided, insym is set automaticially. For edges, insym is a named tuple (; src, dst). If give as vector tuple is created automaticially.
• src/dst: Index or name of the vertices at src and dst end. Enables graphless constructor.
• ff: FeedForwardType of component. Will be typically infered from g automaticially.
• obssym/obsf: Define additional "observable" states.
• symmetadata/metadata: Provide prefilled metadata dictionaries.
• extin=nothing: Define "external" inputs for the model with Network indices, i.e. extin=[VIndex(7,:x), ..]. Those inputs will be provided as another input vector f(x, insrc, indst, extin, p, t) and g(ysrc, ydst, x, insrc, indst, extin, p, t).

All Symbol arguments can be used to set default values, i.e. psym=[:K=>1, :p].

VertexModel(sys::ODESystem, inputs, outputs;
            verbose=false, name=getname(sys), extin=nothing, ff_to_constraint=true, kwargs...)

Create a VertexModel object from a given ODESystem created with ModelingToolkit. You need to provide 2 lists of symbolic names (Symbol or Vector{Symbols}):

• inputs: names of variables in you equation representing the aggregated edge states
• outputs: names of variables in you equation representing the node output

Additional kw arguments:

• name: Set name of the component model. Will be lifted from the ODESystem name.
• extin=nothing: Provide external inputs as pairs, i.e. extin=[:extvar => VIndex(1, :a)] will bound the variable extvar(t) in the equations to the state a of the first vertex.
• ff_to_constraint=true: Controlls, whether output transformations g which depend on inputs should be transformed into constraints. Defaults to true since ND.jl does not handle vertices with FF yet.

EdgeModel(sys::ODESystem, srcin, srcout, dstin, dstout;
          verbose=false, name=getname(sys), extin=nothing, ff_to_constraint=false, kwargs...)

Create a EdgeModel object from a given ODESystem created with ModelingToolkit. You need to provide 4 lists of symbolic names (Symbol or Vector{Symbols}):

• srcin: names of variables in you equation representing the node state at the source
• dstin: names of variables in you equation representing the node state at the destination
• srcout: names of variables in you equation representing the output at the source
• dstout: names of variables in you equation representing the output at the destination

Additional kw arguments:

• name: Set name of the component model. Will be lifted from the ODESystem name.
• extin=nothing: Provide external inputs as pairs, i.e. extin=[:extvar => VIndex(1, :a)] will bound the variable extvar(t) in the equations to the state a of the first vertex.
• ff_to_constraint=false: Controlls, whether output transformations g which depend on inputs should be transformed into constraints.

EdgeModel(sys::ODESystem, srcin, dstin, AntiSymmetric(dstout); kwargs...)

Create a EdgeModel object from a given ODESystem created with ModelingToolkit for single sided models.

Here you only need to provide one list of output symbols: dstout. To make it clear how to handle the single-sided output definiton, you musst wrap the symbol vector in

• AntiSymmetric(dstout),
• Symmetric(dstout), or
• Directed(dstout).

Additional kwargs are the same as for the double-sided EdgeModel MTK constructor.

StateMask(i::AbstractArray)
StateMaks(i::Number)

A StateMask is a predefined output function. It can be used to define the output of a component model by picking from the internal state.

I.e. g=StateMask(2:3) in a vertex function will output the internal states 2 and 3. In many contexts, StateMasks can be constructed implicitly by just providing the indices, e.g. g=1:2.

For EdgeModel this needs to be combined with a Directed, Symmetric, AntiSymmetric or Fiducial coupling, e.g. g=Fiducial(1:2, 3:4) forwards states 1:2 to dst and states 3:4 to src.

Symmetric(g)

Wraps a single-sided output function g turns it into a double sided output function which applies

y_dst = g(...)
y_src = y_dst

g can be a Number/AbstractArray to impicitly wrap the corresponding StateMask.

See also AntiSymmetric, Directed, Fiducial and StateMask.

AntiSymmetric(g_dst)

Wraps a single-sided output function g_dst turns it into a double sided output function which applies

y_dst = g_dst(...)
y_src = -y_dst

g_dst can be a Number/AbstractArray to impicitly wrap the corresponding StateMask.

See also Symmetric, Directed, Fiducial and StateMask.

Directed(g_dst)

Wraps a single-sided output function g_dst turns it into a double sided output function which applies

y_dst = g_dst(...)

With Directed there is no output for the src side. g_dst can be a Number/AbstractArray to impicitly wrap the corresponding StateMask.

See also AntiSymmetric, Symmetric, Fiducial and StateMask.

Fiducial(g_src, g_dst)

Wraps two single-sided output function g_src and g_dst and turns them into a double sided output function which applies

y_dst = g_src(...)
y_src = g_dst(...)

g can be a Number/AbstractArray to impicitly wrap the corresponding StateMask.

See also AntiSymmetric, Directed, Fiducial and StateMask.

fftype(x)

Retrieve the feed forward trait of x.

dim(c::ComponentModel)::Int

Retrieve the dimension of the component.

sym(c::ComponentModel)::Vector{Symbol}

Retrieve the symbols of the component.

outdim(c::VertexModel)::Int
outdim(c::EdgeModel)::@NamedTuple(src::Int, dst::Int)

Retrieve the output dimension of the component

outsym(c::VertexModel)::Vector{Symbol} outsym(c::EdgeModel)::@NamedTuple{src::Vector{Symbol}, dst::Vector{Symbol}}

Retrieve the output symbols of the component.

pdim(c::ComponentModel)::Int

Retrieve the parameter dimension of the component.

psym(c::ComponentModel)::Vector{Symbol}

Retrieve the parameter symbols of the component.

obssym(c::ComponentModel)::Vector{Symbol}

Retrieve the observation symbols of the component.

hasinsym(c::ComponentModel)

Checks if the optioan field insym is present in the component model.

insym(c::VertexModel)::Vector{Symbol}
insym(c::EdgeModel)::@NamedTuple{src::Vector{Symbol}, dst::Vector{Symbol}}

Musst be called after hasinsym/hasindim returned true. Gives the insym vector(s). For vertex model just a single vector, for edges it returns a named tuple (; src, dst) with two symbol vectors.

hasindim(c::ComponentModel)

Checks if the optioan field insym is present in the component model.

indim(c::VertexModel)::Int
indim(c::EdgeModel)::@NamedTuple{src::Int,dst::Int}

Musst be called after hasinsym/hasindim returned true. Gives the input dimension(s).

abstract type FeedForwardType end

Abstract supertype for the FeedForwardType traits.

PureFeedForward <: FeedForwardType

Trait for component output functions g that have pure feed forward behavior (do not depend on x):

g!(outs..., ins..., p, t)

See also FeedForward, NoFeedForward and PureStateMap.

FeedForward <: FeedForwardType

Trait for component output functions g that have feed forward behavior. May depend on everything:

g!(outs..., x, ins..., p, t)

See also PureFeedForward, NoFeedForward and PureStateMap.

NoFeedForward <: FeedForwardType

Trait for component output functions g that have no feed forward behavior (do not depend on inputs):

g!(outs..., x, p, t)

See also PureFeedForward, FeedForward and PureStateMap.

PureStateMap <: FeedForwardType

Trait for component output functions g that only depends on state:

g!(outs..., x)

See also PureFeedForward, FeedForward and NoFeedForward.

NWParameter(nw_or_nw_wraper, pflat)

Indexable wrapper for flat parameter array pflat. Needs Network or wrapper of Network, e.g. ODEProblem.

p = NWParameter(nw)
p.v[idx, :sym] # get parameter :sym of vertex idx
p.e[idx, :sym] # get parameter :sym of edge idx
p[s::Union{VPIndex, EPIndex}] # get parameter for specific index

Get flat array representation using pflat. The order of parameters in the flat representation corresponds to the order given by parameter_symbols.

NWParameter(nw_or_nw_wraper;
            ptype=Vector{Float64}, pfill=filltype(ptype), default=true)

Creates "empty" NWParameter object for the Network/Wrapper nw with flat type ptype. The array will be prefilled with pfill (defaults to NaN).

If default=true the default parameter values attached to the network components will be loaded.

NWParameter(p::NWParameter; ptype=typeof(p.pflat))

Create NWParameter based on other parameter object, just convert type.

NWParameter(int::SciMLBase.DEIntegrator)

Create NWParameter object from integrator.

pflat(p::NWParameter)
pflat(s::NWState)

Retrieve the wrapped flat array representation of the parameters. The order of parameters in this flat representation corresponds exactly to the order given by parameter_symbols.

SymbolicIndexingInterface.parameter_symbols(nw::Network)

Returns a vector of all symbolic network indices which in the same order as the flat parameter vector.

See also: NWParameter, NWState, pflat.

NWState(nw_or_nw_wrapper, uflat, [pflat], [t])

Indexable wrapper for flat state & parameter array. Needs Network or wrapper of Network, e.g. ODEProblem.

s = NWState(nw)
s.v[idx, :sym] # get state :sym of vertex idx
s.e[idx, :sym] # get state :sym of edge idx
s.p.v[idx, :sym] # get parameter :sym of vertex idx
s.p.e[idx, :sym] # get parameter :sym of edge idx
s[s::Union{VIndex, EIndex, EPIndex, VPIndex}] # get parameter for specific index

Get flat array representation using uflat and pflat. The order of states in the flat representation corresponds to the order given by variable_symbols, and the order of parameters corresponds to parameter_symbols.

NWState(nw_or_nw_wrapper;
        utype=Vector{Float64}, ufill=filltype(utype),
        ptype=Vector{Float64}, pfill=filltype(ptype), default=true)

Creates "empty" NWState object for the Network/Wrapper nw with flat types utype & ptype. The arrays will be prefilled with ufill and pfill respectively (defaults to NaN).

If default=true the default state & parameter values attached to the network components will be loaded.

NWState(p::NWState; utype=typeof(uflat(s)), ptype=typeof(pflat(s)))

Create NWState based on other state object, just convert types.

NWState(p::NWParameter; utype=Vector{Float64}, ufill=filltype(utype), default=true)

Create NWState based on existing NWParameter object.

NWState(int::SciMLBase.DEIntegrator)

Create NWState object from integrator.

uflat(s::NWState)

Retrieve the wrapped flat array representation of the state. The order of states in this flat representation corresponds exactly to the order given by variable_symbols.

SymbolicIndexingInterface.variable_symbols(nw::Network)

Returns a vector of all symbolic network indices which in the same order as the flat state vector.

See also: NWState, uflat.

VIndex{C,S} <: SymbolicStateIndex{C,S}
idx = VIndex(comp, sub)

A symbolic index for a vertex state variable.

• comp: the component index, either int or a collection of ints
• sub: the subindex, either int, symbol or a collection of those.

VIndex(1, :P)      # vertex 1, variable :P
VIndex(1:5, 1)     # first state of vertices 1 to 5
VIndex(7, (:x,:y)) # states :x and :y of vertex 7
VIndex(2)          # references the second vertex model

Can be used to index into objects supporting the SymbolicIndexingInterface, e.g. NWState, NWParameter or ODESolution.

See also: EIndex, VPIndex, EPIndex

EIndex{C,S} <: SymbolicStateIndex{C,S}
idx = EIndex(comp, sub)

A symbolic index for an edge state variable.

• comp: the component index, either int or a collection of ints
• sub: the subindex, either int, symbol or a collection of those.

EIndex(1, :P)      # edge 1, variable :P
EIndex(1:5, 1)     # first state of edges 1 to 5
EIndex(7, (:x,:y)) # states :x and :y of edge 7
EIndex(2)          # references the second edge model

Can be used to index into objects supporting the SymbolicIndexingInterface, e.g. NWState, NWParameter or ODESolution.

See also: VIndex, VPIndex, EPIndex

VPIndex{C,S} <: SymbolicStateIndex{C,S}
idx = VPIndex(comp, sub)

A symbolic index into the parameter a vertex:

• comp: the component index, either int or a collection of ints
• sub: the subindex, either int, symbol or a collection of those.

Can be used to index into objects supporting the SymbolicIndexingInterface, e.g. NWParameter or ODEProblem.

See also: EPIndex, VIndex, EIndex

EPIndex{C,S} <: SymbolicStateIndex{C,S}
idx = VEIndex(comp, sub)

A symbolic index into the parameter a vertex:

• comp: the component index, either int or a collection of ints
• sub: the subindex, either int, symbol or a collection of those.

Can be used to index into objects supporting the SymbolicIndexingInterface, e.g. NWParameter or ODEProblem.

See also: VPIndex, VIndex, EIndex

@obsex([name =] expression)

Define observable expressions, which are simple combinations of knonw states/parameters/observables. @obsex(...) returns an ObservableExpression which can be used as an symbolic index. This is mainly intended for quick plotting or export of common "derived" variables, such as the argument of a 2-component complex state. For example:

sol(t; idxs=@obsex(arg = atan(VIndex(1,:u_i), VIndex(1,:u_r))]
sol(t; idxs=@obsex(δrel = VIndex(1,:δ) - VIndex(2,:δ)))

vidxs([inpr], components=:, variables=:) :: Vector{VIndex}

Generate vector of symbolic indexes for vertices.

• inpr: Only needed for name matching or : access. Can be Network, sol, prob, ...
• components: Number/Vector, :, Symbol (name matches), String/Regex (name contains)
• variables: Symbol/Number/Vector, :, String/Regex (all sym containing)

Examples:

vidxs(nw)                 # all vertex state indices
vidxs(1:2, :u)            # [VIndex(1, :u), VIndex(2, :u)]
vidxs(nw, :, [:u, :v])    # [VIndex(i, :u), VIndex(i, :v) for i in 1:nv(nw)]
vidxs(nw, "ODEVertex", :) # all symbols of all vertices with name containing "ODEVertex"

vidxs([inpr], components=:, variables=:) :: Vector{EIndex}

Generate vector of symbolic indexes for edges.

• inpr: Only needed for name matching or : access. Can be Network, sol, prob, ...
• components: Number/Vector, :, Symbol (name matches), String/Regex (name contains)
• variables: Symbol/Number/Vector, :, String/Regex (all sym containing)

Examples:

eidxs(nw)                # all edge state indices
eidxs(1:2, :u)           # [EIndex(1, :u), EIndex(2, :u)]
eidxs(nw, :, [:u, :v])   # [EIndex(i, :u), EIndex(i, :v) for i in 1:ne(nw)]
eidxs(nw, "FlowEdge", :) # all symbols of all edges with name containing "FlowEdge"

vpidxs([inpr], components=:, variables=:) :: Vector{VPIndex}

Generate vector of symbolic indexes for parameters. See vidxs for more information.

epidxs([inpr], components=:, variables=:) :: Vector{EPIndex}

Generate vector of symbolic indexes for parameters. See eidxs for more information.

metadata(c::ComponentModel)

Retrieve metadata object for the component.

See also metadata

has_metadata(c::ComponentModel, key::Symbol)
has_metadata(nw::Network, idx::Union{VIndex,EIndex}, key::Symbol)

Checks if metadata key is present for the component.

get_metadata(c::ComponentModel, key::Symbol)
get_metadata(nw::Network, idx::Union{VIndex,EIndex}, key::Symbol)

Retrieves the metadata key for the component.

set_metadata!(c::ComponentModel, key::Symbol, value)
set_metadata!(nw::Network, idx::Union{VIndex,EIndex}, key::Symbol, value)

Sets the metadata key for the component to value.

delete_metadata!(c::ComponentModel, key::Symbol)
delete_metadata!(nw::Network, idx::Union{VIndex,EIndex}, key::Symbol)

Removes the component-wide metadata key from the component model, or from a component referenced by idx in a network. Returns true if the metadata existed and was removed, false otherwise.

has_graphelement(c::ComponentModel)
has_graphelement(nw::Network, idx::Union{VIndex,EIndex})

Checks if the edge or vertex function has the graphelement metadata.

get_graphelement(c::EdgeModel)::@NamedTuple{src::T, dst::T}
get_graphelement(c::VertexModel)::Int
get_graphelement(nw::Network, idx::Union{VIndex,EIndex})

Retrieves the graphelement metadata for the component model. For edges this returns a named tuple (;src, dst) where both are either integers (vertex index) or symbols (vertex name).

set_graphelement!(c::EdgeModel, nt::@NamedTuple{src::T, dst::T})
set_graphelement!(c::EdgeModel, p::Pair)
set_graphelement!(c::VertexModel, vidx::Int)
set_graphelement!(nw::Network, idx::Union{VIndex,EIndex}, value)

Sets the graphelement metadata for the component. For edges this takes a named tuple (;src, dst) where both are either integer (vertex index) or symbol (vertex name). For vertices it takes a single integer vidx.

has_position(v::VertexModel)
has_position(nw::Network, vidx::VIndex)

Checks if vertex v has position metadata.

See also: get_position, set_position!.

get_position(v::VertexModel)
get_position(nw::Network, vidx::VIndex)

Returns the position metadata of vertex v. Might error if not present.

See also: has_position, set_position!.

set_position!(v::VertexModel, val)
set_position!(nw::Network, vidx::VIndex, val)

Sets the position metadata of vertex v to val.

See also: has_position, get_position.

has_marker(v::VertexModel)
has_marker(nw::Network, vidx::VIndex)

Checks if vertex v has marker metadata.

See also: get_marker, set_marker!.

get_marker(v::VertexModel)
get_marker(nw::Network, vidx::VIndex)

Returns the marker metadata of vertex v. Might error if not present.

See also: has_marker, set_marker!.

set_marker!(v::VertexModel, val)
set_marker!(nw::Network, vidx::VIndex, val)

Sets the marker metadata of vertex v to val.

See also: has_marker, get_marker.

symmetadata(c::ComponentModel)::Dict{Symbol,Dict{Symbol,Any}}

Retrieve the metadata dictionary for the symbols. Keys are the names of the symbols as they appear in sym, psym, obssym and insym.

See also symmetadata

get_metadata(c::ComponentModel, sym::Symbol, key::Symbol)
get_metadata(nw::Network, sni::SymbolicIndex, key::Symbol)

Retrieves the metadata key for symbol sym in a component model, or for a symbol referenced by sni in a network. Throws an error if the symbol does not exist in the component model.

has_metadata(c::ComponentModel, sym::Symbol, key::Symbol)
has_metadata(nw::Network, sni::SymbolicIndex, key::Symbol)

Checks if symbol metadata key is present for symbol sym in a component model, or for a symbol referenced by sni in a network. Throws an error if the symbol does not exist in the component model.

set_metadata!(c::ComponentModel, sym::Symbol, key::Symbol, value)
set_metadata!(nw::Network, sni::SymbolicIndex, key::Symbol, value)
set_metadata!(c::ComponentModel, sym::Symbol, pair::Pair)
set_metadata!(nw::Network, sni::SymbolicIndex, pair::Pair)

Sets the metadata key for symbol sym to value in a component model, or for a symbol referenced by sni in a network. Throws an error if the symbol does not exist in the component model.

delete_metadata!(c::ComponentModel, sym::Symbol, key::Symbol)
delete_metadata!(nw::Network, sni::SymbolicIndex, key::Symbol)

Removes the metadata key for symbol sym in a component model, or for a symbol referenced by sni in a network. Returns true if the metadata existed and was removed, false otherwise. Throws an error if the symbol does not exist in the component model.

has_default(c::ComponentModel, sym::Symbol)
has_default(nw::Network, sni::SymbolicIndex)

Checks if a default value is present for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also get_default, set_default!.

get_default(c::ComponentModel, sym::Symbol)
get_default(nw::Network, sni::SymbolicIndex)

Returns the default value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_default, set_default!.

set_default!(c::ComponentModel, sym::Symbol, value)
set_default!(nw::Network, sni::SymbolicIndex, value)

Sets the default value for symbol sym to value in a component model, or for a symbol referenced by sni in a network.

See also has_default, get_default.

delete_default!(c::ComponentModel, sym::Symbol)
delete_default!(nw::Network, sni::SymbolicIndex)

Removes the default value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_default, set_default!.

has_guess(c::ComponentModel, sym::Symbol)
has_guess(nw::Network, sni::SymbolicIndex)

Checks if a guess value is present for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also get_guess, set_guess!.

get_guess(c::ComponentModel, sym::Symbol)
get_guess(nw::Network, sni::SymbolicIndex)

Returns the guess value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_guess, set_guess!.

set_guess!(c::ComponentModel, sym::Symbol, value)
set_guess!(nw::Network, sni::SymbolicIndex, value)

Sets the guess value for symbol sym to value in a component model, or for a symbol referenced by sni in a network.

See also has_guess, get_guess.

delete_guess!(c::ComponentModel, sym::Symbol)
delete_guess!(nw::Network, sni::SymbolicIndex)

Removes the guess value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_guess, set_guess!.

has_init(c::ComponentModel, sym::Symbol)
has_init(nw::Network, sni::SymbolicIndex)

Checks if a init value is present for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also get_init, set_init!.

get_init(c::ComponentModel, sym::Symbol)
get_init(nw::Network, sni::SymbolicIndex)

Returns the init value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_init, set_init!.

set_init!(c::ComponentModel, sym::Symbol, value)
set_init!(nw::Network, sni::SymbolicIndex, value)

Sets the init value for symbol sym to value in a component model, or for a symbol referenced by sni in a network.

See also has_init, get_init.

delete_init!(c::ComponentModel, sym::Symbol)
delete_init!(nw::Network, sni::SymbolicIndex)

Removes the init value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_init, set_init!.

has_bounds(c::ComponentModel, sym::Symbol)
has_bounds(nw::Network, sni::SymbolicIndex)

Checks if a bounds value is present for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also get_bounds, set_bounds!.

get_bounds(c::ComponentModel, sym::Symbol)
get_bounds(nw::Network, sni::SymbolicIndex)

Returns the bounds value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_bounds, set_bounds!.

set_bounds!(c::ComponentModel, sym::Symbol, value)
set_bounds!(nw::Network, sni::SymbolicIndex, value)

Sets the bounds value for symbol sym to value in a component model, or for a symbol referenced by sni in a network.

See also has_bounds, get_bounds.

delete_bounds!(c::ComponentModel, sym::Symbol)
delete_bounds!(nw::Network, sni::SymbolicIndex)

Removes the bounds value for symbol sym in a component model, or for a symbol referenced by sni in a network.

See also has_bounds, set_bounds!.

set_defaults!(nw::Network, s::NWState)

Set the default values of the network to the values of the given state. Can be used to "store" the found fixpoint in the network metadata.

Values of missing, nothing or NaN are ignored.

set_defaults!(nw::Network, p::NWParameter)

Set the parameter default values of the network to the values of the given parameter object.

Values of missing, nothing or NaN are ignored.

set_interface_defaults!(nw::Network, s::NWState; verbose=false)

Sets the interface (i.e. node and edge inputs/outputs) defaults of a given network to the ones defined by the given state. Notably, while the graph topology and interface dimensions of the target network nw and the source network of s musst be identicaly, the systems may differ in the dynamical components.

This is mainly inteded for initialization purposes: solve the interface values with a simpler – possible static – network and "transfer" the steady state interface values to the full network.

dump_state([IO=stdout], sol, t, idx; sigdigits=5)

Takes a Network solution sol and prints the state at t as well as the initial state of the specified component model to IO (defaults to stdout).

idx musst a valid component index, i.e. VIndex or EIndex without symbol specification.

dump_state(sol, 1.0, VIndex(4))
dump_state(sol, 1.0, EIndex(2))

See also: dump_initial_state.

dump_initial_state([IO=stdout], cf::ComponentModel; sigdigits=5, p=true, obs=true)

Prints the initial state of the component model cf to IO (defaults to stdout). Optionally contains parameters and observed.

See also: get_initial_state and dump_state.

get_initial_state(c::ComponentModel, syms; missing_val=nothing)
get_initial_state(nw::Network, sni::SymbolicIndex; missing_val=nothing)

Returns the initial state for symbol sym (single symbol or vector) of the component model c. Returns missing_val if the symbol is not initialized. Also works for observed symbols.

See also: dump_initial_state.

describe_vertices(nw::Network, extras...; parameters=true, states=true, batch=nothing)

Creates a DataFrame containing information about the vertices in a Network.

Arguments

• nw::Network: The network to describe
• extras...: Additional pairs of (key, function) to include as columns, where the function gets the VertexModel as its only parameter to extract a custom metadata field for example..
• parameters=true: Whether to include parameter values
• states=true: Whether to include state values
• batch=nothing: Optionally filter by specific batches

Returns

A DataFrame with columns for vertex indices, names, batch numbers, and any parameter/state values.

describe_edges(nw::Network, extras...; parameters=true, states=true, batch=nothing)

Creates a DataFrame containing information about the edges in a Network.

Arguments

• nw::Network: The network to describe
• extras...: Additional pairs of (key, function) to include as columns, where the function gets the EdgeModel as its only parameter to extract a custom metadata field for example..
• parameters=true: Whether to include parameter values
• states=true: Whether to include state values
• batch=nothing: Optionally filter by specific batches

Returns

A DataFrame with columns for edge indices, source-destination pairs, names, batch numbers, and any parameter/state values.

find_fixpoint(nw::Network, [x0::NWState=NWState(nw)], [p::NWParameter=x0.p]; kwargs...)
find_fixpoint(nw::Network, x0::AbstractVector, p::AbstractVector; kwargs...)
find_fixpoint(nw::Network, x0::AbstractVector; kwargs...)

Convenience wrapper around SteadyStateProblem from SciML-ecosystem. Constructs and solves the steady state problem, returns found value wrapped as NWState.

initialize_component!(cf::ComponentModel; verbose=true, apply_bound_transformation=true, kwargs...)

Initialize a ComponentModel by solving the corresponding NonlinearLeastSquaresProblem. During initialization, everyting which has a default value (see Metadata) is considered "fixed". All other variables are considered "free" and are solved for. The initial guess for each variable depends on the guess value in the Metadata.

The result is stored in the ComponentModel itself. The values of the free variables are stored in the metadata field init.

The kwargs are passed to the nonlinear solver.

Bounds of free variables

When encountering any bounds in the free variables, NetworkDynamics will try to conserve them by applying a coordinate transforamtion. This behavior can be supressed by setting apply_bound_transformation. The following transformations are used:

• (a, b) intervals where both a and b are positive are transformed to u^2/sqrt(u)
• (a, b) intervals where both a and b are negative are transformed to -u^2/sqrt(-u)

init_residual(cf::T; t=NaN, recalc=false)

Calculates the residual |du| for the given component model for the values provided via default and init Metadata.

If recalc=false just return the residual determined in the actual initialization process.

See also initialize_component!.

abstract type ComponentCallback end

Abstract type for a component based callback. A component callback bundles a ComponentCondition as well as a ComponentAffect which can be then tied to a component model using add_callback! or set_callback!.

On a Network level, you can automaticially create network wide CallbackSets using get_callbacks.

See ContinousComponentCallback and VectorContinousComponentCallback for concrete implemenations of this abstract type.

ContinousComponentCallback(condition, affect; kwargs...)

Connect a ComponentCondition and a [ComponentAffect)[@ref] to a continous callback which can be attached to a component model using add_callback! or set_callback!.

The kwargs will be forwarded to the VectorContinuousCallback when the component based callbacks are collected for the whole network using get_callbacks. DiffEq.jl docs for available options.

VectorContinousComponentCallback(condition, affect, len; kwargs...)

Connect a ComponentCondition and a [ComponentAffect)[@ref] to a continous callback which can be attached to a component model using add_callback! or set_callback!. This vector version allows for condions which have len output dimensions. The affect will be triggered with the additional event_idx argument to know in which dimension the zerocrossing was detected.

The kwargs will be forwarded to the VectorContinuousCallback when the component based callbacks are collected for the whole network using get_callbacks(::Network). DiffEq.jl docs for available options.

DiscreteComponentCallback(condition, affect; kwargs...)

Connect a ComponentCondition and a [ComponentAffect)[@ref] to a discrete callback which can be attached to a component model using add_callback! or set_callback!.

Note that the condition function returns a boolean value, as the discrete callback perform no rootfinding.

The kwargs will be forwarded to the DiscreteCallback when the component based callbacks are collected for the whole network using get_callbacks(::Network). DiffEq.jl docs for available options.

PresetTimeComponentCallback(ts, affect; kwargs...)

Tirgger a ComponentAffect at given timesteps ts in discrete callback, which can be attached to a component model using add_callback! or set_callback!.

The kwargs will be forwarded to the PresetTimeCallback when the component based callbacks are collected for the whole network using get_callbacks(::Network).

The PresetTimeCallback will take care of adding the timesteps to the solver, ensuring to exactly trigger at the correct times.

ComponentCondition(f::Function, sym, psym)

Creates a callback condition for a [ComponentCallback].

• f: The condition function. Must be a function of the form out=f(u, p, t) when used for ContinousComponentCallback or DiscreteComponentCallback and f!(out, u, p, t) when used for VectorContinousComponentCallback.
  • Arguments of f
    • u: The current value of the selecte sym states, provided as a SymbolicView object.
    • p: The current value of the selected psym parameters.
    • t: The current simulation time.
• sym: A vector or tuple of symbols, which represent states (including inputs, outputs, observed) of the component model. Determines, which states will be available thorugh parameter u in the callback condition function f.
• psym: A vector or tuple of symbols, which represetn parameters of the component mode. Determines, which parameters will be available in the condition function f

Example

Consider a component model with states [:u1, :u2], inputs [:i], outputs [:o] and parameters [:p1, :p2].

ComponentCondition([:u1, :o], [:p1]) do u, p, t
    # access states symbolicially or via int index
    u[:u1] == u[1]
    u[:o] == u[2]
    p[:p1] == p[1]
    # the states/prameters `:u2`, `:i` and `:p2` are not available as
    # they are not listed in the `sym` and `psym` arguments.
end

ComponentAffect(f::Function, sym, psym)

Creates a callback condition for a [ComponentCallback].

• f: The affect function. Must be a function of the form f(u, p, [event_idx], ctx) where event_idx is only available in VectorContinousComponentCallback.
  • Arguments of f
    • u: The current (mutable) value of the selected sym states, provided as a SymbolicView object.
    • p: The current (mutalbe) value of the selected psym parameters.
    • event_idx: The current event index, i.e. which out element triggerd in case of VectorContinousComponentCallback.
    • ctx::NamedTuple a named tuple with context variables.
      • ctx.model: a referenc to the ocmponent model
      • ctx.vidx/ctx.eidx: The index of the vertex/edge model.
      • ctx.src/ctx.dst: src and dst indices (only for edge models).
      • ctx.integrator: The integrator object. Use extract_nw to obtain the network.
      • ctx.t=ctx.integrator.t: The current simulation time.
• sym: A vector or tuple of symbols, which represent states (excluding inputs, outputs, observed) of the component model. Determines, which states will be available thorugh parameter u in the callback condition function f.
• psym: A vector or tuple of symbols, which represetn parameters of the component mode. Determines, which parameters will be available in the condition function f

Example

Consider a component model with states [:u1, :u2], inputs [:i], outputs [:o] and parameters [:p1, :p2].

ComponentAffect([:u1, :o], [:p1]) do u, p, ctx
    u[:u1] = 0 # change the state
    p[:p1] = 1 # change the parameter
    @info "Changed :u1 and :p1 on vertex $(ctx.vidx)" # access context
end

SymbolicView{N,VT} <: AbstractVetor{VT}

Is a (smallish) fixed size vector type with named dimensions. Its main purpose is to allow named acces to variables in ComponentCondition and ComponentAffect functions.

I.e. when the ComponentAffect declared sym=[:x, :y], you can acces u[:x] and u[:y] inside the condition function.

get_callbacks(nw::Network)::CallbackSet

Returns a CallbackSet composed of all the "component-based" callbacks in the metadata of the Network components.

has_callback(c::ComponentModel)
has_callback(nw::Network, idx::Union{VIndex,EIndex})

Checks if the component has a callback function in metadata.

get_callbacks(c::ComponentModel)
get_callbacks(nw::Network, idx::Union{VIndex,EIndex})

Gets all callback functions for the component. Wraps in tuple, even if there is only a single one.

set_callback!(c::ComponentModel, cb; check=true)
set_callback!(nw::Network, idx::Union{VIndex,EIndex}, cb; check=true)

Sets the callback function for the component. Overwrites any existing callback. See also add_callback!.

add_callback!(c::ComponentModel, cb; check=true)
add_callback!(nw::Network, idx::Union{VIndex,EIndex}, cb; check=true)

Adds a callback function to the component. Does not overwrite existing callbacks. See also set_callback!.

abstract type ExecutionStyle{buffered::Bool} end

Abstract type for execution style. The coreloop dispatches based on the Execution style stored in the network object.

• buffered=true means that the edge input es explicitly gathered, i.e. the vertex outputs in the output buffer will be copied into a dedicated input buffer for the edges.
• buffered=false means, that the edge inputs are not explicitly gathered, but the corloop will perform a redirected lookup into the output buffer.

struct SequentialExecution{buffered::Bool}

Sequential execution, no parallelism. For buffered see ExecutionStyle.

struct PolyesterExecution{buffered}

Parallel execution using Polyester.jl. For buffered see ExecutionStyle.

struct ThreadedExecution{buffered}

Parallel execution using Julia threads. For buffered see ExecutionStyle.

struct KAExecution{buffered}

Parallel execution using KernelAbstractions.jl. Works with GPU and CPU arrays. For buffered see ExecutionStyle.

abstract type Aggregator end

Abstract sypertype for aggregators. Aggregators operate on the output buffer of all components and fill the aggregation buffer with the aggregatated edge values per vertex.

All aggregators have the constructor

Aggegator(aggfun)

for example

SequentialAggreator(+)

SequentialAggregator(aggfun)

Sequential aggregation.

SparseAggregator(+)

Only works with additive aggregation +. Aggregates via sparse inplace matrix multiplication. Works with GPU Arrays.

ThreadedAggregator(aggfun)

Parallel aggregation using Julia threads.

PolyesterAggregator(aggfun)

Parallel aggregation using Polyester.jl.

KAAggregator(aggfun)

Parallel aggregation using KernelAbstractions.jl. Works with both GPU and CPU arrays.

save_parameters!(integrator::SciMLBase.DEIntegrator)

Save the current parameter values in the integrator. Call this function inside callbacks if the parameter values have changed. This will store a timeseries of said parameters in the solution object, thus alowing us to recosntruct observables which depend on time-dependet variables.

ff_to_constraint(v::VertexModel)

Takes VertexModel v with feed forward and turns all algebraic output states into internal states by defining algebraic constraints contraints 0 = out - g(...). The new output function is just a StateMask into the extended internal state vector.

Returns the transformed VertexModel.

copy(c::NetworkDynamics.ComponentModel)

Shallow copy of the component model. Creates a deepcopy of metadata and symmetadata but references the same objects everywhere else.

extract_nw(thing)

Try to extract the Network object from thing.

Thing can by many things, e.g. ODEProblem, ODESolution, Integrator, NWState, NWParameter, ...

inspect(sol; restart=false, reset=false, display=nothing)

Main entry point for gui. Starts the server and serves the app for soution sol.

• restart: If true, the display will be restartet (i.e. new Electron window, new server or new Browser tab)
• reset: If true, reset the appstate with the new solution sol.
• display=CURRENT_DISPLAY[]: Can be BrowserDisp(), ServerDisp() or ElectronDisp(). Per default, the current display will be used (defaults toBrowserDisp()).

dump_app_state()

Generate a list of set_sol!, set_state!, set_graphplot! and define_timeseries! commands to recreate the current appstate. The intended usecase is to quickly recreate "starting points" for interactive exploration.

set_sol!(sol)

Set the solution of the current appstate to sol.

set_state!(; sol, t, tmin, tmax)

Set the solution, current time and time limits of the current appstate.

To automaticially create commands see dump_app_state().

set_graphplot!(; nstate, estate, nstate_rel, estate_rel, ncolorrange, ecolorrange)

Set the properties of the graphplot of the current appstate.

To automaticially create commands see dump_app_state().

set_timeseries!(key; selcomp, states, rel)

Set properties of the timeseries plot with key key. See also define_timeseries!.

To automaticially create commands see dump_app_state().

define_timeseries!(tsarray)

Defines timeseries, where tsarray is an array of timeseries keyword arguments (see set_timeseries!).

To automaticially create commands see dump_app_state().