Metadata-Version: 2.5
Name: degali
Version: 0.1.0
Summary: Dense Gas Dispersion for Liquid Hydrogen, built on a verified DEGADIS 2.1 reimplementation
Project-URL: Source, https://github.com/lyullee/degali
Project-URL: Documentation, https://github.com/lyullee/degali#readme
Project-URL: Changelog, https://github.com/lyullee/degali/blob/main/CHANGELOG.md
Author: Ugwiyeon Lee
License: MIT License
        
        Copyright (c) 2026 degali contributors
        
        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.
        
        ---
        
        DEGADIS 2.1, on which this work is based, was developed by Thomas O. Spicer
        and Jerry A. Havens at the University of Arkansas under US Coast Guard
        contract DT-CG-23-80-C-20029, with subsequent support from the Gas Research
        Institute, the American Petroleum Institute and the US Environmental
        Protection Agency. The original source is in the public domain and is
        distributed by EPA through SCRAM. Copies of it are included under
        reference/fortran for validation purposes.
License-File: LICENSE
Keywords: DEGADIS,LNG,consequence modelling,cryogenic hydrogen,dense gas,dispersion,heavy gas,liquid hydrogen,process safety
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 :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Provides-Extra: coolprop
Requires-Dist: coolprop>=6.4; extra == 'coolprop'
Provides-Extra: test
Requires-Dist: coolprop>=6.4; extra == 'test'
Requires-Dist: openpyxl>=3.1; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Requires-Dist: pyyaml>=6; extra == 'test'
Description-Content-Type: text/markdown

# DEGALI — Dense Gas Dispersion for Liquid Hydrogen

DEGALI stands for **Dense Gas Dispersion for Liquid Hydrogen**. It is a modern
Python model built from a verified reimplementation of the US EPA DEGADIS 2.1
dense-gas dispersion model and extended for cryogenic hydrogen releases.

> **Alpha research software.** The DEGADIS 2.1 compatibility path is strongly
> regression-tested. The liquid-hydrogen extensions are suitable for research,
> scenario comparison and sensitivity studies, but are not independently
> certified for regulatory separation distances or safety-critical design.

한국어 요약: 현재 공개본은 원본 DEGADIS 재현 경로와 액화수소 연구 확장을
함께 제공합니다. PRESLHY 수평 야외제트 범위에서 정량 비교를 마쳤지만,
미완성 TKE/압력/열폭 폐쇄와 제한된 독립 검증 때문에 설비 인허가 판단의
단독 근거로 사용하면 안 됩니다. 자세한 판정은
[1차 결과](docs/stage1-results-2026-09-06.md)를 참고하십시오.

## What is included

- Python ports of all six DEGADIS 2.1 programs. The independently obtained
  Fortran oracle is retained locally and is not redistributed.
- Steady, transient, receptor-dose and jet-to-ground workflows.
- Legacy and modern thermodynamic backends.
- Opt-in LH2 source flashing, buoyant trajectory, air condensation/freezing,
  component enthalpy, ground interaction and thermal-profile research paths.
- Experimental finite-TKE, independent thermal-width and Reynolds-stress
  operators. These are deliberately marked as research-only until their
  physical closure inputs and downstream field performance are validated.

## Current evidence

The port reproduces the five EPA reference cases and was checked locally
against a source-built Fortran implementation. The first frozen LH2 assessment uses
seven horizontal outdoor PRESLHY trials, 38 concentration sections, 17
vertical profiles and 41 temperature sensors.

| Quantity | Current provided path |
|---|---:|
| Concentration MG (observed/predicted; ideal 1) | 1.102 |
| Concentration VG (ideal 1) | 1.233 |
| Concentration FAC2 | 36/38 |
| Vertical width, predicted/measured | 1.091 |
| Plume-centre MAE | 0.054 m |
| Minimum-temperature MAE | 27.25 K |

An opt-in thermal-profile candidate lowers minimum-temperature MAE to 16.47 K
but worsens other acceptance metrics, so it is not the default. These samples
are correlated observations from one campaign, not 38 or 41 independent
validation experiments.

See [model status](docs/stage1-results-2026-09-06.md),
[claim grading](docs/claim-grading.md), and
[data/reproduction notes](docs/DATA_AND_REPRODUCTION.md).

## Installation

Create a Python 3.10 or newer environment and install from a clone:

```bash
python -m pip install -e ".[test]"
```

CoolProp is optional for the DEGADIS 2.1 compatibility path and required for
most cryogenic-hydrogen calculations:

```bash
python -m pip install -e ".[coolprop]"
```

## Quick start

```python
from degali import run_steady, run_transient, run_jet_to_ground

profile, source = run_steady("B9.INP")
print(profile.distance_to(0.05))

transient = run_transient("B9T.INP")
profile, jet, source = run_jet_to_ground("EX2.INO", "EX2.IN")
```

The command-line interface exposes the same main workflows:

```bash
degali steady B9.INP
degali transient B9T.INP --snapshot 60 --snapshot 120
degali dose B9T.INP --at 200 --at 400 --at 800
degali jet EX2.INO --bridge EX2.IN
```

## Verification

Fast development checks:

```bash
python -m pytest -m "not slow" -q
```

The original Fortran oracle and raw REDIPHEM, SMEDIS and PRESLHY files are not
redistributed. Tests that need
them skip with an explicit message unless the documented environment variables
are configured. Their provenance, reduction method and aggregate validation
results are documented. See [publication scope](docs/publication-scope.md).

The consolidated [technical reference](docs/technical-reference.md) describes
the governing physics, LH2 extensions, validation process, quantitative
results and remaining model-form limitations.

## Repository layout

```text
src/degali/  model and validation code
tests/       self-contained numerical, physical and regression tests
tools/       research and release verification utilities
docs/        derivations, provenance, audits, limitations and results
```

## Scope and safety

The current validated domain does not cover arbitrary equipment conditions,
obstacles, indoor releases, pool spreading, downward/strongly wind-steered
jets, or general transient source behaviour. Always compare safety-critical
results with independent experiments and an accepted consequence-analysis
workflow. See [security and safety reporting](SECURITY.md).

## Citation and license

Citation metadata are provided in [`CITATION.cff`](CITATION.cff). Zenodo's
GitHub integration assigns the DOI after the first release; the DOI is added
to the citation metadata in the first post-release metadata update.

The complete GitHub, Zenodo DOI and PyPI release sequence is documented in the
[publication guide](docs/publication-guide.md).

The DEGALI Python implementation is available under the MIT License. Original
Fortran implementations and external experimental datasets are not bundled or
redistributed.

The chronological development log that previously occupied this front page is
preserved in [docs/README-development-log-2026-09-06.md](docs/README-development-log-2026-09-06.md)
and [CHANGELOG.md](CHANGELOG.md).
