{
  "slug": "citylearn-2020",
  "title": "CityLearn",
  "canonical_source_url": "https://www.citylearn.net/overview/environment.html",
  "official_documentation_url": "https://www.citylearn.net/",
  "official_code_url": "https://github.com/citylearn-project/CityLearn",
  "introducing_source_url": "https://arxiv.org/abs/2012.10504",
  "introducing_source": "wiki/sources/citylearn-2020.md",
  "dataset_type": "Gymnasium reinforcement-learning environment and dataset schema for building energy coordination, load shaping, and demand response",
  "domain": "urban building energy management and distributed energy resources",
  "temporal_structure": "simulation time steps over virtual districts; schema files define simulation start/end, episode splits, and seconds per time step; flat CSV time-series files provide action-agnostic calendar, building, weather, carbon-intensity, and pricing observations while other observations are computed during simulation",
  "data_structure": {
    "environment": "virtual district composed of building energy models and distributed energy resources",
    "data_files": [
      "building_id.csv",
      "weather.csv",
      "carbon_intensity.csv",
      "pricing.csv",
      "schema.json",
      "optional LSTM model file for thermal dynamics"
    ],
    "observation_categories": [
      "calendar",
      "weather",
      "district",
      "building"
    ],
    "runtime_observations": [
      "storage state of charge",
      "net electricity consumption",
      "device efficiencies",
      "served heating/cooling/domestic-hot-water demand",
      "dynamic indoor dry-bulb temperature in supported versions"
    ]
  },
  "actions_or_interventions": "continuous control inputs in [-1, 1] for storage charge/discharge and device power fractions, including cooling_storage, heating_storage, dhw_storage, electrical_storage, cooling_device, and heating_device in the current documentation",
  "tasks": [
    "multi-agent reinforcement learning",
    "model predictive control benchmarking",
    "demand response",
    "building load shaping",
    "district energy coordination"
  ],
  "action_conditioned_world_model_fit": "strong simulator-backed action-conditioned environment; less a fixed static dataset than a configurable environment whose schema and generated rollouts can produce observation, action, reward/cost, and next-observation trajectories",
  "known_limitations": [
    "not a single immutable dataset payload",
    "environment behavior changes across CityLearn versions",
    "source CSVs may be simulated, measured, or precomputed depending on schema",
    "earlier versions maintain ideal indoor dry-bulb temperature and do not model load shedding in the same way as version 2.0.0 and later"
  ],
  "license_note": "GitHub repository lists MIT license; dataset/source-file licenses should be checked for any externally supplied building, weather, carbon-intensity, or pricing files before operational reuse",
  "access_note": "public documentation, open-source code, and package; this knowledge base records metadata only and does not mirror CityLearn datasets or simulation outputs",
  "created": "2026-06-09",
  "updated": "2026-06-09"
}