LH2-STM: Liquid Hydrogen Simplified Transfer Model

---

About this fork

This is a fork of Albert-Gil/LH2-STM, maintained by Muhammad Sami Khan for MSc thesis work on liquid hydrogen transfer modelling. All original modelling work is by Albert Gil-Esmendia; this fork adds only the minimum changes needed to run the model, plus a correction to two invalid initial conditions (see below).

Upstream is related to Gil-Esmendia, Flores & Brouwer, "Modeling and improving liquid hydrogen transfer processes", Applied Energy 390 (2025) 125779. Note that the paper implements a different codebase (LH2TransferModel, REFPROP-based, ODE-solved); LH2-STM is a simplified, CoolProp-based descendant with additional top-fill and station-level features.

Requirements

• MATLAB R2016b or newer (scripts use local functions); developed on R2026a
• Python 3.13.15 reachable from MATLAB via pyenv, with CoolProp 8.0.0 installed Verified with MATLAB R2026a on Windows 11. (py -m pip install CoolProp)
• No REFPROP licence required
• No MATLAB toolboxes required — base functions only

Verify the bridge before running (should return ≈ 20.2713):

pyenv
py.CoolProp.CoolProp.PropsSI('T','P',101325,'Q',0,'parahydrogen')

Set MATLAB's current folder to the repository root — STM_Main.m loads PrecoolingLoad.mat by relative path.

Baseline

The tag baseline-upstream marks the last unmodified upstream commit. To see every change made in this fork:

git diff baseline-upstream

Scope: 5 files changed, 1 file added, 13 modified lines.

Changes

Upstream did not run as published — STM_Main.m aborted at line 40 with a CoolProp ValueError. The following changes were made.

1. Queried critical-point constants (STM_Initialization.m)

Parahydrogen Tcrit, Pcrit and rhocrit are now queried from CoolProp at runtime rather than hardcoded. The upstream literal 32.938 sits above the true critical temperature (32.93785506891549 K) and makes any quality flash throw.

2. Repaired invalid catch fallbacks — no effect on results

Two upstream try/catch blocks had fallbacks that could not fall back: one called an invalid literal (32.938), the other repeated the failing call verbatim, so the error escaped and aborted the run. Fixed at STM_Simulation_Pump_Topfill.m 195, 212, 355, 373 and STM_Simulation_Pump.m 154, 171, 306, 323.

Safe on two independent grounds: these paths execute only at supercritical conditions where upstream crashes outright, and the assigned variables (VbulkCondDens, LbulkEvapDens) are never read anywhere in either file.

3. Guarded saturation-temperature calls — no effect on results

Upstream guarded the result of a PropsSI call (if Stemp >= 32.93) that throws before the guard can run. Added SatT_pH2.m, which checks the input pressure and clamps to Tcrit when supercritical. Applied at STM_Simulation_Pump_Topfill.m 328, 491, 499 and STM_Simulation_Pump.m 280, 433.

Below Pcrit this returns a bit-identical result to upstream. In the validated run the clamp never engaged at any timestep (find(T1.p >= H2PcritSafe, 1) returns empty).

4. Corrected ullage initial conditions — ⚠️ this does change results

STM_Parameters_Pump_TF.m lines 44 and 73:

Parameter	Upstream	This fork	Reason
T1.Vtempini	25 K	28 K	Tsat(4 bar) = 25.952 K — 25 K is subcooled liquid (64.658 kg/m³), not vapour (~4.24)
T2.Vtempini	50 K	31.5 K	Tcrit = 32.938 K — 50 K is supercritical, where saturation and condensation are undefined

Upstream initialised tank 1's ullage with roughly 15× too much mass. The model still ran to completion, producing plausible-looking figures while tank 1 oscillated between 5.6 and 20.7 bar and spent 2,564 of 2,581 steps on clamped values.

Unlike changes 1–3, this alters the simulated scenario. The original values were thermodynamically impossible so some change was unavoidable, but 28 K and 31.5 K are choices made here, not the author's. Any values within (25.95, 32.94) K and (30.56, 32.94) K are equally valid and give different results. Note that the upstream value of 50 K suggests a warm ullage was intended for tank 2, which at 9 bar is unachievable below the critical point — arguably T2.pinibar is the parameter that should move instead. Anyone reproducing this work should treat these two values as an open modelling decision.

A startup assertion in STM_Initialization.m now validates both against Tsat(p_ini) and Tcrit, so invalid values fail loudly rather than producing plausible output.

What is unchanged

No equation, correlation, balance, or solver structure was modified. The following are byte-identical to upstream: topfill.m, SubcooledJet_ConvCoeff.m, SubcooledJet_ConvCoeff_Incropera.m, VentFlow.m, both HorizontalCyl_*.m, cylVToH.m, vaporpressure.m, STM_Plots.m, STM_Main.m, and all parameter files other than STM_Parameters_Pump_TF.m.

Status

Working: pump-driven top-fill transfer (TopFill = 1, the default). Reference run — tank 1 decays smoothly 4.00 → 2.41 bar while draining; tank 2 vents in six cycles against its 10 bar limit (peak 10.05 bar); no clamping at any step.

Known issues, not yet addressed:

• Bottom-fill path (TopFill = 0) does not run. STM_Parameters_BF.m:102 tests an undefined Reliquefaction, and STM_Simulation_Pump.m:130 uses PumpMassTransferFast, which that parameter file never defines.
• Mass-balance closure not yet verified. The related paper closes its balances to within 0.9–1.7 %; this has not been checked here.
• Three hardcoded absolute paths in STM_Main.m (lines 16, 20, 24). Harmless while SavePlots, UpdateLog and SaveResults are 0.
• TotalVenting and RelativeVenting in STM_Plots.m (lines 16–17) are commented out and reference a data.Boiloff_ST structure that does not exist in this repository.
• SubcooledJet_ConvCoeff.m recomputes 100 Bessel roots on every call; these are constants and could be cached.
• topfill.m defines a function named topfill_v2; MATLAB dispatches on the filename so this works, but the code analyser flags it.

Licence

GPL-3.0, inherited from upstream. Original author: Albert Gil-Esmendia.

This repository contains a MATLAB-based simulation framework for modeling the thermodynamic and mass transfer behavior of liquid hydrogen (LH₂) refueling processes. It supports bottom-fill, top-fill, and pump-based transfer methods with detailed physics including venting, heat transfer, and condensation dynamics.

Features

• Modular and extensible 0D simulation framework
• Two-tank system (supply and receiver)
• Models wall-fluid and interface heat transfer
• Supports top-fill splash cooling and subcooled jet modeling
• Integrates CoolProp (via Python) for accurate hydrogen properties
• Results exportable to .txt/.xls format with automatic logging
• Generates plots for pressure, temperature, mass flow, venting

Folder Structure

• STM_Main.m: Main script to run simulations
• STM_Parameters_*.m: Define parameter sets (Pump, Top-fill, etc.)
• STM_Simulation_*.m: Simulation scripts for each configuration
• STM_Plots.m: Visualization tool for key outputs
• STM_Initialization.m: Initializes variables and vectors
• SubcooledJet_ConvCoeff.m: Computes h for splash-cooling jets
• VentFlow.m: Models venting flow rate

How to Run

1. Set up parameters in one of the STM_Parameters_*.m files.
2. Run STM_Main.m.
3. View plots and results in the output folder.

Dependencies

• MATLAB
• CoolProp (accessed via Python integration)

Licensing

This project is licensed under the GPL-3.0 License.

Authors

• Albert Gil, University of California, Irvine (PhD Research)