[ANN] Jusdl.jl v0.1.2 - Signal-Flow Graphs, Detecting and Breaking Algebraic Loops

Hi all,

I am pleased to announce the changes in the new patch release v0.1.2 of Jusdl.

One big change is that a signal-flow graph(which simply a directed graph consisting of nodes and branches) is associated with the model to be simulated. As the model is modified by new adding nodes(i.e components) and new branches(i.e connections), the signal flow graph of the model is modified accordingly to keep track of the changes in the topology of the model.

Here is an example case study from the docs of Jusdl. Consider the following model block diagram


The construction of the model using Jusdl is as follows. We start with an empty model and add nodes connections to the model.

using Jusdl 

# Construct an empty model 
model = Model()
# Add nodes to the model 
addnode(model, SinewaveGenerator(frequency=2), label=:gen1)
addnode(model, Gain(gain=1), label=:gain1)
addnode(model, Adder((+,+)), label=:adder1)
addnode(model, SinewaveGenerator(frequency=3), label=:gen2)
addnode(model, Adder((+, +, -)), label=:adder2)
addnode(model, Gain(gain=1), label=:gain2)
addnode(model, Writer(), label=:writer)
addnode(model, Gain(gain=1), label=:gain3)

# Add branches to the model
addbranch(model, :gen1 => :gain1, 1 => 1)
addbranch(model, :gain1 => :adder1, 1 => 1)
addbranch(model, :adder1 => :adder2, 1 => 1)
addbranch(model, :gen2 => :adder1, 1 => 2)
addbranch(model, :gen2 => :adder2, 1 => 2)
addbranch(model, :adder2 => :gain2, 1 => 1)
addbranch(model, :gain2 => :writer, 1 => 1)
addbranch(model, :gain2 => :gain3, 1 => 1)
addbranch(model, :gain3 => :adder2, 1 => 3)

Note that when a node is added, it is given a label so that the node can be accessed by its label. And the syntax, addbranch(model, src_node_label => dst_node_label, src_node_output_port_subindex => dst_node_inport_subindex is used to connect the pins (indexed by src_node_output_port_subindex) of output port of a source node to the input pins(indexed by dst_node_inport_subindex) of the input port of a destination node.

The signal flow of the model can be plotted using signalflow, which uses the tools provided by GraphPlot.


Associating a signal-flow graph to the model makes it possible to carry out graph-theoretic analysis on the model topology(by using the tools provided by LightGraphs). An example to such an analysis is the inspection and breaking algebraic loops. An algebraic loop is a closed-loop consisting of one or more components whose outputs are directly dependent on their inputs. If algebraic loops exist in a model, the simulation gets stuck because none of the components in the loop can generate output to break the loop. Such a problem can be broken by rearranging the model without algebraic loops, solving the feed-forward algebraic equation of the loop, or inserting a memory component with a certain initial condition anywhere in the loop. Jusdl provides all these loop-breaking solutions. During the inspection stage, in case they are detected, all the loops are broken. Otherwise, a report is printed to notify the user to insert memory components to break the loops.

Note that the model has an algebraic loop consisting of the components adder2, gain2 and gain3 and during the simulation Jusdl detects and breaks this loop without requiring any user intervention. To see this, let us simulate the model.


Here are the log messages printed on the console during the simulation. The algebraic loop between the nodes adder2, gain2 and gain3, (as nodes are added to the model, an index is assigned to access them, and node indices of adder2, gain2 and gain3 are 5, 6, and 8, respectively.), is detected and broken during the inspection stage of the simulation.

[ Info: 2020-05-04T21:39:00.768 Started simulation...
[ Info: 2020-05-04T21:39:00.768 Inspecting model...
┌ Info: 	The model has algrebraic loops:[[5, 6, 8]]
└ 		Trying to break these loops...
[ Info: 	Loop [5, 6, 8] is broken
[ Info: 2020-05-04T21:39:00.964 Done.
[ Info: 2020-05-04T21:39:00.964 Initializing the model...
[ Info: 2020-05-04T21:39:01.143 Done...
[ Info: 2020-05-04T21:39:01.144 Running the simulation...
[ Info: 2020-05-04T21:39:01.364 Done...
[ Info: 2020-05-04T21:39:01.364 Terminating the simulation...
[ Info: 2020-05-04T21:39:01.367 Done.

When the simulation is completed, the simulation data saved in writer file can be read back and any offline data analysis can be performerd. Through its Plugins interface, Jusdl also provides online(while the model is being simulated) data analysis.

t, x = read(getnode(model, :writer).component)
plot(t, x)


The docs provides further information and short tutorials about the capabilities of Jusdl.

Jusdl is still in its development phase and any form of contribution is welcome. Please feel free to open an issue for bug reports, feature requests, new ideas and suggestions etc., or to send a pull request for any bug fixes.