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

5.5 KiB
Raw Permalink Blame History

RL State Variables

Markdown report of a non-markdown source document.
Source docs/_originals/STATE VARIABLES AND DESCRIPTIONS.docx
Format Microsoft Word (.docx), 14.7 kB
MD5 59dde2384627aa8cdc0412ed6d7f589f
Owner AI & Control Systems cluster
Status Current — but see Naming mismatch
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 (what the agent may do) and RL Reward Function (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 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