CityLearn
Source
- Dataset metadata snapshot: citylearn-2020
- Metadata JSON: metadata.json
- Official environment documentation: https://www.citylearn.net/overview/environment.html
- Official observations documentation: https://www.citylearn.net/overview/observations.html
- Official actions documentation: https://www.citylearn.net/overview/actions.html
- Official dataset documentation: https://www.citylearn.net/overview/dataset.html
- Official code: https://github.com/citylearn-project/CityLearn
- Introducing arXiv source: https://arxiv.org/abs/2012.10504
Core Claim
CityLearn is a configurable Gymnasium environment for building energy coordination, load shaping, and demand response. It is useful to this wiki because it exposes multivariate building-energy observations, exogenous context, continuous control inputs, and rewards or costs in a non-vision domain.
Dataset Notes
- CityLearn models a virtual district composed of building energy models and distributed energy resources.
- Flat CSV files provide action-agnostic observations such as calendar values, building loads, weather, carbon intensity, and electricity pricing.
- Other observations are computed during simulation, including storage state of charge, net electricity consumption, device efficiencies, and dynamic indoor temperature in supported versions.
- A schema controls the simulation window, episode splitting, time resolution, active observations, and active actions.
Action-Time-Series Notes
CityLearn has a clean control-input interface. The current documentation describes real-valued actions in [-1, 1] for storage charge/discharge or device power fractions. Named channels include cooling, heating, domestic-hot-water, and electrical storage, plus cooling and heating device controls.
For action-conditioned world-model work, the strongest use is to generate trajectories under fixed policies or candidate controllers:
building/district observations + weather/pricing/context + action_t
-> next building/district observations + reward/costGotchas
- CityLearn is not a single immutable dataset payload; it is an environment and dataset schema.
- Dynamics and available controls can depend on the schema and CityLearn version.
- Source CSVs can be simulated, measured, or precomputed depending on how a dataset is constructed.
- Repository code is MIT-licensed, but externally supplied building, weather, pricing, or carbon-intensity files should be checked before reuse.
Foundation TSFM Relevance
| Agenda slot | Verdict | Evidence | Missing pieces |
|---|---|---|---|
| Causal structure, counterfactuals, and control | partially closes | Provides explicit continuous control inputs for building energy storage and devices, with simulator transitions and reward/cost functions. | Needs pinned benchmark protocols and versioned schemas before comparing general TSFM-style action-conditioned models. |
| Context interface: channel context and general context | partially closes | Schema and CSV files expose building metadata, weather, pricing, carbon intensity, and active observation/action definitions. | Needs a reusable typed context schema across energy, industrial, and operations datasets. |
| Time representation and irregular event streams | adjacent | Uses explicit simulation time steps, episode ranges, and forecasted exogenous variables. | Mostly regular simulation time; not a stress test for irregular event streams. |
| Benchmarks: what level of modeling is tested? | adjacent | Standardizes controller evaluation for building demand response and district coordination. | Benchmark target is control performance, not a foundation time-series model suite with broad cross-domain transfer. |