1 unstable release
0.1.0 | Oct 27, 2024 |
---|
#14 in Simulation
146 downloads per month
75KB
1.5K
SLoC
Rust API for Mosaik
This project allows Rust code to operate with Mosaik simulations in Python. It provides a high-level API for simulators written in Rust to communicate with the Mosaik Smart-Grid co-simulation framework.
The API is based on the Mosaik API and is compatible with Mosaik version 3 but does not support asynchronous communication yet.
Content of this repository
The src folder contains the components for communicating between Rust simulators and Mosaik:
- The trait for the high-level API in lib.rs.
- The data types used in the API and simulators in types.rs.
- The TCP manager in tcp.rs.
- The parsing and handling of MosaikMessages and low-level connection to simulators in mosaik_protocol.rs.
The examples folder contains example simulators based on the official Python tutorial to demonstrate the API. See section Running the example scenarios for more information.
Requirements
- A working Rust environment (Install Rust). The dependencies are declared in the Cargo.toml file.
- To run the examples you need a working Python environment, the setup of which is described below.
Implementing a simulation in Rust
For a simulator written in Rust to successfully communicate with Mosaik you must:
- Add
mosaik-api = { git = "https://github.com/ekut-es/mosaik-api" }
to yourCargo.toml
as a dependency. - Implement the
MosaikApi
trait for your simulator. - Use the
run_simulation()
function in yourmain
to connect your simulator to Mosaik. This connects your simulator to Mosaik and handles the communication over a TCP channel. TheConnectionDirection
depends on how you connect your simulator to Mosaik in Python (see Connection Setup). - Then connect the simulators in the
SIM_CONFIG
of your Mosaik python script as described in the following paragraph.
Connection Setup
We support two ways to connect Rust simulators for communication with Mosaik. It is sufficient to implement one but possible to implement both simultaneously as shown in the examples.
- Invoke the Rust simulator and parse Mosaik's
addr
to it, via the"cmd"
keyword in Mosaik'sSIM_CONFIG
in Python. For this you need theConnectionDirecton::ConnectToAddress
in Rust with the given address of Mosaik. - Run the Rust simulator manually with a predefined
addr
and connect Mosaik to it with the"connect"
keyword in Mosaik'sSIM_CONFIG
in Python. In Rust you need to useConnectionDirecton::ListenOnAddress
for therun_simulation()
.
Example setup to illustrate these two options with ADDR
as the address of the communication channel between Mosaik and the Rust simulator, e.g. 127.0.0.1:5678
:
Mosaik SIM_CONFIG key |
Rust ConnectionDirection for run_simulation() |
Notes |
---|---|---|
"cmd": "cargo run SIMULATOR -- -a=%(addr)s" |
ConnectionDirection::ConnectToAddress(ADDR) |
ADDR needs to be read in from the CLI in Rust. |
"connect": "ADDR" |
ConnectionDirection::ListenOnAddress(ADDR) |
Simulator needs to be started before running the Python script on the predefined ADDR. |
Running the example scenarios
The example simulations are located in the examples folder. It includes two scenarios inspired by the Python tutorials: demo1 and demo2. In contrast to the Python tutorials, the simulations are written in Rust and only invoked by a modified Python script to connect the Rust simulators with Mosaik (or connecting Mosaik with the simulators as shown by the Controller in demo2).
- The scenario in Demo 1 consists of an example model
Model
used in the hybridExampleSim
both implemented in example_sim.rs and an event-based Monitor calledCollector
in collector.rs. - The scenario in Demo 2 consists additionaly of the Rust implementation of an event-based
Controller
. This controller is connected via a TCP connection instead of being run by the Python script for the sake of demonstration.
To run them, build a virtual environment for python:
virtualenv .venv_examples && \
source .venv_examples/bin/activate && \
pip install "mosaik>=3.3"
Then run the example scenarios with:
cargo build --examples
python examples/demo1.py
or
cargo build --examples
cargo run --example connector & python examples/demo2.py
Local Development
For further development in this repository, it is recommended that you use pre-commit and install the local pre-commit hook by running pre-commit install
in your terminal.
Dependencies
~5–15MB
~210K SLoC