Loading replay

Change versus CityLearn's no-control reference

How it works, every simulated hour

1
The agent decidesIt reads the district, prices and forecasts and proposes cooling, hot water and battery actions as strict JSON.
2
The safety envelope checksPlain code enforces ranges, ramps, charge limits, comfort, the price spread, the peak cap and the cooling trim hold, and logs every clamp.
3
CityLearn simulatesOne hour of three buildings: indoor temperature, heat pumps, batteries, hot water and rooftop solar.
4
CityLearn scoresIts own KPI evaluation compares the month with the no-control reference: cost, carbon, comfort and the grid.

Day 1, 01:00

No control

CityLearn reference

Agent

Too coolToo warmTeal is inside CityLearn's comfort band, setpoint plus or minus 2 C. A glow means the safety envelope stepped in.

Electricity price along the topClampedFallback

Indoor temperature

AgentNo controlComfort band

District grid draw

kWh per hour

AgentNo control

Battery charge

Building 1

AgentNo control

The agent's reasons, hour by hour

CityLearn KPI scorecard

From CityLearn's own evaluate(). Lower is better on every KPI.

Run it yourself

Everything runs on one machine: CityLearn and the dataset ship with the repository, so there is no simulator server. The rule-based and baseline controllers need no key; a model run reads its key from an environment variable and stops at the budget you set.

# Windows PowerShell, Python 3.10 to 3.12
git clone https://github.com/AddisonTech/Hyperbolic
cd Hyperbolic
py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install --no-deps CityLearn==3.0.2
.\.venv\Scripts\python -m pip install -e ".[dev]"

# Watch a run live in your browser on 127.0.0.1
.\.venv\Scripts\python -m hyperbolic serve

# Or from the command line: a rule-based month,
# a model month with a key set, then compare
.\.venv\Scripts\python -m hyperbolic run --scripted
.\.venv\Scripts\python -m hyperbolic run --budget 2.00
.\.venv\Scripts\python -m hyperbolic compare

On macOS or Linux, use python in place of .\.venv\Scripts\python. Every run is saved and hyperbolic replay reproduces it with no model or simulator calls.

This is a simulator, not a real building. Every number on this page comes from CityLearn, an open source district energy simulator, scored by CityLearn's own KPIs. Nothing here is connected to a real building, BAS or customer system. A win in simulation is a reason to look closer, not proof of savings in the field.