# offis-dai/cosima architecture

> Architecture diagram of the GitHub repository offis-dai/cosima, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/offis-dai/cosima
- Repository: https://github.com/offis-dai/cosima

## Overview

##### Project Type and Purpose
- This project is essentially a simulation integrator. It bridges (i) a Python-based simulation environment (cosima_core) that orchestrates various scenarios, agent behaviors, and simulation utilities with (ii) a C++/OMNeT++-based project (cosima_omnetpp_project) that models detailed communication networks.
- The README clearly states that the aim is to integrate the communication simulator OMNeT++ into agent communication. It supports Smart Grid co-simulation (with mosaik) and provides a direct coupling to the mango agent framework.

##### File Structure
- The top-level folders include:
- cosima_core: Contains the core Python modules for scenarios, simulators, messaging (with protobuf definitions), and various utilities.
- cosima_omnetpp_project: Contains the OMNeT++ configuration files, network definitions (ned files, C++ modules, message definitions), and related project configuration files.
- Data, Docs, Tests, and Setup scripts: which support configuration, testing, and documentation.
- Within cosima_core, you see the main components:
– scenarios: Different simulation use cases (communication, negotiation, mango-related scenarios, tutorials).
– simulators: Modules for various simulation aspects – from communication simulation, data collection, to agent simulation examples.
– messages: Protobuf message definitions and generated files (Python and C++ versions) to ensure consistent communication between the Python core and the OMNeT++ simulation.
– util: Various helper scripts (e.g., building OMNeT projects, configuration).
- The cosima_omnetpp_project holds OMNeT++ models including network definitions (ned files), modules (with simulation logic in C++), and the integration points for the protobuf-based messages.

##### Extract Key Architectural Components and Their Relationships
- Main Components:
1. Scenario & Simulation Orchestration (cosima_core/scenarios and run.py): This serves as the entry point where users choose simulation scenarios and parameters (e.g., simulation mode, network types, and simulation timing).
2. Simulation Logic & Message Handling (cosima_core/messages, util, and simulators): Houses the business logic that triggers simulations. It leverages protobuf messages to encode and exchange simulation data.
3. Communication Simulator Integration:
– OMNeT++ Project (cosima_omnetpp_project): Contains modules, networks (ned and XML files), and configuration (cosima.ini) that set up the actual simulation of communication channels (e.g., 5G networks, LTE, WiFi) using INET (and optionally SimuLTE).
– Integration of generated protobuf artifacts – note that the C++ message implementations are used both in Python (via cosima_core/messages/message_pb2.py) and in OMNeT++ (via cosima_omnetpp_project/messages).
4. External Dependencies:
– Mosaik: A Smart Grid co-simulation framework into which cosima can be integrated.
– Mango: The agent framework that enables high-performance simulation of agent behaviors.
– OMNeT++/INET/SimuLTE: The simulation backend for communication.
- Relationships:
– The Python core (cosima_core) initiates simulation scenarios, which in turn use the simulators to send and receive messages.
– Protobuf messages act as the interface boundary between Python and the OMNeT++ simulation components.
– The OMNeT++ project consumes these messages and uses them to configure network elements and execute the simulation.
– Data flows from scenario setup to the simulators, then to message generation, crossing over to the OMNeT++ simulation environment and back as results (recorded in cosima_core/results).

##### Important Architectural Patterns and Technologies
- Separation of Concerns: The project is clearly divided into simulation orchestration (Python) and network simulation (OMNeT++), making it easier to update either part independently.
- Messaging & Interface Consistency: The use of protobuf for defining messages ensures that both C++ (OMNeT++) and Python parts communicate reliably.
- Modular Design: Each scenario, simulator, and message component is encapsulated in its own module.
- Extensibility: The architecture supports adding new simulation scenarios, network configurations, or external integrations (e.g., with SimuLTE or additional communication modules).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Simulation Core
    subgraph "Python Simulation Core"
        subgraph "Simulation Orchestration"
            runpy["run.py"]
            scenarios["Simulation Scenarios"]
        end
        subgraph "Simulation Logic & Message Handling"
            messages["Protobuf Messages (cosima_core/messages)"]
            simulators["Simulators (cosima_core/simulators)"]
            util["Utilities (cosima_core/util)"]
            mango["Mango Direct Connection (cosima_core/mango_direct_connection)"]
        end
    end

    %% Communication Simulation Environment (OMNeT++ Integration)
    subgraph "Communication Simulation Environment"
        config["Project Config (cosima_omnetpp_project)"]
        msgArtifacts["Message Artifacts (cosima_omnetpp_project/messages)"]
        modules["Simulation Modules (cosima_omnetpp_project/modules)"]
        networks["Network Definitions (cosima_omnetpp_project/networks)"]
    end

    %% External Dependencies
    mosaik["Mosaik"]
    omnetpp_external["OMNeT++"]
    inet["INET"]
    simulte["SimuLTE"]
    mangoExt["Mango"]

    %% Flow within Python Simulation Core
    runpy -->|"selects"| scenarios
    scenarios -->|"initiates"| messages

    %% Flow from Python Simulation Core to OMNeT++ Environment
    messages -->|"triggers"| config
    simulators -->|"influences"| config
    util -->|"supports"| config

    %% Internal flow inside OMNeT++ Environment
    config -->|"generates"| msgArtifacts
    msgArtifacts -->|"integrates with"| modules
    modules -->|"defines"| networks

    %% External Integration flows
    scenarios -->|"integrates"| mosaik
    config -->|"configured by"| omnetpp_external
    config -->|"uses"| inet
    config -->|"supports"| simulte
    mango -->|"connects to"| mangoExt

    %% Styling for clarity
    class runpy,scenarios,messages,simulators,util,mango pythonStyle
    class config,msgArtifacts,modules,networks omnetStyle
    class mosaik,omnetpp_external,inet,simulte,mangoExt externalStyle

    %% Click Events for Python components
    click runpy "https://github.com/offis-dai/cosima/blob/master/run.py"
    click scenarios "https://github.com/offis-dai/cosima/tree/master/cosima_core/scenarios"
    click messages "https://github.com/offis-dai/cosima/tree/master/cosima_core/messages"
    click simulators "https://github.com/offis-dai/cosima/tree/master/cosima_core/simulators"
    click util "https://github.com/offis-dai/cosima/tree/master/cosima_core/util"
    click mango "https://github.com/offis-dai/cosima/tree/master/cosima_core/mango_direct_connection"

    %% Click Events for OMNeT++ components
    click config "https://github.com/offis-dai/cosima/tree/master/cosima_omnetpp_project"
    click msgArtifacts "https://github.com/offis-dai/cosima/tree/master/cosima_omnetpp_project/messages"
    click modules "https://github.com/offis-dai/cosima/tree/master/cosima_omnetpp_project/modules"
    click networks "https://github.com/offis-dai/cosima/tree/master/cosima_omnetpp_project/networks"

    %% Class Definitions (colors and style)
    classDef pythonStyle fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef omnetStyle fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef externalStyle fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
