CBD.simulator module

class CBD.simulator.Simulator(model)

Bases: object

Simulator for a CBD model. Allows for execution of the simulation. This class implements the semantics of CBDs.

Parameters

model (CBD.Core.CBD) – A CBD model to simulate.

Defaults

The following properties further define the internal mechanisms of the simulator. As a handy look-up table, all defaults are listed in the table below. Take a look at the See Also column for more info on the property.

Property	Default	See Also
real-time?	False	setRealTime()
real-time scale	1.0	setRealTime()
termination time	float('inf')	setTerminationTime()
termination condition	None	setTerminationCondition()
scheduler	CBD.scheduling.TopologicalScheduler	setScheduler()
threading platform (subsystem)	CBD.realtime.threadingPython.threadingPython	setRealTimePlatform(), setRealTimePlatformThreading(), setRealTimePlatformTk(), setRealTimePlatformGameLoop()
progress bar?	False	setProgressBar()
strong component system solver	CBD.linearsolver.LinearSolver	setAlgebraicLoopSolver()
state event locator	CBD.state_events.locators.RegulaFalsiStateEventLocator	setStateEventLocator()

run(term_time=None)

Simulates the model.

Parameters

term_time (float) – When not None, overwrites the termination time with the new value. This value will be accurate upto 8 decimal points.

stop()

Requests a termination of the current running simulation.

is_running()

Returns True as long as the simulation is running. This is a convenience function to keep real-time simulations alive, or to interact from external sources.

getClock()

Gets the simulation clock.

See also

• getTime()

• getRelativeTime()

• getDeltaT()

• setDeltaT()

• CBD.lib.std.Clock

getTime()

Gets the current simulation time.

See also

• getClock()

• getRelativeTime()

• getDeltaT()

• setDeltaT()

• CBD.lib.std.Clock

getRelativeTime()

Gets the current simulation time, ignoring a starting offset.

See also

• getClock()

• getTime()

• getDeltaT()

• setDeltaT()

• CBD.lib.std.Clock

getDeltaT()

Gets the delta in-between iteration steps.

See also

• getClock()

• getTime()

• getRelativeTime()

• setDeltaT()

• CBD.lib.std.Clock

setDeltaT(delta_t)

Sets the delta in-between iteration steps.

Parameters

delta_t (float) – The delta.

Note

If the model has a CBD.lib.std.Clock block instance, calling this function will have no effect. It is merely meant to be used for fixed step simulations.

Note

While unnecessary, this function is kept for backwards compatibility.

See also

• getClock()

• getTime()

• getRelativeTime()

• getDeltaT()

• CBD.lib.std.Clock

• setStepSize()

setScheduler(scheduler)

Sets the scheduler for the simulation. It will identify the order of the components in a computation.

Parameters

scheduler (CBD.scheduling.Scheduler) – The scheduler to use.

setAlgebraicLoopSolver(solver)

Sets the algebraic loop solver for the simulation. It will identify the order of the components in a computation.

Parameters

solver (CBD.loopsolvers.solver.Solver) – The loop solver to use.

setStateEventLocator(stel)

Sets the state event locator to use when level crossings occur.

Parameters

stel (CBD.state_events.locators.StateEventLocator) – The new state event to use.

registerStateEvent(event)

Registers a state event to the current simulator.

Parameters

event (CBD.state_events.StateEvent) – The event to register.

setBlockRate(block_path, rate)

Sets the rate for a specific block. Independent of the stepsize, the rate will identify that a certain block must only execute every r time.

Note

Blocks for which no rate has been set will always be computed.

Parameters

• block_path (str) – The path of the block to set a rate of.

• rate (float) – The rate of the block.

setRealTime(enabled=True, scale=1.0)

Makes the simulation run in (scaled) real time.

Parameters

• enabled (bool) – When True, realtime simulation will be enabled. Otherwise, it will be disabled. Defaults to True.

• scale (float) – Optional scaling for the simulation time. When greater than 1, the simulation will run slower than the actual time. When < 1, it will run faster. E.g. scale = 2.0 will run twice as long. Defaults to 1.0.

setProgressBar(enabled=True)

Uses the tqdm package to display a progress bar of the simulation.

Parameters

enabled (bool) – Whether or not to enable/disable the progress bar. Defaults to True (= show progress bar).

Note

A progressbar hijacks printing to the console, hence no output shall be shown.

Raises

AssertionError – if the tqdm module cannot be located.

setTerminationCondition(func)

Sets the system’s termination condition.

Parameters

func – A function that takes the model and the current iteration as input and produces True if the simulation needs to terminate.

Note

When set, the progress bars (see setProgressBar()) may not work as intended.

See also

setTerminationTime()

setTerminationTime(term_time)

Sets the termination time of the system.

Note

This is accurate upto 8 decimal points.

Parameters

term_time (float) – Termination time for the simulation.

setRealTimePlatform(subsystem, *args)

Sets the realtime platform to a platform of choice. This allows more complex/efficient simulations.

Calling this function automatically sets the simulation to realtime.

Parameters

• subsystem (Platform) – The platform to use.

• args – Optional arguments for this platform. Currently, only the TkInter platform makes use of these arguments.

Note

To prevent misuse of the function, please use one of the wrapper functions when you have no idea what you’re doing.

See also

• setRealTimePlatformThreading()

• setRealTimePlatformTk()

• setRealTimePlatformGameLoop()

setRealTimePlatformThreading()

Wrapper around the setRealTimePlatform() call to automatically set the Python Threading backend.

Calling this function automatically sets the simulation to realtime.

See also

• setRealTimePlatform()

• setRealTimePlatformTk()

• setRealTimePlatformGameLoop()

setRealTimePlatformGameLoop()

Wrapper around the setRealTimePlatform() call to automatically set the Game Loop backend. Using this backend, it is expected the user will periodically call the realtime_gameloop_call() method to update the simulation step. Timing is still maintained internally.

Calling this function automatically sets the simulation to realtime.

See also

• setRealTimePlatform()

• setRealTimePlatformThreading()

• setRealTimePlatformTk()

• realtime_gameloop_call()

• Realtime Simulation

setRealTimePlatformTk(root)

Wrapper around the setRealTimePlatform() call to automatically set the TkInter backend.

Calling this function automatically sets the simulation to realtime.

Parameters

root – TkInter root window object (tkinter.Tk)

See also

• setRealTimePlatform()

• setRealTimePlatformThreading()

• setRealTimePlatformGameLoop()

realtime_gameloop_call(time=None)

Do a step in the realtime-gameloop platform.

Parameters

time (float) – Simulation time to be passed on. Only to be used for the alternative gameloop backend.

Note

This function will only work for a Platform.GAMELOOP or a Platform.GLA simulation, after the run() method has been called.

See also

• setRealTimePlatform()

• setRealTimePlatformGameLoop()

• run()

connect(name, function)

Connect an event with an additional, user-defined function. These functions will be executed on a separate thread and polled every 50 milliseconds.

Warning

It is expected that the passed function terminates at a certain point in time, to prevent an infinitely running process.

Warning

There is no guarantee that these functions will be executed in-order of connection. For safety, it is best to see these events as not thread-safe.

The functions will be called in the order they were connected to the events, with the associated arguments. The accepted signals are:

• started: Raised whenever the simulation setup has completed,

  but before the actual simulation begins.

• finished: Raised whenever the simulation finishes.

• prestep(t, st): Raised before a step is done. t is the real

  time before the step and st is the simulation time.

• poststep(o, t, st): Raised after a step is done. o is the real

  time before the step, t is the real time after the step and st is the simulation time of the step.

• clock_update(delta): Raised whenever the clock updates. It takes the (new)

  delta for the simulation.

Parameters

• name (str) – The name of the signal to raise.

• function – A function that will be called with the optional arguments whenever the event is raised.

signal(name, *args)

Raise a signal with a specific name and arguments.

The accepted signals are:

• started: Raised whenever the simulation setup has

  completed, but before the actual simulation begins.

• finished: Raised whenever the simulation finishes.

• prestep: Raised before a step is done.

• poststep: Raised after a step is done.

• clock_update(delta): Raised whenever the clock updates. It takes

  the (new) delta for the simulation.

Note

Normally, users do not need to call this function.

Parameters

• name (str) – The name of the signal to raise.

• *args – Additional arguments to pass to the connected events.

See also

connect()

setCustomTracer(*tracer)

Sets a custom tracer.

Parameters

*tracer – Either a single instance of a subclass of CBD.tracers.baseTracer.BaseTracer or three elements filename (str), classname (str) and args (tuple) to allow instantiation similar to PythonPDEVS.

Note

Calling this function multiple times with the same arguments will continuously add new tracers. Thus output to multiple files is possible, though more inefficient than simply (manually) copying the file at the end.

setVerbose(filename=None)

Sets the verbose tracer.

Parameters

filename (Union[str, None]) – The file to which the trace must be written. When None, the trace will be written to the console.

Note

Calling this function multiple times will continuously add new tracers. Thus output to multiple files is possible, though more inefficient than simply (manually) copying the file at the end.

Warning

Using multiple verbose tracers with the same filename will yield errors and undefined behaviour.