CityLearn v3: A Configurable Simulation and Evaluation Framework for Realistic Control Studies of Renewable Energy Communities

Tiago Fonseca; Luis Lino Ferreira; Armando Sousa; Ava Mohammadi; Zoltan Nagy

cs.MASep 18, 2026

CityLearn v3: A Configurable Simulation and Evaluation Framework for Realistic Control Studies of Renewable Energy Communities

Authors: Tiago Fonseca, Luis Lino Ferreira, Armando Sousa, Ava Mohammadi, Zoltan Nagy

Organizations: INESC TEC / Polytechnic of Porto - School of Engineering, Porto, Portugal · FEUP - Faculty of Engineering, University of Porto / INESC TEC, Porto, Portugal · Department of the Built Environment, Building Services, Eindhoven University of Technology, Eindhoven, the Netherlands

Abstract

Renewable energy communities (RECs) coordinate buildings, photovoltaic generation, batteries, electric vehicles and flexible loads. Controller studies often simplify changing participation, equipment availability, service deadlines and data quality, so lower cost or peak demand can conceal missed services or infeasible power requests. This paper presents CityLearn v3, a configurable simulation and evaluation framework for REC control studies under these conditions. It represents changing members and assets, flexible-load deadlines, demand-response requests, local energy sharing, and data or equipment failures within one simulation environment. Building and phase power limits constrain controllable requests, while a declared timestep preserves consistent power-to-energy accounting. The framework records controller inputs and distinguishes requested actions from those applied to the simulated equipment. Reference controllers, service- and constraint-aware performance indicators, and trajectory exports support comparisons within and across communities. Software checks and application examples examine service delivery, electrical constraints, settlement and changing scenarios; a synthetic high-frequency trace replay illustrates how aggregation can conceal short peaks without changing annual energy. Together, these records allow aggregate performance to be interpreted alongside service failures, action reductions and participant-level outcomes.

Figures & tables

Platform	Primary purpose	Control-study interface	Community and service scope
EnergyPlus and Modelica Buildings ( Crawley et al. 2001 ; Wetter et al. 2014 )	Detailed building, HVAC and district-energy physics	Control interfaces and component models are available; the experiment protocol is assembled by the user	Community membership, local settlement and common controller-evaluation semantics are study-specific
BOPTEST ( Blum et al. 2021 )	Repeatable benchmarking of building control using high-fidelity emulators	Standard API, test cases, baseline control and KPIs	Centred on building and HVAC control; REC services and community electrical constraints require additional modelling
HELICS and mosaik ( Hardy et al. 2024 ; Steinbrink et al. 2019 )	Synchronization and data exchange across heterogeneous simulators	Coordinates user-supplied models and controllers; evaluation logic is defined by the federation or scenario	Can support multi-domain REC studies, but REC, service and audit semantics are supplied by the coupled components
CityLearn v2 ( Nweye et al. 2025 )	Data-driven district control benchmarking	Common Gym-compatible loop with reference and learning controllers and shared KPIs	Integrated buildings, distributed energy resources and EV studies within a shared district-control benchmark

Table 1: Base capabilities of selected simulation and control-benchmarking platforms.

ID	REC requirement	Real example	How CityLearn v3 represents it
D1	Multiple communities	A project may study several communities but must retain the result of each one.	Synchronized community simulations with local and combined results.
D2	Demand-response requests	A grid operator requests a power change during a stated time window.	Time-stamped interval DR specifications, delivered response, shortfall and payment.
D3	Local energy sharing and settlement	PV surplus can meet another member’s demand and change both members’ costs.	Participant-level local import, local export, and settlement with the grid and community.
D4	Changing community members and assets	A household joins, a charger is installed or a PV system is removed during the study.	Member and equipment changes that update controller inputs, actions and results.
D5	Flexible-load schedules and deadlines	An appliance or process may start operation later, but must complete before a deadline.	Cycle profiles, allowed start windows, deadlines and service indicators.
D6	Data and equipment failures	A meter value is missing, a forecast is biased, a command is lost or a battery is unavailable.	Repeatable changes to measurements, forecasts, commands and equipment availability.

Table 2: Requirements for realistic REC scenarios.

ID	Evaluation requirement	Why it matters	How CityLearn v3 addresses it
S1	Controller inputs and applied actions	The user must know what the controller received, requested and actually caused.	Structured observations with persistent identities, availability masks, feasible action ranges and separate requested/applied actions.
S2	Performance indicators and result exports	One reward or aggregate curve can hide service failures and local outcomes.	Extended KPIs with energy, cost, emissions, service and constraint indicators with time-series and comparison exports.
S3	Reference controllers and fair comparisons	A normalized result is meaningful only when the comparison case uses the same given configuration and accounting rules.	Business-as-usual (BAU) and rule-based reference controllers evaluated in the same scenario.
S4	Software validation	More scenario rules create more opportunities for plausible but incorrect results.	Regression tests, physical checks, interface checks, indicator-consistency checks and saved evidence.
S5	Computational cost	High-frequency data, structured inputs and several communities can slow repeated controller studies.	Measurements of run time, memory usage, data export time, data format.

Table 3: Requirements for fair and reproducible controller comparisons.

Figure 1: How CityLearn v3 represents one or more renewable energy communities.

Panel of Figure 2 — Figure 2: Flexible-load start window, deadline and energy cycle.

Figure 3: Timeline of data and equipment failures in the controller loop.

Panel of Figure 4 — Figure 4: Main choices in a CityLearn v3 experiment. The selected dataset provides initial settings; the user configures assets, services, constraints and control before running the study and comparing its results.

Family	Example metrics	Why it matters
Energy and power limits	grid import/export, net exchange, peak, ramping, load factor, building/phase-limit exceedance	Retains district-control indicators and shows requests outside configured power limits.
Cost and settlement	energy cost, local settlement, comparison cost, savings, demand-response payments and penalties	Separates energy cost, local energy sharing and demand-response payments.
Emissions	emissions totals, daily averages and ratios to the reference controller	Keeps environmental performance visible alongside cost and service.
PV and local energy sharing	PV generation/export, self-consumption, local import/export, shared energy and sharing ratios	Shows local energy sharing instead of hiding it in aggregate net load.
EV service	departure counts, target/minimum/tolerance success, SOC deficit/surplus, charged and V2G energy	Distinguishes grid flexibility from mobility-service failure.
Flexible-load service	completed/missed cycles, service level, served/unserved energy and start delay	Evaluates flexible demand as a service with a deadline.

Table 4: Performance-indicator families in CityLearn v3.

Figure 5: Time-series and KPI comparison views in the CityLearn UI.

Policy class	What it represents	Interpretation in REC studies
NormalNoBatteryPolicy	Day-to-day operation for EVs and flexible loads without stationary battery control.	Separates native service demand from the value of stationary storage.
NormalPolicy	BAU operation with the same native service logic plus simple PV self-consumption storage.	Serves as the main reference line for annual scorecards and normalized KPI interpretation.
RBCBasicPolicy	Service-aware rule-based control with simple price response.	Checks whether a transparent controller can improve cost or import while tracking EV targets more precisely than normal charging.
RBCSmartPolicy	Solar-, price- and peak-aware rule-based control.	Provides a stronger internal RBC reference for grid, carbon and service KPIs.
RBCCommunityPolicy	REC-aware rule-based control using community surplus and import context.	Tests whether local sharing and settlement objectives can be inspected separately from grid and carbon outcomes.

Table 5: Reference controllers used in the CityLearn v3 evaluation workflow.

Check	Protected failure mode	Current evidence
Full regression suite	General simulator behaviour and compatibility with existing CityLearn tests.	423 passed tests; 18 warnings.
Targeted REC requirements	KPI exports, demand-response requests, data and equipment failures, structured controller inputs, changing community members and assets, and runs with multiple communities.	103 passed tests; 8 warnings.
Physics and time-unit audit	Energy/power consistency when the same scenario is evaluated at 60, 300, 900 and 3600 s timesteps.	16/16 scenarios passed.
Controller-input and change audit	Persistent member/equipment identities, relations, action rows and configuration versions when equipment or members change.	Strict pass.
BAU/KPI sanity audit	Reference-controller rows, duplicated KPI keys, finite KPI values and delta-to-BAU identities in controller exports.	3317 rows per export, 1401 BAU-derived rows and no duplicate KPI keys.
Thermal/HVAC compatibility tests	Inherited thermal and heat-pump behaviour alongside the new REC capabilities.	12 passed tests.

Table 6: Software validation checks used in this manuscript revision.

Check	Compared cases	Observed change	Interpretation
Basic structured input	Matched building/phase-limit run, flat input versus the basic structured input.	5.30 to 5.51 ms/step; about +0.21 ms/step or +4.1%.	Persistent identities, relations, masks and action feedback are available with measured but small basic overhead.
High-frequency storage	Two 15 s CSV/Parquet pairs: power limits and changing community members and assets.	2.446 GB to 12.405 MB and 2.619 GB to 12.740 MB; initialization falls from 25.37 to 15.61 s and from 28.59 to 18.92 s.	Parquet makes both datasets about 200 times smaller and reduces initialization time by 34–38%; post-load step time remains similar.
Structured-input size	Flat input versus the most detailed standard structured input.	4.88 to 10.18 ms/step; 165 flat values to 2538 table values and 302 feature names.	Step time approximately doubles while the exposed input payload becomes more than 15 times larger.
Multiple communities	One, two and four synchronized communities in the heterogeneous run.	5.02, 7.08 and 11.41 ms/step; four communities export 5227 KPI rows, including 107 combined rows.	Four synchronized communities require 2.27 times the single-community step time while retaining local and combined outcomes.

Table 7: Computational-cost evidence.

Example	Study question	Scenario/controller	Reported outcome
Reference controllers	Can BAU and transparent reference controllers be interpreted with the expanded KPI families on a full annual REC/EV scenario?	8760-step hourly REC scenario with EVs, flexible loads, local energy sharing and building/phase power limits; legacy EV-RBC, BAU and rule-based controllers.	The scorecard compares energy, cost, EV and flexible-load service, settlement and requested power-limit exceedances.
Time resolution and energy units	Can the same energy trace imply different visible power peaks at different time resolutions?	One synthetic annual 15 s REC trace viewed at 1 h, 15 min and 15 s; all views are derived from the same physical signal.	Equal annual energy can produce different visible peaks, so the declared timestep matters for capacity-sensitive studies.
Local energy sharing and settlement	Does local settlement change the annual economic interpretation of a community-aware controller?	Full-year RBCCommunityPolicy ; grid-only comparison versus configured local settlement for the same trajectory.	Local exchange changes final cost and member outcomes and cannot be inferred from district net load alone.
Demand-response requests	Can a time-window request be translated into delivery and settlement evidence?	180-step scenario with three non-overlapping requests; one evening request shown against operation without a request.	Request-level results expose requested energy, credited response, shortfall and payment.
Changing community members and assets	Do time-stamped changes propagate to controller inputs, actions and results?	One run in which a member, chargers and PV equipment are added or removed; detailed structured-input results are archived.	Member/equipment counts and controller rows change together while identities remain traceable.
Data and equipment failures	Do repeatable failures change the controller trajectory and appear in the results?	Same controller and period in a clean run and a run with declared measurement, forecast, command and equipment failures.	Declared failures produce identifiable changes in controller inputs, applied actions and exported results.

Table 8: Application-example protocol used in this manuscript.

Figure 6: Annual REC/EV controller scorecard normalized to the CityLearn v3 BAU reference.

Figure 7: EV charging requests over 24 h and the corresponding timestep-boundary SOC states for one charger.

Figure 8: High-frequency peak visibility from one synthetic 15 s trace.

Figure 9: Full-year REC settlement accounting for the same RBCCommunityPolicy trajectory.

Case	Requested	Delivered	Shortfall	Compliance	Net DR revenue	Cost after settlement
	kWh	kWh	kWh	ratio	EUR	EUR
Reference operation	190.0	82.5	101.1	0.43	-100.2	863.6
Event-aware dispatch	190.0	300.9	51.6	0.70	-16.0	790.6

Table 9: Combined demand-response results for the three-request scenario.

Figure 10: Selected demand-response request and settlement opportunity.

Figure 11: Counts of changing community members and assets.

Figure 12: Data and equipment failures in the example scenario.

Figure 13: Missing measurements and biased forecasts.

Figure 14: Inter-community sharing opportunity under independent local control.

Appendix figures & tables5 assets

Supplementary material from the paper’s appendix.

Appendix

Scenario	Temporal scope	Equipment represented	Changing conditions	Paper role
Base REC	$3600\text{\,}\mathrm{s}$ ; 48-step KPI check, 600-step runtime check and full-year reference-controller scorecard	Buildings, PV, batteries, EV chargers and flexible loads	none	BAU/KPI checks and the annual controller scorecard.
EV departure target	$3600\text{\,}\mathrm{s}$ ; scorecard service result	EVs, chargers, PV, batteries and buildings	none	Checks strict target, tolerance and minimum-feasible EV departure indicators.
Flexible-load schedules and deadlines	$3600\text{\,}\mathrm{s}$ ; scorecard service result	Buildings and flexible appliances	Start windows and deadlines	Checks completed/missed cycles and flexible-load service indicators.
Demand-response requests	$3600\text{\,}\mathrm{s}$ ; 48-step KPI check and 180-step application experiment	Buildings, PV, batteries and EV chargers	Demand-response request file	Checks request, delivery, shortfall and settlement indicators.
Data and equipment failures	$3600\text{\,}\mathrm{s}$ ; 48-step KPI check and hourly-week application experiment	Buildings, PV, batteries and EV chargers	Data and equipment failure file ( robustness internally)	Checks measurement, forecast, command and equipment-availability failures.
Changing community members and assets	60, 300, 900 and $3600\text{\,}\mathrm{s}$ ; 160-step audits, plus an hourly application with changes at steps 1000–1600	Buildings, chargers, PV, batteries and flexible loads	Member and equipment changes	Checks identities, active periods, controller inputs and result windows.

Appendix

Table 10: Software-validation configurations and application-evidence scenarios.

ID and requirement	Scenario declaration	Linked file or record fields and supported values
D1 Multiple communities	MultiCommunityEnv receives communities ; each entry contains community_id , schema , optional env_kwargs and optional weight . Wrapper output uses optional render_directory and render_session_name .	community_id is unique; weight is finite and non-negative, with at least one positive weight. Child scenarios must use matching seconds_per_time_step , episode length, interface and central-agent settings.
D2 Demand-response requests	Top-level demand_response : enabled , requests_file , baseline_method , baseline_window_seconds and allow_overlapping_requests . The current baseline mode is rolling_pre_event_average ; overlapping requests are not currently supported.	Request-file columns: request_id , issuer , direction , start_time_step , end_time_step , target_power_kw , activation_price_eur_per_kwh , shortfall_penalty_eur_per_kwh and optional tolerance_power_kw . Issuer is dso or tso ; direction is up or down .
D3 Local energy sharing and settlement	Top-level community_market : enabled , local_price_ratio_to_grid_import , optional import_member_weights , kpis.community_local_traded_enabled and kpis.community_self_consumption_enabled .	The price ratio is clipped to $[0,1]$ ; intra_community_sell_ratio is accepted as a legacy alias. Residual grid export is recorded but has zero remuneration in the current implementation; it has no active configurable settlement price.
D4 Changing community members and assets	Top-level topology_mode and topology_events . Dynamic changes require topology_mode=dynamic and the entity controller interface.	Event fields: id , time_step , operation , target_member_id , target_asset_type , target_asset_id , optional source_member_id , source_asset_id and overrides . Operations are add_member , remove_member , add_asset and remove_asset ; asset types are charger , deferrable_appliance , pv and electrical_storage .
D5 Flexible-load schedules and deadlines	Under buildings.<id>.deferrable_appliances.<id> : cycle_profiles_file , flexibility_schedule_file and optional attributes.trigger_threshold .	Cycle-profile columns: profile_id , duration_steps , total_energy_kwh , load_profile . Schedule columns: cycle_id , profile_id , earliest_start_time_step , latest_start_time_step , deadline_time_step , priority , must_run . The must_run field is the mandatory-service flag described in the main text.
D6 Data and equipment failures	Top-level data and equipment failure block ( robustness internally): enabled , events_file , random_seed , missing_replacement_value and modules.<observations\|forecasts\|actions\|assets>.enabled .	Event-file columns: event_id , module , target_type , target_id , target_feature , start_time_step , end_time_step , mode , with optional value , std , min_value , max_value , replacement_value and delay_steps . Modes depend on the channel: missing/noise/bias/stuck/clip for measurements and forecasts; dropout/noise/bias/stuck/delay/clip for commands; unavailable for equipment.

Appendix

Table 11: Exact configuration reference for the eight REC requirements in Section 3.

Item	Main fields or files	Purpose
EV service	EV connection and departure schedules, charger power limits, V2G availability, target/minimum state of charge and departure-service fields	Preserves mobility requirements next to grid objectives so a low cost or peak does not hide a missed departure target.
Controller inputs and applied actions	interface , structured-input sets, action masks and action feedback	Defines what the controller receives and keeps requested and applied actions separate.
Performance indicators and result exports	KPI/export settings, output fields and CSV or Parquet result format	Defines the indicators, trajectories and diagnostics retained for comparison and audit.

Appendix

Table 12: Related service and evaluation configuration.

Family	KPI	Definition / rationale	Unit
Energy and power limits	Net electricity consumption	$E^{\mathrm{net}}_{b,t}$ or $E^{\mathrm{net}}_{\mathcal{C},t}$ after equipment operation and local accounting.	kWh/step
Energy and power limits	Net-boundary grid import	$\sum_{t}\max(E^{\mathrm{grid}}_{t},0)$ for signed energy at the stated boundary; distinguish this from summed member imports.	kWh
Energy and power limits	Net-boundary grid export	$\sum_{t}\max(-E^{\mathrm{grid}}_{t},0)$ at the same boundary; distinguish this from summed member exports.	kWh
Energy and power limits	Net grid energy	Grid import minus grid export.	kWh
Energy and power limits	Average daily peak	Mean of daily maximum net import power.	kW
Energy and power limits	Peak import	Maximum net grid import power over the evaluation window.	kW

Appendix

Table 13: Expanded KPI catalogue for CityLearn v3.

Area	Scope	Role in the paper
Mobility and flexible services	EVs, chargers and appliance cycles	Represents charging obligations and flexible service windows.
Core simulation	Buildings, storage, PV, control loop, established KPIs and datasets	Provides the simulation basis for the REC requirements in Section 2 .
Software distribution	Official CityLearn repository and versioned releases	Distributes the simulator and its public examples.
Control loop and physical corrections	Terminal states, action parsing, SOC, storage and high-frequency timestep handling	Supports explicit scenarios and comparable controller studies.
Performance indicators and exports	Runtime, loading, export and KPI separation	Supports auditable KPI calculation and result inspection.
Structured inputs and changing members/assets	Identified controller inputs and changing active periods	Supports structured control and changing community members and assets.

Appendix

Table 14: Implementation areas supporting the scenario and evaluation capabilities.

Power Systems

Power systems research studies the planning, operation, control, and protection of electrical grids and their integration with energy resources.

See all 230 papers

EnergyBridge: Benchmarking Household Energy Management, User Participation, and Grid Flexibility
Aug 9, 2026Xudong Wu, Zeqing Wu, Jiarui Zhang +8Human-in-the-Loop Evaluation Building Energy Management
1The University of Hong Kong · 2Tianjin University · 3Beihang University
A Network-Aware Evaluation of Distributed Energy Resource Control in Smart Distribution Systems
Apr 21, 2026Houchao GanDistributed Optimization Feedback Control
Department of Computer Science City University of New York
Bridging Natural Language and Microgrid Dynamics: A Context-Aware Simulator and Dataset
Apr 7, 2026Tinko Sebastian Bartels, Ruixiang Wu, Xinyu Lu +5Power Systems Digital Twins
School of Data Science, The Chinese University of Hong Kong-Shenzhen, Shenzhen, China. · Department of Mechanical and Automation Engineering, The Chinese University of Hong Kong, Hong Kong, China.

Aug 9, 2026J/K move · Enter open · S save

EnergyBridge: Benchmarking Household Energy Management, User Participation, and Grid Flexibility

Xudong Wu, Zeqing Wu, Jiarui Zhang, Xuhao Fan+7

1The University of Hong Kong · 2Tianjin University · 3Beihang University

Human-in-the-Loop Evaluation Building Energy Management Demand Response User Simulation

Open paper AskPDF arXiv

Residential virtual power plants (VPPs) can provide grid flexibility by shifting household demand, but physical flexibility becomes dependable capacity only when residents authorize a plan and the promised response is delivered. Existing benchmarks evaluate control but omit event-specific authorization. We present EnergyBridge, a benchmark and agent framework connecting capacity reporting, household authorization, and physical execution. It combines region-specific EnergyPlus environments for Tianjin and Berlin with an LLM-based User Participation Simulator. Against 584 persona- and event-matched human role-play judgments, the LLM-based User Participation Simulator preserves method ordering with a 5.3-point mean absolute acceptance error. Across conventional controllers and agent baselines, EnergyBridge achieves the highest simulated authorization, lowest event-window energy, and the most reliable capacity commitment in both regions. We release human data and codes for reproducible human-centered grid-flexibility research: https://github.com/Agentic-Intelligence-Lab/EnergyBridge.

Abstract

Power Systems

Explore similar work

EnergyBridge: Benchmarking Household Energy Management, User Participation, and Grid Flexibility

A Network-Aware Evaluation of Distributed Energy Resource Control in Smart Distribution Systems

Bridging Natural Language and Microgrid Dynamics: A Context-Aware Simulator and Dataset