How ugr-sail/sinergym works
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.