Releases

Changes, compatibility, validation and measured performance for the current CityLearn release. Older notes are retained in the release archive.

For package publication, version policy and the release checklist, see the publishing guide.

v3.2.0 - 2026-11-06

Release maintainer: Tiago Fonseca (@calofonseca). Simulator changes contributed by Mark Colley in PR #169.

  • Support Gymnasium 1.x alongside 0.28.1. Stacked wrappers and agents use the environment’s public attribute access. The CLI starts without Stable-Baselines3.

  • Return simulated indoor temperatures to agents using LSTM dynamics. Use deterministic LSTM inference, correct periodic and occupant observations, and reset action feedback, constraint violations and dynamic series at each episode.

  • Convert LSTM heating and cooling actions, thermal storage and autosizing between dataset and control resolutions. Count initial thermal storage discharge once, and support outage signals in partial-day episodes.

  • Keep the energy provenance ledger enabled by default. When disabled, skip optional provenance KPIs and carry the setting into BAU and the export manifest. CSV and partitioned Parquet, BAU control logic and dataset files are retained.

  • Return one float per building for per-building reward functions. See the migration guide for the required indexing change, corrected trajectories and optional EULP dependencies.

  • Reduce observation preparation for LSTM inference and use scalar clipping on frequently executed paths. The minute-encoding regression test reads a short window of the same 15-second dataset.

Validation and performance

The runtime passed CI on Python 3.9 and 3.10, the installed-wheel export smoke and the Sphinx build. The runtime audit covered 16 physical scenarios (12,000 intervals), 32 official dataset probes, entity contracts and six fixed-command reference cases. Six real exports opened in the CityLearn UI. The two controlled comparisons matched all 10,274 KPI records and retained the same BAU series and scorecards.

Bounded case

Mean step before → after (ms)

Peak process RSS before → after (MiB)

EVs, 400 steps

7.27 → 7.24

637.95 → 636.25

LSTM, 120 steps

2.47 → 2.27

646.88 → 646.97

Dynamic topology, 1,840 steps

11.90 → 11.25

655.30 → 654.55

The table gives medians of three runs against the pre-merge 3.1.1 development head, with identical inputs, fixed commands and physical checks enabled. The dynamic case applied all five events at the same steps, and KPI evaluation took 2.36 → 2.26 seconds. These measurements cover the stated windows.

v3.1.1 - 2026-11-04

Release owner: Tiago Fonseca (@calofonseca).

  • Honor explicit random_episode_split=True and False constructor overrides; None continues to inherit the schema setting (PR #166).

  • Compound the configured hourly standby-loss fraction over the physical step, independently of dataset cadence (PR #164). A 1% hourly loss now leaves 99% after one hour at both hourly and 15-minute resolution, within float precision.

  • Convert dataset energy to average step power when autosizing heat pumps, electric heaters and batteries. Battery daily peaks use physical 24-hour periods. Thermal storage capacity remains energy for one control step.

  • Preserve public energy-command interfaces, explicit equipment settings, BAU control logic, KPI definitions, dataset files and export schemas. Subhourly SOC, derived KPIs and automatically selected equipment may change because of the corrections; no file migration is required. See migration notes.

  • Simplify user documentation and correct tutorial prose/docstring typos (PR #154), retaining notebook execution logic, stored outputs and metadata.

Validation of the corrected runtime: 1,249 tests, 16 physical scenarios, 32 bounded official-dataset checks, entity contracts and six fixed-command reference cases passed. The reviewed standby reference reproduces the old baseline exactly when only the old loss formula is restored; hourly reference results are unchanged. Release CI, distribution checks and installed-package evidence accompany the GitHub release. No new annual campaign, equipment calibration or performance improvement is claimed for this patch. The 3.1.0 performance evidence below remains historical evidence for that release.

v3.1.0 - 2026-11-02

Release owner and integration maintainer: Tiago Fonseca (@calofonseca).

Summary

Integrates the validated runtime improvements from SoftCPS Simulator 2.0.0 into CityLearn, with CityLearn package identity, interfaces and official datasets preserved. Production CPS datasets and working audit notes are not imported.

Fixed and added

  • Shared outage energy budgets across simultaneous EV chargers, conservative battery reserves and applied single/three-phase service limits.

  • Independent energy/cash balance checks, EV departure and deferrable-service ledgers, executed-window KPI populations, family coverage and temporal evidence.

  • Robustness composition, missing-input validation, input fingerprints and versioned experiment comparison/export manifests.

  • Internal loading, observation, electrical-limit and KPI responsibilities split into focused modules while retaining public entry points.

  • Local schema roots resolve independently of the working directory, including the existing repository-relative Parquet schemas.

  • Strict physics, entity, dataset and fixed-command audits; generic regression tests and installed-wheel export checks in CI and before publication.

Performance evidence

Local medians of three repetitions on three existing official datasets, with physics checks enabled, fixed zero commands, one BLAS thread, 1,200 / 1,400 / 1,200 transitions and current topology-aware action shapes. The market is explicitly enabled; robustness events are extended in temporary copies only. These are bounded integration measurements, not annual whole-catalog timings.

The optimization comparison uses the corrected functional integration before optimization, with the same additional audits and KPI coverage:

Case

Step, ms before → after

KPI evaluation, s before → after

RSS after evaluation, MiB before → after

Static, flat

6.304 → 6.162 (−2.3%)

2.241 → 1.168 (−47.9%)

658 → 641

Dynamic topology, entity

9.965 → 9.235 (−7.3%)

7.225 → 1.653 (−77.1%)

668 → 646

Sustained robustness events, entity

15.449 → 13.442 (−13.0%)

1.683 → 0.724 (−57.0%)

1,365 → 662 (−51.5%)

  • Compact market storage: 18.26 → 2.29 MB (static/robust), 22.45 → 2.75 MB (dynamic), approximately 87% less retained storage.

  • Robustness storage in the sustained-event case: 699.61 → 13.72 MB, 98.0% less. Public history reconstruction remains available on demand.

  • All 16,737 KPI rows across the three cases and every energy/cost trace are exactly equal before and after optimization, in all three repetitions.

  • Changes include compact lossless histories, batched EV feasibility replay, reusable KPI populations, indexed deferrable cycles and cached observation / forecast preparation. Missing values retain their meaning.

  • Compared directly with original 3.0.2, mean step times are 5.298 → 6.162 ms (static), 8.885 → 9.235 ms (dynamic) and 14.548 → 13.442 ms (robust). KPI output grows from 2,099 / 2,227 / 2,243 to 5,427 / 5,739 / 5,571 rows. The added checks and coverage have a cost: this release is not faster in every case than 3.0.2. Host load and allocator behavior affect timings.

  • RAM measurements cover initialization through KPI evaluation, before deep storage inspection or reconstructing public histories. Raw measurements and the benchmark protocol accompany the GitHub release.

Dataset and compatibility impact

  • All 32 existing official datasets and existing data/test fixtures/assets are unchanged: 1,254 protected files verified by SHA-256. No dataset/schema migration is required; retired datasets remain retired.

  • Distribution/import: citylearn; registry: citylearn-project/CityLearn at tag v3.1.0. CSV, partitioned Parquet and KPI sidecar exports are retained.

  • The native BAU is now explicitly immediate-full-charge-v1: request maximum available EV charging to 100%, share electrical capacity proportionally and perform no PV, tariff or departure-target scheduling. Constructor order is retained; custom target/deadline EV options now raise a clear error and belong in configurable RBC policies. This deliberately changes historical BAU requests.

  • Corrected functional KPI/accounting results can differ from 3.0.2. Use matching-version references. See the migration guide.

Validation and limits

  • Complete local suite: 1,138 passed, no failures or skips (44 Gymnasium float32 precision warnings).

  • Strict runtime audits: 16/16 physical scenarios; 32/32 official datasets in bounded supported-interface probes; entity contracts; six fixed-command reference cases. No reference snapshot updates were needed.

  • Critical lint, wheel/source builds and twine check: passed.

  • Isolated installed-wheel KPI, BAU, provenance and service-sidecar export: passed.

  • Documentation: 208 HTML pages, 19,096 local links/assets, zero link errors (40 retained Sphinx warnings).

  • Benchmark: 27 successful runs, 34,200 transitions, active physical checks and exact functional/optimized KPI and energy/cost parity in all repetitions.

The physical models are validated by deterministic checks and simulated inputs; this release does not claim calibration against real equipment, successful annual runs of every official dataset or that every requested EV departure SOC is physically attainable. Existing infeasible service events remain visible.

Earlier releases, with their original validation notes: release archive.