CityLearn

CityLearn is an open-source Farama Foundation Gymnasium environment for building energy coordination, demand response and multi-agent reinforcement learning. Version 3 integrates the extended simulator developed by the Soft-CPS Research Group, including EVs, normalized deferrable appliances, sub-hourly physics, entity observations, dataset-driven demand response, robustness events, dynamic topology, three-phase electrical service, community KPIs and performance work for large datasets.

Package name:

pip install citylearn

Python import path:

from citylearn.citylearn import CityLearnEnv

Default documentation is in English. Portuguese documentation is available under docs/pt.

Current source release: 3.0.1.

Start Here

Additional reference: KPI v2 naming tree.

Capability Snapshot

Quickstart

import numpy as np
from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv(
    "data/datasets/citylearn_challenge_2022_phase_all_plus_evs/schema.json",
    interface="flat",
    episode_time_steps=24,
    render_mode="none",
)

observations, info = env.reset()
terminated = truncated = False

while not (terminated or truncated):
    actions = [np.zeros(space.shape, dtype="float32") for space in env.action_space]
    observations, reward, terminated, truncated, info = env.step(actions)

kpis = env.evaluate_v2()

Entity interface:

from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv(
    "data/datasets/citylearn_three_phase_dynamic_topology_demo/schema.json",
    interface="entity",
    topology_mode="dynamic",
)

observations, info = env.reset()
specs = env.entity_specs

Compact 15s parquet dataset with dynamic asset changes:

env = CityLearnEnv(
    "data/datasets/citylearn_three_phase_dynamic_asset_changes_demo_15s_parquet/schema.json",
    interface="entity",
    topology_mode="dynamic",
)

Demand response dataset:

env = CityLearnEnv(
    "data/datasets/citylearn_challenge_2022_phase_all_demand_response/schema.json",
    interface="entity",
)

Robustness dataset:

env = CityLearnEnv(
    "data/datasets/citylearn_challenge_2022_phase_all_robustness/schema.json",
    interface="entity",
)

Multi-community portfolio:

from citylearn.multi_community import MultiCommunityEnv

env = MultiCommunityEnv(
    communities=[
        {
            "community_id": "community_a",
            "schema": "data/datasets/community_a/schema.json",
            "env_kwargs": {"interface": "entity", "episode_time_steps": 48},
            "weight": 1.0,
        },
        {
            "community_id": "community_b",
            "schema": "data/datasets/community_b/schema.json",
            "env_kwargs": {"interface": "entity", "episode_time_steps": 48},
            "weight": 1.0,
        },
    ],
)

Unit Contract

Real power data conversion:

kWh_per_step = kW * seconds_per_time_step / 3600

Validation

Recommended pre-release checks:

.venv/bin/pytest -q
.venv/bin/python scripts/audit/audit_entity_contract.py --strict
.venv/bin/python scripts/audit/audit_physics.py

See Developer guide for lint, smoke simulations, benchmarks and architecture notes.

Documentation and UI

The CityLearn documentation covers the base concepts, examples and Version 3 extensions: official docs.

CityLearn UI is a visual dashboard for inspecting simulation data and KPIs:

The KPI export consumed by the UI is generated from evaluate_v2() by default, while evaluate() remains available for legacy workflows.