Running

Running a block diagram

There is a distinction between the block diagram model, and the execution environment for the model. A simulation environment object is created by

#!/usr/bin/env python3

import bdsim

sim = bd.BDSim()

which parses all command line options, searches for and dynamically loads block definitions, and manages UI windows for all graphical sink blocks. A block diagram instance is created by a factory method

sim = bd.BDSim()

and is itself a factory object with upper-case-named methods which are constructors for each block class, for example

gain = bd.GAIN(10)

invokes the constructor for the class Gain which was found in the block path, by default bdsim/blocks/*.py.

A block diagram object is executed by the BDSim object

sim.run(bd, 10)

The separation is designed to make it possible to execute a block diagram on a low-end platform, with no graphics, or perhaps even no operating system (eg. MicroPython).

Options

There are a number of run-time options which can be set from the code or the command line.

Command line switch	Argument to BDSim	Default	Behaviour
--graphics, +g	graphics	True	enable graphical display
--no-nographics, -g	graphics	True	disable graphical display
--animation, +a	animation	False	update graphics at each time step
--no-animation, -a	animation	False	don't update graphics at each time step
--noprogress, -p	progress	True	do not display simulation progress bar
--backend BE	backend	"Qt5Agg"	Matplotlib backend
--altscreen, +A	alt screen	True	put scope windows on second screen
--no-altscreen, -A	alt screen	True	put scopes on main screen
--tiles RxC, -t RxC	tiles	"3x4"	arrangement of figure tiles on the display
--shape WxH	shape	""	size of scope window in inches
--verbose, -v	verbose	False	be verbose
--debug F, -d F	debug	""	debug flag string

Options can be set in the code at constructor time

sim = bdsim.BDSim(progress=False) # disable progress bar

or later by

sim.set_options(progress=False) # disable progress bar

Options can be set from the command line, and they override any code options

% ./eg1 --progress

so in this case, the progress bar will be displayed.

To prevent BDSim "taking" the command line options pass the option

sim = BDSim(sysargs=False, ...)

and explicitly set the other options.

Graphics and animation options

By default, with no animation, the graphics windows do not appear until run returns.

If animation is enabled the windows will appear at the start of the run and the graphics will be updated (animated) after every integration step.

At the end of simulation, if the program exits immediately the windows will all close. This may happen so fast you don't see them at all. You could add a delay or some blocking input call, but the interactive features of the graphics windows will not work because the window event loop is not active. To activate this event loop use

sim.done(bd, block=True)

after run has completed. This call blocks until all the windows are closed, or a SIGINT is received. Without this and the graphics are not seen. Type "q" in a graphics window to close it.

Debug options

The debug option is string comprising single letter flags that enable additional run-time information to stdout.

|flag | meaning | |s | display the complete state vector |p | display the signals propagating through the data flow graph (extensive)| |deriv| display the complete state derivative vector| |i | enter the interactive debugger |

Debugging strategies

Debugging a model is non trivial. There are three common types of error, and each has a different approach to resolution.

Compile-time errors

These errors occur during the execution of the compile method and are typically:

• block connectivity errors, a block input driven by more than one output blocks, block inputs not connected, algebraic loops, or bad parameters passed to the block
• block inputs having the wrong type or, if a NumPy array, the wrong shape

Check the parameters of the block and the blocks that drive it. Use the Wire table displayed by the report method to ensure the signals on the wires are of the type and shape you expect.

A report() is displayed if a compile error occurs.

Execution errors

At run-time one of the blocks in the model generates an exception, which is caught and the error traceback is displayed in red. This includes the input values to the block.

In practice these errors are related to unexpected input values, perhaps the type of an input has changed (a None value), its shape has changed, or it contains an inf or nan value.

Incorrect results

This error occurs when the block diagram model executes successfully, but does not generate the expected response. The best way to debug this situation is to inspect the values of the signals that contribute to the incorrect one. In a complex model, if this is not obvious, you can create the data flow graph as a GraphViz dot file

bd.plan_dotfile('dataflow.dot')

and then convert that to a PDF (or whatever) file and display it, eg.

% dot -Tpdf dataflow.dot > dataflow.pdf

There are many ways to do inspect additional signals:

• "watch" additional block outputs using the watch option to run. The time-history of these signals will be included in the object returned by run.
• add additional SCOPE blocks to the model
• add PRINT blocks to the model which will "print" the values of the signals to stdout.
• use the interactive debugger
• a FUNCTION block executes user code, so instrument the function with additional print functions.

Generally models start to diverge early in the simulation, so to reduce waiting time and reduce the amount of time history to look at, set the maximum simulation time to a small value.

Interactive debugger

This is invoked by the "i" debug flag, either from the command line or set programmatically. This is a keyboard interactive tool that displays a prompt

(bdsim, t=1.2) 

that includes the current simulation time. Commands are very simple

Command	Purpose
h	display a list of commands
p	print the output of all blocks
pID	print the output of block with specified ID
i	display SciPy integrator status
s	single step, move to next time step
c	continue execution
tTIME	continue execution until simulation time >= TIME
q	quit

Ways to execute a bdsim model

A standalone script

These have a hash-bang line at the top

#!/usr/bin/env python3

and if the file is executable, can be invoked just like any other executable. Command line options are taken by BDSim.

Jupyter notebook

something about where the plots go, not embedded the notebook