mosaik 3.7 released

More Control over Simulator Processes

Simulators started with CmdStarter are now managed using Python’s asynchronous subprocess infrastructure, integrating them more cleanly with mosaik’s asyncio-based architecture.

The new termination_manager option gives you more control over what happens to a simulator process when mosaik shuts down. You can let mosaik terminate the process automatically, optionally with a timeout, or allow the process to keep running:

from mosaik.process_termination_managers import auto_terminate
from mosaik.starters import CmdStarter

starter = CmdStarter(
    "python simulator.py %(addr)s",
    termination_manager=auto_terminate(timeout=5),
)

The existing auto_terminate option remains available for backwards compatibility. In addition, the new stdout and stderr parameters make it possible to redirect or suppress a simulator’s output.

More information is available in the CmdStarter API reference and the process termination manager reference.

Trace Simulator Calls

Calls between mosaik and simulators can now be traced in both directions at Loguru’s TRACE level. The trace records arguments, return values, and exceptions and identifies the relevant simulator, making it easier to follow interactions and isolate problems in complex scenarios. See How to trace simulator calls for configuration instructions and an example.

Clearer and More Specific Errors

mosaik now provides dedicated exception classes for many common scenario and simulation errors. Instead of relying mainly on generic ScenarioError and SimulationError messages, applications can now distinguish between problems such as invalid simulator configurations, duplicate simulator IDs, connection errors, invalid step times, and simulator start failures.

This makes errors easier to understand and also allows applications to handle specific failures programmatically. An overview of the new exception hierarchy is available in the mosaik exceptions API reference.

Reports of dataflow cycles have also been improved. Instead of listing only the simulators involved, mosaik now shows the entity and attribute connections that form the cycle:

Your scenario contains a cycle:
- A.0.0.val_out -> B.0.0.val_in
- B.0.0.val_in -> A.0.0.val_out

This should make accidental cycles considerably easier to locate and resolve.

More Reliable Progress Calculation

The scheduler now correctly considers a predecessor simulator’s current step when calculating simulation progress.

Previously, a simulator that was still executing a blocking step could under certain circumstances cause mosaik to calculate an incorrect progress bound and attempt to move backwards in simulation time. This has been fixed, improving the reliability of scenarios containing blocking or slow-running simulators.

Scheduler Performance Improvements

Several internal scheduling operations have been streamlined to address a performance regression. Dependency waiting now avoids unnecessary task creation, completed progress futures are cleaned up more efficiently, and operations on mosaik’s internal tiered-time representation have been optimized.

These changes reduce scheduling overhead, particularly in scenarios with many simulators and connections.

Python 3.12 Is Now Required

mosaik 3.7.0 raises the minimum supported Python version from Python 3.8 to Python 3.12.

This allows mosaik to use modern Python features and current versions of important dependencies. The project is now tested against Python 3.12, 3.13, and 3.14.

If your scenario still runs on Python 3.8 through 3.11, you will need to update your Python environment before upgrading to mosaik 3.7.0.

Updated and More Reliable Documentation

Large parts of the documentation have been reviewed and reorganized.

The updated mosaik ecosystem overview now provides clearer descriptions of available simulators, adapters, APIs, example scenarios, and supporting tools. The documentation for the high-level simulator APIs has also been restructured, with updated information for Python, Java, Julia, Matlab, C#, and Rust.

The troubleshooting section and API reference have been extended, while internal developer APIs are now separated more clearly from the public scenario API.

What’s Next?

mosaik 3.7.0 modernizes the project’s technical foundation while making simulations easier to debug, more reliable, and more efficient. The new process-management infrastructure and exception hierarchy also lay the groundwork for future extensions, whatever version numbers they will have.

As always, we invite you to try the new version, explore the improvements, and share your feedback or questions in the OFFIS-mosaik GitHub Discussions forum.

Happy simulating with mosaik 3.7.0!