Skip to content
Projects

citylearn-project/CityLearn has 661 GitHub stars and 222 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 23:35 UTC. Last push 2026-11-13.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Official reinforcement learning environment for demand response and load shaping

Learning

README.md

Original

CityLearn

CityLearn is an open-source Gymnasium environment for building energy coordination, demand response and reinforcement learning. Use it to configure renewable energy communities, run controllers and compare energy, cost and service outcomes.

CityLearn v3 brings together buildings and thermal systems, PV, batteries, EVs and flexible loads with electrical limits, local energy sharing, changing members and assets, and data or equipment failures. It builds on the CityLearn community's work and the extensions developed by the Soft-CPS Research Group.

Documentation · Features · KPIs and scorecard · CityLearn UI

Install

python -m pip install citylearn

Use Python 3.9 or newer in a virtual environment. See the installation guide for setup and optional dependencies, including Parquet support.

Configure your community

CityLearn v3: configurable renewable energy communities with buildings, PV, storage, EVs, flexible loads, controllers, electrical limits, demand response and community KPIs.

The figure illustrates community configurations and services available in CityLearn. Individual scenarios can use different time resolutions; synchronized multi-community runs use a common timestep.

Run your first simulation

This example downloads a public dataset on first use, runs a short episode with the built-in business-as-usual controller and prints community KPIs. It works outside a repository checkout.

from citylearn.agents.baseline import BusinessAsUsualAgent
from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv(
    "citylearn_challenge_2022_phase_all_plus_evs",
    episode_time_steps=24,
    interface="flat",
    render_mode="none",
)
agent = BusinessAsUsualAgent(env)
observations, info = env.reset(seed=0)
terminated = truncated = False

while not (terminated or truncated):
    actions = agent.predict(observations)
    observations, rewards, terminated, truncated, info = env.step(actions)

kpis = env.evaluate_v2()
selected = [
    "district_cost_total_control_eur",
    "district_energy_grid_total_import_control_kwh",
    "district_ev_performance_departure_min_acceptable_feasible_ratio",
    "district_electrical_service_phase_violations_energy_total_kwh",
]
print(kpis.loc[
    (kpis["level"] == "district") & kpis["cost_function"].isin(selected),
    ["cost_function", "value"],
].to_string(index=False))
env.close()

The first-simulation guide explains the loop, outputs and next steps. A runnable copy is in examples/first_simulation.py.

Learn more

Cite and contribute

See Publications and applications and Cite CityLearn for studies and the published reference. CityLearn is distributed under the MIT license; its development is supported by the project contributors.