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.

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: v2.4.2...v2.5.0

v2.4.2

Full Changelog: v2.4.1...v2.4.2

Fixes #145

v2.3.1

Full Changelog: v2.4.2...v2.3.1

v2.4.1

class import bug fixes

v2.4.0

What's Changed

• Feature Expansion: Data Export, Reward Functions, Time Granularity, Washing Machine Asset and Stochasticity by @RuiRioPina in #141

New Contributors

• @RuiRioPina made their first contribution in #141

Full Changelog: v2.3.0...v2.4.0

v2.3.0

Full Changelog: v2.2.0...v2.3.0

v2.2.0

Issues

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

What's Changed

• Gymnasium migration and Python version upgrade by @kingsleynweye in #112
• Gymnasium migration: docs requirements and text refactoring by @kingsleynweye in #114
• added setuptools to sphinx docs requirements by @kingsleynweye in #115
• Rllib wrapper et al. by @kingsleynweye in #116
• Docs build bug fixes by @kingsleynweye in #117
• Merge eulp dev with master for beta releease by @kingsleynweye in #120
• minor updates by @kingsleynweye in #121
• Occ interaction by @kingsleynweye in #123
• Datasets from eulp by @kingsleynweye in #124
• Merge EV Learn from fork to CityLearn Branch by @calofonseca in #127
• master into eulp by @kingsleynweye in #128
• Datasets from eulp by @kingsleynweye in #130
• Datasets from eulp by @kingsleynweye in #131
• Datasets from eulp ev learn by @kingsleynweye in #132
• Datasets not in installation by @kingsleynweye in #133

New Contributors

• @calofonseca made their first contribution in #127

Full Changelog: v2.1.2...v2.2.0

v2.2b0

What's Changed

• Gymnasium migration and Python version upgrade by @kingsleynweye in #112
• Gymnasium migration: docs requirements and text refactoring by @kingsleynweye in #114
• added setuptools to sphinx docs requirements by @kingsleynweye in #115
• Rllib wrapper et al. by @kingsleynweye in #116
• Docs build bug fixes by @kingsleynweye in #117
• Merge eulp dev with master for beta releease by @kingsleynweye in #120
• minor updates by @kingsleynweye in #121

Full Changelog: v2.1.2...v2.2b0

v2.1.2

Full Changelog: v2.1.1...v2.1.2