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

[calofonseca]

Summary

This PR 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 integration.

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 and UI contract 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.