lh2poolx 0.1.0__tar.gz

lh2poolx-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+build/
+dist/

lh2poolx-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — 2026-09-09
+
+- First public release.
+- Isenthalpic LH2 flash with CoolProp.
+- Explicit deposition fraction and quasi-steady ground-conduction source term.
+- Confined-pool accumulation status to prevent use as an unqualified steady source.
+- Optional adapters supplied by SLABx and DEGADISx; no dispersion model is a dependency.

lh2poolx-0.1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use LH2PoolX, please cite this software and the experimental sources underlying your analysis."
+title: "LH2PoolX"
+version: 0.1.0
+date-released: 2026-09-09
+authors:
+  - family-names: Lee
+    given-names: Ugwiyeon
+license: MIT
+repository-code: "https://github.com/lyullee/lh2poolx"

lh2poolx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ugwiyeon Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lh2poolx-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: lh2poolx
+Version: 0.1.0
+Summary: Transparent liquid-hydrogen pool source terms for dispersion models
+Project-URL: Source, https://github.com/lyullee/lh2poolx
+Project-URL: Documentation, https://github.com/lyullee/lh2poolx#readme
+Author: Ugwiyeon Lee
+License: MIT License
+        
+        Copyright (c) 2026 Ugwiyeon Lee
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: LH2,liquid hydrogen,pool evaporation,process safety,source term
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: coolprop>=6.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# LH2PoolX
+
+LH2PoolX calculates an **evidence-qualified, quasi-steady liquid-hydrogen
+pool source term** for a declared time window.  It is an upstream input module
+for dispersion models, not a dispersion model and not a general jet-impact or
+pool-spreading solver.
+
+## What it calculates
+
+For a specified release rate, storage pressure, elapsed time, substrate and
+ground-deposition fraction, LH2PoolX calculates:
+
+1. isenthalpic flash fraction using CoolProp;
+2. liquid mass reaching the ground;
+3. heat-limited evaporation flux using a semi-infinite ground-conduction
+   relation with an LH2 critical-heat-flux cap; and
+4. the unconfined equilibrium pool area and evaporation rate.
+
+`deposition_fraction` is deliberately explicit.  The package does **not**
+predict impingement, splashing, droplet transport, drainage, barriers, or
+transient pool spreading.  A confined result reports liquid accumulation and
+must not be used as a steady source without a separate inventory model.
+
+## Install
+
+```bash
+pip install lh2poolx
+```
+
+## Minimal use
+
+```python
+from lh2poolx import LH2Release, evaluate_pool_source
+
+release = LH2Release(rate_kg_s=0.1055, storage_pressure_barg=1.0)
+source = evaluate_pool_source(release, elapsed_s=300.0)
+print(source.area_m2, source.evaporation_rate_kg_s)
+```
+
+## Evidence boundary
+
+The concrete heat-transfer implementation is checked against the four
+published PRESLHY E3.4 Concrete02 mass-loss windows.  That comparison is a
+restricted substrate-and-condition check, not validation for other substrates
+or for jet-to-ground deposition.  Literature supports the physical form of
+the source chain; it does not turn unknown deposition into a fitted value.
+
+## License
+
+MIT.  Cite the accompanying software record when one is released, plus the
+underlying experimental and heat-transfer sources used in an analysis.

lh2poolx-0.1.0/README.md

@@ -0,0 +1,51 @@
+# LH2PoolX
+
+LH2PoolX calculates an **evidence-qualified, quasi-steady liquid-hydrogen
+pool source term** for a declared time window.  It is an upstream input module
+for dispersion models, not a dispersion model and not a general jet-impact or
+pool-spreading solver.
+
+## What it calculates
+
+For a specified release rate, storage pressure, elapsed time, substrate and
+ground-deposition fraction, LH2PoolX calculates:
+
+1. isenthalpic flash fraction using CoolProp;
+2. liquid mass reaching the ground;
+3. heat-limited evaporation flux using a semi-infinite ground-conduction
+   relation with an LH2 critical-heat-flux cap; and
+4. the unconfined equilibrium pool area and evaporation rate.
+
+`deposition_fraction` is deliberately explicit.  The package does **not**
+predict impingement, splashing, droplet transport, drainage, barriers, or
+transient pool spreading.  A confined result reports liquid accumulation and
+must not be used as a steady source without a separate inventory model.
+
+## Install
+
+```bash
+pip install lh2poolx
+```
+
+## Minimal use
+
+```python
+from lh2poolx import LH2Release, evaluate_pool_source
+
+release = LH2Release(rate_kg_s=0.1055, storage_pressure_barg=1.0)
+source = evaluate_pool_source(release, elapsed_s=300.0)
+print(source.area_m2, source.evaporation_rate_kg_s)
+```
+
+## Evidence boundary
+
+The concrete heat-transfer implementation is checked against the four
+published PRESLHY E3.4 Concrete02 mass-loss windows.  That comparison is a
+restricted substrate-and-condition check, not validation for other substrates
+or for jet-to-ground deposition.  Literature supports the physical form of
+the source chain; it does not turn unknown deposition into a fitted value.
+
+## License
+
+MIT.  Cite the accompanying software record when one is released, plus the
+underlying experimental and heat-transfer sources used in an analysis.

lh2poolx-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lh2poolx"
+version = "0.1.0"
+description = "Transparent liquid-hydrogen pool source terms for dispersion models"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Ugwiyeon Lee" }]
+keywords = ["liquid hydrogen", "LH2", "pool evaporation", "source term", "process safety"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = ["CoolProp>=6.5"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Source = "https://github.com/lyullee/lh2poolx"
+Documentation = "https://github.com/lyullee/lh2poolx#readme"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "CITATION.cff"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lh2poolx"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

lh2poolx-0.1.0/src/lh2poolx/__init__.py

@@ -0,0 +1,19 @@
+"""Evidence-qualified LH2 pool source terms for dispersion-model inputs."""
+
+from .pool import (
+    CONCRETE_CRYOGENIC,
+    CRITICAL_HEAT_FLUX_W_M2,
+    LH2Release,
+    PoolSource,
+    Substrate,
+    evaluate_pool_source,
+    flash_vapour_fraction,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__", "CONCRETE_CRYOGENIC", "CRITICAL_HEAT_FLUX_W_M2",
+    "LH2Release", "PoolSource", "Substrate", "evaluate_pool_source",
+    "flash_vapour_fraction",
+]

lh2poolx-0.1.0/src/lh2poolx/pool.py

@@ -0,0 +1,148 @@
+"""Quasi-steady LH2 pool source terms with explicit evidence boundaries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+
+import CoolProp.CoolProp as CP
+
+
+CRITICAL_HEAT_FLUX_W_M2 = 120e3
+
+
+@dataclass(frozen=True)
+class Substrate:
+    """Effective cryogenic substrate properties for the stated evidence case."""
+
+    name: str
+    conductivity_W_mK: float
+    diffusivity_m2_s: float
+
+
+# PRESLHY E3.4 Concrete02 effective cryogenic properties.  Do not use this as
+# a generic concrete correlation without an explicit applicability decision.
+CONCRETE_CRYOGENIC = Substrate("concrete_cryogenic_e34", 2.0, 2.5e-7)
+
+
+@dataclass(frozen=True)
+class LH2Release:
+    """Declared inputs for an LH2 release reaching a possible ground pool."""
+
+    rate_kg_s: float
+    storage_pressure_barg: float
+    deposition_fraction: float = 1.0
+    max_radius_m: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.rate_kg_s <= 0.0:
+            raise ValueError("rate_kg_s must be > 0")
+        if self.storage_pressure_barg < 0.0:
+            raise ValueError("storage_pressure_barg must be >= 0")
+        if not 0.0 <= self.deposition_fraction <= 1.0:
+            raise ValueError("deposition_fraction must be in [0, 1]")
+        if self.max_radius_m is not None and self.max_radius_m <= 0.0:
+            raise ValueError("max_radius_m must be > 0 when supplied")
+
+
+@dataclass(frozen=True)
+class PoolSource:
+    """A source term for one declared time window, not a pool trajectory."""
+
+    elapsed_s: float
+    flash_vapour_fraction: float
+    deposition_fraction: float
+    liquid_to_ground_kg_s: float
+    pool_temperature_K: float
+    latent_heat_J_kg: float
+    evaporative_flux_kg_m2_s: float
+    unconfined_radius_m: float
+    radius_m: float
+    area_m2: float
+    evaporation_rate_kg_s: float
+    liquid_accumulation_rate_kg_s: float
+    confined: bool
+    source_status: str
+
+
+def flash_vapour_fraction(storage_pressure_barg: float, *,
+                          ambient_pressure_Pa: float = 101325.0) -> float:
+    """Isenthalpic saturated-liquid LH2 flash fraction at ambient pressure."""
+    if storage_pressure_barg < 0.0:
+        raise ValueError("storage_pressure_barg must be >= 0")
+    p0 = storage_pressure_barg * 1e5 + ambient_pressure_Pa
+    if p0 >= CP.PropsSI("Pcrit", "Hydrogen"):
+        raise ValueError("storage pressure is at or above H2 critical pressure")
+    h0 = CP.PropsSI("H", "P", p0, "Q", 0, "Hydrogen")
+    x = CP.PropsSI("Q", "P", ambient_pressure_Pa, "H", h0, "Hydrogen")
+    return min(max(float(x), 0.0), 1.0)
+
+
+def _ground_flux(*, substrate: Substrate, latent_heat_J_kg: float,
+                 ambient_temperature_K: float, pool_temperature_K: float,
+                 elapsed_s: float,
+                 critical_heat_flux_W_m2: float | None) -> float:
+    if elapsed_s <= 0.0:
+        raise ValueError("elapsed_s must be > 0")
+    if latent_heat_J_kg <= 0.0:
+        raise ValueError("latent_heat_J_kg must be > 0")
+    if critical_heat_flux_W_m2 is not None and critical_heat_flux_W_m2 <= 0.0:
+        raise ValueError("critical_heat_flux_W_m2 must be > 0 or None")
+    delta_T = ambient_temperature_K - pool_temperature_K
+    if delta_T <= 0.0:
+        return 0.0
+    q = substrate.conductivity_W_mK * delta_T / math.sqrt(
+        math.pi * substrate.diffusivity_m2_s * elapsed_s
+    )
+    if critical_heat_flux_W_m2 is not None:
+        q = min(q, critical_heat_flux_W_m2)
+    return q / latent_heat_J_kg
+
+
+def evaluate_pool_source(release: LH2Release, *, elapsed_s: float,
+                         substrate: Substrate = CONCRETE_CRYOGENIC,
+                         ambient_temperature_K: float = 282.0,
+                         ambient_pressure_Pa: float = 101325.0,
+                         critical_heat_flux_W_m2: float | None =
+                         CRITICAL_HEAT_FLUX_W_M2) -> PoolSource:
+    """Calculate a quasi-steady pool source for one elapsed-time window.
+
+    The pool area instantaneously balances the declared liquid-to-ground rate
+    against heat-limited evaporation.  This is appropriate only after a pool
+    exists and where a quasi-steady source approximation is justified.
+    """
+    x = flash_vapour_fraction(release.storage_pressure_barg,
+                              ambient_pressure_Pa=ambient_pressure_Pa)
+    T_pool = float(CP.PropsSI("T", "P", ambient_pressure_Pa, "Q", 0,
+                              "Hydrogen"))
+    latent = float(CP.PropsSI("H", "P", ambient_pressure_Pa, "Q", 1,
+                              "Hydrogen") - CP.PropsSI(
+                                  "H", "P", ambient_pressure_Pa, "Q", 0,
+                                  "Hydrogen"))
+    flux = _ground_flux(
+        substrate=substrate, latent_heat_J_kg=latent,
+        ambient_temperature_K=ambient_temperature_K,
+        pool_temperature_K=T_pool, elapsed_s=elapsed_s,
+        critical_heat_flux_W_m2=critical_heat_flux_W_m2,
+    )
+    liquid_to_ground = release.rate_kg_s * (1.0 - x) * release.deposition_fraction
+    radius_unconfined = (0.0 if liquid_to_ground == 0.0 else math.sqrt(
+        liquid_to_ground / (math.pi * flux)))
+    radius = radius_unconfined if release.max_radius_m is None else min(
+        radius_unconfined, release.max_radius_m)
+    area = math.pi * radius * radius
+    evaporation = area * flux
+    confined = (release.max_radius_m is not None and
+                 radius_unconfined > release.max_radius_m)
+    return PoolSource(
+        elapsed_s=elapsed_s, flash_vapour_fraction=x,
+        deposition_fraction=release.deposition_fraction,
+        liquid_to_ground_kg_s=liquid_to_ground, pool_temperature_K=T_pool,
+        latent_heat_J_kg=latent, evaporative_flux_kg_m2_s=flux,
+        unconfined_radius_m=radius_unconfined, radius_m=radius, area_m2=area,
+        evaporation_rate_kg_s=evaporation,
+        liquid_accumulation_rate_kg_s=max(liquid_to_ground - evaporation, 0.0),
+        confined=confined,
+        source_status=("quasi_steady_equilibrium" if not confined else
+                       "confined_pool_requires_inventory_model"),
+    )

lh2poolx-0.1.0/tests/test_pool.py

@@ -0,0 +1,35 @@
+import math
+
+import pytest
+
+from lh2poolx import LH2Release, evaluate_pool_source, flash_vapour_fraction
+
+
+def test_flash_rises_with_storage_pressure():
+    values = [flash_vapour_fraction(p) for p in (0.8, 2.0, 6.0)]
+    assert values[0] < values[1] < values[2]
+
+
+def test_unconfined_source_closes_the_mass_balance():
+    source = evaluate_pool_source(LH2Release(0.1055, 1.0), elapsed_s=300.0)
+    assert source.source_status == "quasi_steady_equilibrium"
+    assert source.evaporation_rate_kg_s == pytest.approx(
+        source.liquid_to_ground_kg_s)
+
+
+def test_radius_scales_with_deposition_fraction():
+    full = evaluate_pool_source(LH2Release(0.1055, 1.0, 1.0), elapsed_s=300.0)
+    quarter = evaluate_pool_source(LH2Release(0.1055, 1.0, 0.25), elapsed_s=300.0)
+    assert quarter.radius_m / full.radius_m == pytest.approx(0.5)
+
+
+def test_confinement_reports_accumulation():
+    source = evaluate_pool_source(LH2Release(9.5, 0.1, max_radius_m=0.5),
+                                  elapsed_s=300.0)
+    assert source.confined
+    assert source.liquid_accumulation_rate_kg_s > 0.0
+
+
+def test_bad_deposition_fraction_is_rejected():
+    with pytest.raises(ValueError):
+        LH2Release(1.0, 1.0, 1.1)