# ugr-sail/sinergym architecture

> Architecture diagram of the GitHub repository ugr-sail/sinergym, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ugr-sail/sinergym
- Repository: https://github.com/ugr-sail/sinergym

## Overview

##### Project Type and Purpose
- Sinergym is a simulation and control framework that leverages Gymnasium to enable reinforcement learning and other control strategies via simulation engines (e.g., EnergyPlus).
- Its purpose is to provide a benchmark and testbed for various building energy management experiments, supporting different controllers, wrappers, and logging mechanisms (including integrations like Stable Baselines 3, Weights & Biases, and Google Cloud).

##### Main System Components
- User/External Interface: Client code (examples, user scripts, notebooks) that create and interact with Gym environments.
- Core API / Environment Layer:
- Gymnasium integration: Sinergym uses the standard Gymnasium API to represent simulation environments.
- Environment creation and configuration: Handling building models, actuator definitions, and environmental parameters (see “sinergym/config”).
- Simulation Engine Integration:
- EnergyPlus simulator: This layer communicates with EnergyPlus to simulate building performance.
- Controllers & Wrappers:
- Controller modules (custom and RL controllers) that can be plugged into the system.
- Wrappers for observation/action normalization, reward shaping, logging, and other customizations (located in sinergym/utils/wrappers.py and related modules).
- Utility and Support Modules:
- Logging, callbacks, rewards, and controllers utilities (within sinergym/utils).
- Configuration adapters and common helper functions.
- Data and Building Models:
- Building definitions are stored in sinergym/data, including .epJSON and .yaml configuration files.
- Weather and energy cost data that are essential inputs to the simulation.
- Continuous Integration & Deployment:
- GitHub Actions workflows in .github/workflows and containerization (Dockerfiles and devcontainer) indicate automated testing, code quality, and deployment options.
- Documentation and Testing:
- The docs directory and examples provide usage guidance.
- The tests directory ensures quality and correctness of the modules.

##### Relationships and Interactions
- The user code (in examples and notebooks) calls the Gymnasium interface provided by Sinergym.
- The environment initialization then loads building models and configuration parameters from the data/config directories.
- Interactions flow between:
- The Gym environment and the EnergyPlus simulation engine (through the EnergyPlus Python API layer in sinergym/simulators/eplus.py).
- The control loop where actions (from a controller or an RL agent) lead to state changes in the simulation.
- Wrappers modify observations, handle reward computations, and integrate logging and diagnostics.
- Supporting utilities (callbacks, gcloud utilities, logger modules) operate as side components that monitor, log, or extend the main simulation loop.
- DevOps/CI components ensure that the code is tested and released in controlled environments (via GitHub workflows and Docker).

##### Architectural Patterns and Design Principles
- Modularity: The code is separated into clear modules for configuration, simulation, utilities, controllers, and wrappers.
- Separation of Concerns: There is a clear delineation between the environment/simulation logic and the control algorithms.
- Extensibility: With separate modules for wrappers, controllers, and configuration, users can easily plug in their custom logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        UI["User Interface\n(User/External)"]:::user
    end

    %% Core Environment Layer
    subgraph "Core Environment"
        CORE["Core API / Environment Layer\n(Gymnasium & Config)"]:::core
        DATA["Building Models & Data\n(sinergym/data/)"]:::data
    end

    %% Simulation Integration Layer
    subgraph "Simulation Integration"
        SIM["EnergyPlus Simulator\n(sinergym/simulators/eplus.py)"]:::sim
    end

    %% Control and Wrappers Layer
    subgraph "Control and Wrappers"
        CTRL["Controllers\n(sinergym/utils/controllers.py)"]:::ctrl
        WRAP["Wrappers\n(sinergym/utils/wrappers.py)"]:::ctrl
    end

    %% Utilities Layer
    subgraph "Utilities"
        UTIL["Utilities & Support\n(sinergym/utils/)"]:::util
    end

    %% DevOps Layer
    subgraph "DevOps"
        CICD["CI/CD\n(.github/workflows/, Docker, Devcontainer)"]:::ci
    end

    %% Documentation and Testing Layer
    subgraph "Documentation & Testing"
        DOC["Documentation\n(docs/)"]:::doc
        TEST["Testing\n(tests/)"]:::doc
    end

    %% Data Flow/Interactions
    UI -->|"calls"| CORE
    CORE -->|"loads_config"| DATA
    CORE -->|"sends_sim_request"| SIM
    SIM -->|"returns_results"| CORE
    CTRL -->|"act_on_env"| CORE
    CORE -->|"state_feedback"| CTRL
    WRAP -->|"modify_io"| CORE
    CORE -->|"state_update"| WRAP
    CORE -->|"logs_event"| UTIL
    UTIL -->|"support_feedback"| CORE
    UI -->|"usage_docs"| DOC
    CICD -->|"ci_cd"| CORE
    TEST -->|"test_results"| CORE

    %% Click Events
    click UI "https://github.com/ugr-sail/sinergym/tree/main/examples/"
    click CORE "https://github.com/ugr-sail/sinergym/tree/main/sinergym/envs/"
    click DATA "https://github.com/ugr-sail/sinergym/tree/main/sinergym/data/"
    click SIM "https://github.com/ugr-sail/sinergym/blob/main/sinergym/simulators/eplus.py"
    click CTRL "https://github.com/ugr-sail/sinergym/blob/main/sinergym/utils/controllers.py"
    click WRAP "https://github.com/ugr-sail/sinergym/blob/main/sinergym/utils/wrappers.py"
    click UTIL "https://github.com/ugr-sail/sinergym/tree/main/sinergym/utils/"
    click CICD "https://github.com/ugr-sail/sinergym/tree/main/.github/workflows/"
    click DOC "https://github.com/ugr-sail/sinergym/tree/main/docs/"
    click TEST "https://github.com/ugr-sail/sinergym/tree/main/tests/"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef sim fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef ctrl fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef data fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef ci fill:#9370DB,stroke:#000,stroke-width:2px;
    classDef doc fill:#F0E68C,stroke:#000,stroke-width:2px;
```
