degadisx 0.1.0__tar.gz

degadisx-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

degadisx-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+reference/
+*.pdf
+*.xls
+*.xlsx
+*.csv
+*.dbf

degadisx-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 — 2026-09-07
+
+- First public release of the legacy DEGADIS 2.1 Python reimplementation.
+- Separates the original-model route from non-public DEGALI/LH2 research extensions.
+- Records reproducibility evidence without redistributing EPA reference material or experimental data.

degadisx-0.1.0/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use DEGADISx, please cite it and the original EPA DEGADIS 2.1 report."
+title: "DEGADISx: a Python reimplementation of EPA DEGADIS 2.1"
+version: 0.1.0
+date-released: 2026-09-07
+authors:
+  - family-names: Lee
+    given-names: Ugwiyeon
+license: MIT
+repository-code: "https://github.com/lyullee/degadisx"
+references:
+  - type: report
+    authors:
+      - family-names: Spicer
+        given-names: Thomas O.
+      - family-names: Havens
+        given-names: Jerry A.
+    title: "User’s Guide for the DEGADIS 2.1 Dense Gas Dispersion Model"
+    institution: "U.S. Environmental Protection Agency"
+    number: "EPA-450/4-89-019"
+    year: 1989

degadisx-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Contributions should preserve the public scope: the legacy DEGADIS 2.1 route only. Do not add proprietary, experimental, or third-party reference inputs/outputs without documented redistribution permission. New numerical changes should state whether they preserve reference behaviour and include a public, synthetic test where possible.

degadisx-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+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.

degadisx-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: degadisx
+Version: 0.1.0
+Summary: A Python reimplementation of EPA DEGADIS 2.1
+Project-URL: Source, https://github.com/lyullee/degadisx
+Project-URL: Documentation, https://github.com/lyullee/degadisx#readme
+Project-URL: Changelog, https://github.com/lyullee/degadisx/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,consequence modelling,dense gas,dispersion,process safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# DEGADISx
+
+**DEGADISx** is a Python reimplementation of the U.S. EPA **DEGADIS 2.1** dense-gas dispersion model. Its public interface deliberately retains the legacy DEGADIS thermodynamic and numerical route; it is not an LH2 extension and does not contain DEGALI research modules.
+
+## Scope
+
+DEGADISx provides the original model's ground-level steady and transient routes, pressurised-jet route, deck readers, and bridge from jet touchdown to the ground-level model. It is intended for transparent reproduction, software inspection, and research use. It is not a substitute for site-specific consequence-model selection or safety engineering review.
+
+## Install
+
+```bash
+pip install degadisx
+```
+
+From a checkout:
+
+```bash
+pip install .
+degadisx --help
+```
+
+## Reproduction evidence and data policy
+
+The implementation was checked against the EPA DEGADIS 2.1 reference distribution and published EPA benchmark listings. The quantitative audit, its limits, and exact source locations are in [docs/reproduction.md](docs/reproduction.md).
+
+This repository deliberately contains **no** third-party Fortran source, EPA input/output decks, experimental measurements, reduced observation data, or PDFs. See [docs/data-policy.md](docs/data-policy.md).
+
+## Citation
+
+Please cite both this software (see [CITATION.cff](CITATION.cff)) and the original model:
+
+> Spicer, T. O., and Havens, J. A. (1989). *User’s Guide for the DEGADIS 2.1 Dense Gas Dispersion Model*. U.S. Environmental Protection Agency, EPA-450/4-89-019.
+
+## License
+
+The Python implementation is MIT licensed. DEGADIS is cited as the original model; the original Fortran distribution and source materials are not redistributed here.

degadisx-0.1.0/README.md

@@ -0,0 +1,36 @@
+# DEGADISx
+
+**DEGADISx** is a Python reimplementation of the U.S. EPA **DEGADIS 2.1** dense-gas dispersion model. Its public interface deliberately retains the legacy DEGADIS thermodynamic and numerical route; it is not an LH2 extension and does not contain DEGALI research modules.
+
+## Scope
+
+DEGADISx provides the original model's ground-level steady and transient routes, pressurised-jet route, deck readers, and bridge from jet touchdown to the ground-level model. It is intended for transparent reproduction, software inspection, and research use. It is not a substitute for site-specific consequence-model selection or safety engineering review.
+
+## Install
+
+```bash
+pip install degadisx
+```
+
+From a checkout:
+
+```bash
+pip install .
+degadisx --help
+```
+
+## Reproduction evidence and data policy
+
+The implementation was checked against the EPA DEGADIS 2.1 reference distribution and published EPA benchmark listings. The quantitative audit, its limits, and exact source locations are in [docs/reproduction.md](docs/reproduction.md).
+
+This repository deliberately contains **no** third-party Fortran source, EPA input/output decks, experimental measurements, reduced observation data, or PDFs. See [docs/data-policy.md](docs/data-policy.md).
+
+## Citation
+
+Please cite both this software (see [CITATION.cff](CITATION.cff)) and the original model:
+
+> Spicer, T. O., and Havens, J. A. (1989). *User’s Guide for the DEGADIS 2.1 Dense Gas Dispersion Model*. U.S. Environmental Protection Agency, EPA-450/4-89-019.
+
+## License
+
+The Python implementation is MIT licensed. DEGADIS is cited as the original model; the original Fortran distribution and source materials are not redistributed here.

degadisx-0.1.0/SECURITY.md

@@ -0,0 +1,3 @@
+# Security policy
+
+Please report security issues privately to the repository owner rather than opening a public issue with exploitable details.

degadisx-0.1.0/docs/data-policy.md

@@ -0,0 +1,10 @@
+# Data and redistribution policy
+
+DEGADISx publishes implementation code and a concise reproduction audit only. It does **not** publish or package:
+
+- original DEGADIS Fortran source or binaries;
+- EPA example decks or output listings;
+- experimental concentration, meteorological, or source-term data;
+- reduced experimental data, figures derived from them, or third-party PDFs.
+
+Where provenance is needed, this repository provides bibliographic citations and source locations rather than copies of the materials. Downstream contributions must follow the same rule unless the contributor has confirmed that redistribution is permitted.

degadisx-0.1.0/docs/reproduction.md

@@ -0,0 +1,21 @@
+# Reproduction audit
+
+## What was checked
+
+DEGADISx was audited against a locally obtained EPA DEGADIS 2.1 reference distribution and its published benchmark listings. The audit has two distinct layers:
+
+1. **Reference executable versus EPA listings.** Five EPA examples were replayed: B9 steady, B9 transient, EX1, EX2, and EX3. The steady and jet/listing cases reproduced all non-timestamp listing lines. The transient B9 listing had eight differences confined to seventh-significant-digit numerical formatting.
+2. **Python implementation versus source-built reference executable.** Input-deck scalars and density-table values matched exactly; scalar thermodynamic and closure checks differed only at floating-point round-off. At driver level, the original adaptive integration and loose tolerance conventions produce documented non-bitwise differences: step sequences were within 6e-10 relative for the DEG1 check, and representative profile/handoff values within 1e-6. Some full-driver concentration outputs differed by up to about 3%, depending on quantity, because the original implementation intentionally retains coarse internal tolerances (including `ADDHEAT` settings).
+
+These are reproduction checks, not experimental validation. No claim is made that all outputs are bit-identical or that the software is valid outside the original model's assumptions.
+
+## Materials not redistributed
+
+The reference Fortran code, EPA example input decks, EPA output listings, compiled executables, and all third-party data were used only in the local audit. They are excluded from this repository and its source/wheel distributions. A user wishing to repeat the independent oracle comparison must obtain the materials from their original rightsholder/source.
+
+## Primary sources
+
+- Spicer, T. O., and Havens, J. A. (1989). *User’s Guide for the DEGADIS 2.1 Dense Gas Dispersion Model*. U.S. EPA, EPA-450/4-89-019.
+- U.S. EPA Support Center for Regulatory Atmospheric Modeling (SCRAM), historical **DEGADIS 2.1** distribution and example materials. Access path: https://www.epa.gov/scram.
+
+The citation is retained for provenance. The source files themselves are not supplied by DEGADISx.

degadisx-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "degadisx"
+version = "0.1.0"
+description = "A Python reimplementation of EPA DEGADIS 2.1"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Ugwiyeon Lee" }]
+keywords = ["DEGADIS", "dense gas", "dispersion", "consequence modelling", "process safety"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = ["numpy>=1.23", "scipy>=1.10"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+degadisx = "degadisx.cli:main"
+
+[project.urls]
+Source = "https://github.com/lyullee/degadisx"
+Documentation = "https://github.com/lyullee/degadisx#readme"
+Changelog = "https://github.com/lyullee/degadisx/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/degadisx"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "tools", "docs", "README.md", "LICENSE", "CHANGELOG.md", "CITATION.cff", "CONTRIBUTING.md", "SECURITY.md", ".gitattributes"]
+exclude = ["**/*.pdf", "**/*.xls", "**/*.xlsx", "**/*.csv", "**/*.dbf", "reference/**"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

degadisx-0.1.0/src/degadisx/__init__.py

@@ -0,0 +1,26 @@
+"""DEGADISx: a Python reimplementation of EPA DEGADIS 2.1.
+
+DEGADISx is deliberately a *legacy-model* package. It exposes the original
+DEGADIS 2.1 modelling route and its documented numerical conventions; it does
+not include the separate DEGALI liquid-hydrogen research extensions.
+"""
+
+__version__ = "0.1.0"
+
+from .run import (
+    Receptor,
+    SourceResult,
+    TransientOutput,
+    run_jet,
+    run_jet_to_ground,
+    run_source,
+    run_steady,
+    run_transient,
+)
+
+__all__ = [
+    "__version__",
+    "Receptor", "SourceResult", "TransientOutput",
+    "run_source", "run_steady", "run_transient", "run_jet",
+    "run_jet_to_ground",
+]

degadisx-0.1.0/src/degadisx/cli.py

@@ -0,0 +1,84 @@
+"""Command-line interface for the legacy DEGADIS 2.1 route."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from .run import Receptor, run_jet, run_jet_to_ground, run_steady, run_transient
+
+
+def _profile_table(rows: np.ndarray, limit: int = 20) -> str:
+    head = f"{'dist (m)':>10} {'mole frac':>11} {'kg/m3':>11} {'T (K)':>8} {'Sz (m)':>8} {'Sy (m)':>8}"
+    step = max(1, len(rows) // limit)
+    lines = [head, "-" * len(head)]
+    for r in rows[::step]:
+        lines.append(f"{r[0]:10.4g} {r[2]:11.4g} {r[3]:11.4g} {r[5]:8.1f} {r[7]:8.3g} {r[8]:8.3g}")
+    return "\n".join(lines)
+
+
+def _cmd_steady(args) -> int:
+    profile, src = run_steady(args.deck, er1=args.er1, er2=args.er2)
+    gas = src.case.gas
+    print(f"Steady release: {gas.name}, {src.blanket.ess:.4g} kg/s [DEGADIS 2.1 legacy properties]")
+    print(f"  wind-profile exponent alpha = {src.alpha:.5f}")
+    print(f"  profile: {len(profile.rows)} points; transition at {profile.transition:.4g} m")
+    for name, level in (("upper", gas.ulc), ("lower", gas.llc)):
+        d = profile.distance_to(level)
+        shown = "not reached" if np.isnan(d) else f"{d:.4g} m"
+        print(f"  distance to the {name} level of concern ({level * 100:.4g} mol %): {shown}")
+    print("\n" + _profile_table(profile.rows))
+    return 0
+
+
+def _cmd_transient(args) -> int:
+    times = np.array(args.snapshot, dtype=float) if args.snapshot else None
+    out = run_transient(args.deck, er1=args.er1, er2=args.er2, times=times)
+    print(f"Transient release: {out.source.case.gas.name}, {len(out.field.observers)} observers, {len(out.snapshots)} snapshots")
+    for snap in out.snapshots:
+        print(f"t={snap.time:.4g} s; extent={snap.column('dist')[-1]:.4g} m; peak={snap.column('yc').max():.5g}")
+    return 0
+
+
+def _cmd_dose(args) -> int:
+    out = run_transient(args.deck, er1=args.er1, er2=args.er2)
+    for history in out.dose([Receptor(x=x) for x in args.at]):
+        peak, time = history.peak
+        print(f"x={history.receptor.x:.4g} m; peak={peak:.5g} at {time:.4g} s; dose={history.dose():.5g}")
+    return 0
+
+
+def _cmd_jet(args) -> int:
+    if args.bridge is None:
+        jet, deck = run_jet(args.deck)
+        print(f"Jet release: {deck.erate:.4g} kg/s; touchdown={jet.touchdown}")
+        return 0
+    profile, jet, _src = run_jet_to_ground(args.deck, args.bridge, er1=args.er1, er2=args.er2)
+    print(f"Jet release: touchdown at {jet.distance:.5g} m\n" + _profile_table(profile.rows))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="degadisx", description="DEGADISx — EPA DEGADIS 2.1 legacy reimplementation")
+    sub = parser.add_subparsers(dest="command", required=True)
+    def common(command, help_text):
+        command.add_argument("deck", type=Path, help=help_text)
+        command.add_argument("--er1", type=Path, help="source-model parameter file")
+        command.add_argument("--er2", type=Path, help="downwind parameter file")
+    steady = sub.add_parser("steady", help="steady ground-level release"); common(steady, "the .INP input deck"); steady.set_defaults(func=_cmd_steady)
+    transient = sub.add_parser("transient", help="unsteady ground-level release"); common(transient, "the .INP input deck"); transient.add_argument("--snapshot", type=float, action="append"); transient.set_defaults(func=_cmd_transient)
+    dose = sub.add_parser("dose", help="concentration history at fixed receptors"); common(dose, "the .INP input deck"); dose.add_argument("--at", type=float, action="append", required=True); dose.set_defaults(func=_cmd_dose)
+    jet = sub.add_parser("jet", help="pressurised release"); common(jet, "the .INO jet deck"); jet.add_argument("--bridge", type=Path); jet.set_defaults(func=_cmd_jet)
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (ValueError, RuntimeError) as exc:
+        print(f"degadisx: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

degadisx-0.1.0/src/degadisx/core/__init__.py

@@ -0,0 +1,71 @@
+"""Physics and numerics of the DEGADIS model."""
+
+from .atmosphere import (
+    StabilityDefaults,
+    absolute_humidity,
+    ambient_density,
+    fit_alpha,
+    friction_velocity,
+    psi,
+    richardson_star,
+    richardson_thermal,
+    stability_defaults,
+    wind_log,
+    wind_power,
+)
+from .blanket import Blanket, BlanketParameters, BlanketResult, BlanketState
+from .crfg import SourceVectors, build_source_vectors
+from .dose import DoseHistory, DoseRun, Receptor, receptor_times
+from .downwind import Downwind, DownwindConstants, DownwindState, series
+from .driver import DriverParameters, SourceRun
+from .entrainment import entrainment_velocity, phi, phi_hat, surface_exchange
+from .jetplume import JetCoefficients, JetPlume, JetResult, JetState, ellipse
+from .observer import (
+    Observer,
+    ObserverKinematics,
+    ObserverState,
+    crossing_downwind,
+    crossing_upwind,
+    release_times,
+)
+from .steady import Profile, SteadyStateRun
+from .szf import LayerState, sigma_z_over_source
+from .thermo import (
+    AdiabaticTable,
+    AmbientConditions,
+    CoolPropBackend,
+    GasProperties,
+    LegacyBackend,
+    MixtureState,
+    Thermo,
+    make_backend,
+)
+from .timesort import Snapshot, TimeSort, sort_times
+from .transient import ObserverResult, TransientResult, TransientRun
+
+__all__ = [
+    # atmosphere
+    "StabilityDefaults", "absolute_humidity", "ambient_density", "fit_alpha",
+    "friction_velocity", "psi", "richardson_star", "richardson_thermal",
+    "stability_defaults", "wind_log", "wind_power",
+    # thermodynamics
+    "AdiabaticTable", "AmbientConditions", "CoolPropBackend", "GasProperties",
+    "LegacyBackend", "MixtureState", "Thermo", "make_backend",
+    # closures
+    "entrainment_velocity", "phi", "phi_hat", "surface_exchange",
+    # source
+    "Blanket", "BlanketParameters", "BlanketResult", "BlanketState",
+    "DriverParameters", "SourceRun", "SourceVectors", "build_source_vectors",
+    "LayerState", "sigma_z_over_source",
+    # downwind
+    "Downwind", "DownwindConstants", "DownwindState", "series",
+    "Profile", "SteadyStateRun",
+    # transient
+    "Observer", "ObserverKinematics", "ObserverState", "crossing_downwind",
+    "crossing_upwind", "release_times",
+    "ObserverResult", "TransientResult", "TransientRun",
+    "Snapshot", "TimeSort", "sort_times",
+    "DoseHistory", "DoseRun", "Receptor", "receptor_times",
+    # jet/plume
+    "JetCoefficients", "JetPlume", "JetResult", "JetState", "ellipse",
+]