mosaik.exceptions — mosaik specific error types

This module provides mosaik-specific exception types.

Exceptions are sorted into two types:

• A ScenarioError indicates that you as the author of the scenario have made an error in their setup.

• A SimulationError occurs during the simulation. This often indicates that there is an error in a simulator. (But the error might also be due to an error in using it.) Check your usage carefully (including the simulator’s documentation), and then potentially contact the simulator author about the error.

exception ScenarioError

This exception is raised if something fails during the creation of a scenario.

This is usually due to an error on the part of the part of the scenario author.

exception SimulationError(msg: str, exc: BaseException | None = None)

This exception is raised if a simulator cannot be started or if a problem arises during the execution of a simulation.

These exceptions can be due to errors in the scenario or due to errors in the simulators.

Parameters:

• msg (str)

• exc (BaseException | None)

exception SimulatorError(simulator: str, *args: Any)

This is the supertype for exceptions raised if a simulator does not behave correctly.

If you encounter one of these exceptions as a scenario author, you should usually contact the author of the simulator in question to resolve the issue.

Parameters:

• simulator (str)

• args (Any)

exception NonSerializableOutputsError(dest: str)

This exception is raised if a simulator started via "python" returns output that cannot be serialized to JSON but you try to transmit this data to a simulator started via "cmd" or "connect".

There are two possible resolutions:

• Contact the simulator author to have them change their output datatypes to standard Python types that can be serialized.

• Start the destination simulator via "python" as well. This resolution is mostly sensible if the two simulators are tightly coupled and are supposed to exchange non-primitive objects directly.

Parameters:

dest (str)

exception DuplicateEntityIdError(simulator: str, entity_id: str)

This exception is raised if a simulator returns multiple entities with the same entity ID.

Parameters:

• simulator (str)

• entity_id (str)

exception ConnectionClosedError(simulator: str, method_called: str)

This exception is raised if a simulator closes the socket connection (or if it breaks for other reasons) when mosaik is not expecting it to be broken.

Parameters:

• simulator (str)

• method_called (str)

exception SimulatorInitError(sim_id: str, cause: BaseException)

This exception is raised if an error occurs while mosaik is calling init on a simulator. It wraps the original error (which might, for example, have been raised by the simulator itself) for additional context.

Parameters:

• sim_id (str)

• cause (BaseException)

exception ApiVersionTooNewError(sim_id: str, version: list[int])

This exception is raised if a simulator reports an API version that is newer than what this version of mosaik supports. Try upgrading the mosaik package.

Parameters:

• sim_id (str)

• version (list[int])

exception ApiVersionMismatchError(sim_id: str, explicit_version: list[int], actual_version: list[int])

This exception is raised if the API version explicitly specified for a simulator (in its SimConfig entry) does not match the version that the simulator actually reports.

Parameters:

• sim_id (str)

• explicit_version (list[int])

• actual_version (list[int])

exception ForcedOldApiUsageError(sim_id: str, version: list[int])

This exception is raised if a simulator’s init or step method is missing the parameters required for API version 3 or higher (namely, the time_resolution keyword parameter of init and the max_advance parameter of step) but the simulator’s meta nevertheless claims to support that version.

Parameters:

• sim_id (str)

• version (list[int])

exception MissingSimIdError

This exception is raised if World.start is called with a Starter object but without an explicit sim_id. (A sim_id cannot be generated automatically in this case, as it usually is, because there is no simulator name to base it on.)

exception MissingSimConfigError

This exception is raised if a simulator is started by name (i.e. by giving a key into the world’s sim_config) but no sim_config was specified when the world was created.

exception UnknownStarterNameError(starter_name: str)

This exception is raised if a simulator is started by a name that is not defined in the world’s sim_config.

Parameters:

starter_name (str)

exception DuplicateSimIdError(sim_id: str)

This exception is raised if a simulator is started with a sim_id that has already been used for another simulator in this world.

Parameters:

sim_id (str)

exception WeakConnectionOutsideGroupError

This exception is raised if a weak connection is created between (entities of) two simulators that do not share a simulator group.

Weak connections are only legal within groups, which clarify whether and how weak connections in different parts of the simulation interact, see Weak connections.

exception AttributeConnectionError(src: Entity, dest: Entity, src_attr: Attr, dest_attr: Attr, missing_src_attr: bool = False, missing_dest_attr: bool = False, missing_initial_data: bool = False)

This exception is raised if a single attribute connection (as established by connect_one) cannot be made, for example because the source or destination attribute does not exist, or because a weak or time-shifted connection into a non-trigger attribute is missing initial data.

Parameters:

• src (Entity)

• dest (Entity)

• src_attr (Attr)

• dest_attr (Attr)

• missing_src_attr (bool)

• missing_dest_attr (bool)

• missing_initial_data (bool)

exception ConnectError(errors: list[ScenarioError])

This exception is raised by connect if one or more of the requested attribute connections could not be made. The individual errors (usually AttributeConnectionError instances) are available in errors.

Parameters:

errors (list[ScenarioError])

exception DataflowCycleError(cycle: list[str], connections: list[tuple[str, str, str, str]])

This exception is raised if the connections between simulators result in a cyclic dataflow with no delay anywhere in the cycle. Such a cycle cannot be resolved during the simulation, as it would result in each simulator in the cycle waiting on another one in the cycle indefinitely.

You can resolve such a cycle by making (at least) one of the connections in the cycle weak or time-shifted.

Parameters:

• cycle (list[str])

• connections (list[tuple[str, str, str, str]])

exception UnknownExtraMethodError(sim_id: str, method_name: str)

This exception is raised if you attempt to call an extra method on a simulator that is not listed as one of its extra_methods.

Parameters:

• sim_id (str)

• method_name (str)

exception MissingSimulatorTypeError(sim_id: str)

This exception is raised if a simulator’s meta does not specify a type (one of "time-based", "event-based" or "hybrid"), which is required starting from API version 3.

Parameters:

sim_id (str)

exception InvalidSimulatorTypeError(sim_id: str, type: str)

This exception is raised if a simulator’s meta specifies a type that is not one of "time-based", "event-based" or "hybrid".

Parameters:

• sim_id (str)

• type (str)

exception IllegalModelNameError(sim_id: str, model_name: str)

This exception is raised if a simulator declares a model whose name clashes with one of the mosaik API methods.

Parameters:

• sim_id (str)

• model_name (str)

exception IllegalExtraMethodNameError(sim_id: str, method_name: str, clashes_with_model: bool = False)

This exception is raised if a simulator declares an extra method whose name clashes with one of the mosaik API methods or with one of the simulator’s own models.

Parameters:

• sim_id (str)

• method_name (str)

• clashes_with_model (bool)

exception SimulatorConnectionLostError(sim_id: str, cause: BaseException | None = None, during: str | None = None)

This exception is raised if the connection to a simulator closes unexpectedly while mosaik is communicating with it during a running simulation.

Parameters:

• sim_id (str)

• cause (BaseException | None)

• during (str | None)

exception StepTimeMismatchError(sim_id: str, step_time: TieredTime, progress_time: TieredTime)

This exception is raised if a simulator is about to perform a step at some time but mosaik has previously determined that that simulator had already passed that time.

This usually indicates an internal scheduling error in mosaik; please report it on our issue tracker.

Parameters:

• sim_id (str)

• step_time (TieredTime)

• progress_time (TieredTime)

exception MaxLoopIterationsExceededError(sim_id: str, max_loop_iterations: int, step_time: TieredTime)

This exception is raised if a simulator performs a sub-step (as part of a same-time loop) more often than max_loop_iterations. This usually indicates that the scenario has run into an infinite loop. If not, max_loop_iterations can be increased to get rid of this error.

Parameters:

• sim_id (str)

• max_loop_iterations (int)

• step_time (TieredTime)

exception InvalidNextStepTypeError(sim_id: str, next_step_time: int)

This exception is raised if the next step time returned by a simulator’s step method is not of type int.

Parameters:

• sim_id (str)

• next_step_time (int)

exception InvalidNextStepTimeError(sim_id: str, next_step_time: int, current_step_time: int)

This exception is raised if the next step time returned by a simulator’s step method is not later than the time of the step that was just performed.

Parameters:

• sim_id (str)

• next_step_time (int)

• current_step_time (int)

exception InvalidOutputTimeError(sim_id: str, output_time: int, last_step_time: TieredTime)

This exception is raised if a simulator reports an output time that is earlier than the time of the step whose output is being collected.

Parameters:

• sim_id (str)

• output_time (int)

• last_step_time (TieredTime)

exception EventInNonRealTimeModeError(sim_id: str)

This exception is raised if a simulator tries to schedule an event (using set_event) in a non-real-time simulation.

Events can only sensibly be scheduled in real-time mode, as there is no relation between the real time at which the event occurs and and mosaik’s internal simulation time, otherwise.

Parameters:

sim_id (str)

exception AsyncRequestsNotConnectedError(src_sim_id: str, dest_sim_id: str)

This exception is raised if a simulator tries to make an asynchronous request (using get_data or set_data) to another simulator that it is not connected to.

Parameters:

• src_sim_id (str)

• dest_sim_id (str)

exception AsyncRequestsNotEnabledError(src_sim_id: str, dest_sim_id: str)

This exception is raised if a simulator tries to make an asynchronous request (using get_data or set_data) to another simulator that it is connected to, but without async_requests=True having been set for that connection.

Parameters:

• src_sim_id (str)

• dest_sim_id (str)

exception UnknownStarterConfigError(starter_config: StarterConfig)

This exception is raised if a StarterConfig does not match any of the known Starter subclasses. (By default, it must contain one of the keys "python", "cmd", or "connect".)

Parameters:

starter_config (StarterConfig)

exception MalformedPythonImportStringError(import_string: str)

This exception is raised if a "python" starter config’s import string does not have the form "module_name:ClassName".

Parameters:

import_string (str)

exception PythonImportError(module_name: str, class_name: str, cause: BaseException)

This exception is raised if the module or class specified for a PythonStarter could not be imported.

Parameters:

• module_name (str)

• class_name (str)

• cause (BaseException)

exception OutdatedMosaikApiPackageError

This exception is raised if the installed version of the mosaik_api_v3 package is too old to be used with mosaik 3.

exception ConflictingTerminationManagerError(auto_terminate: bool, termination_manager: ProcessTerminationManager)

This exception is raised if both auto_terminate and termination_manager are specified for a CmdStarter. As auto_terminate is just a shorthand for choosing one of two built-in termination managers, at most one of the two arguments should be given.

Parameters:

• auto_terminate (bool)

• termination_manager (ProcessTerminationManager)

exception ProcessStartError(sim_id: str, cause: BaseException)

This exception is raised if the process for a CmdStarter could not be started, for example because the command or the working directory could not be found.

Parameters:

• sim_id (str)

• cause (BaseException)

exception MalformedConnectAddressError(address: str)

This exception is raised if the address string given for a ConnectStarter cannot be parsed. It should be of the form "host:port".

Parameters:

address (str)

exception SimulatorStartTimeoutError(sim_id: str)

This exception is raised if a simulator started via a CmdStarter does not connect to mosaik within the configured start_timeout.

Parameters:

sim_id (str)

exception SimulatorConnectError(sim_id: str, host: str, port: int)

This exception is raised if mosaik could not connect to a simulator via a ConnectStarter, for example because no simulator is listening at the given address.

Parameters:

• sim_id (str)

• host (str)

• port (int)