mosaik.starters — Descriptions of how to start simulators

Starters describe how mosaik instantiates or connects to simulators.

This module provides the abstract base class Starter, and the three concrete subclasses PythonStarter for starting a simulator by instantiating a Simulator subclass in the running process, CmdStarter for starting a simulator by spawning a separate process, and ConnectStarter for connecting to a simulator running at some TCP/IP address.

These starters can be used by storing them in a SIM_CONFIG dict mapping simulator names to Starter objects. When such a SIM_CONFIG is given to the mosaik World at creation, instances of the simulators can be spawned by simply giving the simulator name to the worlds mosaik.World.start method. Alternatively, this method also accepts a Starter object directly. (In this case, you need to specify the simulator ID, as it cannot be auto-generated from the simulator name.)

Finally, traditionally, SIM_CONFIG would be a dict of dicts, where the inner dicts correspond to our Starter objects. To keep supporting this, Starter objects can be parsed from such a dict using the from_starter_config method; to try parsing into all starters automatically, use get_starter_from_starter_config.

class Starter[source]

Description of how to start or connect to a mosaik simulator.

In practice, you will usually use one of the subclasses PythonStarter, CmdStarter, or ConnectStarter.

api_version: str | None[source]

The API version of this simulator. This should be set if the simulator is using an outdated version of the API.

abstractmethod async start(sim_id: mosaik_api_v3.SimId, mosaik_remote: MosaikRemote, mosaik_config: MosaikConfigTotal) → BaseProxy[source]

Start the simulator as described by this Starter under the name sim_id and using the supplied mosaik_remote to allow it to make callbacks to mosaik.

This may raise ScenarioError (or appropriate subclasses) if the simulator cannot be started.

Parameters:
Return type:

BaseProxy

abstractmethod classmethod from_starter_config(starter_config: StarterConfig) → Starter | None[source]

Attempt to create a starter from the given StarterConfig. If the StarterConfig does not match this type of Starter, return None to indicate that a different Starter should be tried.

Parameters:

starter_config (StarterConfig)

Return type:

Starter | None

classmethod from_sim_config_entry(entry: StarterConfig | Starter) → Starter[source]

Create a Starter from an entry in a SimConfig. This is intended to be called on a subclass of Starter and will check that the given entry is either already an instance of that subclass or that it can be parsed into one by that subclass’s from_starter_config method.

This is a convenience method if you already have a SimConfig. In most cases, you will either construct starters directly or use get_starter_from_starter_config, instead.

Parameters:

entry (Union[StarterConfig, Starter])

Return type:

Starter

class PythonStarter(cls: type[Simulator], *, api_version: str | None = None, args: tuple[Any, ...] = (), kwargs: dict[str, Any] = {})[source]

Description of how to start a simulator based on its mosaik_api_v3.Simulator class.

In traditional mosaik, this starter corresponds to a "python" entry in the SimConfig, and it can be constructed from such an entry using from_starter_config.

Parameters:
cls: type[Simulator][source]

The Simulator subclass started by this starter. When started, the class’s constructor will be called with args and kwargs.

args: tuple[Any, ...][source]

The args to give to the constructor of the simulator.

kwargs: dict[str, Any][source]

The kwargs to give to the constructor of the simulator.

async start(sim_id: mosaik_api_v3.SimId, mosaik_remote: MosaikRemote, mosaik_config: MosaikConfigTotal) → BaseProxy[source]

Start the simulator as described by this Starter under the name sim_id and using the supplied mosaik_remote to allow it to make callbacks to mosaik.

This may raise ScenarioError (or appropriate subclasses) if the simulator cannot be started.

Parameters:
Return type:

BaseProxy

classmethod from_module_class_name(mod_name: str, cls_name: str, *, api_version: str | None = None) → PythonStarter[source]

Attemp to import the simulator class cls_name from the module mod_name, and return a PythonStarter using this class if successful.

Parameters:

  • mod_name (str)

  • cls_name (str)

  • api_version (str | None)

Return type:

PythonStarter

classmethod from_string(import_string: str, *, api_version: str | None = None) → PythonStarter[source]

Attempt to import the a simulator class based on import_string: It should follow the form “module_name:ClassName” (note the colon instead of a dot). Return a PythonStarter if successful.

Parameters:

  • import_string (str)

  • api_version (str | None)

Return type:

PythonStarter

classmethod from_starter_config(starter_config: StarterConfig) → Starter | None[source]

Attempt to create a starter from the given StarterConfig. If the StarterConfig does not match this type of Starter, return None to indicate that a different Starter should be tried.

Parameters:

starter_config (StarterConfig)

Return type:

Starter | None

class CmdStarter(cmd: str, *, api_version: str | None = None, auto_terminate: bool = True, bind_addr: tuple[str, int | None] | None = None, connect_timeout: float | None = None, cwd: str = '.', env: dict[str, str] = {}, new_console: bool = False, posix: bool = False)[source]

Description of how to start a simulator in a new process.

In traditional mosaik, this starter corresponds to a "cmd" entry in the SimConfig, and it can be constructed from such an entry using from_starter_config.

Parameters:
cmd: str[source]

The command to start the process

posix: bool[source]

Whether we are running on a POSIX machine (for parsing the cmd)

cwd: str[source]

The current working directory for the started simulator

env: dict[str, str][source]

Additional enviroment variables (will be joined with our own)

new_console: bool[source]

Whether to open a new console for this simulator (only works on Windows)

auto_terminate: bool[source]

Whether to automatically terminate the process when the world is shut down

async start(sim_id: mosaik_api_v3.SimId, mosaik_remote: MosaikRemote, mosaik_config: MosaikConfigTotal) → BaseProxy[source]

Start the simulator as described by this Starter under the name sim_id and using the supplied mosaik_remote to allow it to make callbacks to mosaik.

This may raise ScenarioError (or appropriate subclasses) if the simulator cannot be started.

Parameters:
Return type:

BaseProxy

classmethod from_starter_config(starter_config: StarterConfig) → Starter | None[source]

Attempt to create a starter from the given StarterConfig. If the StarterConfig does not match this type of Starter, return None to indicate that a different Starter should be tried.

Parameters:

starter_config (StarterConfig)

Return type:

Starter | None

class ConnectStarter(host: str, port: int, *, api_version: str | None = None)[source]

Description of how to “start” a simulator already running at some address by connecting to it.

In traditional mosaik, this starter corresponds to a "connect" entry in the SimConfig, and it can be constructed from such an entry using from_starter_config.

Parameters:

  • host (str)

  • port (int)

  • api_version (str | None)

async start(sim_id: mosaik_api_v3.SimId, mosaik_remote: MosaikRemote, mosaik_config: MosaikConfigTotal) → BaseProxy[source]

Start the simulator as described by this Starter under the name sim_id and using the supplied mosaik_remote to allow it to make callbacks to mosaik.

This may raise ScenarioError (or appropriate subclasses) if the simulator cannot be started.

Parameters:
Return type:

BaseProxy

classmethod from_addr_string(address: str, *, api_version: str | None = None) → ConnectStarter[source]

Construct a ConnectStarter from an address string in the format “host:port”.

Parameters:

  • address (str)

  • api_version (str | None)

Return type:

ConnectStarter

classmethod from_addr(addr: str | tuple[str, int], *, api_version: str | None = None) → ConnectStarter[source]

Construct a ConnectStarter from a host-port pair.

Parameters:
Return type:

ConnectStarter

classmethod from_starter_config(starter_config: StarterConfig) → Starter | None[source]

Attempt to create a starter from the given StarterConfig. If the StarterConfig does not match this type of Starter, return None to indicate that a different Starter should be tried.

Parameters:

starter_config (StarterConfig)

Return type:

Starter | None

STARTERS: list[type[Starter]] = [<class 'mosaik.starters.PythonStarter'>, <class 'mosaik.starters.CmdStarter'>, <class 'mosaik.starters.ConnectStarter'>][source]

The default starters used by mosaik.

You can add additional Starter subclasses to this list to make parsing their starter configs availabe in your SimConfig. Alternatively, your own starters can also be used as entries in the SimConfig directly, or be passed to world.start directly.

get_starter_from_starter_config(starter_config: StarterConfig) → Starter[source]

Construct a Starter from the given StarterConfig by trying the Starter subclasses in STARTERS one by one (using the Starter.from_starter_config method from each).

Parameters:

starter_config (StarterConfig)

Return type:

Starter