pepe/ALLSHIFT
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ALLSHIFT/docs/02-specifications/rl-state-variables.md
pepe 72dd781dbc Organize documentation into docs/ and superseded/ 
Audit every document in the repository, convert the non-markdown ones into
markdown reports, and split current documentation from outdated material.

docs/ — 31 markdown documents in seven numbered sections. Twenty are new
reports generated from .docx / .pdf / .xlsx / .mlx / .m sources that were
previously unreadable in the browser and undiffable in git. Each report
carries a provenance block (source path, format, MD5) and links back to its
original; all 13 recorded checksums verify against the files on disk.
Machine-extraction losses (PDF table column interleaving, Word OMML
equations, embedded figures) are called out explicitly rather than silently
smoothed over.

superseded/ — outdated material with a documented reason per entry:
two byte-identical ClickUp re-exports, an older revision of the BIDMC/UCSD
energy-flow doc (the retained copy adds the SoC Violation Rate KPI), a
duplicate of Shift input data.docx, the May 2026 simulation plan, the
root PV+Battery.md now covered by a fuller report, GitHub's stock
demo-repository template, and a zero-byte placeholder. Its README also
records what was deliberately NOT retired and why — the "Old Frameworks"
and "Old Simulations" folders hold unique Simulink revisions, and
"Big Ugly Folder" holds the only copy of framework revision 1.3.

Findings worth flagging, all documented in the reports:
- Simulink lineage recovered from each .slx's internal coreProperties.xml
  revision counter. The current model is
  Current Framework/Bobert0206_Initial_Simulation_Framework.slx (rev 2.7);
  the top-level copy is rev 1.3, five revisions behind.
- Simulations/Constants.m is a truncated byte-prefix of the Current
  Framework copy, silently missing H2_leak, H2_cap and E_H2_vol_h.
- The PEM electrolyser and fuel cell are unmodified MathWorks Simscape
  examples still at vendor defaults; the "10x bigger" sizing TODO recorded
  in Constants.m was never carried out.
- controller-claude.m does not compile — undefined P_Electro_max, outputs
  unassigned on several paths.
- The specification set uses two incompatible variable naming conventions
  and disagrees on action-space size (5 vs 16).
- MA_hourly_load.csv (13.7 MB) is the same 35,040 rows as 89993-0.parquet
  (2.4 MB).
- Clinical data is the MIMIC-IV *demo* (ODbL, 100 patients), not full
  MIMIC-IV — redistributable, but the licence and citation are unrecorded.

Housekeeping: untrack 21 Simulink build artefacts (slprj/, *.slxc) and add
ignore rules for them. Root README rewritten around the new layout.

Recruitment notes naming individual candidates are excluded from version
control via .gitignore rather than committed; the generic question template
is kept in docs/07-team-and-operations/.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-25 21:20:33 -07:00

128 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# RL State Variables
> **Markdown report of a non-markdown source document.**
>
> | | |
> |---|---|
> | **Source** | [`docs/_originals/STATE VARIABLES AND DESCRIPTIONS.docx`](../_originals/STATE%20VARIABLES%20AND%20DESCRIPTIONS.docx) |
> | **Format** | Microsoft Word (.docx), 14.7 kB |
> | **MD5** | `59dde2384627aa8cdc0412ed6d7f589f` |
> | **Owner** | AI & Control Systems cluster |
> | **Status** | Current — but see [Naming mismatch](#naming-mismatch-with-the-simulator-io-contract) |
> | **Report generated** | 2026-07-25 |
## What this document is
The observation space for the reinforcement-learning controller: everything the agent is
allowed to *see* at each timestep. It is the counterpart to
[RL Action Variables](rl-action-variables.md) (what the agent may *do*) and
[RL Reward Function](rl-reward-function.md) (how it is *scored*).
Thirty-two variables in eight groups. The source document gives a name and a one-line
description for each; it does **not** specify units, ranges, or datatypes — those are
implied at best. Adding them is the obvious next revision.
## State variables
### Photovoltaic array
| Variable | Description |
|---|---|
| `PV_Generation` | Current electrical power produced by the solar panels. |
| `Solar_Irradiance` | Amount of sunlight hitting the panels (W/m²). |
| `PV_Temperature` | Panel temperature affecting efficiency. |
| `PV_Efficiency` | Conversion efficiency of the PV array at the current moment. |
### Battery
| Variable | Description |
|---|---|
| `Battery_SOC` | Battery state of charge (%) indicating energy stored. |
| `Battery_Current` | Charge/discharge current flowing through the battery. |
| `Battery_Voltage` | Terminal voltage of the battery pack. |
| `Battery_Temperature` | Battery temperature affecting performance and lifespan. |
### Electrolyser
| Variable | Description |
|---|---|
| `Electrolyzer_Power` | Electrical power supplied to the electrolyzer. |
| `Electrolyzer_H2_ProductionRate` | Amount of hydrogen being produced per unit time. |
| `Electrolyzer_WaterLevel` | Water reservoir level needed for electrolysis. |
| `Electrolyzer_Temperature` | Stack temperature affecting efficiency and safety. |
| `Electrolyzer_StackHealth` | Degradation/health level of the electrolyzer stack. |
### Hydrogen storage
| Variable | Description |
|---|---|
| `HydrogenTank_Level` | Current amount of hydrogen stored in the tank. |
| `HydrogenTank_Pressure` | Internal pressure of the hydrogen storage tank. |
| `HydrogenTank_Temperature` | Tank temperature affecting pressure and safety. |
### Fuel cell
| Variable | Description |
|---|---|
| `FuelCell_Power` | Current electrical power produced by the fuel cell. |
| `FuelCell_Temperature` | Fuel cell stack temperature. |
| `FuelCell_H2_ConsumptionRate` | Rate at which the fuel cell consumes hydrogen. |
| `FuelCell_StackHealth` | Degradation/health of the fuel cell stack. |
### Grid
| Variable | Description |
|---|---|
| `Grid_Status` | Whether the grid is online/offline/faulted. |
| `Grid_Price` | Current real-time electricity price from the grid. |
| `Grid_Availability` | Whether grid import or export is allowed at the moment. |
### Hospital load
| Variable | Description |
|---|---|
| `Hospital_Load` | Total electrical demand of the hospital. |
| `Critical_Load` | Portion of the load that must always be powered. |
| `NonCritical_Load` | Flexible load that can be shed or shifted. |
| `Predicted_Load` | Forecasted load in the near future. |
### Environment and calendar
| Variable | Description |
|---|---|
| `Ambient_Temperature` | Outside temperature affecting PV, battery, and loads. |
| `Ambient_Humidity` | Humidity affecting cooling and equipment performance. |
| `TimeOfDay` | Current hour used for daily patterns in generation/load. |
| `DayType` | Whether it is a weekday, weekend, or holiday (affects load patterns). |
## Naming mismatch with the simulator I/O contract
This document and the [Simulator I/O Interface](simulator-io-interface.md) describe the same
system with **two different naming conventions**, and neither references the other:
| Concept | This document | Simulator I/O sheet |
|---|---|---|
| Battery state of charge | `Battery_SOC` (%) | `SoC(t)` (0–1) |
| PV power | `PV_Generation` | `P_PV_available(t)` / `P_PV_used(t)` |
| Hydrogen stored | `HydrogenTank_Level` | `H2_level(t)` (mol or kg) |
| Critical demand | `Critical_Load` | `L_crit(t)` (W) |
| Grid availability | `Grid_Availability`, `Grid_Status` | `grid_on(t)` (1/0) |
The simulator sheet also **omits** several states listed here — stack health, water level,
humidity, and all four component temperatures — because it assumes an isothermal tank and no
degradation model (both flagged as open questions in that document).
Conversely this document lists no `DayType` or `TimeOfDay` equivalent in the simulator outputs.
**Neither document is wrong; they are unreconciled.** Before the environment is coded, one
naming convention and one authoritative variable set has to win. The Simulator I/O sheet is the
more rigorous artefact (it has units, ranges, sign conventions, and an explicit power-balance
invariant), so it is the natural base — but it needs the health/temperature states from this
document if degradation or thermal effects are to be modelled at all.
## Related
- [RL Action Variables](rl-action-variables.md) — the action space
- [RL Reward Function](rl-reward-function.md) — the reward terms
- [Simulator I/O Interface](simulator-io-interface.md) — the typed simulator contract
- [Rule-Based Controller](rule-based-controller.md) — the baseline policy this agent must beat
Reference in a new issue View git blame Copy permalink