citylearn-project/CityLearn

What it solves

CityLearn provides a standardized simulation environment for optimizing building energy coordination and demand response. It allows researchers and developers to test multi-agent reinforcement learning (MARL) algorithms to balance energy loads, integrate renewable energy like solar (PV), and manage electric vehicle (EV) charging without relying on expensive real-world deployments.

How it works

Built as a Farama Foundation Gymnasium environment, CityLearn simulates the electrical interactions of buildings and communities. It uses dataset-driven simulations where users can define building schemas, energy profiles, and electrical topologies. The environment supports multiple interfaces: a "flat" vector mode for standard RL and an "entity" mode that provides table-based observations and edges, making it suitable for Graph Neural Networks (GNNs) or Transformers. It can handle complex scenarios including three-phase electrical services, dynamic topology (adding/removing assets during simulation), and robustness events like asset outages.

Who it’s for

It is designed for researchers and engineers working on smart grids, energy management systems, and multi-agent reinforcement learning applied to urban energy efficiency.

Highlights

• Comprehensive Energy Assets: Supports electric vehicles (EVs) with V2G capabilities, deferrable appliances, and escalator control.
• Flexible Time Resolution: Handles simulations from hourly down to 15-second intervals.
• Advanced Topology: Supports three-phase power systems and dynamic changes to the community structure during a simulation.
• Multi-Community Orchestration: Ability to synchronize and manage multiple independent energy communities simultaneously.
• Robustness Testing: Includes dataset-driven perturbations to test how agents handle forecast errors or asset failures.