Simulator Core API Reference

Simulator Core

These are the user relevant methods of the simulator core:

class moddy.sim_core.Sim

Simulator main class

is_running()

Return if simulator is running

run(stop_time, max_events=100000, enable_trace_printing=True, stop_on_assertion_failure=True)

run the simulator until

• stop_time reached

• no more events to execute

• max_events reached

• model called assertionFailed() and stop_on_assertion_failure ==True

• a model exception (including exceptions from vThreads) has been caught

Parameters

• stop_time (float) – simulation time at which the simulator shall stop latest

• maxEvents (int) – (default: 100000) maximum number of simulator events to process. Can be set to None for infinite events

• enable_trace_printing (bool) – (default: True) if set to False, simulator will not display events as they are executing

• stop_on_assertion_failure (bool) – (default: True) if set to False, don’t stop when model calls assertionFailed(). Just print info at end of simulation

Raise

exceptions coming from model or simulator

smart_bind(bindings)

Create many port bindings at once using simple lists.

Example:

simu.smart_bind( [
    ['App.out_port1', 'Dev1.in_port', 'Dev2.in_port'],
    ['App.io_port1', 'Server.net_port' ]  ])

Parameters

bindings (list) – Each list element must be a list of strings, which specifies ports that shall be connected to each other. The strings must specify the hierarchy names of the ports.

stop()

stop simulator

time()

Return current simulation time

time_str(time)

return a formatted time string of time based on the display scale

Simulator Tracing

class moddy.sim_core.SimTracing(time_func)

Simulator Tracing and logging

set_display_time_unit(unit)

Define how the simulator prints/displays time units

Parameters

unit (str) – can be “s”, “ms”, “us”, “ns”

Simulator Monitoring

class moddy.sim_monitor.SimMonitorManager

Manage functions to be called at each simulation step

add_monitor(monitor_func)

Register a function to be called at each simulator step. Usually used by monitors or stimulation routines

Parameters

monitor_func – function to call. Gets called with no arguments

delete_monitor(monitor_func)

Delete a monitor function that has been registered with ‘addMonitor’ before

Parameters

monitor_func – function to delete

Raises

ValueError – if monitorFunc is not registered

SimPart

These are the user relevant methods of the SimPart class:

class moddy.sim_part.SimPart(sim, obj_name, parent_obj=None, elems=None)

an instance of SimPart forms a moddy object

Parameters

• sim – Simulator instance

• obj_name – part’s name

• parent_obj – parent part. None if part has no parent. Defaults to None

• elems (dict) – A dictionary with elements (ports and timers) to create, e.g. { 'in': 'inPort1', 'out': ['outPort1', 'outPort2'], 'tmr' : 'timer1' }

annotation(text)

Add annotation from model at current simulation time

assertion_failed(assertion_str, frame_idx=1)

Add an assertion failure trace event Increment simulator global assertion failure counter Stop simulator if configured so

Parameters

• assertion_str – error message to display

• frame_idx – traceback frame index (1 if caller’s frame, 2 if caller-caller’s frame…)

create_ports(ptype, list_port_names)

Convinience functions to create multiple ports at once.

Parameters

• ptype – Type of ports, must be one of ‘in’, ‘out’ or ‘io’

• list_port_names (list) – list of port names to create

Raise

ValueError if unknown port type

The function creates for each port a member variable with this name in the part. For “in” and “io” ports, a receive function <portName>_recv must be provided by caller

create_timers(list_timer_names)

Convinience functions to create multiple timers at once.

Parameters

list_timer_names (list) – list of timer names to create

The function creates for each port a member variable with this name in the part. A timer callback function <tmrName>_expired must be provided by caller

new_input_port(name, msg_received_func)

Add a new input port to the part

Parameters

• name – name of port

• msg_received_func – callback function to call for message receiption. Signature func(port, msg)

new_io_port(name, msg_received_func)

Add a new “I/O” port to the part

Parameters

• name – name of port

• msg_received_func – callback function to call for message receiption. Signature func(port, msg)

new_output_port(name)

Add a new output port to the part

Parameters

name – name of port

new_timer(name, elapsed_func)

Add a new timer to the part

Parameters

• name – name of timer

• elapsed_func – callback function to call for timer expiry. Signature func(timer)

new_var_watcher(var_name, format_string)

Add a variable to the watched variables. A watched variables value will be checked for changes during simulation. If a value change is detected, a simulator trace event is generated.

Parameters

• var_name (string) – Variable name as seen from part’s scope

• format_string (string) – print() like format to format the value when traced

set_state_indicator(text, appearance=None)

set part’s state from model at simulation time

Parameters

• text – text to show in life line

• appearance (dict) – appearance of state indicator. Dictionary with color values, e.g. {'boxStrokeColor':'black', 'boxFillColor':'green',             'textColor':'white'}

start_sim()

Called from simulator when simulation begins

terminate_sim()

Called from simulator when simulation stops. Terminate block (e.g. stop threads)

time()

Get current simulation time

Input Port

class moddy.sim_ports.SimInputPort(sim, part, name, msg_received_func, io_port=None)

Simulator input port

Parameters

• sim (sim) – Simulator instance

• part (SimPart) – simPart that contains this port

• name – port name

• msg_received_func – callback function to call for message receiption. Signature func(port, msg). May be None

• io_port – reference to the IOPort which contains this inPort (None if not part of IOPort).

set_msg_started_func(msg_started_func)

register a function that gets called when the bound output port begins a message transmission

Parameters

msg_started_func – callback function to call on message transmission start. Signature func(in_port, msg, out_port, flight_time)

Output Port

class moddy.sim_ports.SimOutputPort(sim, part, name, color=None, io_port=None)

Simulator output port

Parameters

• sim (sim) – Simulator instance

• part (simPart) – simPart that contains this port

• name – port name

• color – message color to use in sequence diagram. Use default color if None

• ioPort – reference to the IOPort which contains this outPort (None if not part of IOPort).

bind(input_port)

bind an output port to an input port

Parameters

input_port – input port to which this output port shall be bound

Raises

RuntimeError – if input port is already bound to that output port

inject_lost_message_error_by_sequence(next_seq)

Inject error. Force one of the next messages sent via this port to be lost. If nextSeq is 0, the next message sent via this port will be lost, if it is 1 the next but one message is lost etc.

send(msg, flight_time)

User interface to send a message

Parameters

• msg – message to send

• flight_time – flight time of message

set_color(color)

Set color for messages leaving that port

I/O Port

class moddy.sim_ports.SimIOPort(sim, part, name, msg_received_func, special_in_port=None)

An element that contains one input and one output port

Parameters

• sim (sim) – Simulator instance

• part (simPart) – simPart that contains this port

• name – port name

• msg_received_func – callback function to call for message receiption. Signature func(port, msg)

• special_in_port – if None, create a standard simInputPort, otherwise use the supplied specialInPort

bind(other_io_port)

Bind IOPort to another IOPort, in/out will be crossed

inject_lost_message_error_by_sequence(next_seq)

inject error on IoPorts output port Refer to simOutputPort.inject_lost_message_error_by_sequence() for details.

loop_bind()

Loop in/out ports of an IO port together

send(msg, flight_time)

send message to IoPorts output port

Refer to simOutputPort.send() for parameters.

set_color(color)

Set color for messages leaving that IOport

set_msg_started_func(msg_started_func)

register a function that gets called when the bound output port begins a message transmission

Refer to simInputPort.setMsgStartedFunc() for details.

Timer

class moddy.sim_ports.SimTimer(sim, part, name, elapsed_func)

Simulator Timer timer is either running or stopped timer can be canceled, and restarted

Parameters

• sim (sim) – Simulator instance

• part (simPart) – simPart that contains this port

• name – port name

• elapsed_func – callback function to call for timer expiry. Signature func(timer)

restart(timeout)

Restart timer, works whether timer is running or not.

Parameters

timeout – Timer will fire after timeout

start(timeout)

Start the timer.

Parameters

timeout – Timer will fire after timeout

Raise

RuntimeError if timer already started

Raise

AttributeError if timeout <= 0

stop()

Stop timer. Does nothing if timer not running

Global Constants

Predefined color names for status boxes

moddy.constants.BC_WHITE_ON_GREEN = {'boxFillColor': 'green', 'boxStrokeColor': 'black', 'textColor': 'white'}

constant for white on green status box

moddy.constants.BC_WHITE_ON_RED = {'boxFillColor': 'red', 'boxStrokeColor': 'black', 'textColor': 'white'}

constant for white on red status box

moddy.constants.BC_WHITE_ON_RED = {'boxFillColor': 'red', 'boxStrokeColor': 'black', 'textColor': 'white'}

constant for white on red status box

moddy.constants.BC_WHITE_ON_BROWN = {'boxFillColor': 'brown', 'boxStrokeColor': 'brown', 'textColor': 'white'}

constant for white on brown status box

moddy.constants.BC_WHITE_ON_BLACK = {'boxFillColor': 'black', 'boxStrokeColor': 'black', 'textColor': 'white'}

constant for white on black status box

moddy.constants.BC_BLACK_ON_PINK = {'boxFillColor': 'pink', 'boxStrokeColor': 'pink', 'textColor': 'black'}

constant for black on pink status box

moddy.constants.BC_BLACK_ON_GREY = {'boxFillColor': 'grey', 'boxStrokeColor': 'grey', 'textColor': 'black'}

constant for black on grey status box

moddy.constants.BC_WHITE_ON_GREY = {'boxFillColor': 'grey', 'boxStrokeColor': 'grey', 'textColor': 'white'}

constant for white on grey status box

moddy.constants.BC_BLACK_ON_WHITE = {'boxFillColor': 'white', 'boxStrokeColor': 'black', 'textColor': 'black'}

constant for black on white status box