CityLearn is an open source OpenAI Gym environment for the implementation of Multi-Agent Reinforcement Learning (RL) for building energy coordination and demand response in cities [16, 18]. A major challenge for RL in demand response is the ability to compare algorithm performance [20]. Thus, CityLearn facilitates and standardizes the evaluation of RL agents such that different algorithms can be easily compared with each other.

demand response

Districts and cities have periods of high demand for electricity, which raise electricity prices and the overall cost of the power distribution networks. Flattening, smoothening, and reducing the overall curve of electrical demand helps reduce operational and capital costs of electricity generation, transmission, and distribution networks. CityLearn allows the easy implementation of reinforcement learning agents in a single or multi-agent setting to reshape their aggregated curve of electrical demand by controlling the storage of energy by every agent.


CityLearn has been utilized in the following projects and publications:



Incentive based demand-response

Deltetto et al. [1]

Collaborative demand-response

Glatt et al. [3]

Independent energy management

Nweye et al. [8]

Coordinated energy management

Kathirgamanathan et al. [4], Pinto et al. [11], Pinto et al. [13], Vazquez-Canteli et al. [19]

Benchmarking reinforcement learning algorithms

Dhamankar et al. [2], Nweye et al. [7], Pinto et al. [12], Qin et al. [14]

Voltage regulation

Pigott et al. [10]

Cite CityLearn

   author = {V\'{a}zquez-Canteli, Jos\'{e} R. and K\"{a}mpf, J\'{e}r\^{o}me and Henze, Gregor and Nagy, Zoltan},
   title = {CityLearn v1.0: An OpenAI Gym Environment for Demand Response with Deep Reinforcement Learning},
   year = {2019},
   isbn = {9781450370059},
   publisher = {Association for Computing Machinery},
   address = {New York, NY, USA},
   url = {},
   doi = {10.1145/3360322.3360998},
   booktitle = {Proceedings of the 6th ACM International Conference on Systems for Energy-Efficient Buildings, Cities, and Transportation},
   pages = {356–357},
   numpages = {2},
   keywords = {Smart Grid, Building Energy Control, Smart Buildings},
   location = {New York, NY, USA},
   series = {BuildSys '19}


CityLearn is an open-source project that continues to benefit from community-driven updates and suggestion. Before you begin contributing please, read our Contributor Covenant Code of Covenant.

Visit the CityLearn GitHub repository to join the community and start contributing.

Refer to our bug report template for guidelines on how to report bugs or feature request template to propose enhancements and functionalities that you will like to be implemented.

Indices and tables