| --- |
| license: mit |
| tags: |
| - reinforcement-learning |
| - multi-agent |
| - time-series |
| - diffusion-model |
| - energy-management |
| - smart-grid |
| --- |
| # SolarSys: Scalable Hierarchical Coordination for Distributed Solar Energy |
|
|
| SolarSys is a novel **Hierarchical Multi-Agent Reinforcement Learning (HRL)** system designed to manage energy storage and peer-to-peer (P2P) trading across large communities of solar-equipped residences[cite: 10]. This repository contains the full source code for the SolarSys system, including the trained policies, the custom Gym environment, and the hierarchical diffusion model used for data augmentation. |
|
|
| --- |
|
|
|
|
| ## System Architecture |
|
|
| The core of SolarSys is a two-level decision hierarchy: |
|
|
| 1. [cite_start]**Low-Level (Intra-Cluster):** Individual households use a **MAPPO** agent to make instantaneous decisions (charge, discharge, local P2P trade, grid trade) based on local meter readings and price signals[cite: 13, 313]. |
| 2. [cite_start]**High-Level (Inter-Cluster):** Cluster Managers use a **Mean-Field** policy to coordinate bulk energy transfers between clusters, ensuring the overall system remains balanced against grid constraints[cite: 14, 314]. |
|
|
|
|
|
|
| --- |
|
|
| ## Data Generation Framework |
|
|
| [cite_start]To enable large-scale simulation with realistic temporal dynamics, SolarSys includes a **Hierarchical Diffusion Model** for generating synthetic, long-duration energy profiles that maintain both long-term (seasonal/monthly) and short-term (daily/hourly) characteristics[cite: 254, 255]. |
| |
| * [cite_start]**Model:** Hierarchical Diffusion U-Net [cite: 254, 255] |
| * [cite_start]**Input:** Household ID and Day-of-Year conditioning [cite: 256] |
| * **Output:** High-resolution time series for Grid Usage and Solar Generation (kWh). |
| |
| |
| |
| --- |
| |
| ## Repository Structure |
| |
| The project is organized into core modules and data folders. |
| |
| ```tree |
| SolarSys/ |
| ├── data/ |
| │ ├── per_house/ # Raw CSVs for diffusion model training |
| │ ├── training/ # Cleaned RL training datasets |
| │ └── testing/ # Cleaned RL evaluation datasets |
| ├── models/ |
| │ ├── diffusion_models/ # Trained Hierarchical Diffusion Model checkpoints |
| │ ├── mappo_models/ # Trained MAPPO baselines and low-level agents |
| │ └── inter_agent_models/ # Trained MeanField high-level coordinator |
| ├── Environment/ |
| │ ├── __init__.py |
| │ └── solar_sys_environment.py # Custom Gym environment for flat RL |
| ├── cluster/ |
| │ ├── __init__.py |
| │ └── inter_cluster_coordinator.py # Logic for high-level trade matching |
| └── trainers/ |
| ├── __init__.py |
| ├── hierarchical_train.py # Main SolarSys HRL training script |
| └── evaluation_scripts/ # Scripts for baselines (PG, MADDPG, MAPPO, MFAC) |
| |
|
|
