This documentation is built from the development branch, master. It includes the changes listed under Unreleased, which the latest release, CityLearn 3.6.0, does not have. To read the documentation of the version you installed (pip show citylearn), open the docs folder at its tag on GitHub, for example v3.6.0.

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, baseline always 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 the baseline_condition of evaluate_v2(). It is not the Business as usual controller. Two class names also contain the word: BaselineAgent is a passive controller that disables every active action (no control), and ZeroActionBaselineAgent requests 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.json and 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’s topology_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=25 covers 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_function column) reads level_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) or 1, 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, RBCSmartPolicy and RBCCommunityPolicy in citylearn.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 CityLearnEnv override 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_step seconds. Energy series are in kWh per time step: at a 15-minute step, 1 kW for one step is 0.25 kWh.