CBD.Core module

class CBD.Core.InputLink(block, output_port)

Bases: tuple

block

Alias for field number 0

output_port

Alias for field number 1

class CBD.Core.Signal(time, value)

Bases: tuple

time

Alias for field number 0

value

Alias for field number 1

class CBD.Core.Port(name, direction, block)

Bases: object

Defines a port of a block.

Parameters

• name (str) – The name of the port.

• direction (Port.Direction) – The direction of the port; i.e., if it is an input or an output port.

• block (BaseBlock) – The block to which this port belongs.

Direction

Possible port directions.

alias of CBD.util.Enum

set(value)

Sets the value of the port and transfers this to all outgoing connections. This will mainly update the current history.

Parameters

value (float) – The new value of the port.

get()

Obtains the current value of the port.

clear()

Clears all port signal history.

reset()

Resets the port’s connections.

getOutgoing()

Obtains all outgoing connections from this port.

getIncoming()

Obtains the incoming connection to this port.

getHistory()

Obtains all historic information about the signals of this port.

getPreviousPortClosure()

Find the previous port to which this port is connected that has no incoming connections. Hierarchical blocks and useless connections can/will be solved using this method.

I.e., it obtains the port whose signal changes will eventually transfer to this port.

getNextPortClosure()

Find the next ports to which this port is connected that has no outgoing connections. Hierarchical blocks and useless connections can/will be solved using this method.

I.e., it obtains the ports to whom this port transfers signals.

count()

Counts how often a signal was changed on this port.

static connect(source, target)

Connects two ports together.

Parameters

• source (Port) – The source port from which a connection starts.

• target (Port) – The target port where a connection ends.

static disconnect(source, target)

Disconnects two previously connected ports.

Parameters

• source (Port) – The source port from which a connection starts.

• target (Port) – The target port where a connection ends.

class CBD.Core.Connector(source, target)

Bases: object

A connection that links two ports together.

Parameters

• source (Port) – The source port from which a connection starts.

• target (Port) – The target port where a connection ends.

transfer()

Transfers the signal from the source port to the target port.

class CBD.Core.BaseBlock(name, input_ports, output_ports)

Bases: object

A base class for all types of basic blocks

Parameters

• name (str) – The name of the block. When empty, a CBD.util.hash64() encoded name of the instance id() will be used, however this is a bad practice and will result in a warning. When using non-alphanumeric characters, a warning will also be shown.

• input_ports (iter) – List of input port names (strings).

• output_ports (iter) – List of output port names (strings).

addInputPort(name)

Adds an input port if there is no port with the given name.

Parameters

name (str) – The name of the port.

addOutputPort(name)

Adds an output port if there is no port with the given name.

Parameters

name (str) – The name of the port.

getInputPorts()

getInputPortNames()

getInputPortByName(name)

hasInputPortWithName(name)

getOutputPorts()

getOutputPortByName(name)

getOutputPortNames()

hasOutputPortWithName(name)

reparentPorts()

clone()

(Deep) copies the current block, ignoring all connections or links that were set on this block.

getBlockName()

Gets the name of the block.

getFunctionName()

Obtains the block’s function name, based on the block type.

setBlockName(block_name)

Sets the name of the block.

Parameters

block_name (str) – The name.

setParent(parent)

Sets the block’s parent.

Parameters

parent (CBD) – The parent of the block.

getBlockType()

Gets the type of the block. This is the name of the class.

getClock()

Gets the simulation clock. Only works if the block is part of a CBD model.

appendToSignal(value, name_output=None)

Appends the value to the set of obtained signals and links it to the current simulation time.

Parameters

• value (Any) – The value to append.

• name_output (str) – The name of the output port. If not set, or None, the value of OUT1 will be used.

getSignalHistory(name_output=None)

Obtains the set of signals this block has sent over an output port.

Parameters

name_output (str) – The name of the output port. If not set, or None, the value of OUT1 will be used.

clearPorts()

Clears all signal data from the ports.

resetPorts()

Clears all signal data from the ports and resets all connections.

getDependencies(curIteration)

Helper function to help the creation of the dependency graph.

Parameters

curIteration (int) – The current simulation’s iteration, for which the dependency graph must be constructed.

Returns

A list of ports that must be computed in order to compute this block, at the time of the iteration.

getPortConnectedToInput(input_port)

Get the block that is connected to a specific input.

Parameters

input_port (str) – The name of the input port.

getInputSignal(curIteration=- 1, input_port='IN1')

Returns the signal sent out by the input block.

Parameters

• curIteration (int) – The iteration at which the signal is obtained. When None or -1, the last value will be used.

• input_port (str) – The name of the input port. If omitted, or when None, the value of IN1 will be used.

getPath(sep='.')

Gets the path of the current block. This includes the paths from its parents. When the block has no parents i.e. when it’s the top-level block, the block’s name is returned.

Parameters

sep (str) – The separator to use. Defaults to .

Returns

The full path as a string.

Examples

A block called grandchild, which is located in the child CBD, that in its turn is located in this CBD has a path of child.grandchild.

compute(curIteration)

Computes this block’s operation, based on its inputs and store it as an output signal.

Parameters

curIteration (int) – The iteration at which we must compute this value.

linkToInput(in_block, *, name_input=None, name_output='OUT1')

Links the output of the in_block to the input of this block.

Parameters

in_block (BaseBlock) – The block that must be linked before the current block.

Keyword Arguments

• name_input (str) – The name of the input port. When None or omitted, the next input port is used. E.g. if the last port was IN1, the input is assumed to be IN2.

• name_output (str) – The name of the output port. Defaults to OUT1.

unlinkInput(name_input)

Unlinks the input for this block.

Parameters

name_input (str) – The name of the input.

info(indent=0)

Returns a string with the block’s details.

Parameters

indent (int) – The amount of indentation that is required at the start of each line. Defaults to 0.

class CBD.Core.CBD(block_name, input_ports=None, output_ports=None)

Bases: CBD.Core.BaseBlock

The CBD class, contains an entire Causal Block Diagram Call the run function to simulate the model.

clone()

(Deep) copies the current block, ignoring all connections or links that were set on this block.

getTopCBD()

Finds the highest-level CBD instance.

flatten(ignore=None, psep='.')

Flatten the CBD inline and call recursively for all sub-CBDs.

Parameters

• parent (CBD) – Reference to the parent. Used for the recursive call. Defaults to None. Users should ignore this parameter.

• ignore (iter) – Block class names to ignore in the flattening. When None, no blocks are ignored. Defaults to None.

• psep (str) – The path separator to use. Defaults to ".".

Changed in version 1.5: When an empty CBD block is encountered during flattening, this block will be removed from the resulting flattened model. Add it to the ignore iterable to prevent such a removal.

getBlocks()

Gets the list of blocks.

getBlockByName(name)

Gets a block by its name.

Parameters

name (str) – The block’s name

hasBlock(name)

Checks if the CBD has a block with the given name.

Parameters

name (str) – The name of the block to check.

clearBlocks()

Clears the block information. Calling this function will “empty” the current block.

getClock()

Gets the current simulation clock. This will always be the block of the highest-level CBD.

addFixedRateClock(prefix='clock', delta_t=1.0, start_time=0.0)

Adds a clock with a fixed rate.

Two blocks are added to the simulation: a Clock and a ConstantBlock for the rate. Their names will be <prefix>-<what>, where <what> identifies the purpose of the block (which is one of clock or delta).

Parameters

• prefix (str) – The prefix for the names of the blocks. Defaults to "clock".

• delta_t (float) – The interval when the clock must tick. Defaults to 1.

• start_time (float) – The time at which the simulation starts. Defaults to 0.

Note

Whenever this function is not called, upon simulation start a clock is added with the default values.

Warning

Clock Usage Assumption: When adding a (custom) clock to your model(s), its outputs will always represent the (relative) simulated time and time-delta, independent of the simulation algorithm used. I.e., changing the delay of a fixed-rate clock should only influence the accuracy of the signals, not the correctness of the signals. It is forbidden to misuse these outputs for specific simulations (e.g., using the time as a counter, using delta as a constant value…).

In other words, the clock is guaranteed to output a correct value and should only be used in the context of “time”. When exporting the CBD model to other formalisms/simulators, the Clock’s outputs should be replaced with the corresponding simulator’s clock without loss of generality.

addBlock(block)

Add a block to the CBD model

Parameters

block (BaseBlock) – The block to add.

Returns

The block that was passed as an argument.

removeBlock(block)

Removes a block from the CBD.

Parameters

block (BaseBlock) – The block to remove.

addConnection(from_block, to_block, *, input_port_name=None, output_port_name='OUT1')

Adds a connection between from_block with input_port_name to to_block with outport_port_name.

Parameters

• from_block (str) – The block to start the connection from.

• to_block (str) – The target block of the connection.

Keyword Arguments

• input_port_name (str) – The name of the input port. When None or unset, the next port is used. E.g. when called after IN1 is already set, IN2 will be used.

• output_port_name (str) – The name of the output port. Defaults to OUT1.

Note

Connecting from and to ports is possible by setting the from_block and/or to_block arguments to the port names.

See also

BaseBlock.linkToInput()

getDependencies(curIteration)

Helper function to help the creation of the dependency graph.

Parameters

curIteration (int) – The current simulation’s iteration, for which the dependency graph must be constructed.

Returns

A list of ports that must be computed in order to compute this block, at the time of the iteration.

removeConnection(block, input_port_name)

Removes an input connection of block block and port input_port_name.

Parameters

• block (BaseBlock) – A block to remove an input connection for.

• input_port_name (str) – The (input) port name.

find(path, sep='.')

Obtain a block/port in a submodel of this CBD.

Parameters

• path (str) – The path of the block to find. Empty string for the current block, child.grandchild for the block called code:grandchild, which is located in the child CBD that is located in this CBD.

• sep (str) – The path separator to use. Defaults to .

Returns

The block that corresponds to the given path and the path to the block itself.

Note

The block/port that will be returned has a different path than the path provided in this function call. This is because this function assumes you already have a path to the CBD you call it on. For instance, if this CBD contains a child called child, which has a grandchild block in its turn, calling find on the child to locate the grandchild only needs grandchild to be passed as a path. If the function is called on the current CBD block instead, child.grandchild is required to obtain the same block.

info(indent=0)

Obtains the model structure recursively.

Parameters

indent (int) – The level of indents to start at.

dump()

Dumps the model information to the console.

dumpSignals()

Dumps the signal information to the console.

getSignalHistory(name_output=None)

Obtains the set of signals this block has sent over an output port.

Parameters

name_output (str) – The name of the output port. If not set, or None, the value of OUT1 will be used.

getSignals()

Obtains all signal histories.

clearSignals()

Clears the output signals of all blocks and ports.

compute(curIteration)

Computes this block’s operation, based on its inputs and store it as an output signal.

Parameters

curIteration (int) – The iteration at which we must compute this value.

getUniqueBlockName(prefix='', hash=False)

Fetches a name that is unique within the given model. This name is in the form <prefix><suffix>. The suffix is the string representation of a unique identifier. This identifier is continuously increased and tested.

Parameters

• prefix (str) – The prefix of the name to fetch. When a valid name by itself, this will be returned, ignoring any suffix. Defaults to the empty string.

• hash (bool) – When True, the current object id will be used as a starting point for the identifier. Additionally, the CBD.util.hash64() function will be used for the suffix representation. When False, the identifier will start at 1 and no hashing will be done. Defaults to False.