pepe/ALLSHIFT
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ALLSHIFT/docs/04-simulations/existing-est-model.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

240 lines
11 KiB
Markdown
Raw Permalink Blame History

# Existing EST Model (vendored)
> **Markdown report of a vendored third-party subtree.**
>
> | | |
> |---|---|
> | **Location** | `Shift Matlab Drive/Shift Matlab Drive/Simulations/Exisiting EST Model/est-model-main/` |
> | **Upstream** | `https://gitlab.tue.nl/p.b.r.arnaud.de.calavon/est-model.git` (TU/e GitLab) |
> | **Licence** | **MIT** — © 2023 Energy Storage and Transport |
> | **Status** | **Vendored — do not reorganise.** SHIFT modifications live in the outer layer |
> | **Report generated** | 2026-07-25 |
> [!IMPORTANT]
> This subtree is **not SHIFT's own work**. It is an externally authored, MIT-licensed model
> reused as a baseline. Its internal structure — including its duplicate data files and its
> ~100 MATLAB Project bookkeeping XMLs — is upstream's business, not a documentation defect.
> Nothing inside it has been moved, renamed, or retired.
>
> The folder name `Exisiting EST Model` contains a typo for *Existing*. It is left as-is:
> renaming it changes paths for no benefit.
## What EST is
**EST — Energy Storage and Transport.** From the upstream README:
> This project contains the *Simulink model* for the **Energy Storage and Transport (EST)**
> project. This Simulink model contains a simplified version of a real-life energy storage and
> transport system, which describes the flow of energy in such a system. Supporting MATLAB
> files are provided which can be used to predefine parameters and to post-process data into
> figures.
It is a TU/e teaching/reference model for generic energy storage — supply, storage, transport,
demand, with dissipation coefficients on each stage. SHIFT uses it as a **starting framework**,
not as a hydrogen model.
## The double-nested structure
```
Exisiting EST Model/
└── est-model-main/ ← SHIFT's working layer (modifications + stock GitLab README)
├── README.md ← stock GitLab template boilerplate, NOT project docs
├── ModelDevelopment.prj ← MATLAB Project file (essentially empty)
├── Add_Mu_and_Gen_eff.m ← SHIFT modification
├── Control_to_sell_and_buy.m ← SHIFT modification
├── injection.m ← SHIFT modification
├── Injection_run.m ← SHIFT modification
├── run2.m ← SHIFT modification
├── resources/project/ ← ~100 machine-generated MATLAB Project XMLs
└── EST-model-main/ ← pristine upstream copy
├── README.md ← the REAL EST documentation
├── LICENSE ← MIT
├── EST.slx ← the model
├── preprocessing.m / postprocessing.m
├── scripts/ ← constants.m, loadDemandData.m, loadSupplyData.m
├── data/ ← Team03_demand.csv, Team03_supply.csv
├── images/ ← README screenshots
└── versions/ ← EST_R2021a/b, R2022a
```
**The inner `EST-model-main/` is the pristine upstream copy.** It holds the LICENSE, the real
README, the model, and the version ladder. **The outer `est-model-main/` is SHIFT's layer** —
five new `.m` files sitting beside a GitLab-template README that nobody edited.
> The outer `README.md` is entirely GitLab's *"To make it easy for you to get started with
> GitLab, here's a list of recommended next steps"* boilerplate — checkbox lists about setting
> up CI/CD and inviting collaborators. It contains **zero project information**. Do not read it
> looking for EST documentation; read `EST-model-main/README.md`.
## Upstream requirements and usage
From the real README:
- **Requires MATLAB R2022b or newer** with the Simulink toolbox.
- Install by cloning/downloading the **entire** repository and opening `EST.slx`. Downloading
only `EST.slx` does not work.
- Older, untested versions are in `versions/` — copy the file matching your release into the
main directory and restart both MATLAB and Simulink before running.
- `preprocessing.m` runs automatically before the model (`initFcn` callback) to define
parameters and read supply/demand data; `postprocessing.m` runs after to plot results.
- The MATLAB working directory must be the folder containing `EST.slx`.
### Version ladder
| File | MATLAB release |
|---|---|
| `EST.slx` | **R2022b+ — current** |
| `versions/EST_R2022a.slx` | R2022a |
| `versions/EST_R2021b.slx` | R2021b |
| `versions/EST_R2021a.slx` | R2021a |
The `versions/` files are upstream's deliberate backwards-compatibility exports, not stale
drafts. They stay.
### Default parameters
From `preprocessing.m`:
```matlab
timeUnit = 's';
supplyFile = "SolarExample_supply.csv"; supplyUnit = "kW";
demandFile = "SolarExample_demand.csv"; demandUnit = "kW";
deltat = 5*unit("min");
stopt = min([Supply.Timeinfo.End, Demand.Timeinfo.End]);
aSupplyTransport = 0.01; % Dissipation coefficient
```
> Note the mismatch: `preprocessing.m` references `SolarExample_supply.csv` /
> `SolarExample_demand.csv`, but the files actually present in `data/` are
> **`Team03_demand.csv` and `Team03_supply.csv`**. Running the model as shipped will fail on
> the missing example files unless `preprocessing.m` is edited or the data files renamed. This
> is an upstream/vendoring seam, not a SHIFT bug.
## SHIFT's modifications — gravity storage, not hydrogen
The five `.m` files in the outer layer model a **gravity storage** system: electric motors
lifting mass blocks up towers to store energy, releasing them to generate. This is a
storage technology SHIFT evaluated alongside hydrogen; it does not appear in the current
[system architecture](../02-specifications/simulator-io-interface.md).
### `injection.m` — the core function
```matlab
function [PfromInjection, DInjection, nUse, aInjection] = injection( ...
Psupply, massBlock, v, rho, Cd, areaBlock, n, mu, eta_motor)
g = 9.81; % Gravity [m/s²]
P_lift = massBlock * g * v; % Mechanical power to lift [W]
P_drag = 0.5 * rho * Cd * areaBlock * abs(v)^3; % Air drag [W]
P_fric = mu * massBlock * g * abs(v); % Friction [W]
Ploss = P_drag + P_fric;
P_required = (P_lift + Ploss) / eta_motor; % Electrical input [W]
aInjection = Ploss / P_required; % Dynamic loss coefficient
DInjection = aInjection * P_required; % Power lost [W]
PfromInjection = P_required - DInjection; % Net stored [W]
if Psupply == 0
nUse = 0;
elseif Psupply <= n * P_required
nUse = ceil(Psupply / P_required); % Towers needed
else
nUse = n; % All towers active
end
end
```
The interesting idea here is `aInjection` — replacing EST's **fixed** dissipation coefficient
with one **computed from physics** at the current operating point. That is exactly the move the
hydrogen models need too, and it is the reusable insight from this branch of work.
### Parameter sets
| Parameter | `run2.m` | `Injection_run.m` | Unit |
|---|---:|---:|---|
| `massBlock` | 10,000 | 10,000 | kg |
| `v` | 2 | 2 | m/s |
| `rho` | **1.225** | **1.293** | kg/m³ |
| `Cd` | 1.05 | 1.05 | — |
| `areaBlock` | 100 | 100 | m² |
| `n` | 10 | 10 | towers |
| `mu` | 0.05 | 0.05 | — |
| `eta_motor` | 0.85 | 0.85 | — |
| `Psupply` | 1e6 (1 MW) | 1e6 | W |
`run2.m` is annotated *"Constants from poster"*. The two scripts differ only in air density —
1.225 kg/m³ (ISA sea level, 15 °C) versus 1.293 kg/m³ (0 °C). `Injection_run.m` also notes
`v = 2` is *"slower than extraction to reduce losses"*.
### The other three files
| File | Content | State |
|---|---|---|
| `Add_Mu_and_Gen_eff.m` | Sets `mu = 0.1`, `eff_gen = 0.9`, then calls `dissipationBeta(...)` | **Broken** — passes `eta_gen` (undefined; the variable set is `eff_gen`) and calls `dissipationBeta`, which is not defined anywhere in the repository |
| `Injection_run.m` | Parameter block, then calls `injectionBeta(...)` | **Broken** — `injectionBeta` is not defined anywhere in the repository; the defined function is `injection` |
| `Control_to_sell_and_buy.m` | 211 bytes | Stub |
Three of the five SHIFT files call functions (`dissipationBeta`, `injectionBeta`) that do not
exist in this repository. Only `run2.m` → `injection.m` is a runnable pair. The missing
`*Beta` functions were presumably a later iteration that never got committed here.
## Duplicate data files
`Team03_demand.csv` and `Team03_supply.csv` each exist **twice**, byte-identical:
| Path | MD5 |
|---|---|
| `EST-model-main/Team03_demand.csv` | `26553f17` |
| `EST-model-main/data/Team03_demand.csv` | `26553f17` |
| `EST-model-main/Team03_supply.csv` | `7ce0330e` |
| `EST-model-main/data/Team03_supply.csv` | `7ce0330e` |
0.65 MB each, so ~1.3 MB duplicated. `preprocessing.m` reads from the `data/` directory, so the
root-level copies are the redundant ones — but they are **inside the vendored subtree** and are
left untouched. Removing them would create a divergence from upstream for a 1.3 MB saving.
## `resources/project/` — machine-generated
Roughly 100 XML files with opaque hash names
(`8d6963sHFjo3KDafHny-kBqH4Ew/HzZAGbjCGV27z4vxUS7B-4SgGnAd.xml` and similar), organised into
hash-named directories with paired `…d.xml` / `…p.xml` files.
This is **MATLAB Project bookkeeping** — the metadata store behind `ModelDevelopment.prj`,
tracking file labels, dependencies, and project structure. It is machine-generated, unreadable,
and carries no documentation value. It is **not** documentation and is excluded from all
documentation indexes.
`ModelDevelopment.prj` itself is essentially empty:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<MATLABProject xmlns="http://www.mathworks.com/MATLABProjectFile"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"/>
```
## Disposition
Everything in this subtree is **kept in place**:
| Item | Why kept |
|---|---|
| Inner `EST-model-main/` | Pristine upstream, MIT-licensed — keeping it intact preserves attribution and the ability to diff against upstream |
| `versions/EST_R202*.slx` | Deliberate upstream compatibility exports, not stale drafts |
| Duplicate `Team03_*.csv` | Inside the vendored tree; divergence not worth 1.3 MB |
| `resources/project/**` | Machine-generated, but deleting it breaks the MATLAB Project |
| Outer stock `README.md` | Boilerplate, but it is upstream's file — flagged here instead of deleted |
| SHIFT's five `.m` files | Contain the reusable physics-based dissipation-coefficient idea |
The one thing worth adding is a short `NOTE.md` in `Exisiting EST Model/` recording the upstream
URL, the MIT licence, and the fact that three of the five SHIFT scripts reference undefined
functions — so the next person does not spend an afternoon discovering it.
## Related
- [Simulink Model Inventory](simulink-model-inventory.md) — SHIFT's own models
- [PV + Battery Simulink Model](pv-battery-simulink.md)
- [Work Packages](../01-project/work-packages.md) — WP3, simulation environment
Reference in a new issue View git blame Copy permalink