Block library

The block diagrams comprise blocks which belong to one of a number of different categories. These come from the package bdsim.blocks, roboticstoolbox.blocks, machinevisiontoolbox.blocks.

Icons, if shown to the left of the black header bar, are as used with bdedit.

Inheritance diagram of bdsim.components.SourceBlock, bdsim.components.SinkBlock, bdsim.graphics.GraphicsBlock, bdsim.components.FunctionBlock, bdsim.components.ContinuousBlock, bdsim.components.SampledBlock, bdsim.components.SubsystemBlock

Block class hierarchy, arrow from parent class to subclass

Source blocks

Two of the sources output the state of the system rather than a signal: State for the continuous-time state and State_S for the discrete-time state of the blocks on a clock.

Source blocks:

  • have outputs but no inputs

  • have no state variables

  • are a subclass of SourceBlock → Block

class bdsim.blocks.sources.Constant(value=0, asarray=True, **blockargs)[source]

Bases: SourceBlock

CONSTANT

Constant value.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

any

constant value

The output value is a constant and can be any Python type, for example float, string or Numpy ndarray.

A list or tuple of numbers is converted to a Numpy ndarray by default, with dtype int64 if the elements are all integers and float64 if any is a float, so CONSTANT([1, 2, 3]) is a vector of int64. Anything else, such as a list of strings or of objects, is emitted as given. Other dtypes are chosen by passing an array, and a list of numbers is emitted as a list with asarray=False:

bd.CONSTANT([1, 2, 3])                   # int64 array
bd.CONSTANT([1, 2.5])                    # float64 array
bd.CONSTANT([1, 2, 3], asarray=False)    # the list [1, 2, 3]
bd.CONSTANT(np.float32([1, 2, 3]))       # float32 array
__init__(value=0, asarray=True, **blockargs)[source]
Parameters:
  • value (Any) – the constant, defaults to 0

  • asarray (bool) – convert a list or tuple of numbers to an ndarray of int64 or float64, defaults to True

  • blockargs (Any) – common block options

class bdsim.blocks.sources.Piecewise(*args, seq=None, asarray=True, **blockargs)[source]

Bases: SourceBlock, EventSource

PIECEWISE

Piecewise constant signal.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

float

\(y(t)\)

Generate a signal that is a piecewise constant function of time. This is described as a series of 2-tuples (time, value). The output value is taken from the active tuple, that is, the latest one in the list whose time is no greater than simulation time.

The tuples can be provided in two different ways. Firstly, a form convenient for Python programming:

steering = bd.PIECEWISE((0,0), (2, 0.5), (3,0), (4,-0.5), (5,0))

Secondly, in a form that can be used from bdsim where we explicitly pass in a list in a way that can be represented in a JSON file:

steering = bd.PIECEWISE(seq=[(0,0), (3, 0.5), (4,0), (5,-0.5), (6,0)])

(Source code, png, hires.png, pdf)

_images/bdsim-blocks-1.png

Note

  • The tuples must be ordered by monotonically increasing time.

  • There is no default initial value, the list should contain a tuple with time zero otherwise the output will be undefined.

Note

The block declares an event for the start of each segment.

Seealso:

simstate.declare_event()

__init__(*args, seq=None, asarray=True, **blockargs)[source]
Parameters:
property seq: list[tuple[float, Any]]

The (time, value) pairs, in order of time.

Setter accepts:

Any

class bdsim.blocks.sources.Ramp(T=1, off=0, slope=1, **blockargs)[source]

Bases: SourceBlock, EventSource

RAMP

Ramp signal.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

float

\(y(t)\)

Generate a signal that starts increasing from the value off when time equals T linearly with time, with a gradient of slope.

Example:

step = bd.RAMP(2, off=-1, slope=2/3, T=2)

(Source code, png, hires.png, pdf)

_images/bdsim-blocks-2.png

Note

The block declares an event for the ramp start time.

Seealso:

simstate.declare_event()

__init__(T=1, off=0, slope=1, **blockargs)[source]
Parameters:
class bdsim.blocks.sources.State(blocks=None, **blockargs)[source]

Bases: _StateReader, SourceBlock

STATE

Continuous state of the system.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

ndarray(n)

\(x(t)\)

Outputs the state vector \(x\) of the diagram, which is what state feedback needs. For example, to apply the force \(F = -K x\) to a cart and pole with a gain matrix \(K\) from linear quadratic regulator (LQR) design:

F = -K * bd.STATE()

What the state is. A block that has continuous state, such as an INTEGRATOR or an LTI_SS, contributes its state to the state vector of the diagram, and this is the vector that the solver advances. The blocks contribute in the order they were added to the diagram, so the output is in the same order as bd.statenames, and as the states of functions() and linearize(). A gain matrix designed from the A and B of linearize therefore applies directly to this output. The output of an integrator is its state, so this block gives the same signal as a MUX of the integrators, in a guaranteed order.

If the controller has states of its own, such as an integrator added for integral action, they are also in the diagram’s state. To read only the states of the plant, list its blocks, by block or by name, in the order that suits the gain matrix:

x = bd.STATE([x_dot, x, theta_dot, theta])
x = bd.STATE(["x_dot", "x", "theta_dot", "theta"])

Checking the state. The block reports what its output is made of. After the diagram is compiled:

x = bd.STATE()
x.statenames   # ['x_dot', 'x', 'theta_dot', 'theta']
x.index        # which slice of the output belongs to which block

bd.statenames gives the state names of the whole diagram.

This is the state of the simulation, a perfect and instantaneous measurement. It does not exist on hardware, where a controller uses sensors or an estimator, and it is not offered as an input of functions() or linearize(): the state is the argument x of those functions.

Note

The output is a vector, so K * x with a NumPy matrix K makes a GAIN block that multiplies it. A single state is a scalar, as for any size-1 signal.

Parameters:

blocks (Block | str | list[Block | str] | None) – blocks, or their names, whose state to output, in this order, defaults to the continuous states of every block in the diagram

Seealso:

linearize() functions() State_S Time

__init__(blocks=None, **blockargs)[source]
Parameters:
class bdsim.blocks.sources.State_S(clock, blocks=None, **blockargs)[source]

Bases: _StateReader, SourceBlock

STATE_S

Discrete-time state of the system.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

ndarray(n)

\(X(k)\)

Outputs the discrete-time state vector \(X\) of the blocks that run on a clock, for example the state of an observer or a digital controller. For example:

clock = bd.clock(0.01)
X = bd.STATE_S(clock)

What the state is. A clocked block such as INTEGRATOR_S, ZOH or LTI_SS_S has discrete state that changes only at the ticks of its clock. The output is the state of the blocks on the clock, in the order they were added to it, which is the order of clock.statenames. Between ticks it is the state after the most recent tick, and before the first tick it is the initial state.

To read only some of the clock’s blocks, list them, by block or by name, in the order wanted:

X = bd.STATE_S(clock, [observer])

To feed the continuous state of a plant to a digital controller, sample it with a ZOH on the same clock, bd.ZOH(clock) applied to bd.STATE(); this block is for the state that belongs to the discrete time blocks.

Checking the state. After the diagram is compiled:

X.statenames   # the name of each element of the output
X.index        # which slice of the output belongs to which block

Like STATE, this is a perfect and instantaneous measurement of the simulation, and is not offered as an input of functions() or linearize().

Parameters:
  • clock (Clock) – the clock whose blocks’ state is output

  • blocks (Block | str | list[Block | str] | None) – blocks on the clock, or their names, whose state to output, in this order, defaults to every block on the clock

Seealso:

State linearize() ZOH

__init__(clock, blocks=None, **blockargs)[source]
Parameters:
  • clock (Clock) – the clock whose blocks’ state is output

  • blocks (Block | str | list[Block | str] | None) – blocks on the clock, or their names, whose state to output, in this order, defaults to every block on the clock

  • blockargs (Any) – common block options

class bdsim.blocks.sources.Step(T=1, off=0, on=1, asarray=True, **blockargs)[source]

Bases: SourceBlock, EventSource

STEP

Step signal.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

float

\(y(t)\)

Generate a step signal that transitions from the value off to on when time equals T.

Example:

step = bd.STEP(2, off=-1, on=1)

(Source code, png, hires.png, pdf)

_images/bdsim-blocks-3.png

Note

The block declares an event for the step time.

Seealso:

simstate.declare_event()

__init__(T=1, off=0, on=1, asarray=True, **blockargs)[source]
Parameters:
  • T (float) – time of step, defaults to 1

  • off (Any) – initial value, defaults to 0

  • on (Any) – final value, defaults to 1

  • asarray (bool) – convert a list or tuple of numbers to an ndarray of int64 or float64, defaults to True

  • blockargs (Any) – common block options

Raises:
  • TypeError – off and on are of different types

  • ValueError – off and on are arrays with different shape or dtype

The output is always of one type. off and on can be any Python object, but must be the same type, for example two arrays or two strings. A list or tuple of numbers is first converted to an ndarray of int64 or float64 (see asarray). Numbers are promoted to a common type, so off=0, on=1.0 gives 0.0 and 1.0. A bool cannot be mixed with a number.

class bdsim.blocks.sources.Time(value=None, **blockargs)[source]

Bases: SourceBlock

TIME

Simulation time.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

float

\(t\)

Outputs the current simulation time.

For example:

time = bd.TIME()
__init__(value=None, **blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.sources.WaveForm(wave='square', freq=1, unit='Hz', phase=0, amplitude=1, offset=0, min=None, max=None, duty=0.5, **blockargs)[source]

Bases: SourceBlock, EventSource

WAVEFORM

Waveform generator.

Inputs:

0

Outputs:

1

States:

0

Port type

Port number

Types

Description

Output

0

float

\(y(t)\)

A general waveform generator. For example:

wave = bd.WAVEFORM(wave='sine', freq=2)   # 2Hz sine wave varying from -1 to 1
wave = bd.WAVEFORM(wave='square', freq=2, unit='rad/s') # 2rad/s square wave varying from -1 to 1

The minimum and maximum values of the waveform are given by default in terms of amplitude and offset. The signals are symmetric about the offset value. For example:

wave = bd.WAVEFORM(wave='sine') # varies between -1 and +1
wave = bd.WAVEFORM(wave='sine', amplitude=2) # varies between -2 and +2
wave = bd.WAVEFORM(wave='sine', offset=1) # varies between 0 and +2
wave = bd.WAVEFORM(wave='sine', amplitude=2, offset=1) # varies between -1 and +3

Alternatively we can specify the minimum and maximum values which override amplitude and offset:

wave = bd.WAVEFORM(wave='triangle', min=0, max=5) # varies between 0 and +5

At time 0 the sine and triangle wave are zero and increasing, and the square wave has its first rise. We can specify a phase shift with a number in the range [0,1] where 1 corresponds to one cycle.

Note

For discontinuous signals (square, triangle) the block declares events for every discontinuity.

Seealso:

simstate.declare_event()

__init__(wave='square', freq=1, unit='Hz', phase=0, amplitude=1, offset=0, min=None, max=None, duty=0.5, **blockargs)[source]
Parameters:
  • wave (str) – type of waveform to generate, one of: ‘sine’, ‘square’ [default], ‘triangle’

  • freq (float) – frequency, defaults to 1

  • unit (str) – frequency unit, one of: ‘rad/s’, ‘Hz’ [default]

  • amplitude (float) – amplitude, defaults to 1

  • offset (float) – signal offset, defaults to 0

  • phase (float) – Initial phase of signal in the range [0,1], defaults to 0

  • min (float | None) – minimum value, defaults to None

  • max (float | None) – maximum value, defaults to None

  • duty (float) – duty cycle for square wave in range [0,1], defaults to 0.5

  • blockargs (Any) – common block options

property freq: float

Frequency, in unit.

property max: float

Maximum value of the signal, derived from amplitude and offset.

property min: float

Minimum value of the signal, derived from amplitude and offset.

Sink blocks

Sink blocks:

  • have inputs but no outputs

  • have no state variables

  • are a subclass of SinkBlock → Block

  • that perform graphics are a subclass of GraphicsBlock → SinkBlock → Block

class bdsim.blocks.sinks.Event(direction, func, fargs=None, fkwargs=None, **blockargs)[source]

Bases: SinkBlock

EVENT

Runtime event detector for solve_ivp.

Inputs:

1

Outputs:

0

States:

0

The input signal is used as an event function value. A zero crossing triggers an event in solve_ivp.

Direction can be one of:

  • '^' or '+': positive-going crossing (direction = +1)

  • 'v' or '-': negative-going crossing (direction = -1)

Event handling callback signature is:

func(block, *fargs, **fkwargs)

where block is this EVENT block instance.

__init__(direction, func, fargs=None, fkwargs=None, **blockargs)[source]
Parameters:
property direction: str

Crossing direction, '^' for positive-going or 'v' for negative-going.

event_handler(t_crossing, y_crossing, state_map, simstate=None)[source]
Return type:

None

property fargs: list[Any]

Extra positional arguments passed to the callback.

Setter accepts:

Any

property fkwargs: dict[str, Any]

Extra keyword arguments passed to the callback.

Setter accepts:

Any

class bdsim.blocks.sinks.Null(nin=1, **blockargs)[source]

Bases: SinkBlock

NULL

Discard signal.

Inputs:

N

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

i

any

\(x_i\)

Create a sink block with arbitrary number of input ports that discards all data, like /dev/null. Useful for testing.

Note

bdsim issues a warning for unconnected outputs but execution can continue.

__init__(nin=1, **blockargs)[source]
Parameters:
class bdsim.blocks.sinks.Print(fmt=None, file=None, **blockargs)[source]

Bases: SinkBlock

PRINT

Print signal.

Inputs:

1

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

0

any

\(x\)

Creates a console print block which displays the value of the input signal at each simulation time step. The display format is like:

PRINT(print.0 @ t=0.100) [-1.0 0.2]

and includes the block name, time, and the formatted value.

The numerical formatting of the signal is controlled by fmt:

  • if not provided, str() is used to format the signal

  • if provided:

    • a scalar is formatted by the fmt.format()

    • a NumPy array is formatted by fmt.format() applied to every element

Examples:

bd.PRINT(name="X")  # block name appears in the printed text
bd.PRINT(fmt="{:.1f}") # print with explicit format

Note

  • By default writes to stdout

  • The output is cleaner if progress bar printing is disabled using the -p command line option.

__init__(fmt=None, file=None, **blockargs)[source]
Parameters:
Returns:

A PRINT block

class bdsim.blocks.sinks.Stop(func=None, **blockargs)[source]

Bases: SinkBlock

STOP

Conditionally stop simulation.

Inputs:

1

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

0

any

\(x\)

Conditionally stop the simulation if the input \(x\) is:

  • bool type and True

  • numeric type and > 0

If func is provided, then it is applied to the block input and if it returns True the simulation is stopped.

__init__(func=None, **blockargs)[source]
Parameters:
event_handler(t_crossing, y_crossing, state_map, simstate=None)[source]
Return type:

None

class bdsim.blocks.sinks.Watch(nin=1, **blockargs)[source]

Bases: SinkBlock

WATCH

Watch a signal.

Inputs:

N

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

i

any

\(x_i\)

Causes the output ports connected to this block’s input ports \(x_i\) to be logged during the simulation run. Equivalent to adding it as the watch= argument to bdsim.run.

For example:

step = bd.STEP(5)
ramp = bd.RAMP()
watch = bd.WATCH(2) # watch 2 ports
watch[0] = step
watch[1] = ramp
Seealso:

run()

__init__(nin=1, **blockargs)[source]
Parameters:

Display blocks

Sink blocks:

  • have inputs but no outputs

  • have no state variables

  • are a subclass of SinkBlock → Block

  • that perform graphics are a subclass of GraphicsBlock → SinkBlock → Block

class bdsim.blocks.displays.Animation(init, update, projection=None, **blockargs)[source]

Bases: GraphicsBlock

ANIMATION

Create an animation from user-defined functions.

Inputs:

1

Outputs:

0

States:

0

The animation is defined by two user-provided functions:

  1. Animation setup function init with signature:

        init(block, fig, ax)
    
    * ``block`` is the animation block instance
    * ``fig`` is the Matplotlib figure object for the animation
    * ``ax`` is the Matplotlib axes object for the animation
    
  2. Animation update function update with signature:

        update(block, t, inports)
    
    
    * ``block`` is the animation block instance
    * ``t`` is the current time
    * ``inports`` is a list of values applied to the block's input ports at the
      current time
    

Matplotlib artist handles created in init can be stored as attributes of the block instance and used in the update function. Note that attributes fig and ax are reserved for the figure and axes objects and will be set by the block before calling init.

The animation will run when the block diagram is executed with animation enabled. The movie block option can be used to save the animation to a file as well as displaying it on screen.

By default ax is a 2D axes. For a three-dimensional scene give projection="3d" and ax is a Matplotlib 3D axes, on which init can add, for example, polygon collections (mpl_toolkits.mplot3d.art3d.Poly3DCollection) that update moves. The 3D axes have no blitting, and Matplotlib sorts the polygons of a 3D scene by depth as it draws, which can put a large polygon in front of a small one that is really in front of it. If that matters set ax.computed_zorder = False in init and give the artists an explicit zorder, which for a fixed camera is cheap to arrange.

TIMESTAMP = True
__init__(init, update, projection=None, **blockargs)[source]
Parameters:
Raises:

ValueError – init or update is not callable, or projection is not None or "3d"

class bdsim.blocks.displays.Scope(nin=1, vector=None, styles=None, stairs=False, scale='auto', labels=None, grid=True, title=None, loc='best', **blockargs)[source]

Bases: GraphicsBlock

SCOPE

Plot input signals against time.

Inputs:

N

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

i

float

\(x_i\) is the i’th line

Create a scope block that plots multiple signals against time.

For each line plotted we can specify the:

  • line style as a heterogeneous list of:

    • Matplotlib fmt string comprising a color and line style, eg. "k" or "r:"

    • a dict of Matplotlib line style options for Line2D , eg. {"color": "k", "linewidth": 3, "alpha": 0.5)

  • line label, used in the legend and vertical axis. This can include math mode notation or unicode characters.

The vertical scale factor defaults to auto-scaling but can be fixed by providing a 2-tuple [ymin, ymax]. All lines are plotted against the same vertical scale.

example of generated graphic

Example of scope display.

Scalar input ports against time

The number of lines to plot will be inferred from:

  • the length of the labels list if specified

  • the length of the styles list if specified

  • nin if specified, it defaults to 1

These numbers must be consistent.

Examples:

bd.SCOPE()       # a scope with 1 input port
bd.SCOPE(nin=3)  # a scope with 3 input ports
bd.SCOPE(styles=["k", "r--"])        # a scope with 2 input ports
bd.SCOPE(labels=["x", r"$\gamma$"])  # a scope with 2 input ports
bd.SCOPE(styles=[{'color': 'blue'}, {'color': 'red', 'linestyle': '--'}])

Single input port with NumPy array

The port is fed with a 1D-array, and vector is an:

  • int, this is the expected width of the array, all its elements will be plotted

  • a list of ints, interpretted as indices of the elements to plot.

Examples:

bd.SCOPE(vector=[0,1,2]) # display elements 0, 1, 2 of array on port 0
bd.SCOPE(vector=[0,1], styles=[{'color': 'blue'}, {'color': 'red', 'linestyle': '--'}])

Note

  • If the vector is of width 3, by default the inputs are plotted as red, green and blue lines.

  • If the vector is of width 6, by default the first three inputs are plotted as solid red, green and blue lines and the last three inputs are plotted as dashed red, green and blue lines.

__init__(nin=1, vector=None, styles=None, stairs=False, scale='auto', labels=None, grid=True, title=None, loc='best', **blockargs)[source]
Parameters:
  • nin (int) – number of inputs, defaults to 1 or if given, the length of style vector

  • vector (int | list[int] | None) – vector signal on single input port, defaults to None

  • styles (str | dict | list[str | dict] | None) – styles for each line to be plotted

  • stairs (bool) – force staircase style plot for all lines, defaults to False

  • scale (Union[Literal['auto'], float]) – fixed y-axis scale, or ‘auto’, defaults to ‘auto’

  • labels (list[str] | None) – labels for the plotted signals, defaults to block name and port of the source of each signal if not given. Used for vertical axis label, legend and cursor readout.

  • grid (bool | list | tuple) – draw a grid, defaults to True. Can be boolean or a tuple of options for grid()

  • title (str | None) – title of plot

  • loc (str) – location of legend, see matplotlib.pyplot.legend(), defaults to “best”

  • blockargs (Any) – common GraphicsBlock options

labels: list[Any] | None
line: list
record(t, inports)[source]

Append one sample. Runs on every accepted sample (see step()).

Return type:

None

styles: list[Any] | None
class bdsim.blocks.displays.ScopeXY(style=None, scale='auto', aspect='equal', labels=['X', 'Y'], init=None, **blockargs)[source]

Bases: GraphicsBlock

SCOPEXY

Plot X against Y.

Inputs:

2

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

0

float

\(x\)

Input

1

float

\(y\)

Create an XY scope where input \(y\) (vertical axis) is plotted against \(x\) (horizontal axis).

Line style is one of:

  • Matplotlib fmt string comprising a color and line style, eg. "k" or "r:"

  • a dict of Matplotlib line style options for Line2D , eg. dict(color="k", linewidth=3, alpha=0.5)

The scale factor defaults to auto-scaling but can be fixed by providing either:

  • a 2-tuple [min, max] which is used for the x- and y-axes

  • a 4-tuple [xmin, xmax, ymin, ymax]

TIMESTAMP = True
__init__(style=None, scale='auto', aspect='equal', labels=['X', 'Y'], init=None, **blockargs)[source]
Parameters:
line: Any
xdata: list[Any]
ydata: list[Any]
class bdsim.blocks.displays.ScopeXY1(indices=[0, 1], labels=('x', 'y'), **blockargs)[source]

Bases: ScopeXY

SCOPEXY1

Plot X[0] against X[1].

Inputs:

1

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(x\)

Create an XY scope where input \(x_j\) (vertical axis) is plotted against \(x_i\) (horizontal axis). This block has one vector input and the elements to be plotted are given by a 2-element iterable \((i, j)\).

Line style is one of:

  • Matplotlib fmt string comprising a color and line style, eg. "k" or "r:"

  • a dict of Matplotlib line style options for Line2D , eg. dict(color="k", linewidth=3, alpha=0.5)

The scale factor defaults to auto-scaling but can be fixed by providing either:

  • a 2-tuple [min, max] which is used for the x- and y-axes

  • a 4-tuple [xmin, xmax, ymin, ymax]

__init__(indices=[0, 1], labels=('x', 'y'), **blockargs)[source]
Parameters:
  • indices (list[int]) – indices of elements to select from block input vector, defaults to [0,1]

  • style (optional str or dict) – line style

  • scale (str or array_like(2) or array_like(4)) – fixed y-axis scale, or ‘auto’, defaults to ‘auto’

  • labels (2-element tuple or list) – axis labels (xlabel, ylabel)

  • init (callable) – function to initialize the graphics, defaults to None

  • blockargs (Any) – common GraphicsBlock options

Function blocks

Functions

Function blocks:

  • have inputs and outputs

  • have no state variables

  • are a subclass of FunctionBlock → Block

class bdsim.blocks.functions.Abs(**blockargs)[source]

Bases: CrossingMixin, FunctionBlock

ABS

Absolute value block.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(|x|\)

The output is the absolute value of the input. If the input is a Numpy array, this operation is performed elementwise.

For example:

absval = bd.ABS()
Seealso:

Sign

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.functions.Clip(min=-inf, max=inf, **blockargs)[source]

Bases: CrossingMixin, FunctionBlock

CLIP

Signal clipping.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(\min(\max(x,a), b)\)

The input signal is clipped to the range from minimum to maximum inclusive.

The signal can be a 1D-array in which case each element is clipped. The minimum and maximum values can be:

  • a scalar, in which case the same value applies to every element of the input vector , or

  • a 1D-array, of the same shape as the input vector that applies elementwise to the input vector.

For example:

clip = bd.CLIP(-1, 1)
__init__(min=-inf, max=inf, **blockargs)[source]
Parameters:
class bdsim.blocks.functions.Deadband(d=1, **blockargs)[source]

Bases: CrossingMixin, FunctionBlock

DEADBAND

Dead band (dead zone).

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(y\)

The output is zero while the input is within the band from \(a\) to \(b\) inclusive. Outside the band the output is the distance of the input from the nearest edge of the band, so the output is continuous:

\[\begin{split}y = \begin{cases} x - b & x > b \\ 0 & a \le x \le b \\ x - a & x < a \end{cases}\end{split}\]

The band is specified by d which can be:

  • a scalar, in which case the band is \(-d\) to \(+d\), or

  • a 2-element array_like, the lower and upper edges of the band \((a, b)\).

If the input is a Numpy array the same band is applied to every element.

For example:

deadband = bd.DEADBAND(0.1)         # band is -0.1 to 0.1
deadband = bd.DEADBAND([-0.1, 0.3]) # band is -0.1 to 0.3
Seealso:

Clip

__init__(d=1, **blockargs)[source]
Parameters:
Raises:

ValueError – d is not a scalar or 2-element array_like, or the band is empty (lower edge above upper edge)

property lower: float

Lower edge of the band.

property upper: float

Upper edge of the band.

class bdsim.blocks.functions.Function(func=None, nin=1, nout=1, persistent=False, fargs=None, fkwargs=None, **blockargs)[source]

Bases: FunctionBlock

FUNCTION

Python function.

Inputs:

N

Outputs:

M

States:

0

Port type

Port number

Types

Description

Input

i

any

\(x_i\)

Output

j

any

\(f_j(x_0, \ldots, x_{N-1})\)

Inputs to the block are passed as separate arguments to the function. Programmatic ositional or keyword arguments can also be passed to the function.

A block with one output port that sums its two input ports is:

func = bd.FUNCTION(lambda u1, u2: u1+u2, nin=2)

A block with a function that takes two inputs and has two additional arguments:

def myfun(u1, u2, param1, param2):
    pass

FUNCTION(myfun, nin=2, args=(p1,p2))

If we need access to persistent (static) data, to keep some state:

def myfun(u1, u2, param1, param2, state):
    pass

func = bd.FUNCTION(myfun, nin=2, args=(p1,p2), persistent=True)

where a dictionary is passed in as the last argument and which is kept from call to call.

A block with a function that takes two inputs and additional keyword arguments:

def myfun(u1, u2, param1=1, param2=2, param3=3, param4=4):
    pass

func = bd.FUNCTION(myfun, nin=2, kwargs=dict(param2=7, param3=8))

A block with two inputs and two outputs, the outputs are defined by two lambda functions with the same inputs:

FUNCTION( [ lambda x, y: x_t, lambda x, y: x* y])

A block with two inputs and two outputs, the outputs are defined by a single function which returns a list:

def myfun(u1, u2):
    return [ u1+u2, u1*u2 ]

func = bd.FUNCTION( myfun, nin=2, nout=2)
__init__(func=None, nin=1, nout=1, persistent=False, fargs=None, fkwargs=None, **blockargs)[source]
Parameters:
property args: list[Any]

The extra positional arguments, fargs and then the state dictionary if persistent.

property kwargs: dict[str, Any]
property persistent: bool

Whether the function is passed a dictionary to hold state between calls.

class bdsim.blocks.functions.Gain(K=1, premul=False, **blockargs)[source]

Bases: FunctionBlock

GAIN

Gain block.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(K x\)

Either or both the input and gain can be Numpy arrays and Numpy will compute the appropriate product \(u K\).

If \(u\) and K are both NumPy arrays the @ operator is used and \(u\) is postmultiplied by the gain. To premultiply by the gain, to compute \(K u\) use the premul option.

For example:

gain = bd.GAIN(2.5)
__init__(K=1, premul=False, **blockargs)[source]
Parameters:
class bdsim.blocks.functions.Interpolate(x=None, y=None, xy=None, time=False, kind='linear', **blockargs)[source]

Bases: FunctionBlock

INTERPOLATE

Interpolate signal.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float

\(x\)

Output

0

float

\(f(x)\)

Interpolate a scalar function of a scalar.

A simple triangle function with domain [0,10] and range [0,1] can be defined by:

interp = bd.INTERPOLATE(x=(0,5,10), y=(0,1,0))

We might also express this as a list of 2D-coordinates:

interp = bd.INTERPOLATE(xy=[(0,0), (5,1), (10,0)])

(Source code, png, hires.png, pdf)

_images/bdsim-blocks-4.png

The data can also be expressed as Numpy arrays. If that is the case, the interpolation function can be vector valued. x has a shape of (N,1) and y has a shape of (N,M). Alternatively xy has a shape of (N,M+1) and the first column is the x-data.

Note:

if time=True then the block has no input ports and acts as a Source not a Function block.

Seealso:

scipy.interpolate.interp1d

__init__(x=None, y=None, xy=None, time=False, kind='linear', **blockargs)[source]
Parameters:
property kind: str

The interpolation method, see scipy.interpolate.interp1d.

property x: ndarray

The x-values of the function.

Setter accepts:

Any

property xy: ndarray

The x- and y-values together, the first column is x. Setting it can change the length.

Setter accepts:

Any

property y: ndarray

The y-values of the function, one row per x-value.

Setter accepts:

Any

class bdsim.blocks.functions.Pow(p=1, matrix=False, **blockargs)[source]

Bases: FunctionBlock

POW

Power block.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(x^p\)

If the input is a Numpy array the result depends on matrix. If matrix is False the block performs an elementwise exponentiation and the result is a Numpy array of the same size.

If matrix is True and the input is a square matrix and p is an integer then matrixwise exponentiation is performedand using repeated matrix multiplication and matrix inversion. If p is not an integer it uses SciPy to compute the power using an eigenvalue decomposition.

For example:

pow = bd.POW(2)
Seealso:

numpy.linalg.matrix_power() scipy.linalg.fractional_matrix_power()

__init__(p=1, matrix=False, **blockargs)[source]
Parameters:
  • p (int | float) – The exponent value, defaults to 1

  • matrix (bool) – matrix power, not elementwise exponentiation, defaults to False

  • blockargs (Any) – common block options

class bdsim.blocks.functions.Prod(ops='**', matrix=None, **blockargs)[source]

Bases: FunctionBlock

PROD

Product junction.

Inputs:

N

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

i

int, float, ndarray

\(x_i\)

Output

0

int, float, ndarray

\(\prod_i \{x_i | \frac{1}{x_i}\}\)

Multiply or divide input signals according to the ops string. The number of input ports is the length of this string.

For example:

prod = PROD('*/*')

is a 3-input product junction which computes in[0] / in[1] * in[2].

Note:

By default the * and / operators are used which perform element-wise operations. If an input is a Numpy array, @ and @ np.linalg.inv() are used instead. The shapes of matrices must conform. A matrix on a / input must be square and non-singular. Matrices are multiplied in ascending port order.

__init__(ops='**', matrix=None, **blockargs)[source]
Parameters:
  • ops (str) – operations associated with input ports, accepted characters: * or /, defaults to ‘**’

  • inputs (Block or Plug) – Optional incoming connections

  • matrix (bool | None) – deprecated, matrix vs elementwise operation is now auto-detected from the input type and this argument has no effect

  • blockargs (Any) – common block options

class bdsim.blocks.functions.Sign(**blockargs)[source]

Bases: CrossingMixin, FunctionBlock

SIGN

Sign block.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(\operatorname{sgn}(x)\)

The output is -1, 0 or +1 according to whether the input is negative, zero or positive. If the input is a Numpy array, this operation is performed elementwise.

For example:

sign = bd.SIGN()
Seealso:

Sqrt

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.functions.Sqrt(**blockargs)[source]

Bases: FunctionBlock

SQRT

Square root block.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

int, float, ndarray

\(x\)

Output

0

int, float, ndarray

\(\operatorname{sgn}(x)\sqrt{|x|}\)

The block computes the signed square root of the input, which is defined for negative inputs: it returns the negative of the square root of the absolute value. If the input is a Numpy array, this operation is performed elementwise.

For example:

sqrt = bd.SQRT()

Useful for square-root controller.

Seealso:

Pow

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.functions.Sum(signs='++', mode=None, **blockargs)[source]

Bases: FunctionBlock

SUM

Summing junction.

Inputs:

N

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

i

int, float, ndarray

\(x_i\)

Output

0

int, float, ndarray

\(\sum_i \pm x_i\)

Add or subtract input signals according to the signs string. The number of input ports is the length of this string.

For example:

sum = bd.SUM('+-+')

is a 3-input summing junction which computes in[0] - in[1] + in[2].

Note:

The signals must be compatible for addition, and if some are arrays they must be broadcastable.

__init__(signs='++', mode=None, **blockargs)[source]
Parameters:
  • signs (str) – a string comprising + or - characters, defaults to ++

  • mode (str | None) – controls addition mode, per element, string comprises r or c or C or L, defaults to None

  • blockargs (Any) – common block options

For example the string +- creates a 2-port block where the second input is subtracted from the first.

mode controls how elements of the input vectors are added/subtracted. Elements which are angles must be treated specially, and this is indicated by the corresponding characters in mode. The string’s length must equal the width of the input vectors. The characters of the string can be:

mode character

purpose

r

real number, don’t wrap (default)

c

angle on circle, wrap to [-π, π)

C

angle on circle, wrap to [0, 2π)

L

colatitude angle, wrap to [0, π]

For example if mode="rc" then a 2-element array would have its second element wrapped to the range [-π, π).

class bdsim.blocks.functions.Switch(threshold=None, **blockargs)[source]

Bases: CrossingMixin, FunctionBlock

SWITCH

Select one of two signals.

Inputs:

3

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0, X

any

signal passed to the output when S selects it

Input

1, Y

same as X

signal passed to the output otherwise

Input

2, S

scalar

the selector

Output

0, Z

same as X

X or Y

The output is X or Y, whichever S selects. X and Y can be of any type but must be of the same type and, if they are arrays, of the same shape, which is checked when the diagram is compiled. An int and a float are not the same type, so a float signal switched against a constant needs CONSTANT(0.0), not CONSTANT(0). The input that is not selected is not used, so a nan or inf on it does not reach the output.

S is a scalar and selects X as follows:

S

Z is X when

Notes

bool

S is true

int

S != 0

unless threshold is given

float

S >= threshold

threshold defaults to 0, so S = 0.0 selects X

int or float with threshold given

S >= threshold

anything else, such as None, a string or a list

bool(S)

an empty list is false

array with more than one element

error

S must be a scalar

A size-1 array counts as a scalar. A nan on a float S compares false and selects Y.

The output jumps when S changes the selection and X and Y differ at that instant. For a numeric S that changes continuously, the solver is restarted exactly where S crosses its threshold, so no step straddles the jump.

For example:

switch = bd.SWITCH(threshold=0.5)
bd.connect(x, switch.X)
bd.connect(y, switch.Y)
bd.connect(s, switch.S)
Seealso:

Clip Sign

__init__(threshold=None, **blockargs)[source]
Parameters:
  • threshold (float | None) – S selects X when S >= threshold; None (the default) uses the rule for the type of S in the table above

  • blockargs (Any) – common block options

Raises:

ValueError – threshold is not a real number

configure()[source]

Prepare the block for a run, using what compile() learned about its wires.

Called once per run, after reset() and before start(). This is the place to read insig and outsig, for example to size per-element detectors or allocate buffers. The signatures are those observed by the trial evaluation in compile(). They are None if the diagram was compiled with evaluate=False, in which case the block should not assume anything about its wires.

The default does nothing. start() keeps its meaning: acquire resources and register with the simulation.

Return type:

None

Linear algebra

Linear algebra blocks:

  • have inputs and outputs

  • have no state variables

  • are a subclass of FunctionBlock → Block

class bdsim.blocks.linalg.Cond(**blockargs)[source]

Bases: FunctionBlock

COND

Matrix condition number.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\mbox{cond}(\mathbf{A})\)

Seealso:

numpy.linalg.cond()

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.linalg.Det(**blockargs)[source]

Bases: FunctionBlock

DET

Matrix determinant.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\mbox{det}(\mathbf{A})\)

Compute the matrix determinant.

Seealso:

numpy.linalg.det()

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.linalg.Flatten(order='C', **blockargs)[source]

Bases: FunctionBlock

FLATTEN

Flatten a multi-dimensional array.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\mbox{vec}(\mathbf{A})\)

Flattens the incoming array in either row major (‘C’) or column major (‘F’) order.

Seealso:

numpy.ndarray.flatten()

__init__(order='C', **blockargs)[source]
Parameters:
class bdsim.blocks.linalg.Inverse(pinv=False, **blockargs)[source]

Bases: FunctionBlock

INVERSE

Matrix inverse.

Inputs:

1

Outputs:

2

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\mathbf{A}^{-1}\)

Output

1

float

\(\mbox{cond}(\mathbf{A})\)

Compute inverse of the 2D-array input signal. If the matrix is square the inverse is computed unless the pinv flag is True. For a non-square matrix the pseudo-inverse is used. The condition number is output on the second port.

Seealso:

numpy.linalg.inv() numpy.linalg.pinv() numpy.linalg.cond()

__init__(pinv=False, **blockargs)[source]
Parameters:
onames = ('inv', 'cond')
class bdsim.blocks.linalg.Norm(ord=None, axis=None, **blockargs)[source]

Bases: FunctionBlock

NORM

Array norm.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\|\mathbf{A}\|\)

Computes the specified norm for a 1D- or 2D-array.

Seealso:

numpy.linalg.norm()

__init__(ord=None, axis=None, **blockargs)[source]
Parameters:
  • axis (Any) – specifies the axis along which to compute the vector norms, defaults to None.

  • ord (Any) – Order of the norm, default to None.

  • blockargs (Any) – common block options

class bdsim.blocks.linalg.Slice1(index, **blockargs)[source]

Bases: FunctionBlock

SLICE1

Slice out subarray of 1D-array.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(v\)

Output

0

ndarray

\(v_{i\dots j}\)

Compute a 1D slice of input 1D array.

If index is None it means all elements.

If index is a list, perform NumPy fancy indexing, returning the specified elements

Example:

slice = bd.SLICE1(index=[2,3]) # return elements 2 and 3 as a 1D array
slice = bd.SLICE1(index=[2])   # return element 2 as a 1D array
slice = bd.SLICE1(index=2)     # return element 2 as a NumPy scalar

If index is a tuple, it must have three elements. It describes a Python slice (start, stop, step) where any element can be None

  • start=None means start at first element

  • stop=None means finish at last element

  • step=None means step by one

rows=None is equivalent to rows=(None, None, None).

Example:

slice = bd.SLICE1(index=(None,None,2))  # return every second element
slice = bd.SLICE1(index=(None,None,-1)) # reverse the elements
Seealso:

Slice1

__init__(index, **blockargs)[source]
Parameters:
property index: slice | list[Any] | int

Elements to select, a slice or a list of element numbers.

Setter accepts:

Any

class bdsim.blocks.linalg.Slice2(rows=None, cols=None, **blockargs)[source]

Bases: FunctionBlock

SLICE2

Slice out subarray of 2D-array.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\mathbf{A}_{i\ldots j, m\ldots n}\)

Compute a 2D slice of input 2D array.

If rows or cols is None it means all rows or columns respectively.

If rows or cols is a list, perform NumPy fancy indexing, returning the specified rows or columns

Example:

slice = bd.SLICE2(rows=[2,3])  # return rows 2 and 3, all columns
slice = bd.SLICE2(cols=[4,1])  # return columns 4 and 1, all rows
slice = bd.SLICE2(rows=[2,3], cols=[4,1]) # return elements [2,4] and [3,1] as a 1D array

If a single row or column is selected, the result will be a 1D array

If rows or cols is a tuple, it must have three elements. It describes a Python slice (start, stop, step) where any element can be None

  • start=None means start at first element

  • stop=None means finish at last element

  • step=None means step by one

rows=None is equivalent to rows=(None, None, None).

Example:

slice = bd.SLICE2(rows=(None,None,2))  # return every second row
slice = bd.SLICE2(cols=(None,None,-1)) # reverse the columns

The list and tuple notation can be mixed, for example, one for rows and one for columns.

Seealso:

Slice1 Index

__init__(rows=None, cols=None, **blockargs)[source]
Parameters:
property cols: slice | list[Any] | int

Columns to select, a slice or a list of column numbers.

Setter accepts:

Any

property rows: slice | list[Any] | int

Rows to select, a slice or a list of row numbers.

Setter accepts:

Any

class bdsim.blocks.linalg.Transpose(**blockargs)[source]

Bases: FunctionBlock

TRANSPOSE

Matrix transpose.

Inputs:

1

Outputs:

2

States:

0

Port type

Port number

Types

Description

Input

0

ndarray

\(\mathbf{A}\)

Output

0

ndarray

\(\mathbf{A}^{\top}\)

Compute transpose of the 2D-array input signal.

Note

  • An input 1D-array of shape (N,) is turned into a 2D-array column vector with shape (N,1).

  • An input 2D-array column vector of shape (N,1) becomes a 2D-array row vector with shape (1,N).

Seealso:

numpy.transpose()

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

Spatial math

class bdsim.blocks.spatial.DPoseIntegrator(*args, **kwargs)[source]

Bases: PoseIntegrator_S

DPOSEINTEGRATOR

Deprecated: use PoseIntegrator_S instead.

__init__(*args, **kwargs)
Parameters:
class bdsim.blocks.spatial.PoseIntegrator(x0=None, **blockargs)[source]

Bases: ContinuousBlock

POSEINTEGRATOR

Continuous-time pose integrator

Inputs:

1

Outputs:

1

States:

6

Port type

Port number

Types

Description

Input

0

ndarray(6,)

\(x\)

Output

0

SE3

\(y\)

This block integrates spatial velocity over time. The block input is a spatial velocity as a 6-vector \((v_x, v_y, v_z, \omega_x, \omega_y, \omega_z)\) and the output is pose as an SE3 instance.

Note

The state vector is a velocity twist.

__init__(x0=None, **blockargs)[source]
Parameters:
deriv(t, u, x)[source]
Return type:

Any

property x0: ndarray

Initial state, the twist of the initial pose. Set it with an SE3, a Twist3 or a 6-vector.

Setter accepts:

Any

class bdsim.blocks.spatial.PoseIntegrator_S(clock, x0=None, **blockargs)[source]

Bases: SampledBlock

POSEINTEGRATOR_S

Discrete-time spatial velocity integrator.

Inputs:

1

Outputs:

1

States:

6

Port type

Port number

Types

Description

Input

0

ndarray(6,)

\(x\)

Output

0

SE3

\(y\)

This block integrates spatial velocity over time. The block input is a spatial velocity as a 6-vector \((v_x, v_y, v_z, \omega_x, \omega_y, \omega_z)\) and the output is pose as an SE3 instance.

Note

State is a velocity twist.

__init__(clock, x0=None, **blockargs)[source]
Parameters:
next(t, u, x)[source]
Return type:

ndarray

property x0: ndarray

Initial state, the twist of the initial pose. Set it with an SE3, a Twist3 or a 6-vector.

Setter accepts:

Any

class bdsim.blocks.spatial.Pose_inverse(**blockargs)[source]

Bases: FunctionBlock

POSE_INVERSE

Pose inverse.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

SEn, SOn

\(\xi\)

Output

0

SEn, SOn

\(\ominus \xi\)

Invert the pose on the input port.

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

class bdsim.blocks.spatial.Pose_postmul(pose=None, **blockargs)[source]

Bases: FunctionBlock

POSE_POSTMUL

Post multiply pose.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

SEn, SOn

\(\xi\)

Output

0

SEn, SOn

\(\xi \oplus \xi_c\)

Postmultiply the input pose by a constant pose.

Note

Pose objects must be of the same type.

Seealso:

Pose_premul

__init__(pose=None, **blockargs)[source]
Parameters:
class bdsim.blocks.spatial.Pose_premul(pose=None, **blockargs)[source]

Bases: FunctionBlock

POSE_PREMUL

Pre multiply pose.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

SEn, SOn

\(\xi\)

Output

0

SEn, SOn

\(\xi_c \oplus \xi\)

Premultiply the input pose by a constant pose.

Note

Pose objects must be of the same type.

Seealso:

Pose_postmul

__init__(pose=None, **blockargs)[source]
Parameters:
class bdsim.blocks.spatial.Transform_vector(**blockargs)[source]

Bases: FunctionBlock

TRANSFORM_VECTOR

Transform a vector.

Inputs:

2

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

SEn, SOn

\(\xi\)

Input

1

ndarray

\(v\), Euclidean 2D or 3D

Output

0

ndarray

\(\xi \bullet v\)

Linearly transform the input vector by the input pose.

__init__(**blockargs)[source]
Parameters:

blockargs (Any) – common block options

Connection blocks

Connection blocks are in two categories:

  1. Signal manipulation:
    • have inputs and outputs

    • have no state variables

    • are a subclass of FunctionBlock → Block

  2. Subsystem support
    • have inputs or outputs

    • have no state variables

    • are a subclass of SubsysytemBlock → Block

class bdsim.blocks.connections.DeMux(nout=1, **blockargs)[source]

Bases: FunctionBlock

DEMUX

Demultiplex signals.

Inputs:

1

Outputs:

N

States:

0

Port type

Port number

Types

Description

Input

0

iterable

\(x\)

Output

i

any

\(x_i\)

This block has a single input port and nout output ports. The input signal is an iterable whose nout elements are routed element-wise to individual scalar output ports. If the input is a 1D Numpy array, then each output port is an element of that array.

Seealso:

Mux

__init__(nout=1, **blockargs)[source]
Parameters:
class bdsim.blocks.connections.Dict(keys, **blockargs)[source]

Bases: FunctionBlock

DICT

Create a dictionary signal.

Inputs:

N

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

i

any

\(x_i\)

Output

0

dict

{key: x[i] for i, key in enumerate(keys)}

Inputs are assigned to a dictionary signal, using the corresponding names from keys. For example:

dd = bd.DICT(["x", "xd", "xdd"])

expects three inputs and assigns them to dictionary items x, xd, xdd of the output dictionary respectively.

This is somewhat like a multiplexer Mux but allows for named heterogeneous data. A dictionary signal can serve a similar purpose to a “bus” in Simulink(R).

Seealso:

Item Mux

__init__(keys, **blockargs)[source]
Parameters:
class bdsim.blocks.connections.InPort(nout=1, **blockargs)[source]

Bases: FunctionBlock

INPORT

Input ports for a subsystem.

Inputs:

0

Outputs:

N

States:

0

Port type

Port number

Types

Description

Output

j

any

\(y_j\)

This block connects a subsystem to a parent block diagram. Inputs to the parent-level SubSystem block appear as the outputs of this block.

Note

Only one INPORT block can appear in a block diagram but it can have multiple ports. This is different to Simulink(R) which would require multiple single-port input blocks.

__init__(nout=1, **blockargs)[source]
Parameters:
class bdsim.blocks.connections.Index(index=None, **blockargs)[source]

Bases: FunctionBlock

INDEX

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

i

iterable

\(x\)

Output

j

iterable

\(x_i\)

The specified element(s) of the input iterable (list, string, etc.) are output. The index can be an integer, sequence of integers, a Python slice object, or a string with Python slice notation, eg. "::-1".

Seealso:

Slice1 Slice2

__init__(index=None, **blockargs)[source]

Index an iterable signal.

Parameters:
property index: Any

Element(s) to select: a list of integers, an integer or a slice.

class bdsim.blocks.connections.Item(item, **blockargs)[source]

Bases: FunctionBlock

ITEM

Select item from a dictionary signal.

Inputs:

1

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

0

dict

D

Output

0

any

D[i]

For a dictionary type input signal, select one item as the output signal. For example:

item = bd.ITEM("xd")

selects the xd item from the dictionary signal input to the block.

This is somewhat like a demultiplexer DeMux but allows for named heterogeneous data. A dictionary signal can serve a similar purpose to a “bus” in Simulink(R).

Seealso:

Dict

__init__(item, **blockargs)[source]
Parameters:
class bdsim.blocks.connections.Mux(nin=1, **blockargs)[source]

Bases: FunctionBlock

MUX

Multiplex signals.

Inputs:

N

Outputs:

1

States:

0

Port type

Port number

Types

Description

Input

i

float, ndarray

\(x_i\)

Output

0

ndarray

\([x_0 \ldots x_{N-1}]\)

This block takes a number of scalar or 1D-array signals and concatenates them into a single 1-D array signal. For example:

mux = bd.MUX(2)
Seealso:

DeMux Dict

__init__(nin=1, **blockargs)[source]
Parameters:
class bdsim.blocks.connections.OutPort(nin=1, **blockargs)[source]

Bases: FunctionBlock

OUTPORT

Output ports for a subsystem.

Inputs:

N

Outputs:

0

States:

0

Port type

Port number

Types

Description

Input

i

any

\(x_i\)

This block connects a subsystem to a parent block diagram. The inputs of this block become the outputs of the parent-level SubSystem block.

Note

Only one OUTPORT block can appear in a block diagram but it can have multiple ports. This is different to Simulink(R) which would require multiple single-port output blocks.

__init__(nin=1, **blockargs)[source]
Parameters:
class bdsim.blocks.connections.SubSystem(subsys, nin=1, nout=1, allow_eval=None, trace_eval=False, globalvars=None, **blockargs)[source]

Bases: SubsystemBlock

SUBSYSTEM

Instantiate a subsystem.

Inputs:

N

Outputs:

M

States:

0

Port type

Port number

Types

Description

Input

i

any

\(x_i\)

Output

j

any

\(y_j\)

This block represents a subsystem in a block diagram. The definition of the subsystem can be:

  • a path to a .bd JSON model file, which is loaded via bdsim.bdload, or

  • the name of a Python module which is imported and must create exactly one BlockDiagram instance, or

  • a BlockDiagram instance

Warning

Module name mode (non-.bd string): importing a module executes all top-level Python code in that file. Only use this with modules you trust completely.

File mode (.bd path): loads a JSON file safely. eval() is only used for parameters starting with "="; control this with allow_eval.

The referenced block diagram must contain either or both of:

  • one InPort block, which has outputs but no inputs. These outputs are connected to the inputs to the enclosing SubSystem block.

  • one OutPort block, which has inputs but no outputs. These inputs are connected to the outputs to the enclosing SubSystem block.

Note

  • The referenced block diagram is treated like a macro and copied into the parent block diagram at compile time. The SubSystem, InPort and OutPort blocks are eliminated, that is, all hierarchical structure is lost.

  • The same subsystem can be used multiple times, its blocks and wires will be cloned. Subsystems can also include subsystems.

  • The number of input and output ports is not specified, they are computed from the number of ports on the InPort and OutPort blocks within the subsystem.

__init__(subsys, nin=1, nout=1, allow_eval=None, trace_eval=False, globalvars=None, **blockargs)[source]
Parameters:
  • subsys (str | BlockDiagram) – Subsystem as a .bd filepath, module name, or BlockDiagram instance

  • nin (int) – Number of input ports, defaults to 1

  • nout (int) – Number of output ports, defaults to 1

  • allow_eval (bool | None) – (.bd mode only) True enables eval silently, False refuses =... expressions, None (default) warns once.

  • trace_eval (bool) – (.bd mode only) print each expression before evaluation.

  • globalvars (dict[str, Any] | None) – (.bd mode only) extra names available when evaluating "=..." parameter expressions.

  • blockargs (Any) – common block options

Raises:
  • ImportError – module not found or no BlockDiagram in it

  • ValueError – invalid argument type or .bd load constraints not met

Continuous-time dynamics

Continuous-time blocks:

  • have inputs and outputs

  • have state variables

  • are a subclass of ContinuousBlock → Block

class bdsim.blocks.continuous.Deriv(alpha, x0=0, y0=None, gain=1.0, **blockargs)[source]

Bases: SubsystemBlock

DERIV

Continuous-time derivative.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float

\(x\)

Output

0

float

\(y\)

Implements the dynamics of a derivative filter, but to be causal (proper) it includes a first-order low-pass filter. The dynamics is

\[\frac{s}{\frac{s}{\alpha} + 1}\]

The pole is at \(s=-\alpha\). A small value of alpha corresponds to a long-time constant in the step reponse. The parameter alpha can be used to achieve the desired tradeoff between noise reduction and phase lag.

The derivative calculation is performed using a complementary filter, implemented as a subsystem with an integrator and a feedback loop. The initial state of the integrator is given by x0:

    +
u ───> SUM ───────> GAIN(alpha) ──┬───>  GAIN(k) ───> y
        ▲ ─                       │
        │                         │
        └───  INTEGRATOR(x0) <────┘

If the initial output of the derivative block is known it can be provided as y0 from which x0 is calculated by \(x_0 = - \alpha y_0\).

The final GAIN block is only included if gain is not 1.0, and can be used to scale the output of the derivative block.

Warning

This derivative block has a direct feedthrough term, and depending on how it is used in a system it may introduce an an algebraic loop which will be flagged at compile time. The Deriv2 blockis an alternative implementation without direct feedthrough and includes a second-order filter which may be more suitable for some applications.

Changed in version 1.2.0: The pole is now at \(s=-\alpha\) instead of \(s=-1/\alpha\).

Seealso:

Integrator

__init__(alpha, x0=0, y0=None, gain=1.0, **blockargs)[source]
Parameters:
property y0: ndarray

The initial output, which is the initial state \(x_0\) scaled by the pole \(\alpha\): \(y_0 = -x_0/\alpha\). Setting it sets the state.

Setter accepts:

Any

class bdsim.blocks.continuous.Deriv2(wn, unit='rad/s', zeta=1, x0=(0, 0), gain=1.0, **blockargs)[source]

Bases: LTI_SS

DERIV2

Continuous-time derivative with second-order filter.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float

\(x\)

Output

0

float

\(y\)

Implements the dynamics of a derivative filter, but to be causal it includes a second-order low-pass filter. The dynamics are

\[\frac{Y(s)}{U(s)} = \frac{s}{s^2 + 2\omega_n \zeta s + \omega_n^2}\]

It is implemented in state-space form using an LTI_SS block. The state-space model is in observer canonical form, with the state vector being the output of the first and second integrators in the chain. The initial state of the integrators is given by x0. The initial output of the derivative block is given by x0[0].

Seealso:

Integrator

__init__(wn, unit='rad/s', zeta=1, x0=(0, 0), gain=1.0, **blockargs)[source]
Parameters:

Damping factor defaults to critical damping, which results in the fastest response without overshoot. A smaller value of zeta results in a faster response but with overshoot, while a larger value results in a slower response with no overshoot. Choose zeta=0.707 (\(1/\sqrt{2}\)) for optimal rise time and overshoot (4.3%).

property gain: float

Gain or scaling factor.

property wn: float

Natural frequency, in unit.

property zeta: float

Damping ratio.

class bdsim.blocks.continuous.Integrator(x0=0, gain=1.0, min=None, max=None, enable=False, **blockargs)[source]

Bases: CrossingMixin, ContinuousBlock

INTEGRATOR

Continuous-time integrator.

Inputs:

1 or 2

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(x\)

Input

1

bool, float

enable, only if created with enable=True

Output

0

any

\(y\)

This block implements the dynamics of a continuous-time integrator with gain \(k\), which is given by

\[\begin{split}\begin{aligned} x(t) &= k \int_0^T u(t) \, dt \\ y(t) &= x(t) \end{aligned}\end{split}\]

The state can be a scalar or a vector. The initial state, and type, is given by x0. The shape of the input signal must match x0.

The gain is applied to the input, before integration: the state is \(x(t) = x_0 + k \int u \, dt\) and the output is \(x\). The limits min and max apply to this scaled state, which is also the output.

The minimum and maximum output values can be:

  • a scalar, in which case the same value applies to every element of the state vector, or

  • a vector, of the same shape as x0 that applies elementwise to the state.

Note

A state that reaches a limit is held there exactly, and is released when the derivative reverses. The solver is stopped and restarted at each of these events, so the time of reaching the limit is found to the solver’s tolerance. The initial state is assumed to be within the limits.

If created with enable=True the block has a second input, the enable signal, which another block can drive. The integrator is enabled while the signal is greater than zero, so a boolean works. When it becomes false the state is set to zero and held there, and when it becomes true again integration resumes from zero. If the signal is false at the start the state is zeroed at t=0, though the first logged sample is still the initial state x0. Changes of the enable signal are found by root-finding, like the limits.

Note

INTEGRATOR_S still takes a Python function for enable.

Seealso:

Deriv

__init__(x0=0, gain=1.0, min=None, max=None, enable=False, **blockargs)[source]
Parameters:
crossing_event(tag, t_crossing, y_crossing, state_map, simstate)[source]

Respond to a detector firing.

Parameters:
  • tag (Any) – the tag the detector was declared with

  • t_crossing (float) – time of the crossing

  • y_crossing (Any) – continuous state vector of the whole diagram at the crossing

  • state_map (dict[Any, Any]) – block to state map, the diagram already evaluated at the crossing; write into state_map[self] to change this block’s state

  • simstate (Any) – the run’s simulation state

Return type:

None

The solver restarts from the state map after this returns.

The default does nothing for the threshold crossings declared by declare_thresholds() and raises for anything else.

property max: ndarray | None

Upper limit of each state, or None for no limit.

Setter accepts:

Any

property min: ndarray | None

Lower limit of each state, or None for no limit.

Setter accepts:

Any

class bdsim.blocks.continuous.LTI_SISO(num=1, den=[1, 1], x0=None, form='ccf', order='backward', verbose=False, **blockargs)[source]

Bases: _TFParams, LTI_SS

LTI_SISO

Continuous-time SISO LTI dynamics.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float

\(u\)

Output

0

float

\(y\)

Implements the dynamics of a continuous-time single-input single-output (SISO) linear time invariant (LTI) system described by numerator and denominator polynomial coefficients. The dynamics are given by

\[\frac{Y(s)}{U(s)} = \frac{N(s)}{D(s)}\]

Coefficients are given in the order from highest order to zeroth order, ie. \(2s^2 - 4s +3\) is [2, -4, 3], \(s^3\) is [1, 0, 0, 0].

The state-space form can be either controller canonical form or observer canonical form, as specified by the form argument.

Examples:

lti = bd.LTI_SISO(N=[1, 2], D=[2, 3, -4])

is the transfer function \(\frac{s+2}{2s^2+3s-4}\).

Note

  • The state-space realization is not unique. The controller canonical form is more common in control design, while the observer canonical form is more common in estimation.

  • The state ordering convention (the direction of the integrator chain) can be specified by the order argument, and results in either 1s on the super-diagonal or sub-diagonal of the A matrix for the controller canonical form.

Note

This block is single-input single-output. For a system with more than one input or output, convert the transfer function to state-space form with scipy.signal.tf2ss(), which takes several numerators with a common denominator, or control.tf2ss() for a full transfer function matrix, and create the block with LTI_SS.

Seealso:

LTI_SS LTI_SISO_S

__init__(num=1, den=[1, 1], x0=None, form='ccf', order='backward', verbose=False, **blockargs)[source]
Parameters:
  • num (int | float | tuple[float, ...] | list[float] | ndarray) – Numerator coefficients in descending powers of \(s\).

  • den (int | float | tuple[float, ...] | list[float] | ndarray) – Denominator coefficients in descending powers of \(s\). Does not have to be normalized.

  • form (str) – The canonical form of the realization, defaults to ‘ccf’.

  • order (str) – The state ordering convention

  • verbose (bool) – If True, print the state-space matrices, defaults to False

Returns:

LTI_SISO block

Return type:

LTI_SISO instance

Coefficients num and den can be specified in the form of an array of coefficients, or an array of factors. The coefficients and factors are arrays of coefficients in decreasing powers of \(s\). For example:

  • [1, 2] is the polynomial \(s+2\),

  • [[1, 1], [1, 2]] is the factors \((s+1)(s+2)\) which are convolved to obtain the coefficients of \(s^2 + 3s + 2\).

  • [2,[1,1], [1,2]] is the factors \(2(s+1)(s+2)\) which are convolved to obtain the coefficients of \(2s^2 + 6s + 4\)

The form of the realization can be one of:

  • 'ccf'Controller Canonical Form. The characteristic equation

    coefficients appear in a row of A. Useful for control design.

  • 'ocf'Observer Canonical Form. The characteristic equation

    coefficients appear in a column of A. Useful for estimation.

The order of the integrator chain can be one of:

  • 'forward'\(x_0\) is the output of the first integrator,

    \(x_n-1\) is the last. Results in 1s on the super-diagonal for 'ccf'.

  • 'backward': \(x_n-1\) is the output of the first integrator,

    \(x_0\) is the last. Results in 1s on the sub-diagonal for 'ccf'.

Note

  • The transfer function is assumed to be strictly proper (\(deg(N) < deg(D)\)).

  • The default form='ccf', order='backward' corresponds to the state-space realization returned by scipy.signal.tf2ss and MATLAB’s tf2ss.

  • num and den are attributes holding the numerator and denominator coefficients (expanded if they were given as factors), and can be changed after the block is created (they are parameters). The state-space matrices are rebuilt from them. The order of the system, the length of den minus one, cannot change.

  • The state-space matrices are available in the A, B, C, and D attributes of the block.

  • If the numerator degree is less than the denominator degree, the block has no feedthrough and D is None. The feedthrough attribute of the block is set to True otherwise. It is used by the scheduler to ensure correct block evaluation order.

Changed in version next: The arguments N and D are renamed num and den, because D is also the feedthrough matrix of the state-space realisation. The old keywords still work, with a DeprecationWarning, and will be removed in a later release.

class bdsim.blocks.continuous.LTI_SS(A, B, C, D=None, x0=None, **blockargs)[source]

Bases: ContinuousBlock

LTI_SS

Continuous-time state-space LTI dynamics

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(u\)

Output

0

float, ndarray

\(y\)

Implements the dynamics of a continuous-time multi-input multi-output (MIMO) linear time invariant (LTI) system described in statespace form. The dynamics are given by

\[\begin{split}\begin{aligned} \dot{x} &= A x + B u \\ y &= C x + D u \end{aligned}\end{split}\]

D is optional and defaults to zero. If it is nonzero the block has direct feedthrough, the output depends on the input at the same instant, which creates an algebraic loop if the output feeds back to the input without a delay.

The output is a single port: a float if C has one row, and otherwise an ndarray with one element for each row of C, so a system with several outputs is one wire, which a DEMUX block can split. The input has one port for each column of B, each carrying a scalar.

Examples:

lti = bd.LTI_SS(A=np.array([[-2.0]]), B=np.array([1.0]), C=np.array([-1.0]))

is the system \(\dot{x}=-2x+u, y=-x\).

Seealso:

LTI_SISO LTI_SS_S

property D: ndarray | None

The feedthrough matrix, None if it is zero.

Setter accepts:

Any

__init__(A, B, C, D=None, x0=None, **blockargs)[source]
Parameters:
class bdsim.blocks.continuous.PID(P=0.0, I=0.0, D=0.0, D_pole=1, I_limit=None, structure='parallel', terms=None, **blockargs)[source]

Bases: SubsystemBlock

PID

Continuous-time PID control.

Inputs:

2

Outputs:

1

States:

2

Port type

Port number

Types

Description

Input

0

float

\(x\), plant output

Input

1

float

\(x^*\), demanded output

Output

0

any

\(u\), control to plant

Implements the dynamics of a continuous-timePID controller as a bdsim subsystem. There are three possible structures:

  • Parallel structure:

          ┌───> P ──────┐
          │             │
          │             ▼
    e ────┼───> Ds ──> SUM ───> y
          │             ▲
          │             │
          └───> I/s ────┘
    
\[\begin{split}\begin{aligned} e &= x^* - x \\ \frac{Y(s)}{E(s)} &= P + \frac{I}{s} + D s \end{aligned}\end{split}\]
  • Ideal or standard structure. Described by ANSI/ISA-S75:

                ┌─────────────┐
                │             │
                │             ▼
    e ────> P ──┼───> Ds ──> SUM ───> y
                │             ▲
                │             │
                └───> I/s ────┘
    
\[\begin{split}\begin{aligned} e &= x^* - x \\ \frac{Y(s)}{E(s)} &= P \left(1 + \frac{I}{s} + D s\right) \end{aligned}\end{split}\]
  • Series structure. Archaic form, essentially a PI controller followed by a PD controller:

                ┌──────────────┐    ┌─────────────┐
                │              │    │             │
                │              ▼    │             ▼
    e ────> P ──┴──> I/s ───> SUM ──┴──>  Ds ──> SUM ───> y
    
\[\begin{split}\begin{aligned} e &= x^* - x \\ \frac{Y(s)}{E(s)} &= P \left(1 + \frac{I}{s}\right)\left(1 + D s\right) \end{aligned}\end{split}\]

Sometimes the gains are written in terms of time constants \(T_i = 1/I\) and \(Td = D\).

The PID controller is a subsytem comprising a number of blocks.

Which terms are built. The controller is a subsystem of ordinary blocks, and a term whose gain is zero is normally left out, to save blocks and states. The proportional term is always built.

  • By default (terms=None) the I term is built only if I is not zero, and the D term only if D is not zero. So bd.PID(P=3, I=1) is a PI controller and bd.PID(P=3) is proportional only.

  • terms overrides this. It is one of "P", "PI", "PD" or "PID", and exactly those terms are built, even if their gain is zero. A term that is built can have its gain changed after the block is created; a term that was left out cannot be added later, because the structure is fixed when the block is created. For example, a PD controller that starts with no derivative action:

    pid = bd.PID(P=3, D=0, terms="PD")
    
  • A non-zero gain for a term that terms does not build is an error, not silently ignored. So is a value of terms other than the four above.

  • The cost of building a term at zero gain is its state: an integrator state that stays at zero, or the state of the derivative filter.

The gain equivalence between the three structures is given by

structure

\(P\)

\(I\)

\(D\)

parallel

\(P_p\)

\(I_p\)

\(D_p\)

ideal

\(P_i\)

\(P_i I_i\)

\(P_i D_i\)

series

\(P_s (1 + D_s I_s)\)

\(P_s I_s\)

\(P_s D_s\)

The derivative is computed by a DERIV block which implements a first-order system

\[\frac{s}{s/a + 1}\]

where the real pole \(a=\) -D_filt can be positioned appropriately.

If I_limit is provided it specifies the limits of the integrator output. The integrator state is clipped to these limits, which can be used to prevent integrator windup. The limits can be specified as:

  • a scalar \(a\) the integrator state is clipped to the interval \([-a, a]\)

  • a 2-tuple \((a,b)\) the integrator state is clipped to the interval \([a, b]\)

Examples:

pid = bd.PID(P=3, D=2, I=1)               # PID
pid = bd.PID(P=3, I=1)                    # PI, no D block
pid = bd.PID(P=3)                         # P only
pid = bd.PID(P=3, D=0, terms="PD")        # PD, with a D block that starts at zero
..note:: The result is a subsystem which will be expanded into 12 blocks for the

PID case, fewer for the PI or PD cases.

Warning

This block has a direct feedthrough term (by definition), and depending on how it is used in a system it may introduce an an algebraic loop which will be flagged at compile time.

Changed in version 1.2.0: The pole is now at -D_pole instead of -1/D_pole.

Seealso:

Deriv Integrator

property I_limit: float | tuple[float | None, float | None] | None

Limit on the integral term: None for none, a number for the limit \(\pm\) that number, or a (lower, upper) pair.

Setter accepts:

Any

__init__(P=0.0, I=0.0, D=0.0, D_pole=1, I_limit=None, structure='parallel', terms=None, **blockargs)[source]
Parameters:
  • type (str, optional) – the controller type, defaults to “PID”

  • P (float) – proportional gain, defaults to 0

  • D (float) – derivative gain, defaults to 0

  • I (float) – integral gain, defaults to 0

  • D_pole (float) – filter pole for derivative estimate, defaults to 1 rad/s

  • I_limit (float | tuple[float, ...] | list[float] | None) – integral limit

  • structure (str) – the structure of the PID implementation, “parallel” (default), “series”, “standard|ideal”

  • terms (str | None) – the terms to build, one of “P”, “PI”, “PD” or “PID”, even if a gain is zero; the default is P, plus I and D if their gain is not zero

  • blockargs (Any) – common block options

Raises:

ValueError – terms is not one of those, or a gain is non-zero for a term that is not built

Sampled-time dynamics

The discrete-time state of the blocks on a clock is read by State_S, which is listed with the source blocks because it is a source.

Sampled-time blocks:

  • have inputs and outputs

  • have discrete-time state variables that are sampled/updated at the times specified by the associated clock

  • are a subclass of SampledBlock → Block

Timing. At each clock tick \(t_k\) with \(k \ge 1\) the block computes its next state from the inputs at that instant and the previous state, and that new state is the block’s output until the next tick. The tick at \(t = 0\) does not update the state, so the output holds x0 for the first sample period. The block formulas below are written for this: \(x_k\) is the state held over \([t_k, t_{k+1})\), and \(x_0\) is x0. A block with feedthrough (DERIV_S) also sees the current input.

Note that the value logged at a tick instant is the one from before that tick’s update, so it appears one sample late. It is the logging, not the block, that lags.

class bdsim.blocks.sampled.Anoise_S(clock, sigma=1, seed=None, x0=None, **blockargs)[source]

Bases: _NoiseMixin, SampledBlock

ANOISE_S

Additive noise block.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(u\)

Output

0

float, ndarray

\(u + n\)

The output is the input plus a sample \(n\) of zero-mean Gaussian noise with standard deviation sigma. A new sample is drawn at each tick of the clock and held until the next, so the noise is piecewise constant and the solver sees a function of time. The input passes through continuously.

The sample for tick \(k\) depends only on seed and \(k\), so a seeded block gives the same noise in every run and whatever the solver does. If seed is None each run uses a new seed.

sigma is a scalar or a vector. If the input is a vector the noise has one element per input element, independent of each other, so sigma (or x0) must have that length. A vector sigma gives each element its own standard deviation.

As for all sampled blocks the tick at \(t=0\) is not applied, so the first sample period carries x0 instead of noise. It is zero by default.

For example:

anoise = bd.ANOISE_S(clock, sigma=0.1, seed=1)
Seealso:

Mnoise_S numpy.random.default_rng()

__init__(clock, sigma=1, seed=None, x0=None, **blockargs)[source]
Parameters:
class bdsim.blocks.sampled.DIntegrator(*args, **kwargs)[source]

Bases: Integrator_S

DINTEGRATOR

Deprecated: use Integrator_S instead.

__init__(*args, **kwargs)
Parameters:
  • clock (Clock) – clock source

  • x0 (array_like, optional) – Initial state, defaults to 0

  • gain (float) – gain or scaling factor, defaults to 1

  • min (float or array_like, optional) – Minimum value of state, defaults to None

  • max (float or array_like, optional) – Maximum value of state, defaults to None

  • enable (callable) – function to enable or disable integration

  • blockargs (dict) – common block options

class bdsim.blocks.sampled.Deriv_S(clock, x0=0, gain=1.0, **blockargs)[source]

Bases: SampledBlock

DERIV_S

Discrete-time derivative.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float

\(x\)

Output

0

float

\(y\)

Implements a discrete-time derivative as a backward difference, with transfer function

\[g \, \frac{1 - z^{-1}}{T}\]

where \(g\) is the gain and \(T\) is the sampling time. The block is causal because the output uses the current input and the input at the previous tick, and no filter is needed.

Unlike the continuous-time derivative blocks, this one includes no smoothing filter, so noise on its input is amplified.

The state is the input at the most recent tick, so the output is the difference between the current input and the input at that tick, scaled by the gain and \(1/T\). The state is x0 during the first sample period.

Added in version 1.2.0.

Seealso:

Integrator_S

__init__(clock, x0=0, gain=1.0, **blockargs)[source]
Parameters:
next(t, u, x)[source]
Return type:

ndarray

class bdsim.blocks.sampled.Hysteresis_S(clock, switch_on=0.5, switch_off=-0.5, output_on=1.0, output_off=0.0, x0=None, **blockargs)[source]

Bases: SampledBlock

HYSTERESIS_S

Discrete-time hysteresis (relay with memory, Schmitt trigger).

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(u\)

Output

0

float, ndarray

\(y\)

The state is the output, which switches between two levels. It switches on when the input reaches switch_on and off when the input falls to switch_off. Between the two it keeps its value, which is the memory:

\[\begin{split}y_{k+1} = \begin{cases} y_\mathrm{on} & u_k \ge u_\mathrm{on} \\ y_\mathrm{off} & u_k \le u_\mathrm{off} \\ y_k & \text{otherwise} \end{cases}\end{split}\]

The input is sampled at each tick of the clock and the output is constant between ticks, as for ZOH: the output from tick \(k\) until the next is decided by the input at tick \(k\). Until the first tick after the start of the run the output is x0. A logged value at a tick instant is the value held before that tick’s update.

The state can be a scalar or a vector, given by the shape of x0 and of the parameters. The switching points and output levels can each be:

  • a scalar, in which case the same value applies to every element, or

  • a vector, of the same shape as the state, that applies elementwise.

Note

The switching points must satisfy switch_off <= switch_on. If they are equal the block is an ideal relay with no hysteresis, and the input exactly at the switching point switches on.

For example, a Schmitt trigger that turns on above 0.6 and off below 0.4:

clock = bd.clock(0.01)
trigger = bd.HYSTERESIS_S(clock, switch_on=0.6, switch_off=0.4)
Seealso:

ZOH

__init__(clock, switch_on=0.5, switch_off=-0.5, output_on=1.0, output_off=0.0, x0=None, **blockargs)[source]
Parameters:
Raises:

ValueError – switch_off is above switch_on, the two output levels are equal, or x0 is not one of them

next(t, inputs, x)[source]
Return type:

ndarray

class bdsim.blocks.sampled.Integrator_S(clock, x0=0, gain=1.0, min=None, max=None, enable=None, **blockargs)[source]

Bases: SampledBlock

INTEGRATOR_S

Discrete-time integrator.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(x\)

Output

0

float, ndarray

\(y\)

This block implements the dynamics of a discrete-time integrator with gain \(g\), which is given by

\[\begin{split}\begin{aligned} x_k &= x_{k-1} + g \cdot u_k \cdot T \\ y_k &= x_k \end{aligned}\end{split}\]

This is backward-Euler (rectangular) integration: the input at a tick contributes to the output from that tick, and \(x_0\) is x0.

The state can be a scalar or a vector. The initial state, and type, is given by x0. The shape of the input signal must match x0.

The gain is applied to the input, before accumulation, as in the update equation above. The limits min and max apply to the resulting state, which is also the output. They are applied at each sample time, so no crossing events are needed.

The minimum and maximum output values can be:

  • a scalar, in which case the same value applies to every element of the state vector, or

  • a vector, of the same shape as x0 that applies elementwise to the state.

Note

The minimum and maximum clip the next state, so a state that would pass a limit is held at it until the input reverses. An initial state outside the limits is clipped at the first sample.

Integration can be controlled by an enable function:

enable(t, u, x): bool

where the arguments are current time, a list of inputs to the integrator block and the state as an ndarray. If the function returns False then the integrator’s state is set to zero.

__init__(clock, x0=0, gain=1.0, min=None, max=None, enable=None, **blockargs)[source]
Parameters:
property max: ndarray | None

Upper limit of each state, or None for no limit.

Setter accepts:

Any

property min: ndarray | None

Lower limit of each state, or None for no limit.

Setter accepts:

Any

next(t, u, x)[source]
Return type:

ndarray

class bdsim.blocks.sampled.LTI_SISO_S(clock, num=1, den=[1, 1], x0=None, form='ccf', order='backward', verbose=False, **blockargs)[source]

Bases: _TFParams, LTI_SS_S

LTI_SISO_S

Discrete-time SISO LTI dynamics.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float

\(u\)

Output

0

float

\(y\)

Implements the dynamics of a discrete-time single-input single-output (SISO) linear time invariant (LTI) system described by numerator and denominator polynomial coefficients. The dynamics are given by

\[\frac{Y(z)}{U(z)} = \frac{N(z)}{D(z)}\]

Coefficients are given in the order from highest to lowest order, ie. \(2z^2 - 4z +3\) is [2, -4, 3], \(1 - z^{-1} + 2 z^{-2}\) is [1, -1, 2].

The state-space form can be either controller canonical form or observer canonical form, as specified by the form argument. For either case, the state is the output of a chain of integrators, and the order argument controls the order in which they are mapped to rows of the state-transition matrix.

Examples:

lti = bd.LTI_SISO_S(clock, num=[1, 2], den=[2, 3, -4])

is the transfer function \(\frac{z+2}{2z^2+3z-4}\).

Note

  • The state-space realization is not unique. The controller canonical form is more common in control design, while the observer canonical form is more common in estimation. The state ordering convention (the direction of the integrator chain) can be specified by the order argument, and results in either 1s on the super-diagonal or sub-diagonal of the A matrix for the controller canonical form.

  • This block is single-input single-output. For a system with more than one input or output, convert the transfer function to state-space form with scipy.signal.tf2ss(), which takes several numerators with a common denominator, or control.tf2ss() for a full transfer function matrix, and create the block with LTI_SS_S.

Added in version 1.2.0.

Seealso:

LTI_SS_S LTI_SISO

__init__(clock, num=1, den=[1, 1], x0=None, form='ccf', order='backward', verbose=False, **blockargs)[source]
Parameters:
  • clock (Clock) – clock source

  • num (int | float | tuple[float, ...] | list[float] | ndarray) – Numerator coefficients in descending powers of \(z\).

  • den (int | float | tuple[float, ...] | list[float] | ndarray) – Denominator coefficients in descending powers of \(z\). Does not have to be normalized.

  • form (str) – The canonical form of the realization, defaults to ‘ccf’.

  • order (str) – The state ordering convention

  • verbose (bool) – If True, print the state-space matrices, defaults to False

Returns:

LTI_SISO_S block

Return type:

LTI_SISO_S instance

Coefficients num and den can be specified in the form of an array of coefficients, or an array of factors. The coefficients and factors are arrays of coefficients in decreasing powers of \(z\), this could be \(z^2 + 0.8z + 0.15\) or \(1 + 0.8z^{-1} + 0.15z^{-2}\), both represented as [1, 0.8, 0.15]. For example:

  • [1, 0.8] is the polynomial \(z+0.8\),

  • [[1, 0.3], [1, 0.5]] is the factors \((z+0.3)(z+0.5)\) which are convolved to obtain the coefficients of \(z^2 + 0.8z + 0.15\).

  • [2,[1,0.3], [1,0.5]] is the factors \(2(z+0.3)(z+0.5)\) which are convolved to obtain the coefficients of \(2z^2 + 1.6z + 0.3\)

The form of the realization can be one of:

  • 'ccf'Controller Canonical Form. The characteristic equation

    coefficients appear in a row of A. Useful for control design.

  • 'ocf'Observer Canonical Form. The characteristic equation

    coefficients appear in a column of A. Useful for estimation.

The order of the integrator chain can be one of:

  • 'forward'\(x_0\) is the output of the first integrator,

    \(x_n-1\) is the last. Results in 1s on the super-diagonal for 'ccf'.

  • 'backward': \(x_n-1\) is the output of the first integrator,

    \(x_0\) is the last. Results in 1s on the sub-diagonal for 'ccf'.

Note

Representation Perspectives:

1. Control Perspective (z-domain): If coefficients represent descending powers of \(z\), the states represent forward shifts.

Example: \(G(z) = \\frac{b_1 z + b_2}{z^2 + a_1 z + a_2}\)

2. DSP Perspective (z⁻¹-domain): If coefficients represent ascending powers of \(z^{-1}\), the states represent physical unit delays.

Example: \(H(z^{-1}) = \\frac{b_0 + b_1 z^{-1}}{1 + a_1 z^{-1} + a_2 z^{-2}}\)

In both cases, this function treats the input arrays as ordered coefficients.

\[\begin{split}x[k+1] = A x[k] + B u[k] \\\\ y[k] = C x[k] + D u[k]\end{split}\]

If form='ccf' and order='forward', the state \(x_i[k]\) corresponds to the output of the \(i\)-th delay element in a tapped delay line.

Note

  • The transfer function is assumed to be strictly proper (\(deg(num) < deg(den)\)).

  • The default form='ccf', order='backward' corresponds to the state-space realization returned by scipy.signal.tf2ss and MATLAB’s tf2ss.

  • num and den are attributes holding the numerator and denominator coefficients (expanded if they were given as factors), and can be changed after the block is created (they are parameters). The state-space matrices are rebuilt from them. The order of the system, the length of den minus one, cannot change.

  • The state-space matrices are available in the A, B, C, and D attributes of the block.

  • If the numerator degree is less than the denominator degree, the block has no feedthrough and D is None. The feedthrough attribute of the block is set to True otherwise. It is used by the scheduler to ensure correct block evaluation order.

Changed in version next: The arguments N and D are renamed num and den, because D is also the feedthrough matrix of the state-space realization. The old keywords still work, with a DeprecationWarning, and will be removed in a later release.

class bdsim.blocks.sampled.LTI_SS_S(clock, A, B, C, D=None, x0=None, **blockargs)[source]

Bases: SampledBlock

LTI_SS_S

Discrete-time state-space LTI dynamics

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(u\)

Output

0

float, ndarray

\(y\)

Implements the dynamics of a discrete-time multi-input multi-output (MIMO) linear time invariant (LTI) system described in statespace form. The dynamics are given by

\[\begin{split}\begin{aligned} x_k &= \Phi x_{k-1} + \Gamma u_k \\ y_k &= C x_k + D u_k \end{aligned}\end{split}\]

where \(x_0\) is x0. The input at a tick takes effect in the output from that tick, as it does for all sampled blocks.

\(\Phi\) and \(\Gamma\) are the usual symbols for the discrete-time system and input matrices. They are given by the arguments A and B, the names used for the continuous-time LTI_SS, and are also available as the attributes Phi and Gamma (or Φ and Γ), which are synonyms for A and B.

D is optional and defaults to zero. If it is nonzero the block has direct feedthrough, the output depends on the input at the same instant, which creates an algebraic loop if the output feeds back to the input without a delay.

The output is a single port: a float if C has one row, and otherwise an ndarray with one element for each row of C, so a system with several outputs is one wire, which a DEMUX block can split. The input has one port for each column of B, each carrying a scalar.

Examples:

lti = bd.LTI_SS_S(
    clock, A=np.array([[-2.0]]), B=np.array([1.0]), C=np.array([-1.0])
)

is the system \(x_k=-2x_{k-1}+u_k, y_k=-x_k\).

Added in version 1.2.0.

Seealso:

LTI_SISO_S LTI_SS

property D: ndarray | None

The feedthrough matrix, None if it is zero.

Setter accepts:

Any

property Gamma: ndarray

The input matrix \(\Gamma\), a synonym for B.

Setter accepts:

Any

property Phi: ndarray

The system matrix \(\Phi\), a synonym for A.

Setter accepts:

Any

__init__(clock, A, B, C, D=None, x0=None, **blockargs)[source]
Parameters:
  • clock (Clock) – clock source

  • A (ndarray) – system matrix \(\Phi\), also available as the attribute Phi

  • B (ndarray) – input matrix \(\Gamma\), also available as the attribute Gamma; a 1D array is a column vector

  • C (ndarray) – output matrix; a 1D array is a row vector

  • D (ndarray | None) – feedthrough matrix, defaults to zero

  • x0 (ndarray | None) – initial states, defaults to None

  • blockargs (Any) – common block options

next(t, u, x)[source]
Return type:

ndarray

property Γ: ndarray

The input matrix \(\Gamma\), a synonym for B.

Setter accepts:

Any

property Φ: ndarray

The system matrix \(\Phi\), a synonym for A.

Setter accepts:

Any

class bdsim.blocks.sampled.Mnoise_S(clock, sigma=1, seed=None, x0=None, **blockargs)[source]

Bases: _NoiseMixin, SampledBlock

MNOISE_S

Multiplicative noise block.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(u\)

Output

0

float, ndarray

\(u \times n\)

The output is the input times a sample \(n\) of Gaussian noise with unit mean and standard deviation sigma. A new sample is drawn at each tick of the clock and held until the next, so the noise is piecewise constant and the solver sees a function of time. The input passes through continuously.

The sample for tick \(k\) depends only on seed and \(k\), so a seeded block gives the same noise in every run and whatever the solver does. If seed is None each run uses a new seed.

sigma is a scalar or a vector. If the input is a vector the noise has one element per input element, independent of each other, so sigma (or x0) must have that length. A vector sigma gives each element its own standard deviation.

As for all sampled blocks the tick at \(t=0\) is not applied, so the first sample period carries x0 instead of noise. It is one by default.

For example:

mnoise = bd.MNOISE_S(clock, sigma=0.1, seed=1)
Seealso:

Anoise_S numpy.random.default_rng()

__init__(clock, sigma=1, seed=None, x0=None, **blockargs)[source]
Parameters:
class bdsim.blocks.sampled.PID_S(clock, P=0.0, I=0.0, D=0.0, I_limit=None, I_band=None, structure='parallel', terms=None, **blockargs)[source]

Bases: SubsystemBlock

PID_S

Discrete-time PID control.

Inputs:

2

Outputs:

1

States:

2

Port type

Port number

Types

Description

Input

0

float

\(x\), plant output

Input

1

float

\(x^*\), demanded output

Output

0

any

\(u\), control to plant

Implements the dynamics of a discrete-timePID controller as a bdsim subsystem. There are three possible structures:

  • Parallel structure:

          ┌───────> P ─────────┐
          │                    │
          │                    ▼
    e ────┼───> D(z-1)/Tz ──> SUM ───> y
          │                    ▲
          │                    │
          └───> IT/(z-1) ──────┘
    
\[\begin{split}\begin{aligned} e &= x^* - x \\ \frac{Y(z)}{E(z)} &= P + I\frac{T}{z-1} + D\frac{z-1}{Tz} \end{aligned}\end{split}\]
  • Ideal or standard structure. Described by ANSI/ISA-S75:

                ┌────────────────────┐
                │                    │
                │                    ▼
    e ────> P ──┼───> D(z-1)/Tz ──> SUM ───> y
                │                    ▲
                │                    │
                └───> IT/(z-1) ──────┘
    
\[\begin{split}\begin{aligned} e &= x^* - x \\ \frac{Y(z)}{E(z)} &= P \left(1 + I\frac{T}{z-1} + D\frac{z-1}{Tz}\right) \end{aligned}\end{split}\]
  • Series structure. Archaic form, essentially a PI controller followed by a PD controller:

                ┌───────────────────┐    ┌────────────────────┐
                │                   │    │                    │
                │                   ▼    │                    ▼
    e ────> P ──┴──> IT/(z-1) ───> SUM ──┴──>  D(z-1)/Tz ──> SUM ───> y
    
\[\begin{split}\begin{aligned} e &= x^* - x \\ \frac{Y(z)}{E(z)} &= P \left(1 + I\frac{T}{z-1} + D\frac{z-1}{Tz}\right) \end{aligned}\end{split}\]

Sometimes the gains are written in terms of time constants \(T_i = 1/I\) and \(Td = D\).

The PID controller is a subsytem comprising a number of blocks.

Which terms are built. The controller is a subsystem of ordinary blocks, and a term whose gain is zero is normally left out, to save blocks and states. The proportional term is always built.

  • By default (terms=None) the I term is built only if I is not zero, and the D term only if D is not zero. So bd.PID_S(clock, P=3, I=1) is a PI controller and bd.PID_S(clock, P=3) is proportional only.

  • terms overrides this. It is one of "P", "PI", "PD" or "PID", and exactly those terms are built, even if their gain is zero. A term that is built can have its gain changed after the block is created; a term that was left out cannot be added later, because the structure is fixed when the block is created. For example, a PD controller that starts with no derivative action:

    pid = bd.PID_S(clock, P=3, D=0, terms="PD")
    
  • A non-zero gain for a term that terms does not build is an error, not silently ignored. So is a value of terms other than the four above.

  • The cost of building a term at zero gain is its state: an integrator state that stays at zero, or the state of the discrete derivative.

The gain equivalence between the three structures is given by

structure

\(P\)

\(I\)

\(D\)

parallel

\(P_p\)

\(I_p\)

\(D_p\)

ideal

\(P_i\)

\(P_i I_i\)

\(P_i D_i\)

series

\(P_s (1 + D_s I_s)\)

\(P_s I_s\)

\(P_s D_s\)

The derivate is computed by a DERIV_S block which is a simple first-order difference, which will exacerbate any noise on its input signal.

The integration is performed by an INTEGRATOR_S block, which has some options to limit the integrator state and to enable/disable integration based on the error signal.

If I_limit is provided it specifies the limits of the integrator state, before multiplication by I. If I_limit is:

  • a scalar \(a\) the integrator state is clipped to the interval \([-a, a]\)

  • a 2-tuple \((a,b)\) the integrator state is clipped to the interval \([a, b]\)

If I_limit is provided it specifies the limits of the integrator output. The integrator state is clipped to these limits, which can be used to prevent integrator windup. The limits can be specified as:

  • a scalar \(s\) the band is the interval \([-s, s]\)

  • a 2-tuple \((a,b)\) the band is the interval \([a, b]\)

If I_band is provided the integrator is reset to zero whenever the error \(e\) is outside the band given by I_band which is:

  • a scalar \(s\) the band is the interval \([-s, s]\)

  • a 2-tuple \((a,b)\) the band is the interval \([a, b]\)

Examples:

pid = bd.PID_S(clock, P=3, D=2, I=1)               # PID
pid = bd.PID_S(clock, P=3, I=1)                    # PI, no D block
pid = bd.PID_S(clock, P=3)                         # P only
pid = bd.PID_S(clock, P=3, D=0, terms="PD")        # PD, with a D block that starts at zero

Warning

This block has a direct feedthrough term (by definition), and depending on how it is used in a system it may introduce an an algebraic loop which will be flagged at compile time.

Added in version 1.2.0.

Seealso:

Deriv_S Integrator_S

property I_band: float | None

The integral term only integrates while the error is smaller than this, or None.

property I_limit: float | tuple[float | None, float | None] | None

Limit on the integral term: None for none, a number for the limit \(\pm\) that number, or a (lower, upper) pair.

Setter accepts:

Any

__init__(clock, P=0.0, I=0.0, D=0.0, I_limit=None, I_band=None, structure='parallel', terms=None, **blockargs)[source]
Parameters:
  • clock (Clock) – clock source

  • P (float) – proportional gain, defaults to 0

  • D (float) – derivative gain, defaults to 0

  • I (float) – integral gain, defaults to 0

  • D_pole (float) – filter pole for derivative estimate, defaults to 1 rad/s

  • I_limit (float | tuple[float, ...] | list[float] | None) – integral limit

  • I_band (float | None) – band within which integral action is active

  • structure (str) – the structure of the PID implementation, “parallel” (default), “series”, “standard|ideal”

  • terms (str | None) – the terms to build, one of “P”, “PI”, “PD” or “PID”, even if a gain is zero; the default is P, plus I and D if their gain is not zero

  • blockargs (Any) – common block options

Raises:

ValueError – terms is not one of those, or a gain is non-zero for a term that is not built

class bdsim.blocks.sampled.ZOH(clock, x0=0, **blockargs)[source]

Bases: SampledBlock

ZOH

Zero-order hold.

Inputs:

1

Outputs:

1

States:

N

Port type

Port number

Types

Description

Input

0

float, ndarray

\(x\)

Output

0

float, ndarray

\(y\)

The output is the input as sampled at the most recent clock tick, \(y_k = u_k\) for \(k \ge 1\), and x0 during the first sample period. There is no further delay. The state can be a scalar or a vector, this is given by the type of x0.

Note

If input is not a scalar, x0 must have the shape of the input signal.

__init__(clock, x0=0, **blockargs)[source]
Parameters:
next(t, inputs, x)[source]
Return type:

ndarray

External Toolbox blocksets

External toolbox block documentation is maintained in each toolbox project.