Skip to content

CityLearn 3.6.0

Latest

Choose a tag to compare

@calofonseca calofonseca released this 19 Nov 22:41
b6fa165

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_power is now a power at every step length; heat pumps and electric heaters no longer exceed nominal_power when they charge thermal storage; on native sub-hourly data a device delivers at most nominal_power x 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 the cooling_demand, heating_demand and dhw_demand observations convert the storage discharge to dataset resolution when time_step_ratio is 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, a RuntimeWarning is 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_headroom and clip_reason_export_headroom name only the asset's own phases and the clipped direction. (#185)
  • Normalized observations. observations(normalize=True, periodic_normalization=False) no longer raises KeyError: 'month'. (#185)
  • Occupant set-point hold. set_point_hold_time_steps in a building schema now reaches LogisticRegressionOccupantInteractionBuilding. 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_6 leaving 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 >= 0 and 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 with noise_std = 0, including all bundled datasets, are unchanged. See the migration guide. (#204)
  • Battery discharge features during outages. During a power outage the entity storage table reported can_discharge = 0 and available_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 read can_discharge, so they now use the battery during outages. In the week with the most outages of pt_rec_30/evaluation/rec_30_robustness.json and rec_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. In pt_rec_100/evaluation/rec_100_allin.json the 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_electrical bundle. Two changes apply only to datasets whose schema does not enable that bundle; pt_rec_* and citylearn_challenge_2022_phase_all_plus_evs enable 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 computes available_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 of citylearn_three_phase_electrical_service_demo with the BAU); only PV above the observed load now counts as surplus. The definition versions become immediate-full-charge-v3, immediate-user-target-v2, basic-v3, smart-local-v3 and community-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 on citylearn_challenge_2022_phase_all, citylearn_challenge_2023_phase_2_local_evaluation and citylearn_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 of evaluate_v2() (predict([])) stays uncorrupted. See the migration guide. (#212)

Agents and wrappers (#208):

  • TabularQLearning no longer bootstraps from the next state on terminal transitions.
  • MARLISARBC explores with its RBC; it used to explore with random actions.
  • MARLISA with pca_compression < 1 sizes its networks to the PCA output instead of failing at the first update.
  • Discrete wrappers. TabularQLearningObservationWrapper declares exactly the prod(bins) states it encodes (it declared prod(bins + 1) - 1 and could encode a state outside the space), and DiscreteObservationWrapper keeps values above the observation space in the top bin. DiscreteObservationWrapper and DiscreteActionWrapper bin the spaces of the env they wrap, so they work over the normalized wrappers. ClippedObservationWrapper no longer modifies the environment's cached observations.
  • OnehotEncoding raises ValueError for 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.
  • InventoryBattery EVs load without nominal_power, which the battery derives from max_charge_kw and max_discharge_kw.
  • Random initial EV SOC is drawn within the battery's declared min_soc and max_soc; an InventoryBattery used to fail when the draw from [0, 1] fell outside them.
  • Entity observations with max_soc < 1 report soc_max_ratio, the energy to full and the available charge power up to max_soc instead of a full battery.

Datasets and dataset cache:

  • Incomplete dataset caches. A cached dataset counted as complete as soon as its schema.json existed, so a cache left by an interrupted download raised FileNotFoundError for its first missing file. A cache is now complete only when every input file that CityLearnEnv reads 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_REPOSITORY and CITYLEARN_DATASET_TAG are read when CityLearnEnv or DataSet is created instead of once at import, and CityLearnEnv(offline=None) honours CITYLEARN_OFFLINE (#198).
  • Dataset names. DataSet.get_dataset_names() keeps a dataset whose name occurs in its parent path and accepts a datasets_path with 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_parquet and citylearn_three_phase_dynamic_assets_only_demo_15s_parquet set a repository-relative root_directory. Passing the schema path returned by DataSet().get_dataset(name) to CityLearnEnv resolved it against the cache folder and raised FileNotFoundError for <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.00 under EV SOC-% instead of adding an EV SOC column.
  • CLI evaluation. citylearn simulate ... evaluate and train --evaluate no longer fail (All arrays must be of the same length, or not enough values to unpack with -te), and train --evaluate evaluates the trained agent instead of a new one.
  • Schema agent attributes. load_agent() without agent keeps schema['agent']['attributes'] when keyword arguments such as env= 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 with activate.bat, which cmd.exe can 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() and compare_exports() read multi-community KPI exports, which repeat each name once per community, instead of raising Duplicate KPI/name rows.
  • JSON files with NumPy values. FileHandler.write_json writes NumPy booleans, integers and floats as JSON booleans and numbers, and NumPy arrays of booleans and numbers as lists, instead of their text (2.5 instead of "2.5", [1.0, null] instead of "[ 1. nan]"). With ignore_nan=False, a NaN NumPy float raises ValueError like a Python float. namedtuples and Decimal values 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. TimeSeriesData keeps 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 up evaluate() and evaluate_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) on citylearn_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) subtracts coefficient times that unserved energy from a base reward, and the new flat observation power_outage_unserved_energy (kWh per step, last settled step) gives it per building with the definition of the power_outage_normalized_unserved_energy_total KPI (#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_power references 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 static limits.total.import_kw and 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 in power_outage. The new flat observation available_grid_power reports 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's can_discharge and available_discharge_power_kw report 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, pip keeps resolving CityLearn 3.5.0. The CLI commands simulate train and simulate evaluate used datetime.UTC, which exists only from Python 3.11, and failed on Python 3.10; they now use datetime.timezone.utc. See the migration guide. (#218)
  • Package metadata in pyproject.toml. The metadata moves from setup.py to a PEP 621 [project] table and setup.py is 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.txt by 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

Full changelog