# CityLearn Canonical source: Official documentation: Official code: Introducing source: Wiki source: [CityLearn](../../wiki/sources/citylearn-2020.md) ## Dataset Type CityLearn is a Gymnasium reinforcement-learning environment and dataset schema for building energy coordination, load shaping, and demand response. It should be treated as a configurable simulator-backed benchmark rather than one fixed static dataset payload. ## System Structure CityLearn models a virtual district composed of building energy models and distributed energy resources such as heat pumps, electric heaters, storage tanks, batteries, and photovoltaic generation. Building, weather, carbon-intensity, pricing, and schema files define the simulation environment and provide action-agnostic observations. ## Temporal Structure The schema defines simulation start/end, episode splits, and `seconds_per_time_step`. Flat CSV time-series files provide calendar, building, weather, carbon-intensity, and pricing variables. Runtime observations such as storage state of charge, net electricity consumption, device efficiencies, supplied thermal demand, and dynamic indoor dry-bulb temperature are computed during simulation. ## Actions Or Interventions The current documentation defines actions as continuous real values in `[-1.0, 1.0]` that prescribe storage charge/discharge or device power fractions. Named action channels include `cooling_storage`, `heating_storage`, `dhw_storage`, `electrical_storage`, `cooling_device`, and `heating_device`. These are clean control inputs for action-conditioned dynamics, but the exact available action set depends on the schema and CityLearn version. ## Inputs And Outputs Inputs include calendar variables, weather variables and forecasts, district carbon intensity, electricity pricing, building end-use loads, solar generation, occupancy, comfort variables, storage states, and device states. Outputs are environment transitions, rewards/costs, KPIs, and simulation records for building-level and district-level control. ## Suitability Note CityLearn is a strong non-vision action-conditioned environment for world-model experiments because it exposes multivariate building-energy observations, continuous control inputs, exogenous weather/pricing context, and reward or cost functions. It is strongest when used to generate trajectories under explicit policies or candidate controllers. It is weaker as a static "dataset" because source data and dynamics are schema/version dependent. ## Access And License Notes The 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. This knowledge base records metadata only and does not mirror CityLearn datasets or simulation outputs.