mosaik.simmanager — Management of external processes

The simulation manager is responsible for starting simulation processes and shutting them down. It also manages the communication between mosaik and the processes.

It is able to start pure Python simulators in-process (by importing and instantiating them), to start external simulation processes and to connect to already running simulators and manage access to them.

mosaik.simmanager.start(world: World, sim_name: str, sim_id: SimId, time_resolution: float, sim_params: Dict[str, Any])

Start the simulator sim_name based on the configuration im world.sim_config, give it the ID sim_id and pass the time_resolution and the parameters of the dict sim_params to it.

The sim config is a dictionary with one entry for every simulator. The entry itself tells mosaik how to start the simulator:

{
    'ExampleSimA': {
        'python': 'example_sim.mosaik:ExampleSim',
    },
    'ExampleSimB': {
        'cmd': 'example_sim %(addr)s',
        'cwd': '.',
    },
    'ExampleSimC': {
        'connect': 'host:port',
    },
}

ExampleSimA is a pure Python simulator. Mosaik will import the module example_sim.mosaik and instantiate the class ExampleSim to start the simulator.

ExampleSimB would be started by executing the command example_sim and passing the network address of mosaik das command line argument. You can optionally specify a current working directory. It defaults to ..

ExampleSimC can not be started by mosaik, so mosaik tries to connect to it.

time_resolution (in seconds) is a global scenario parameter, which tells the simulators what the integer time step means in seconds. Its default value is 1., meaning one integer step corresponds to one second simulated time.

The function returns a mosaik_api.Simulator instance.

It raises a SimulationError if the simulator could not be started.

Return a SimProxy instance.

mosaik.simmanager.start_inproc(world: World, sim_name: str, sim_config: Dict[Literal[‘python’, ‘env’], str], sim_id: SimId, time_resolution: float, sim_params: Dict[str, Any]) → SimProxy

Import and instantiate the Python simulator sim_name based on its config entry sim_config.

Return a LocalProcess instance.

Raise a ScenarioError if the simulator cannot be instantiated.

mosaik.simmanager.start_proc(world: World, sim_name: str, sim_config: Dict[Literal[‘cmd’, ‘cwd’, ‘env’], str], sim_id: SimId, time_resolution: float, sim_params: Dict[str, Any]) → SimProxy

Start a new process for simulator sim_name based on its config entry sim_config.

Return a RemoteProcess instance.

Raise a ScenarioError if the simulator cannot be instantiated.

mosaik.simmanager.start_connect(world: World, sim_name: str, sim_config, sim_id: SimId, time_resolution: float, sim_params: Dict[str, Any])

Connect to the already running simulator sim_name based on its config entry sim_config.

Return a RemoteProcess instance.

Raise a ScenarioError if the simulator cannot be instantiated.

class mosaik.simmanager.SimProxy(name: str, sid: SimId, meta: Meta, world: World)

Handler for an external simulator.

It stores its simulation state and own the proxy object to the external simulator.

rt_start: float

The real time when this simulator started (as returned by perf_counter().

next_step: Optional[int]

This simulator’s immediate next step once it has been determined. The step is removed from the next_steps heap at that point and the has_next_step event is triggered.

predecessors: Dict[Any, Tuple[SimProxy, DataflowEdge]]

This simulator’s predecessors in the dataflow graph and the corresponding edges.

successors: Dict[Any, Tuple[SimProxy, DataflowEdge]]

This simulator’s successors in the dataflow graph and the corresponding edge..

triggering_ancestors: Iterable[Tuple[SimId, bool]]

An iterable of this sim’s ancestors that can trigger a step of this simulator. The second component specifies whether the connecting is weak or time-shifted (False) or immediate (True).

output_time: int

The output time associated with data. Usually, this will be equal to last_step but simulators may specify a different time for their output.

data: OutputData

The newest data returned by this simulator.

related_sims: Iterable[SimProxy]

Simulators related to this simulator. (Currently all other simulators.)

name: str

The name of this simulator (in the SIM_CONFIG).

sid: SimId

This simulator’s ID.

meta: Meta

This simulator’s meta.

proxy: Any

The actual proxy for this simulator.

last_step: int

The most recent step this simulator performed.

next_steps: List[int]

The scheduled next steps this simulator will take, organized as a heap. Once the immediate next step has been chosen (and the has_next_step event has been triggered), the step is moved to next_step instead.

next_self_step: Optional[int]

The next self-scheduled step for this simulator.

progress: int

This simulator’s progress in mosaik time.

This simulator has done all its work before time progress; its next stept will be at time progress or later. For time-based simulators, the next step will happen at time progress.

input_buffer: Dict

Inputs received via set_data.

input_memory: Dict

Memory of previous inputs for persistent attributes.

timed_input_buffer: TimedInputBuffer

‘Usual’ inputs. (But also see world._df_cache.)

sim_proc: Process

The SimPy process for this simulator.

has_next_step: Event

An event that is triggered once this simulator’s next step has been determined.

wait_events: Event

The event (usually an AllOf event) this simulator is waiting for.

interruptable: bool

Set when this simulator’s next step has been scheduled but it is still waiting for dependencies which might trigger earlier steps for this simulator.

stop()

Stop the simulator behind the proxy.

The default implementation does nothing.

class mosaik.simmanager.LocalProcess(name, sid, meta, inst, world)

Proxy for internal simulators.

stop()

Yield a triggered event but do nothing else.

class mosaik.simmanager.RemoteProcess(name, sid, meta, proc, rpc_con, world)

Proxy for external simulator processes.

stop()

Send a stop message to the process represented by this proxy and wait for it to terminate.

class mosaik.simmanager.MosaikRemote(world, sim_id)

This class provides an RPC interface for remote processes to query mosaik and other processes (simulators) for data while they are executing a step() command.

get_progress()

Return the current simulation progress from sim_progress.

Return information about the related entities of entities.

If entities omitted (or None), return the complete entity graph, e.g.:

{
    'nodes': {
        'sid_0.eid_0': {'type': 'A'},
        'sid_0.eid_1': {'type': 'B'},
        'sid_1.eid_0': {'type': 'C'},
    },
    'edges': [
        ['sid_0.eid_0', 'sid_1.eid0', {}],
        ['sid_0.eid_1', 'sid_1.eid0', {}],
    ],
}

If entities is a single string (e.g., sid_1.eid_0), return a dict containing all entities related to that entity:

{
    'sid_0.eid_0': {'type': 'A'},
    'sid_0.eid_1': {'type': 'B'},
}

If entities is a list of entity IDs (e.g., ['sid_0.eid_0', 'sid_0.eid_1']), return a dict mapping each entity to a dict of related entities:

{
    'sid_0.eid_0': {
        'sid_1.eid_0': {'type': 'B'},
    },
    'sid_0.eid_1': {
        'sid_1.eid_1': {'type': 'B'},
    },
}
get_data(attrs)

Return the data for the requested attributes attrs.

attrs is a dict of (fully qualified) entity IDs mapping to lists of attribute names ({'sid/eid': ['attr1', 'attr2']}).

The return value is a dictionary, which maps the input entity IDs to data dictionaries, which in turn map attribute names to their respective values: ({'sid/eid': {'attr1': val1, 'attr2': val2}}).

set_data(data)

Set data as input data for all affected simulators.

data is a dictionary mapping source entity IDs to destination entity IDs with dictionaries of attributes and values ({'src_full_id': {'dest_full_id': {'attr1': 'val1', 'attr2': 'val2'}}}).

set_event(event_time)

Schedules an event/step at simulation time event_time.