ALLSHIFT/AICONTROL/docs/interface-draft.md

# The Simulations → AI interface — draft for the November session

| | |
|---|---|
| **What this is** | Our side of the handover the Project Manual calls "the environment interface": what the agent sees, what it controls, how it is scored. Written by the RL Environment seat; to be finished jointly with Simulations' Simulation Core Developer early in Q2 and frozen before Christmas |
| **Where it lives in code** | `aicontrol/env/spaces.py` builds the spaces from `configs/env.yaml`. Run `uv run python -m aicontrol.env.spaces` to print the current layout |
| **Grown from** | The manual's interface list (section 3.2) and our older Simulator I/O sheet, whose names we keep where they exist |
| **Status** | Draft, 11 Sep 2026. Everything marked *to agree* is open until the joint session |

## The idea in one paragraph

The agent and the simulated hospital talk through a Gymnasium environment: `reset()` starts a
run, `step(action)` advances five minutes and returns what the agent may see next, plus a
score. Simulations owns everything inside `step` (the physics, the KPIs); we own everything
outside it (the agent, the safety layer, the evaluation). The two only have to agree on three
lists, below. Until the twin exists, a placeholder environment with toy physics exposes exactly
these lists so our side can be built now.

## 1. What the agent sees

One flat vector of 64 numbers per step, laid out from `configs/env.yaml`. The first sixteen are
the present; the remaining 48 are the forecasts.

| # | name | size | unit | range | source |
|---|---|---|---|---|---|
| 0 | `time_of_day` | 2 | sin, cos | −1 … 1 | calendar |
| 2 | `time_of_year` | 2 | sin, cos | −1 … 1 | calendar |
| 4 | `P_PV` | 1 | kW | 0 … 460 | twin: solar output now |
| 5 | `L_tier1` | 1 | kW | 0 … 1000 | data: critical load now |
| 6 | `L_tier2` | 1 | kW | 0 … 1000 | data: essential load now |
| 7 | `L_tier3` | 1 | kW | 0 … 1000 | data: non-critical load now |
| 8 | `SoC` | 1 | fraction 0–1 | 0 … 1 | twin: battery state of charge |
| 9 | `H2_level` | 1 | kg | 0 … 200 | twin: hydrogen in the tank |
| 10 | `p_tank` | 1 | bar | 0 … 30 | twin: tank pressure |
| 11 | `price` | 1 | currency/kWh | −1 … 5 | data: electricity price now |
| 12 | `CO2_int` | 1 | kg CO₂/kWh | 0 … 1.5 | data: grid carbon intensity now |
| 13 | `grid_on` | 1 | 0/1 | 0 … 1 | data: grid available |
| 14 | `ele_on` | 1 | 0/1 | 0 … 1 | twin: electrolyser running |
| 15 | `fc_on` | 1 | 0/1 | 0 … 1 | twin: fuel cell running |
| 16–63 | `fcst_<quantity>_<horizon>min` | 3 each | kW | 0 … max | forecaster: p10, p50, p90 for solar, tier1, tier2, tier3 at +60, +180, +360, +1440 min |

Why sin and cos for time: a clock hand, not a number that jumps from 23:59 to 00:00. Why
ranges: they scale the numbers for the network and let a test catch nonsense; they are not
physical guarantees.

*To agree with Simulations:* which of these the twin reports directly (tank pressure or only
kilograms; equipment state as on/off or as a mode); the forecast horizons and whether four are
enough; the load upper bound once the dataset scale is known; the currency.

## 2. What the agent controls

Four floats per step.

| name | range | meaning |
|---|---|---|
| `u_ele` | 0 … 1 | fraction of electrolyser rated power; 0 is off, anything below the minimum load becomes off |
| `u_fc` | 0 … 1 | fraction of fuel cell rated power |
| `u_batt` | −1 … 1 | fraction of battery max power; positive discharges, negative charges |
| `shed` | 0 … 2 | rounded to a shedding level: 0 nothing, 1 Tier 3 shed, 2 Tiers 2 and 3 shed. Tier 1 is never an option |

The grid is not an action: it absorbs whatever is left after the four above, within its
connection limit. Load shedding *is* an action here, as the manual lists it, but the safety
layer will refuse anything that would touch Tier 1.

*To agree with Simulations:* the shedding encoding (a continuous number rounded inside the
environment is the simplest thing that works with Stable-Baselines3, which cannot mix
continuous and discrete actions; the alternative is making all four discrete); whether the
twin wants setpoints in kW or in fractions; ramp limits applied inside the twin or reported
back as a clipped action.

## 3. How it is scored

The score per step is a weighted sum of the terms the manual lists. The *terms* are ours to
propose; the *weights* are agreed with Energy Management and Business, because they say how
much a euro, a kilo of CO₂ and a shed ward are worth relative to each other. The numbers in
`configs/env.yaml` are placeholders so that code can run.

| term | sign | what it measures |
|---|---|---|
| energy cost | − | money paid for grid electricity this step, minus money earned exporting |
| CO₂ | − | grid electricity used × carbon intensity |
| Tier 1 unserved | − − | any critical load not supplied; must dominate every other term |
| Tier 2 / Tier 3 shed | − | non-critical load cut, priced far below Tier 1 |
| limit violation | − | battery or tank pushed past a safe limit |
| switching | − | equipment turned on or off this step, to stop chattering |

*To agree:* whether a clipped action (the twin refused part of it) counts as a violation or
only as a reported difference; whether the perfect-knowledge benchmark and MPC are scored on
exactly this sum, so the comparison is fair.

## 4. What the twin must return so we can compute all of the above

Per step: served load per tier, grid import and export, PV used and curtailed, battery power,
electrolyser and fuel cell power, hydrogen produced and consumed, any limit clipping, and the
KPI increments. The manual's four KPIs (Self-Sufficiency Rate, Grid Dependency Ratio, Critical
Load Uptime, SoC Violation Rate) are computed by Simulations' KPI calculator; we read them,
we do not recompute them.

## 5. What happens when the twin replaces the placeholder

Nothing on our side, if the three lists hold. The training rig, the evaluation pipeline, the
safety wrapper and the dashboard all read the lists above, never the physics. That is the whole
point of drafting this now.