Repository navigation
What's new
3.6.0 collects 26 pull requests: corrections to the physics, KPIs, baselines, agents, data loading and exports, faster simulation steps, three opt-in features, and a Python 3.10 floor with a wider CI. Results change only where a fix applies; the migration guide lists which runs to repeat.
Fixes
Physics and KPIs:
- Power and energy at sub-hourly steps. Several limits compared a power in kW with an energy per step in kWh, which only coincide at 3600 s.
available_nominal_poweris now a power at every step length; heat pumps and electric heaters no longer exceednominal_powerwhen they charge thermal storage; on native sub-hourly data a device delivers at mostnominal_powerx step duration per step; during an outage, the local supply passed to devices and to the non-shiftable load is converted to power and to dataset resolution; and thecooling_demand,heating_demandanddhw_demandobservations convert the storage discharge to dataset resolution whentime_step_ratiois not 1. (#185) - Undersized devices. A device that cannot meet its demand no longer raises
AssertionError: demand is greater than ..._device max output. Its output is clipped, aRuntimeWarningis issued once per device and episode, and the shortfall is reported as unserved thermal service energy. (#185) - Base-power estimate. The estimate behind electrical-service headroom and the feasibility KPIs no longer subtracts thermal storage discharge twice, and it counts escalator power, including a requested escalator state in the step it is requested. (#185)
- Clip reasons.
clip_reason_phase_headroomandclip_reason_export_headroomname only the asset's own phases and the clipped direction. (#185) - Normalized observations.
observations(normalize=True, periodic_normalization=False)no longer raisesKeyError: 'month'. (#185) - Occupant set-point hold.
set_point_hold_time_stepsin a building schema now reachesLogisticRegressionOccupantInteractionBuilding. On the Quebec neighbourhood datasets (4 steps), occupant set-point changes revert to the schedule after 4 steps without interaction instead of holding for the rest of the episode. (#185) - Dynamic topology district baseline. The district reference series summed only the members active at evaluation time, while the control series keep every member's past consumption, so a departed member counted on the control side only. With all-zero actions on
citylearn_three_phase_dynamic_topology_demo(24 steps,Building_6leaving at step 12), the district import delta to baseline was 12.76 kWh, the export delta -11.00 kWh and the emissions delta 4.44 kg, although control and baseline coincide; they are now below 4e-6, the float32 rounding of the reference series. The reference series now sum every member that has been active, each over the steps at which it was a member. (#182) - Electrical-service histories across topology events. A member's requested-pressure, total-power and per-phase power histories were erased when it rejoined or when one of its assets changed, and the electrical-service and phase KPIs lost the earlier steps. They are now kept. (#182)
- Robustness noise. With
noise_std > 0, Gaussian noise could make solar generation, solar irradiance and carbon intensity negative, add generation at night and push outdoor relative humidity outside [0, 100] %. One rule now bounds the noisy values: solar quantities stay>= 0and get no noise at night, humidity stays within [0, 100] % and carbon intensity stays>= 0. The noise draws are unchanged, so values within range are bit-identical. Solar generation noise uses the generation series for its shape instead of the indoor temperature series; both have the same length, so the draws are the same. Runs withnoise_std = 0, including all bundled datasets, are unchanged. See the migration guide. (#204) - Battery discharge features during outages. During a power outage the entity
storagetable reportedcan_discharge = 0andavailable_discharge_power_kw = 0, although the battery can discharge into the islanded building up to its local load (#220). These features now report the battery's discharge capacity without the grid export headroom, as #205 does for vehicle-to-building discharge; the simulator still limits the discharge to the local load. The rule-based baselines readcan_discharge, so they now use the battery during outages. In the week with the most outages ofpt_rec_30/evaluation/rec_30_robustness.jsonandrec_30_combined.json, the BAU discharges 1.2 kWh more and the normalized unserved energy during outages falls from 0.0015 to 0.0007 and from 0.0017 to 0.0008; cost and emissions are unchanged. Inpt_rec_100/evaluation/rec_100_allin.jsonthe observations change but the BAU KPIs of that week do not. Datasets without outages, and the flat interface, are unchanged. See the migration guide. This closes #220. (#221)
Baselines:
- Baselines without the
entity_core_electricalbundle. Two changes apply only to datasets whose schema does not enable that bundle;pt_rec_*andcitylearn_challenge_2022_phase_all_plus_evsenable it and are unchanged. First, the BAU battery reserved the charger's nominal power for a connected EV even when the EV accepted much less, for example in the last step before 100% SOC, and discharged for that demand; it now reserves the power the EV can accept, estimated from the observed SOC, battery capacity, charger power and efficiency as the simulator computesavailable_charge_power_kw(#190). Second, every baseline took the last interval's export as PV surplus, so when a battery discharge overshot the load and was exported, the battery recharged from the grid in the next step (22.8 kWh in the first 48 hours ofcitylearn_three_phase_electrical_service_demowith the BAU); only PV above the observed load now counts as surplus. The definition versions becomeimmediate-full-charge-v3,immediate-user-target-v2,basic-v3,smart-local-v3andcommunity-v3. Over 30 days, the control cost changes by −0.2% to −2.4% and the emissions by −0.8% to −2.5% for every baseline oncitylearn_challenge_2022_phase_all,citylearn_challenge_2023_phase_2_local_evaluationandcitylearn_three_phase_electrical_service_demo, except the default BAU on the last one, which costs 0.4% more because its battery now stores PV that previously went to the community market. See the migration guide. The first change addresses consequence 2 of #190; consequence 1, the one-step battery lag, is unchanged, and #190 stays open. (#213) - Baselines read corrupted observations under the flat interface. Under the flat interface the env corrupts only the flat vectors, and the baselines, which read entity observations, decided from uncorrupted values; under the entity interface they read the corrupted ones (#192). Run as controllers (
predict(observations)), they now get the step's robustness observation events applied to their entity observations as the entity interface applies them, and take the same actions under both interfaces. No random stream is consumed, and the env's flat observations and robustness history are unchanged; the controller KPIs of flat runs with observation events can change. The native BAU reference ofevaluate_v2()(predict([])) stays uncorrupted. See the migration guide. (#212)
Agents and wrappers (#208):
TabularQLearningno longer bootstraps from the next state on terminal transitions.MARLISARBCexplores with its RBC; it used to explore with random actions.MARLISAwithpca_compression < 1sizes its networks to the PCA output instead of failing at the first update.- Discrete wrappers.
TabularQLearningObservationWrapperdeclares exactly theprod(bins)states it encodes (it declaredprod(bins + 1) - 1and could encode a state outside the space), andDiscreteObservationWrapperkeeps values above the observation space in the top bin.DiscreteObservationWrapperandDiscreteActionWrapperbin the spaces of the env they wrap, so they work over the normalized wrappers.ClippedObservationWrapperno longer modifies the environment's cached observations. OnehotEncodingraisesValueErrorfor a value outside its classes.
Data loading (#209):
- Charger files with blank or float states. Charger states are parsed as numbers. A blank cell used to make every state of the charger unreadable, so no EV connected.
InventoryBatteryEVs load withoutnominal_power, which the battery derives frommax_charge_kwandmax_discharge_kw.- Random initial EV SOC is drawn within the battery's declared
min_socandmax_soc; anInventoryBatteryused to fail when the draw from [0, 1] fell outside them. - Entity observations with
max_soc < 1reportsoc_max_ratio, the energy to full and the available charge power up tomax_socinstead of a full battery.
Datasets and dataset cache:
- Incomplete dataset caches. A cached dataset counted as complete as soon as its
schema.jsonexisted, so a cache left by an interrupted download raisedFileNotFoundErrorfor its first missing file. A cache is now complete only when every input file thatCityLearnEnvreads from the schema exists; an incomplete cache is replaced in one step, and offline mode names the missing files (#176, #181). - Dataset environment variables.
CITYLEARN_OFFLINE,CITYLEARN_DATASET_GITHUB_ACCOUNT,CITYLEARN_DATASET_REPOSITORYandCITYLEARN_DATASET_TAGare read whenCityLearnEnvorDataSetis created instead of once at import, andCityLearnEnv(offline=None)honoursCITYLEARN_OFFLINE(#198). - Dataset names.
DataSet.get_dataset_names()keeps a dataset whose name occurs in its parent path and accepts adatasets_pathwith a trailing slash; concurrent first calls list GitHub once and write the cached list atomically. The misc files share the dataset cache code (#199). - 15 s Parquet datasets load from the dataset cache. The schemas of
citylearn_three_phase_electrical_service_demo_15s_parquet,citylearn_three_phase_dynamic_asset_changes_demo_15s_parquetandcitylearn_three_phase_dynamic_assets_only_demo_15s_parquetset a repository-relativeroot_directory. Passing the schema path returned byDataSet().get_dataset(name)toCityLearnEnvresolved it against the cache folder and raisedFileNotFoundErrorfor<cache>/<dataset>/data/datasets/<dataset>/Building_1.parquet(#194). The three schemas now set"root_directory": null, like the other datasets.CityLearnEnv(name)and schema paths inside a repository checkout already found the files and still read the same folder. (#197)
Exports, CLI and files (#207, #202, #203):
- BAU time-series export. The BAU export writes the executed time steps only, like the control exports. It used to add the terminal step, a copy of the last executed step, which inflated totals summed from the file.
- Charger exports. Without an EV, the charger row writes
-1.00underEV SOC-%instead of adding anEV SOCcolumn. - CLI evaluation.
citylearn simulate ... evaluateandtrain --evaluateno longer fail (All arrays must be of the same length, ornot enough values to unpackwith-te), andtrain --evaluateevaluates the trained agent instead of a new one. - Schema agent attributes.
load_agent()withoutagentkeepsschema['agent']['attributes']when keyword arguments such asenv=are passed; keyword arguments override them.Simulator(..., agent_name=None)therefore builds the schema's agent with the schema's parameters. - Windows.
run_work_order()activates virtual environments withactivate.bat, whichcmd.execan run. JSON and YAML files are read and written as UTF-8, so non-ASCII text in schemas is no longer decoded as cp1252. - Multi-community KPI comparison.
load_kpis()andcompare_exports()read multi-community KPI exports, which repeat each name once per community, instead of raisingDuplicate KPI/name rows. - JSON files with NumPy values.
FileHandler.write_jsonwrites NumPy booleans, integers and floats as JSON booleans and numbers, and NumPy arrays of booleans and numbers as lists, instead of their text (2.5instead of"2.5",[1.0, null]instead of"[ 1. nan]"). Withignore_nan=False, a NaN NumPy float raisesValueErrorlike a Python float. namedtuples andDecimalvalues are written as before, and the export manifests are unchanged. See the migration guide. (#203) - pandas 3. Exports no longer emit the two pandas 3 deprecation warnings, and a Parquet render column that mixes text and numbers is written instead of raising
ArrowTypeError. Export files are unchanged (#202).
Performance
None of these changes a result; each PR compared trajectories and KPIs bit for bit with master.
- Single time steps. Per-step code reads one time step of device and storage series instead of rebuilding the whole series, and
evaluate_v2()builds its records without DataFrame scans (#183). - Time-series windows.
TimeSeriesDatakeeps each variable's episode window as a plain attribute, so reading weather, pricing, carbon, charger and energy-simulation values no longer goes through a Python__getattribute__and a new slice per read (#210). - District counterfactuals. The twelve district
*_without_storage*series sum a NumPy matrix instead of building a DataFrame; this speeds upevaluate()andevaluate_v2(), not the simulation step (#206). - Baseline resets. The baselines build their policy engine once per agent instead of at every episode reset; the first
predict()after a reset takes 48 ms instead of 81 ms (flat) and 22 ms instead of 54 ms (entity) oncitylearn_challenge_2022_phase_all_plus_evs(#211).
New opt-in features
These are off by default; existing schemas and results are unchanged.
- Reward for load left unserved during power outages. During an outage a building cannot import, so its net consumption is zero and rewards built on grid import give no signal about the load that PV and storage leave unserved.
OutageUnservedEnergyReward(coefficient, base_reward)subtractscoefficienttimes that unserved energy from a base reward, and the new flat observationpower_outage_unserved_energy(kWh per step, last settled step) gives it per building with the definition of thepower_outage_normalized_unserved_energy_totalKPI (#188). The reward works under both interfaces; the observation is flat only. Both are opt-in, so existing schemas and results are unchanged. (#195) - Time-varying available grid power.
buildings.<name>.electrical_service.available_grid_powerreferences a per-step series of the power a building may import, in kW, from a file with one column per building or a named column (#119). The import limit in force at a step is the smaller of the staticlimits.total.import_kwand the series value, and every reader of the total import limit uses it: the electrical-service allocation (EV chargers and the battery are curtailed first; fixed load stays served and counts as a violation), deferrable start feasibility, the headroom observations, the EV feasibility KPI and the electrical-service violation KPI. A limit of 0 kW does not island the building; outages stay inpower_outage. The new flat observationavailable_grid_powerreports the limit for the coming interval when a series is set, and the rule-based baselines cap their planned import headroom with it. Buildings without a series are unchanged. See the schema reference. (#216) - Vehicle-to-building backup during outages (opt-in). With
power_outage.vehicle_to_building: true, a connected EV may discharge to its building while the grid is down, as a vehicle-to-home backup. The discharge is limited to the non-shiftable load and the thermal device load that PV and the battery leave uncovered, so the building exports nothing to the failed grid. Under the entity interface, the charger'scan_dischargeandavailable_discharge_power_kwreport the vehicle's discharge capacity during the outage. The discharge can take the vehicle below its required departure SOC; that is left to the controller and shows in the EV departure KPIs. The option is off by default, and results without it are unchanged. See the migration guide. (#205)
Build and CI
- Python 3.10 or newer. CityLearn now requires Python 3.10 and is tested on Python 3.10 to 3.14, with NumPy 1.x on 3.10. Python 3.9 reached its end of life in October 2025. On Python 3.9,
pipkeeps resolving CityLearn 3.5.0. The CLI commandssimulate trainandsimulate evaluateuseddatetime.UTC, which exists only from Python 3.11, and failed on Python 3.10; they now usedatetime.timezone.utc. See the migration guide. (#218) - Package metadata in
pyproject.toml. The metadata moves fromsetup.pyto a PEP 621[project]table andsetup.pyis removed; the wheel holds the same files (#201). - Install smoke and compatibility table. CI builds the wheel, installs it with its PyPI dependencies and runs a simulation and export smoke on macOS (arm64) and Windows with Python 3.10 and 3.14; the Ubuntu build job already ran it on the installed wheel (#138). The installation guide gains a compatibility table of Python and dependency versions for every release from 1.5.0 (#150), kept in step with
requirements.txtby a test, and the GitHub Actions are updated (#217). - Windows paths in tests. The nested-dataset download tests compare paths in POSIX form, so they pass on Windows (#200).
Validation
On master at the release commit, with Python 3.10 and NumPy 2: the full test suite passed (1,897 tests, 2 skipped) and the strict runtime audit passed (physics, entity contracts, all 41 bundled datasets and the fixed-command references). The sdist and wheel built and passed twine check. The wheel, installed with its dependencies in a clean virtual environment, passed pip check and the installed-package simulation and export smoke. CSV and Parquet exports of pt_rec_4 made with 3.6.0 opened in the CityLearn UI result importer with the same 1,036 KPI rows and 15 series, and the UI test suite passed. The release CI covered Python 3.10 to 3.14, NumPy 1 on 3.10, the runtime audits and the install smoke on macOS and Windows.
Contributors
- Mark Colley (@M-Colley): the physics, KPI, baseline, agent, data-loading, dataset-cache, export and build fixes, the performance work and vehicle-to-building backup in #181, #182, #183, #185, #197, #198, #199, #200, #201, #202, #203, #204, #205, #206, #207, #208, #209, #210, #211, #212, #213, and the time-varying available grid power, install smoke, compatibility table and Python floor of #196, merged as #216, #217 and #218.
- Prawal Pokharel (@prawalpokharel): the outage unserved-energy reward and observation in #195.
- Tiago Fonseca (@calofonseca): reviewed, validated and integrated the release, split #196 into #216, #217 and #218 with the Python 3.10 floor, and fixed the battery discharge features during outages in #221.