About CityLearn
CityLearn is an open source simulation environment hosted at LF Energy that provides a standardized testbed for developing and comparing control strategies across communities of buildings and their distributed energy resources. Built on the Farama Foundation’s Gymnasium API, it allows researchers and developers to implement and fairly evaluate rule-based control, model predictive control, and single- or multi-agent reinforcement learning on a consistent, reproducible platform.
CityLearn models virtual districts of buildings, providing the observations, actions, reward functions, datasets, and key performance indicators needed to benchmark algorithms on equal footing.
The Challenge
Districts and cities experience periods of high electricity demand that raise prices and increase operational and capital costs across generation, transmission, and distribution networks. Reshaping the aggregated demand curve (flattening peaks and shifting consumption) lowers those costs and supports grid stability. Coordinating distributed building resources (batteries, heat pumps, EVs, and thermal storage) is one of the most practical ways to do it.
Reinforcement learning and model predictive control are well suited to this problem, but researchers have historically been unable to compare algorithms fairly because experiments were hard to reproduce. Different teams used different building models, datasets, action spaces, reward functions, and evaluation metrics, making it difficult to assess whether a new approach genuinely improved on existing methods.
The result was duplicated effort, inconsistent benchmarks, and a slower path from algorithm development to practical deployment.
Key Features
Standardized Simulation Environment
CityLearn provides a common environment built on the Farama Foundation Gymnasium API, with consistent observations, actions, reward functions, datasets, and key performance indicators covering cost, carbon emissions, comfort, and grid-level metrics. Any control approach, from simple rule-based controllers to multi-agent deep reinforcement learning, can be evaluated against the same testbed and compared directly with published results.
Modeled Building Districts and Distributed Energy Resources
CityLearn simulates virtual districts of buildings with a full set of distributed energy resources such as air-to-water heat pumps, electric heaters, thermal storage (hot-water and chilled-water tanks), battery energy storage, electric vehicles, PV arrays, and related DERs.
Agents control energy storage and dispatch at each time step, while an internal backup controller ensures building loads and occupant comfort are always met, regardless of agent decisions.
Developer Tooling
CityLearn includes a command-line interface, extensive tutorials, and the CityLearn UI, a visualization dashboard for inspecting simulation data and comparing KPIs to reduce the barrier to entry for researchers and developers.
Fully Extensible
CityLearn is designed to be extensible with new features, providing opportunities for contributors and end users to customize and add to the tool to improve performance or meet expanding needs.
Key Contributors
- Intelligent Environments Lab, University of Texas at Austin
- TU Eindhoven
- ISEP Portugal, SoftCPS research group
- Politecnico di Torino
- Concordia University
Technical Foundation
CityLearn is built on established open source frameworks and curated real-world datasets.
- Farama Foundation Gymnasium API provides the reinforcement learning environment interface, ensuring compatibility with the standard Python RL ecosystem
- U.S. End-Use Load Profiles (EULP) database provides the underlying building-stock data for simulation datasets
- LSTM-based dynamic thermal modeling (contributed by Politecnico di Torino) supports load-shedding flexibility simulation via indoor temperature dynamics
- PySAM (optional dependency) enables PV autosizing
- MIT license governs the codebase, with source available on GitHub at https://github.com/citylearn-project/CityLearn
- Digital Public Goods Alliance registration confirms alignment with open digital infrastructure standards
Use Cases
The following application areas use CityLearn as the experimental environment.
Benchmarking Control Algorithms
Compare rule-based, model predictive, and single- or multi-agent reinforcement learning controllers on a standardized building energy coordination task, with reproducible datasets and evaluation metrics that allow direct cross-study comparison.
Coordinated Building-Cluster Energy Management
Develop and test coordinated control strategies for clusters of buildings that share energy storage or coordinate demand response without centralized control, including both cooperative and competitive multi-agent approaches.
Incentive-Based Demand Response
Model and test pricing and incentive signals that encourage buildings to shift or reduce demand, supporting utility and aggregator program design.
Model Predictive Control
Use CityLearn’s simulation environment as the plant model for MPC implementations, or compare MPC and RL approaches on identical building scenarios.
Transfer and Meta-Learning
Test whether controllers trained in one building environment can transfer to new buildings or districts with minimal retraining, supporting research into generalization for real-world deployment.
Occupant-Centric and Resilience Studies
Use thermostat override modeling and power outage simulation to study control strategies that maintain occupant comfort under demand response and grid disruption scenarios.
Demand Flexibility Estimation
Estimate the demand flexibility available in residential and commercial building stock (flexibility that can defer feeder and transmission upgrades), providing utilities and aggregators with evidence for grid planning decisions.
Project Roadmap
The v2 series, begun in 2023, has expanded the environment across energy flexibility, resilience, occupant-centric operation, and carbon awareness dimensions and remains under active development.
View the existing technical documentation at https://www.citylearn.net.
Collaboration Opportunities
CityLearn welcomes participation from controls and ML researchers, building energy engineers, power systems researchers, and dataset contributors working on:
- Control algorithm development and benchmarking for building demand response
- Occupant behavior modeling and comfort-aware control strategies
- Grid-interactive building simulation and dataset development
- Carbon-aware and resilience-focused energy management
- RL and MPC approaches to behind-the-meter DER coordination
Research groups seeking a standardized testbed for comparative studies, organizations with building energy datasets suitable for inclusion, and developers building controller implementations are all encouraged to contribute.
CityLearn provides the shared benchmark infrastructure that allows the building energy controls community to measure progress consistently, rather than each team building its own non-comparable simulation environment.
To get involved:
