Glossary
The terms below have one meaning throughout the documentation. Where the code uses a word in more than one sense, the entry says which sense each name carries.
- Agent
- Controller
The policy that chooses actions at each control step. CityLearn ships rule-based controllers (Business as usual, Reference controllers) and reinforcement-learning agents; Custom agents and rewards shows how to write your own.
- Baseline
In KPI names,
baselinealways means the conventional counterfactual: the same buildings without storage (and without partial-load control for buildings with LSTM dynamics), PV retained, computed from the simulator’s own series without another rollout. It is selected by thebaseline_conditionofevaluate_v2(). It is not the Business as usual controller. Two class names also contain the word:BaselineAgentis a passive controller that disables every active action (no control), andZeroActionBaselineAgentrequests zero for every action. The rule-based policies are called Reference controllers, not baselines. In Demand response settlement, the request’s baseline is its pre-event reference power.- Business as usual
- BAU
The operational reference controller,
citylearn.agents.baseline.BusinessAsUsualAgent. It charges connected EVs at full power until 100% SOC by default, starts flexible appliances as soon as they are ready and uses stationary batteries for PV self-consumption.evaluate_v2()runs it on the same scenario and window and reports it in the*_business_as_usual_*KPIs. See Baselines.- Community
- District
The set of buildings simulated together, which share a grid connection and, when enabled, a local market. District KPIs (
level == 'district') describe the community as a whole.- Dataset
A folder with a
schema.jsonand the data files it names: building loads, weather, prices, carbon intensity, EV schedules and events. Public datasets are resolved by name and downloaded on first use; the Dataset catalogue lists them.- Deferrable appliance
A flexible load, such as a washing machine, whose cycle must run once between its earliest start and its deadline. The controller chooses when it starts.
- Demand response
Requests from a grid operator to change the community’s power during an activation window, with a direction, a target power, a payment and a shortfall penalty. Delivery is measured against the mean power before the event. See Features and configuration.
- Dynamic topology
topology_mode='dynamic': members and assets join or leave the community during the episode, following the schema’stopology_events. Requires the Entity interface.- Electrical service
The total and per-phase import and export limits of the community’s connections, and the KPIs that measure violations of them.
- Episode
The run from
reset()until the environment terminates. An episode of N time steps (states) executes N - 1 control steps, because its last state is only the observation after the last action: the 24 hourly states of a day give 23 transitions.episode_time_steps=25covers a whole day of hourly data.- Episode split
How a long time window is divided into episodes: consecutive episodes (the default), rolling episodes that start at every time step, random episodes, or an explicit list of
(start, end)windows. Consecutive episodes share their boundary row, so every interval is simulated once.- EV departure service
Whether an EV leaves with at least its minimum acceptable charge. Target accuracy, a separate KPI, measures how close the departure SOC is to the requested SOC in both directions.
- Evaluation condition
Which series of a building
evaluate_v2()reads: with or without storage, partial load and PV. The defaults evaluate the simulated run as the control and the Baseline as the reference.- Flat interface
- Entity interface
The two observation and action contracts. The flat interface exchanges one vector per agent; the entity interface exchanges tables of buildings, chargers, EVs and other assets with their relations. See Flat and Entity Interfaces.
- KPI
- Key performance indicator
A number that describes a completed simulation, such as cost, imported energy or EV service.
evaluate_v2()returns one row per KPI and scope; the KPI name (cost_functioncolumn) readslevel_family_subfamily_metric_variant_unit. See KPIs.- Member
A building of the Community. With dynamic topology, members can join and leave during an episode.
- Physics version
The version of the device and building physics a run uses:
2(default) or1, the physics of CityLearn 3.6.0. See Moving an existing project to CityLearn v3.- Portfolio
Several communities run in step by
MultiCommunityEnv; portfolio KPIs aggregate them. See Multi-Community Reference.- Reference controllers
The rule-based policies
RBCBasicPolicy,RBCSmartPolicyandRBCCommunityPolicyincitylearn.agents.baseline, used as comparison points for new controllers. See Baselines.- Scenario
One configuration of a Dataset: the schema plus the constructor arguments, such as the time window, services, physics version and random seed. Results are comparable only between runs of the same scenario.
- Schema
The JSON file that describes a Dataset: its buildings and assets, observations, actions, reward, time window and enabled services. Constructor arguments of
CityLearnEnvoverride the matching schema keys. See Schema Reference.- Scorecard
The default selection of KPIs for comparing controllers, returned by
env.scorecard(). See How to read the scorecard.- Time step
One row of the dataset, and one simulated interval of
seconds_per_time_stepseconds. Energy series are in kWh per time step: at a 15-minute step, 1 kW for one step is 0.25 kWh.