mosaik.scenario — Classes related to the scenario creation

This module provides the interface for users to create simulation scenarios for mosaik.

The World holds all necessary data for the simulation and allows the user to start simulators. It provides a ModelFactory (and a ModelMock) via which the user can instantiate model instances (entities). The method World.run() finally starts the simulation.

class mosaik.scenario.World(sim_config, mosaik_config=None, debug=False)

The world holds all data required to specify and run the scenario.

It provides a method to start a simulator process (start()) and manages the simulator instances.

You have to provide a sim_config which tells the world which simulators are available and how to start them. See mosaik.simmanager.start() for more details.

mosaik_config can be a dict or list of key-value pairs to set addional parameters overriding the defaults:

{
    'addr': ('127.0.0.1', 5555),
    'start_timeout': 2,  # seconds
    'stop_timeout': 2,   # seconds
}

Here, addr is the network address that mosaik will bind its socket to. start_timeout and stop_timeout specifiy a timeout (in seconds) for starting/stopping external simulator processes.

If execution_graph is set to True, an execution graph will be created during the simulation. This may be useful for debugging and testing. Note, that this increases the memory consumption and simulation time.

sim_config = None

The config dictionary that tells mosaik how to start a simulator.

config = None

The config dictionary for general mosaik settings.

sims = None

A dictionary of already started simulators instances.

env = None

The SimPy.io networking Environment.

srv_sock = None

Mosaik’s server socket.

df_graph = None

The directed data-flow graph for this scenario.

entity_graph = None

The graph of related entities. Nodes are (sid, eid) tuples. Each note has an attribute entity with an Entity.

sim_progress = None

Progress of the current simulation.

start(sim_name, **sim_params)

Start the simulator named sim_name and return a ModelFactory for it.

connect(src, dest, *attr_pairs, *, async_requests=False)

Connect the src entity to dest entity.

Establish a data-flow for each (src_attr, dest_attr) tuple in attr_pairs. If src_attr and dest_attr have the same name, you you can optionally only pass one of them as a single string.

Raise a ScenarioError if both entities share the same simulator instance, if at least one (src. or dest.) attribute in attr_pairs does not exist, or if the connection would introduce a cycle in the data-flow (e.g., A → B → C → A).

If the dest simulator may make asyncronous requests to mosaik to query data from src (or set data to it), async_requests should be set to True so that the src simulator stays in sync with dest.

get_data(entity_set, *attributes)

Get and return the values of all attributes for each entity of an entity_set.

The return value is a dict mapping the entities of entity_set to dicts containing the values of each attribute in attributes:

{
    Entity(...): {
        'attr_1': 'val_1',
        'attr_2': 'val_2',
        ...
    },
    ...
}
run(until, rt_factor=None, rt_strict=False)

Start the simulation until the simulation time until is reached.

In order to perform real-time simulations, you can set rt_factor to a number > 0. An rt-factor of 1 means that 1 simulation time unit (usually a second) takes 1 second in real-time. An rt-factor 0f 0.5 will let the simulation run twice as fast as real-time.

If the simulators are too slow for the rt-factor you chose, mosaik prints by default only a warning. In order to raise a RuntimeError, you can set rt_strict to True.

Before this method returns, it stops all simulators and closes mosaik’s server socket. So this method should only be called once.

shutdown()

Shut-down all simulators and close the server socket.

class mosaik.scenario.ModelFactory(world, sim)

This is a facade for a simulator sim that allows the user to create new model instances (entities) within that simulator.

For every model that a simulator publicly exposes, the ModelFactory provides a ModelMock attribute that actually creates the entities.

If you access an attribute that is not a model or if the model is not marked as public, an ScenarioError is raised.

class mosaik.scenario.ModelMock(world, name, sim)

Instances of this class are exposed as attributes of ModelFactory and allow the instantiation of simulator models.

You can call an instance of this class to create exactly one entiy: sim.ModelName(x=23). Alternatively, you can use the create() method to create multiple entities with the same set of parameters at once: sim.ModelName.create(3, x=23).

create(num, **model_params)

Create num entities with the specified model_params and return a list with the entity dicts.

The returned list of entities is the same as returned by mosaik_api.Simulator.create(), but the simulator is prepended to every entity ID to make them globally unique.

class mosaik.scenario.Entity(sid, eid, sim_name, type, children, sim)

An entity represents an instance of a simulation model within mosaik.

sid

The ID of the simulator this entity belongs to.

eid

The entity’s ID.

sim_name

The entity’s simulator name.

type

The entity’s type (or class).

children

An entity set containing subordinate entities.

sim

The SimProxy containing the entity.

full_id

Full, globally unique entity id sid.eid.