Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

Recent Releases of CityLearn

CityLearn - Reliability/performance upgrade: EV/BESS/PV fixes, three-phase constraints, community settlement and internal refactor

Summary

This beta release brings a large set of reliability, physics-consistency, and maintainability improvements to CityLearn, developed and validated in a long-running fork and now prepared for upstream beta testing.

Scope includes:

  1. RL/runtime temporal correctness hardening.
  2. EV/BESS/PV physical consistency and sub-hour behavior fixes.
  3. Electrical-service constraints (single/three-phase) and community settlement support.
  4. Export/render pipeline refactor, optimization and stabilization.
  5. KPI expansion (absolute/delta/daily metrics, EV/BESS/PV, phase, market, equity) with stronger robustness.
  6. Internal architectural refactor of loading/runtime/building ops/KPI for maintainability.
  7. CI/performance tooling and broad regression test coverage.

Main Changes

A) RL + Temporal Semantics

  • Hardened terminal step behavior and episode boundary handling.
  • Fixed single-timestep learning path (episode_time_steps=1) in agent loop.
  • Improved action parsing robustness for centralized and decentralized agent modes.
  • Clarified lagged endogenous observation semantics while preserving public API behavior.

B) EV/BESS/PV + Physical/Unit Consistency

  • Fixed EV SOC edge case when charger action is zero while connected.
  • Improved BESS initialization/t=0 accumulation consistency and degradation scaling.
  • Improved sub-hour consistency checks and regressions.
  • Made EV unconnected drift reproducible and time-aware by physical timestep.

C) Electrical Service (Phases) + Community Settlement

  • Added/validated electrical service constraints for mono/three-phase operation.
  • Added robust handling for non-finite limits to avoid NaN propagation.
  • Added community local-market settlement and related metrics paths.
  • Hardened schema validation (including boolean parsing robustness).

D) Export/Render Pipeline

  • Refactored export logic into dedicated component(s), keeping public behavior of:
    • render_mode='none'
    • render_mode='during'
    • render_mode='end'
  • Added contract/regression checks so export layout remains stable for downstream UI.
  • Stabilized KPI CSV schema behavior for undefined metrics.

E) KPIs

  • Extended KPI set with absolute totals, deltas, and daily-normalized metrics.
  • Added EV/BESS/PV KPIs.
  • Added electrical-service (phase/violation) and community-market KPIs.
  • Added equity KPI formulas and comparison tooling.
  • Fixed baseline cost KPI behavior when tariff sums are zero.
  • Preserved legacy KPI compatibility where intended.

F) Internal Refactor

  • Introduced citylearn/internal/* modules and moved major responsibilities:
    • loading pipeline,
    • runtime orchestration,
    • building observation/action ops,
    • KPI evaluation.
  • Kept CityLearnEnv/Building public interfaces as facades (no intentional public API break).

G) Tests / CI / Tooling

  • Added extensive regression/unit/integration coverage across:
    • temporal semantics,
    • EV SOC behavior,
    • reproducibility,
    • KPI formulas,
    • export/UI contract,
    • electrical service/market behavior.
  • Added perf smoke tooling and baseline checks.
  • Reorganized manual scripts outside default pytest discovery.

Backward Compatibility

  • Public API signatures are preserved.
  • Legacy behavior is retained where feasible; changes focus on correctness and robustness.
  • Export modes and expected filenames remain compatible (with additional metrics where applicable).

Validation

  • Full test suite executed in fork CI and local runs.
  • Additional scenario smoke runs (including long rollouts and RBC policies) used to verify end-to-end execution and export behavior.

Energy Systems - Load and Demand Forecasting - Python
Published by calofonseca 11 days ago

CityLearn - v2.5.0

CityLearn 2.5.0 – Data Exports, EV Enhancements, and Extended UI Support

This release finishes the durability work we started in 2.4.x and adds a host of UX and testing upgrades:

Rendering & UI

  • Render pipeline refactor with explicit toggles for UI-friendly exports, direct upload structure, and configurable render directories and fixing identified issues (#145, PR #148).
  • Full-step exporter and minute-level testing to confirm the UI handles sub-hour time granularity.

EVs & Appliances

  • Updated EV datasets and chargers, including minute-level coverage and reference controllers.
  • Taken out EV dataset features that were not used.
  • Regression scripts for RBC/SAC exports; EV/RBC end-to-end tests extended to the full dataset.
  • Washing machine integration + tests to guarantee the new appliance profiles (and their load logic) stay in sync with the rest of the stack.

Validation & Testing

  • UI dataset regression tests, new render-behaviour coverage, and minute-step exports to catch bugs.
  • End-to-end EV dumps, minute-test scaffolding, and SAC regression coverage to make sure the RL loops still converge.

Docs & Polish

  • UI documentation expanded with the new toggles and streaming/export modes.
  • General docs cleanup, including minor typo fixes (#152).

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.4.2...v2.5.0

Energy Systems - Load and Demand Forecasting - Python
Published by calofonseca 6 months ago

CityLearn - v2.3.1

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.4.2...v2.3.1

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye 8 months ago

CityLearn - v2.4.2

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.4.1...v2.4.2

Fixes #145

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye 8 months ago

CityLearn -

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye 9 months ago

CityLearn - v2.4.0

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.3.0...v2.4.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye 9 months ago

CityLearn - v2.3.0

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.2.0...v2.3.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 1 year ago

CityLearn - v2.2.0

Issues

  • Fixes #105
  • Fixes #106
  • Fixes #107
  • Fixes #108
  • Fixes #109
  • Fixes #111

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1.2...v2.2.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 1 year ago

CityLearn - v2.2.0

Issues

  • Fixes #105
  • Fixes #106
  • Fixes #107
  • Fixes #108
  • Fixes #109
  • Fixes #111

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1.2...v2.2.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 1 year ago

CityLearn - v2.2b0

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1.2...v2.2b0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye almost 2 years ago

CityLearn - v2.1.2

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1.1...v2.1.2

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 2 years ago

CityLearn - v2.1.1

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1.0...v2.1.1

Fixes #100, fixes #101

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 2 years ago

CityLearn - v2.1.0

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0.0...v2.1.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b12

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b11...v2.1b12

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b11

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b10...v2.1b11

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b10

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b9...v2.1b10

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b9

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b8...v2.1b9

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b8

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b7...v2.1b8

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b7

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b6...v2.1b7

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b6

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b5...v2.1b6

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b5

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b4...v2.1b5

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b4

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b3...v2.1b4

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b3

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b2...v2.1b3

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b2

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.1b1...v2.1b2

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.1b1

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0.0...v2.1b1

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0.0

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.8.0...v2.0.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b9

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b8...v2.0b9

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b8

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b7...v2.0b8

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b7

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b6...v2.0b7

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b6

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b5...v2.0b6

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b5

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b4...v2.0b5

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b4

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b3...v2.0b4

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 2 years ago

CityLearn - v2.0b3

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0b2...v2.0b3

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye almost 3 years ago

CityLearn - v2.0b2

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v2.0-beta.1...v2.0b2

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye almost 3 years ago

CityLearn - v2.0-beta.1

What's Changed

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.8.0...v2.0-beta.1

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye almost 3 years ago

CityLearn - v1.8.0

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.7.0...v1.8.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 3 years ago

CityLearn - v1.7.0

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.6.0...v1.7.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 3 years ago

CityLearn - v1.6.0

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.5.0...v1.6.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 3 years ago

CityLearn - v1.5.0

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.4.4...v1.5.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 3 years ago

CityLearn - v1.4.4

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.4.3...v1.4.4

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye about 3 years ago

CityLearn - v1.4.3

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.4.2...v1.4.3

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.4.2

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.4.1...v1.4.2

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.4.1

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.4.0...v1.4.1

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.4.0

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.6...v1.4.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.6

This release added a grid cost to the CityLearn Challenge 2022. The grid score is the average of a ramping and (1 - load factor) scores evaluated at the aggregated district net electricity consumption level. The purpose of adding this grid score is to encourage participants to seek a cooperative multi-agent solution in order to achieve grid-level objectives.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.5...v1.3.6

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.5

This release addresses 2 main issues:

  1. The long simulation time as a result of time series variables being recalculated every time step has been solved.2. Simulations, especially with RBCs are much noticeably faster to complete.
  2. There was a bug in the calculation of the battery energy balance that overestimated the energy balance during discharge.
  3. Other minor issues.

Credits to @ludwigbald for finding and proffering solutions to the issues.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.4...v1.3.5

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.4

CityLearn Challenge 2022 sixth release with bug fixes.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.3...v1.3.4

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.3

CityLearn Challenge 2022 fifth release with bug fixes.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.2...v1.3.3

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.2

CityLearn Challenge 2022 fourth release with bug fixes.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.1...v1.3.2

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.1

CityLearn Challenge 2022 third release with bug fixes.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.3.0...v1.3.1

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.3.0

CityLearn Challenge 2022 second release with bug fixes.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.2.0...v1.3.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.2.0

CityLearn Challenge 2022 first release environment.

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.0.0...v1.2.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 3 years ago

CityLearn - v1.1.0

What's Changed

New Contributors

Full Changelog: https://github.com/intelligent-environments-lab/CityLearn/compare/v1.0.0...v1.1.0

Energy Systems - Load and Demand Forecasting - Python
Published by kingsleynweye over 4 years ago