mosaik-mango 0.2.1

An adapter to integrate a mango simulation into mosaik

mosaik-mango

This is an adapter for using the agent framework mango in a mosaik simulation.

This simulator is still work in progress. If you have need for a particular entity or attribute, leave an issue here.

Usage

Installation

This package can be installed from PyPI as mosaik-mango.

The AgentSetup

To configure this simulator, you need to create an agent setup. It is a dict mapping model names (i.e. what the user uses in their scenario script) to AgentSpecs, which describe which class of mango agents should be used for that model and its relevant properties.

An example AgentSetup might look like this:

from mosaik_components.mango import *

AGENT_SETUP: AgentSetup = {
    "Market": AgentSpec(
        agent_class=MarketAgent,
        inputs=["price"],
        outputs=["total_volume"],
    ),
    "Trader": AgentSpec(
        agent_class=TraderAgent,
        params=["node"],
        connection_params={"market": "Market"},
        inputs=["max_amount"],
    ),
}

AgentSpec is a dataclass with the following fields:

• agent_class: The class of the mango agent represented by this model. This must be a subclass of MosaikAgent, see below.
• params: The params that can be given to this agent upon creation in the scenario. The user may provide values for these params in their scenario script, which will be passed to the constructor of your agent class. (Optional, default is no params.)
• connection_params: It is often useful to allow the user to establish agent connections in their scenario. connection_params is a dict mapping additional params to keys in the agent setup. The user may supply the entity ID of a previously-created agent to one of these params. mosaik-mango will translate this entity ID to the address of that agent and pass this address to the constructor. This can be used to send messages to that agent. (Optional, default is no such params.)
• inputs: The list of input attributes of this agent.
• outputs: The list of output attributes of this agent.

Starting the simulator

Having created your agent setup, you can start the simulator like this

import mosaik_api_v3

if __name__ == "__main__":
    sim = MangoSimulator(AGENT_SETUP, codec=codec)
    mosaik_api_v3.start_simulation(sim)

Here, codec should be the mango codec used by your agents. If you use basic JSON, you don't need to specify this.

For now, this simulator only supports running in a separate process. (In other words, it needs to be started using "cmd" or "connect" in the scenario's sim config.) If my_mango_sim is the Python module containing the above call to start_simulation, the sim config might contain

    "Agents": {
        "cmd": "%(python)s -m my_mango_sim %(addr)s",
    },

The simulator can then be started using

agents = world.start("Agents", addr=("localhost", "5556"), step_size=900)

where addr is the address for the mango container.

Creating entities

With the agent setup as above, you might create agents like this

market = agents.Market(id="EnergyMarket")
traders = [
    agents.Trader(node=node, market=market.eid)
    for node in [3, 5, 42]
]

This would result in the following constructor calls:

MarketAgent(suggested_aid="EnergyMarket", container=container)
TraderAgent(suggested_aid="Trader-0", container=container, node=3, market=market_addr)
TraderAgent(suggested_aid="Trader-1", container=container, node=5, market=market_addr)
TraderAgent(suggested_aid="Trader-2", container=container, node=42, market=market_addr)

Here, container is the mango container and market_addr is the address of the MarketAgent constructed in the first line, given as an AgentAddress object with the fields container_addr (the host-port pair for the container address)and aid (for the agent ID).

Mosaik agents

MosaikAgent is an abstract subclass of mango's Agent class. It adds the following methods and property:

• setup_done(self) -> None: This is called once the simulation is about to start (all entities and connection have been set up). After calling setup_done on each agent, the agent system is run, so messages can be exchanged here. During this, the time is -step_size. The run concludes once all agents idle. This is optional, the default implementation does nothing.
• start_mosaik_step(self, inputs: dict[str, dict[str, Any]]) -> None: This is called for each agent when the simulator is stepped. inputs is the part of the simulator's input intended for the entity corresponding to this agent. After start_mosaik_step has been called for each agent, the agent system is run, so messages can be exchanged. The step concludes once all agents idle.
• get_mosaik_output(self, request: list[str]) -> dict[str, Any]: This is called when mosaik calls get_data. A get_data call from mosaik is not garuanteed, so this might not be called. The agent system is not run after this.
• time: A property on the agent giving the current mosaik time.

Development

For the development of this simulator, the following tools are employed:

• Hatch is used as a packaging manager. This offers the following commands:

  • hatch fmt to format the code (using ruff)
  • hatch run test:test to run pytest in a test matrix consisting of Python versions 3.9 and 3.11 and mosaik versions 3.2 and 3.3.0b1.
  • hatch run python for running Python.
  • hatch run to run arbitrary commands in the managed virtualenv.

  Also, we use hatch-vcs to automatically deduce version numbers from git tags. Adding a new tag starting with v on the main branch should automatically release this on PyPI.

• pre-commit is used to run hooks before committing and pushing. Install pre-commit (I recommend pipx) and install the hooks using pre-commit install.