hydrogen-station-sim 0.1.2__tar.gz

hydrogen_station_sim-0.1.2/.gitignore

@@ -0,0 +1,45 @@
+# Local environments and editor state
+.venv/
+.idea/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.ruff_cache/
+.mypy_cache/
+
+# Generated simulation runs, event databases, and server logs
+/data/
+*.log
+*.sqlite3-journal
+*.sqlite3-wal
+*.sqlite3-shm
+
+# Build output and local configuration
+/build/
+/dist/
+/tmp/
+.env
+.env.*
+!.env.example
+.DS_Store
+Thumbs.db
+
+# Locally generated journal build artifacts
+/manuscript/ijhe_manuscript_draft.pdf
+/manuscript/ijhe_manuscript_draft.log
+/output/pdf/ijhe_manuscript_draft.pdf
+/output/partial_mc_default_recheck/
+/output/partial_mc_default_recheck_120/
+
+# Unreal generated assets and compiled artifacts; source and contracts are versioned.
+/unreal/HRSUnreal/Binaries/
+/unreal/HRSUnreal/Intermediate/
+/unreal/HRSUnreal/Saved/
+/unreal/HRSUnreal/DerivedDataCache/
+/unreal/HRSUnreal/Content/
+/unreal/PixelStreamingInfrastructure/
+/unreal/.tooling/
+/output/unreal/
+*.sln
+*.suo

hydrogen_station_sim-0.1.2/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the archived release."
+type: software
+title: "Hydrogen Station Dynamic Simulator"
+authors:
+  - family-names: Lee
+    given-names: Ugwiyeon
+    affiliation: "Korea Gas Safety Corporation"
+version: 0.1.2
+license: MIT
+date-released: 2026-10-18
+repository-code: "https://github.com/lyullee/hydrogen-station-sim"
+url: "https://github.com/lyullee/hydrogen-station-sim"
+doi: "10.5281/zenodo.23084421"
+identifiers:
+  - type: doi
+    value: "10.5281/zenodo.23084421"
+    description: "Concept DOI resolving to the latest archived software release"
+abstract: >-
+  Physics-based dynamic simulation and safety monitoring of a gaseous hydrogen
+  refueling station, including process equipment, incident scenarios, consequence
+  assessment, and operator training interfaces.

hydrogen_station_sim-0.1.2/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.

hydrogen_station_sim-0.1.2/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.5
+Name: hydrogen-station-sim
+Version: 0.1.2
+Summary: First-principles dynamic models for gaseous hydrogen refueling stations
+Project-URL: Homepage, https://github.com/lyullee/hydrogen-station-sim
+Project-URL: Documentation, https://github.com/lyullee/hydrogen-station-sim/blob/main/docs/USER_MANUAL.md
+Project-URL: Repository, https://github.com/lyullee/hydrogen-station-sim
+Project-URL: Issues, https://github.com/lyullee/hydrogen-station-sim/issues
+Project-URL: Archive, https://doi.org/10.5281/zenodo.23084421
+Author: Ugwiyeon Lee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: HAZOP,digital twin,hydrogen,process safety,refueling station
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: fluids<2,>=1.0
+Requires-Dist: ht<2,>=1.0
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<1.16,>=1.11
+Provides-Extra: all
+Requires-Dist: fastapi<0.116,>=0.115; extra == 'all'
+Requires-Dist: hyram==6.1; extra == 'all'
+Requires-Dist: uvicorn[standard]<0.36,>=0.30; extra == 'all'
+Provides-Extra: api
+Requires-Dist: fastapi<0.116,>=0.115; extra == 'api'
+Requires-Dist: uvicorn[standard]<0.36,>=0.30; extra == 'api'
+Provides-Extra: research
+Requires-Dist: coolprop<9,>=7.1; extra == 'research'
+Requires-Dist: h5py<4,>=3.10; extra == 'research'
+Requires-Dist: httpx<0.29,>=0.27; extra == 'research'
+Requires-Dist: matplotlib<4,>=3.9; extra == 'research'
+Requires-Dist: openpyxl<4,>=3.1; extra == 'research'
+Requires-Dist: pillow<13,>=10; extra == 'research'
+Requires-Dist: pypdf<7,>=6; extra == 'research'
+Requires-Dist: pyyaml<7,>=6; extra == 'research'
+Requires-Dist: xlrd<3,>=2.0; extra == 'research'
+Provides-Extra: risk
+Requires-Dist: hyram==6.1; extra == 'risk'
+Provides-Extra: table-build
+Requires-Dist: coolprop<9,>=7.1; extra == 'table-build'
+Provides-Extra: test
+Requires-Dist: httpx<0.29,>=0.27; extra == 'test'
+Requires-Dist: openpyxl<4,>=3.1; extra == 'test'
+Requires-Dist: pypdf<7,>=6; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Hydrogen Station Dynamic Simulator
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23084421.svg)](https://doi.org/10.5281/zenodo.23084421)
+
+The badge DOI resolves to the latest archived release. Earlier versions retain their own DOIs.
+
+Original project software and associated documentation are available under the [MIT license](LICENSE). Bundled third-party libraries and assets retain their respective notices and terms.
+
+## Current documentation
+
+- [Technical report](docs/TECHNICAL_REPORT.md): architecture, physical model, safety logic, APIs, LLM boundaries, validation and limits.
+- [User manual](docs/USER_MANUAL.md): startup, remote operation, incident exercises, response controls, trends and troubleshooting.
+- [Reproducible release candidate](docs/RELEASE_CANDIDATE_0.1.1_RC1.md): exact source boundary, CI evidence, readiness counts and remaining blockers.
+- [Promotional accuracy snapshot](docs/PROMOTIONAL_ACCURACY_SNAPSHOT_2026_10_12.md): claim-bounded metrics for software, tank, release, consequence and SAGA validation.
+- [Paper evaluation](docs/PAPER_EVALUATION.md): repeatable fueling-boundary metrics and alarm-only versus SAGA-PY A/B scoring.
+- [Public-data validation](docs/PUBLIC_VALIDATION.md): checksum-verified SAE J2601 experiments, HIAD incidents, dispersion data, and the publication-readiness gate.
+- [Local station-data inventory](research/LOCAL_HYDROGEN_STATION_DATA_DISCOVERY_RECHECK_2026_10_09.md): privacy-bounded inventory of the measured station-side archive, its validated uses and the remaining vehicle/full-loop boundary.
+- [Local data catalog](research/LOCAL_DATA_CATALOG_2026_10_09.md): aggregate map of station telemetry, operational workbooks, public component data, engineering/media context and the full-loop exclusion screen.
+- [Data-scarcity validation strategy](research/DATA_SCARCITY_VALIDATION_STRATEGY_2026_10_09.md): what the large privacy-bounded station archive can validate now, why vehicle/full-loop claims remain closed, and the smallest three-event request that can open the next gate.
+- [Public station aggregate benchmark](research/calstate_la_multi_year_aggregate_reference_2026_10_09.json): aggregate Cal State LA operating/energy context used only for sanity checks and grounded explanations; it is not raw full-loop validation.
+- [3Emotion bus-station aggregate benchmark](research/threeemotion_station_operating_aggregate_reference_2026_10_09.json): open 350 bar fleet-operation context used for throughput/utilization checks; it is not raw full-loop validation.
+- [Station-data custodian attestation request](research/LOCAL_STATION_CUSTODIAN_ATTESTATION_REQUEST_2026_10_09.md): de-identified semantic and rights checklist required before vehicle/full-loop validation.
+- [MetHyTrucks public intake](research/METHYTRUCKS_2026_PUBLIC_MEASUREMENT_INTAKE.md): 15 checksum-verified physical-HRS sampling-system workbooks and a claim-bounded flow/mass component diagnostic.
+- [Detector-logic replay](research/DISPERSION_DETECTOR_LOGIC_VALIDATION.md): a bounded 22-case replay of alarm/trip thresholds and persistence against public USN/FFI concentration measurements.
+- [HyRAM adapter verification](docs/HYRAM_ADAPTER_VERIFICATION.md): exact v6.1 source identity, upstream experimental validation-suite execution, and field-by-field production-adapter parity.
+- [Consequence geometry validation](research/CONSEQUENCE_GEOMETRY_VALIDATION.md): bounded public-experiment-to-browser traceability for directional plume and sampled radial effects.
+- [PRESLHY blowdown validation](research/PRESLHY_BLOWDOWN_EXTERNAL_VALIDATION.md): prospectively specified 22-case external result, including retained negative cases and claim boundary.
+- [Woodfield metal-tank heat-transfer development](research/WOODFIELD_METAL_TANK_HEAT_TRANSFER_DEVELOPMENT_2026_10_08.md): pinned, aggregate-only filling/discharge replay that supports the existing inlet-mixing mechanism without changing a validation gate or runtime default.
+- [PRESLHY non-adiabatic development](research/PRESLHY_NONADIABATIC_DEVELOPMENT_RESULT.md): immutable follow-up on consumed cases; 20/22 pass the original diagnostic screens but cannot serve as external confirmation.
+- [PRESLHY E5.1 holdout protocol](research/PRESLHY_E5_1_HOLDOUT_PROTOCOL.md): model-hash-locked independent evaluation rules frozen before archive access.
+- [PRESLHY E5.1 holdout result](research/PRESLHY_E5_1_HOLDOUT_RESULT.md): retained ineligible negative result; 3 primary ambient cases and 2/3 joint passes did not meet the frozen minimums or 70% rule.
+- [Independent 90 MPa release holdout](research/PROUST_RELEASE_HOLDOUT_RESULT.md): prospectively frozen INERIS/CEA mass-flow transfer test; all three nozzle series were eligible and all failed the joint screens.
+- [Proust boundary-semantics diagnostic](research/PROUST_RELEASE_BOUNDARY_SEMANTICS_DIAGNOSTIC_2026_10_12.md): post-outcome diagnosis of the diameter-dependent effective coefficient and the unresolved supply-line/valve boundary; it does not change the failed holdout.
+- [Release-flow sensitivity contract](research/RELEASE_FLOW_UNCERTAINTY_CONTRACT_2026_10_13.md): preserves the runtime point model while exposing the independent Proust model--experiment flow range, public-domain status and claim limit to the API, LLM and operator UI.
+- [HIAD expert-review protocol](docs/EXPERT_REVIEW_PROTOCOL.md): frozen casebook, masking, reviewer rubric, endpoints, and analysis plan.
+- [HIAD evaluation readiness](research/hiad_evaluation_readiness.json): machine-checkable status of coordinator review, ethics, holdout collection and independent expert-review gates; advisory prescreen output never counts as approval.
+- [Validation evidence matrix](research/VALIDATION_EVIDENCE_MATRIX_2026_10_11.md): claim-bounded map of the owner-data holdouts, independent component evidence, station-to-vehicle limitation, and SAGA human-study boundary.
+- [Validation split and scope decision](research/VALIDATION_DATA_SPLIT_AND_SCOPE_DECISION_2026_10_11.md): frozen chronology-preserving split of the private station-side archive and the decision to exclude unavailable synchronized station-to-vehicle raw validation from the primary goal.
+- [Ethics and expert-review scope](research/ETHICS_AND_EXPERT_REVIEW_SCOPE_2026_10_11.md): distinguishes institutional ethics determination from independent blinded subject-matter review and defines when each is required.
+- [Paper goal and scope amendment](research/GOAL_SCOPE_AMENDMENT_2026_10_12.md): objective claims, KGS/AI-assisted source handling, station-to-vehicle limitation and facility-specific deployment conditions.
+- [Current validation progress delta](research/PROGRESS_DELTA_2026_10_12.md): current gate counts, scope-adjusted progress, full-loop exclusion, and unresolved P0 physics gates.
+- [IJHE working manuscript](manuscript/ijhe_manuscript_draft.tex): claim-bounded English draft, journal-format checks, figures, graphical abstract and the remaining submission gates.
+- [IJHE reproducibility route](manuscript/REPRODUCIBILITY.md): one-command integrity check, focused tests, full-regression option and the scientific-readiness claim boundary.
+- [Goal closeout checklist](research/GOAL_CLOSEOUT_CHECKLIST_2026_10_14.md): machine-verified completion, required author confirmations, remaining independent-data gates and fixed paper limitations.
+- [New-data search and bounded development decision](research/NEW_DATA_SEARCH_AND_DEVELOPMENT_SCOPE_2026_10_15.md): sources rechecked, unavailable raw-data lanes excluded, and re-entry conditions.
+- [Runtime evidence, uncertainty and paired response runs](docs/53_RUNTIME_EVIDENCE_UNCERTAINTY_AND_COUNTERFACTUALS.md): fail-closed model-use gate, bounded consequence ensemble, automatic counterfactual API and new fault coverage.
+
+The monitor and remote now have a Korean/English language selector. New main and sensor assistant requests use the selected output language while consequence calculations and source data remain unchanged. English answers are advisory translations/analyses; verify exact safety requirements against their original source.
+
+Physics-first Python simulator for gaseous hydrogen refueling stations. The existing
+Java/browser simulator is a visual reference only; this package has an independent
+model, API, and monitoring interface.
+
+## Implemented system
+
+- CoolProp-generated hydrogen property table (runtime lookup; no CoolProp calls in the process solver)
+- Storage mass, energy, and wall-temperature dynamics
+- Three-stage compressor with intercooling and electrical power
+- Three-bank cascade dispatch and recharge with a finite common-header mass and energy inventory
+- Real-gas PCV, nozzle, check valve, and relief primitives
+- Finite-UA precooler and finite-volume hose line-pack
+- Gas, HDPE liner, and CFRP Type IV vehicle tank
+- Split-validated public Type IV tank calibration applied by default; the API
+  exposes an uncalibrated reference sensitivity mode and keeps this component
+  evidence separate from the station-controller model
+- External SAE J2601-compatible APRR schedule boundary
+- Sampled normal control and independent latched safety PLC
+- Sensor, actuator, cooling, compressor, E-stop, and leak faults
+- Leak mass and enthalpy feedback to the physical inventory
+- HyRAM+ 6.1 outdoor and optional indoor consequence bridge
+- FastAPI simulation jobs and responsive monitoring UI
+- H2FillS-compatible validation channels and metrics
+
+Internal units are SI. The API accepts MPa, degrees Celsius, g/s, and millimetres and
+converts them at the boundary.
+
+The process solver reads `src/h2station/data/hydrogen_properties_v1.npz`, generated
+offline by `scripts/generate_hydrogen_table.py`. PCV/nozzle/release choking uses a
+small critical-pressure lookup derived from that same table; unusual pressures or
+temperatures outside its operating grid fall back to direct table-based search.
+
+## Installation
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\python -m pip install -e ".[api]"
+```
+
+Include HyRAM+ when its GPL-3.0 licensing is appropriate for the deployment:
+
+```powershell
+.venv\Scripts\python -m pip install -e ".[all]"
+```
+
+## Run
+
+```powershell
+.venv\Scripts\h2station
+```
+
+Open `http://127.0.0.1:8000`.
+
+## Monitoring and sensor provenance
+
+The monitor keeps the 3D station footprint, process flow, equipment specifications,
+and CCTV gallery in the same 16:9 display region. The 3D scene omits the surrounding
+district and traffic, and caps render resolution to reduce GPU load. The equipment
+and CCTV top-menu entries switch that region without opening a separate dialog.
+
+API monitoring jobs enable simulation outputs for all 82 HAZOP database sensor tags.
+The 15 gas detector tags are virtual zone proxies that respond to injected leaks or explicit sensor faults;
+they are not physical detector connections. Compressor-stage readings follow the
+three-stage model. Shared header and precooler channels are derived from upstream
+flows and temperatures. The coolant flow channel is a thermal-equivalent estimate;
+the vent channels use an assumed ambient boundary until a release is injected.
+Each API signal includes an `origin`, while `/api/hazop/mapping` reports its binding
+and still reports zero physical sensor connections. Site telemetry should replace
+these proxies before operational use.
+
+## Operator process control
+
+The remote's **안전 대응** tab adds simulation-only equipment isolation, delayed
+valve position/flow confirmation, venting, ventilation, cooling, evacuation,
+recovery tests, and training replay. Active sensor scenarios and SAGA response
+cards provide the same executable virtual actions. See
+[`docs/virtual-safety-simulation.md`](docs/virtual-safety-simulation.md) for the
+model assumptions, recovery gates, and limits.
+
+Open `/remote.html` and start continuous monitoring. The trailer supply, storage-bank
+recharge, and each of the two vehicle fills begin **off**. The process inventories
+remain unchanged while no command or fault is active. The remote couples trailer
+supply and storage-bank recharge on one transfer path; either start/stop control
+changes both requests. Vehicle 1 and 2 fills remain individually controlled and
+draw from the cascade banks.
+
+The remote offers 0.5×, 1×, 2×, 3×, 5×, 10×, 30×, 50×, and 100× target speeds and
+allows switching during a run. This changes wall-clock pacing without enlarging
+the physical solver step. The remote shows both the selected target and measured
+speed; a computation-bound run may stay below its target. Accident delays entered
+during a run are anchored at the solver step that accepts the command.
+
+The remote exposes a finite trailer inventory, initial pressure and temperature,
+individual bank starting fills, and configurable bank/vehicle stopping pressures.
+Each process target has an automatic-stop switch. Turning it off allows a virtual
+overfill exercise; relief valves and independent ESD protections remain separate.
+Trailer pressure falls as compressor transfer removes mass. Its fixed volume and
+isothermal temperature are explicit reference-model assumptions.
+
+The **실측 경계 보정** option is an explicit opt-in. It loads only the
+de-identified station-boundary aggregate in
+`research/confidential_operational_envelope_calibration_summary_2026_10_06.json`.
+The observed pressure margin is applied to both cascade-bank dispatch and
+recharge restart selection, reducing READY/CHARGE chatter around the measured
+noise band. The default reference model remains unchanged; the profile does
+not calibrate vehicle-side pressure, temperature, mass flow, protocol
+conformance, or consequence distance.
+
+Seven virtual relief valves cover the three storage banks, two dispenser hoses,
+and two vehicle tanks. Their enable switches, opening and closing pressures, and
+orifice sizes are adjustable during a run. A valve stays open until pressure
+falls to its closing setting; close opening/closing settings reproduce sampled
+chatter. Relief mass flow is deducted from the corresponding inventory and enters
+the same leak, detector, HAZOP, and consequence pipeline as other releases. These
+settings are simulation inputs, not certified relief-valve sizing values.
+
+The remote shows command acknowledgement separately from actual flow, including
+why a requested path is waiting or blocked. It also displays wall-clock lag and
+simulation speed. Operator-mode integration uses SciPy LSODA, while the legacy
+batch API retains BDF. Continuous operator monitoring paces successful solves to
+wall time; if a step takes longer than real time, the solver keeps all physical
+steps and reports the accumulated lag instead of silently skipping them.
+
+## HyRAM configuration
+
+When `hyram==6.1` is installed, the native adapter is selected automatically. Default
+outdoor observation points are spaced every 0.5 m from 0.5–10 m, then at
+12, 15, 20, 25, 30, 40, and 50 m downstream at 1.5 m elevation. The reported
+extent is the farthest threshold-exceeding sample, not a certified safety radius.
+Override them with JSON:
+
+```powershell
+$env:H2STATION_HYRAM_LOCATIONS='[[0.5,0,1.5],[1,0,1.5],[1.5,0,1.5],[2,0,1.5],[2.5,0,1.5],[3,0,1.5],[5,0,1.5],[10,0,1.5]]'
+```
+
+Site overrides replace the entire default sampling transect. Sparse overrides
+can make a threshold crossed between two points appear at the nearer point.
+
+Indoor accumulation requires an explicit enclosure definition through
+`H2STATION_HYRAM_INDOOR_JSON`; no enclosure geometry is invented. A site-specific
+backend can instead be selected with
+`H2STATION_HYRAM_EVALUATOR=module:function`.
+
+The digital-twin SAGA panel and selected-sensor follow-up questions use dedicated
+`/direct` API routes. The simulator first evaluates the current sensor state,
+then sends the operator's actual question and its calculated context to SAGA's
+single-completion LLM endpoint. This bypasses SAGA's multi-stage RAG/review
+pipeline but retains free-form question answering. The operator can manually
+select Service Hub or Groq. Groq's direct model defaults to Qwen with reasoning
+disabled; Service Hub defaults to the non-reasoning Llama instruct model. If the selected LLM is
+unavailable, the interface labels the connection error and retains a local
+sensor-based fallback answer. The older analysis API remains available for
+existing integrations, but the digital-twin interface does not call it.
+
+The direct-answer numeric guard normalizes equivalent value/unit spellings and
+shared-unit ranges before filtering. Its provider-free 5-case regression is
+documented in
+[`research/SAGA_MEASUREMENT_GUARD_REGRESSION_2026_10_08.md`](research/SAGA_MEASUREMENT_GUARD_REGRESSION_2026_10_08.md);
+this verifies filter behavior only, not response correctness or operator benefit.
+
+Consequence evaluation remains in the direct path. An active warning/critical
+state automatically evaluates relevant nodes before building the answer. Normal
+operation only evaluates consequences when the operator explicitly requests an
+impact or uses **센서 기준 가상 평가**. The calculations use current GOOD-quality
+pressure and temperature readings. An active leak uses its current orifice size
+and flow; a hypothetical case uses a 1 mm horizontal release at 1 m height and
+101325 Pa ambient pressure. The calculated result, sensor tags, and assumptions
+are passed to both the direct state endpoint and the one-pass LLM. Reported distance is the farthest sampled
+point exceeding 5 kW/m² or 5 kPa, not a validated site safety boundary. Missing
+sensor pairs or an unavailable backend never produce an invented distance.
+
+## Engineering status
+
+This is a modeling and monitoring prototype, not a certified controller. Reference
+scenario dimensions and thermal parameters are illustrative until calibrated against
+traceable equipment and test data. SAE J2601 tables remain licensed external inputs.
+The complete modeling basis, literature, limitations, and validation plan are in
+`docs/`.
+
+The partial-station boundary experiment is documented in
+[`docs/PARTIAL_STATION_VALIDATION.md`](docs/PARTIAL_STATION_VALIDATION.md).
+It is a development diagnostic with an explicit upstream-pressure assumption;
+it does not upgrade the full-station validation claim.
+
+The current public-data intake lead is documented in
+[`research/NBSDC_HEAVY_VEHICLE_FAST_REFUELING_ACCESS_RECHECK_2026_10_06.md`](research/NBSDC_HEAVY_VEHICLE_FAST_REFUELING_ACCESS_RECHECK_2026_10_06.md).
+Its numerical files require an approved portal request. Once a rights-cleared
+workbook or CSV export is obtained, the explicit-unit loader in
+[`src/h2station/nbsdc_ingest.py`](src/h2station/nbsdc_ingest.py) can produce
+in-memory pressure, temperature and flow traces without publishing raw rows.
+The test-cylinder data remains a component/protocol candidate until its mapping
+to a vehicle-side validation contract is independently confirmed.
+
+For owner-held full-loop logger data, the controlled exporter accepts CSV, XLSX,
+and XLSM sources.  It offers a header-only preflight that does not read
+measurement rows, then writes only canonical columns and relative time to a
+directory outside this repository.  See
+[`research/CONTROLLED_FULL_LOOP_XLSX_INTAKE.md`](research/CONTROLLED_FULL_LOOP_XLSX_INTAKE.md).

hydrogen_station_sim-0.1.2/README.md

@@ -0,0 +1,247 @@
+# Hydrogen Station Dynamic Simulator
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23084421.svg)](https://doi.org/10.5281/zenodo.23084421)
+
+The badge DOI resolves to the latest archived release. Earlier versions retain their own DOIs.
+
+Original project software and associated documentation are available under the [MIT license](LICENSE). Bundled third-party libraries and assets retain their respective notices and terms.
+
+## Current documentation
+
+- [Technical report](docs/TECHNICAL_REPORT.md): architecture, physical model, safety logic, APIs, LLM boundaries, validation and limits.
+- [User manual](docs/USER_MANUAL.md): startup, remote operation, incident exercises, response controls, trends and troubleshooting.
+- [Reproducible release candidate](docs/RELEASE_CANDIDATE_0.1.1_RC1.md): exact source boundary, CI evidence, readiness counts and remaining blockers.
+- [Promotional accuracy snapshot](docs/PROMOTIONAL_ACCURACY_SNAPSHOT_2026_10_12.md): claim-bounded metrics for software, tank, release, consequence and SAGA validation.
+- [Paper evaluation](docs/PAPER_EVALUATION.md): repeatable fueling-boundary metrics and alarm-only versus SAGA-PY A/B scoring.
+- [Public-data validation](docs/PUBLIC_VALIDATION.md): checksum-verified SAE J2601 experiments, HIAD incidents, dispersion data, and the publication-readiness gate.
+- [Local station-data inventory](research/LOCAL_HYDROGEN_STATION_DATA_DISCOVERY_RECHECK_2026_10_09.md): privacy-bounded inventory of the measured station-side archive, its validated uses and the remaining vehicle/full-loop boundary.
+- [Local data catalog](research/LOCAL_DATA_CATALOG_2026_10_09.md): aggregate map of station telemetry, operational workbooks, public component data, engineering/media context and the full-loop exclusion screen.
+- [Data-scarcity validation strategy](research/DATA_SCARCITY_VALIDATION_STRATEGY_2026_10_09.md): what the large privacy-bounded station archive can validate now, why vehicle/full-loop claims remain closed, and the smallest three-event request that can open the next gate.
+- [Public station aggregate benchmark](research/calstate_la_multi_year_aggregate_reference_2026_10_09.json): aggregate Cal State LA operating/energy context used only for sanity checks and grounded explanations; it is not raw full-loop validation.
+- [3Emotion bus-station aggregate benchmark](research/threeemotion_station_operating_aggregate_reference_2026_10_09.json): open 350 bar fleet-operation context used for throughput/utilization checks; it is not raw full-loop validation.
+- [Station-data custodian attestation request](research/LOCAL_STATION_CUSTODIAN_ATTESTATION_REQUEST_2026_10_09.md): de-identified semantic and rights checklist required before vehicle/full-loop validation.
+- [MetHyTrucks public intake](research/METHYTRUCKS_2026_PUBLIC_MEASUREMENT_INTAKE.md): 15 checksum-verified physical-HRS sampling-system workbooks and a claim-bounded flow/mass component diagnostic.
+- [Detector-logic replay](research/DISPERSION_DETECTOR_LOGIC_VALIDATION.md): a bounded 22-case replay of alarm/trip thresholds and persistence against public USN/FFI concentration measurements.
+- [HyRAM adapter verification](docs/HYRAM_ADAPTER_VERIFICATION.md): exact v6.1 source identity, upstream experimental validation-suite execution, and field-by-field production-adapter parity.
+- [Consequence geometry validation](research/CONSEQUENCE_GEOMETRY_VALIDATION.md): bounded public-experiment-to-browser traceability for directional plume and sampled radial effects.
+- [PRESLHY blowdown validation](research/PRESLHY_BLOWDOWN_EXTERNAL_VALIDATION.md): prospectively specified 22-case external result, including retained negative cases and claim boundary.
+- [Woodfield metal-tank heat-transfer development](research/WOODFIELD_METAL_TANK_HEAT_TRANSFER_DEVELOPMENT_2026_10_08.md): pinned, aggregate-only filling/discharge replay that supports the existing inlet-mixing mechanism without changing a validation gate or runtime default.
+- [PRESLHY non-adiabatic development](research/PRESLHY_NONADIABATIC_DEVELOPMENT_RESULT.md): immutable follow-up on consumed cases; 20/22 pass the original diagnostic screens but cannot serve as external confirmation.
+- [PRESLHY E5.1 holdout protocol](research/PRESLHY_E5_1_HOLDOUT_PROTOCOL.md): model-hash-locked independent evaluation rules frozen before archive access.
+- [PRESLHY E5.1 holdout result](research/PRESLHY_E5_1_HOLDOUT_RESULT.md): retained ineligible negative result; 3 primary ambient cases and 2/3 joint passes did not meet the frozen minimums or 70% rule.
+- [Independent 90 MPa release holdout](research/PROUST_RELEASE_HOLDOUT_RESULT.md): prospectively frozen INERIS/CEA mass-flow transfer test; all three nozzle series were eligible and all failed the joint screens.
+- [Proust boundary-semantics diagnostic](research/PROUST_RELEASE_BOUNDARY_SEMANTICS_DIAGNOSTIC_2026_10_12.md): post-outcome diagnosis of the diameter-dependent effective coefficient and the unresolved supply-line/valve boundary; it does not change the failed holdout.
+- [Release-flow sensitivity contract](research/RELEASE_FLOW_UNCERTAINTY_CONTRACT_2026_10_13.md): preserves the runtime point model while exposing the independent Proust model--experiment flow range, public-domain status and claim limit to the API, LLM and operator UI.
+- [HIAD expert-review protocol](docs/EXPERT_REVIEW_PROTOCOL.md): frozen casebook, masking, reviewer rubric, endpoints, and analysis plan.
+- [HIAD evaluation readiness](research/hiad_evaluation_readiness.json): machine-checkable status of coordinator review, ethics, holdout collection and independent expert-review gates; advisory prescreen output never counts as approval.
+- [Validation evidence matrix](research/VALIDATION_EVIDENCE_MATRIX_2026_10_11.md): claim-bounded map of the owner-data holdouts, independent component evidence, station-to-vehicle limitation, and SAGA human-study boundary.
+- [Validation split and scope decision](research/VALIDATION_DATA_SPLIT_AND_SCOPE_DECISION_2026_10_11.md): frozen chronology-preserving split of the private station-side archive and the decision to exclude unavailable synchronized station-to-vehicle raw validation from the primary goal.
+- [Ethics and expert-review scope](research/ETHICS_AND_EXPERT_REVIEW_SCOPE_2026_10_11.md): distinguishes institutional ethics determination from independent blinded subject-matter review and defines when each is required.
+- [Paper goal and scope amendment](research/GOAL_SCOPE_AMENDMENT_2026_10_12.md): objective claims, KGS/AI-assisted source handling, station-to-vehicle limitation and facility-specific deployment conditions.
+- [Current validation progress delta](research/PROGRESS_DELTA_2026_10_12.md): current gate counts, scope-adjusted progress, full-loop exclusion, and unresolved P0 physics gates.
+- [IJHE working manuscript](manuscript/ijhe_manuscript_draft.tex): claim-bounded English draft, journal-format checks, figures, graphical abstract and the remaining submission gates.
+- [IJHE reproducibility route](manuscript/REPRODUCIBILITY.md): one-command integrity check, focused tests, full-regression option and the scientific-readiness claim boundary.
+- [Goal closeout checklist](research/GOAL_CLOSEOUT_CHECKLIST_2026_10_14.md): machine-verified completion, required author confirmations, remaining independent-data gates and fixed paper limitations.
+- [New-data search and bounded development decision](research/NEW_DATA_SEARCH_AND_DEVELOPMENT_SCOPE_2026_10_15.md): sources rechecked, unavailable raw-data lanes excluded, and re-entry conditions.
+- [Runtime evidence, uncertainty and paired response runs](docs/53_RUNTIME_EVIDENCE_UNCERTAINTY_AND_COUNTERFACTUALS.md): fail-closed model-use gate, bounded consequence ensemble, automatic counterfactual API and new fault coverage.
+
+The monitor and remote now have a Korean/English language selector. New main and sensor assistant requests use the selected output language while consequence calculations and source data remain unchanged. English answers are advisory translations/analyses; verify exact safety requirements against their original source.
+
+Physics-first Python simulator for gaseous hydrogen refueling stations. The existing
+Java/browser simulator is a visual reference only; this package has an independent
+model, API, and monitoring interface.
+
+## Implemented system
+
+- CoolProp-generated hydrogen property table (runtime lookup; no CoolProp calls in the process solver)
+- Storage mass, energy, and wall-temperature dynamics
+- Three-stage compressor with intercooling and electrical power
+- Three-bank cascade dispatch and recharge with a finite common-header mass and energy inventory
+- Real-gas PCV, nozzle, check valve, and relief primitives
+- Finite-UA precooler and finite-volume hose line-pack
+- Gas, HDPE liner, and CFRP Type IV vehicle tank
+- Split-validated public Type IV tank calibration applied by default; the API
+  exposes an uncalibrated reference sensitivity mode and keeps this component
+  evidence separate from the station-controller model
+- External SAE J2601-compatible APRR schedule boundary
+- Sampled normal control and independent latched safety PLC
+- Sensor, actuator, cooling, compressor, E-stop, and leak faults
+- Leak mass and enthalpy feedback to the physical inventory
+- HyRAM+ 6.1 outdoor and optional indoor consequence bridge
+- FastAPI simulation jobs and responsive monitoring UI
+- H2FillS-compatible validation channels and metrics
+
+Internal units are SI. The API accepts MPa, degrees Celsius, g/s, and millimetres and
+converts them at the boundary.
+
+The process solver reads `src/h2station/data/hydrogen_properties_v1.npz`, generated
+offline by `scripts/generate_hydrogen_table.py`. PCV/nozzle/release choking uses a
+small critical-pressure lookup derived from that same table; unusual pressures or
+temperatures outside its operating grid fall back to direct table-based search.
+
+## Installation
+
+```powershell
+py -3.12 -m venv .venv
+.venv\Scripts\python -m pip install -e ".[api]"
+```
+
+Include HyRAM+ when its GPL-3.0 licensing is appropriate for the deployment:
+
+```powershell
+.venv\Scripts\python -m pip install -e ".[all]"
+```
+
+## Run
+
+```powershell
+.venv\Scripts\h2station
+```
+
+Open `http://127.0.0.1:8000`.
+
+## Monitoring and sensor provenance
+
+The monitor keeps the 3D station footprint, process flow, equipment specifications,
+and CCTV gallery in the same 16:9 display region. The 3D scene omits the surrounding
+district and traffic, and caps render resolution to reduce GPU load. The equipment
+and CCTV top-menu entries switch that region without opening a separate dialog.
+
+API monitoring jobs enable simulation outputs for all 82 HAZOP database sensor tags.
+The 15 gas detector tags are virtual zone proxies that respond to injected leaks or explicit sensor faults;
+they are not physical detector connections. Compressor-stage readings follow the
+three-stage model. Shared header and precooler channels are derived from upstream
+flows and temperatures. The coolant flow channel is a thermal-equivalent estimate;
+the vent channels use an assumed ambient boundary until a release is injected.
+Each API signal includes an `origin`, while `/api/hazop/mapping` reports its binding
+and still reports zero physical sensor connections. Site telemetry should replace
+these proxies before operational use.
+
+## Operator process control
+
+The remote's **안전 대응** tab adds simulation-only equipment isolation, delayed
+valve position/flow confirmation, venting, ventilation, cooling, evacuation,
+recovery tests, and training replay. Active sensor scenarios and SAGA response
+cards provide the same executable virtual actions. See
+[`docs/virtual-safety-simulation.md`](docs/virtual-safety-simulation.md) for the
+model assumptions, recovery gates, and limits.
+
+Open `/remote.html` and start continuous monitoring. The trailer supply, storage-bank
+recharge, and each of the two vehicle fills begin **off**. The process inventories
+remain unchanged while no command or fault is active. The remote couples trailer
+supply and storage-bank recharge on one transfer path; either start/stop control
+changes both requests. Vehicle 1 and 2 fills remain individually controlled and
+draw from the cascade banks.
+
+The remote offers 0.5×, 1×, 2×, 3×, 5×, 10×, 30×, 50×, and 100× target speeds and
+allows switching during a run. This changes wall-clock pacing without enlarging
+the physical solver step. The remote shows both the selected target and measured
+speed; a computation-bound run may stay below its target. Accident delays entered
+during a run are anchored at the solver step that accepts the command.
+
+The remote exposes a finite trailer inventory, initial pressure and temperature,
+individual bank starting fills, and configurable bank/vehicle stopping pressures.
+Each process target has an automatic-stop switch. Turning it off allows a virtual
+overfill exercise; relief valves and independent ESD protections remain separate.
+Trailer pressure falls as compressor transfer removes mass. Its fixed volume and
+isothermal temperature are explicit reference-model assumptions.
+
+The **실측 경계 보정** option is an explicit opt-in. It loads only the
+de-identified station-boundary aggregate in
+`research/confidential_operational_envelope_calibration_summary_2026_10_06.json`.
+The observed pressure margin is applied to both cascade-bank dispatch and
+recharge restart selection, reducing READY/CHARGE chatter around the measured
+noise band. The default reference model remains unchanged; the profile does
+not calibrate vehicle-side pressure, temperature, mass flow, protocol
+conformance, or consequence distance.
+
+Seven virtual relief valves cover the three storage banks, two dispenser hoses,
+and two vehicle tanks. Their enable switches, opening and closing pressures, and
+orifice sizes are adjustable during a run. A valve stays open until pressure
+falls to its closing setting; close opening/closing settings reproduce sampled
+chatter. Relief mass flow is deducted from the corresponding inventory and enters
+the same leak, detector, HAZOP, and consequence pipeline as other releases. These
+settings are simulation inputs, not certified relief-valve sizing values.
+
+The remote shows command acknowledgement separately from actual flow, including
+why a requested path is waiting or blocked. It also displays wall-clock lag and
+simulation speed. Operator-mode integration uses SciPy LSODA, while the legacy
+batch API retains BDF. Continuous operator monitoring paces successful solves to
+wall time; if a step takes longer than real time, the solver keeps all physical
+steps and reports the accumulated lag instead of silently skipping them.
+
+## HyRAM configuration
+
+When `hyram==6.1` is installed, the native adapter is selected automatically. Default
+outdoor observation points are spaced every 0.5 m from 0.5–10 m, then at
+12, 15, 20, 25, 30, 40, and 50 m downstream at 1.5 m elevation. The reported
+extent is the farthest threshold-exceeding sample, not a certified safety radius.
+Override them with JSON:
+
+```powershell
+$env:H2STATION_HYRAM_LOCATIONS='[[0.5,0,1.5],[1,0,1.5],[1.5,0,1.5],[2,0,1.5],[2.5,0,1.5],[3,0,1.5],[5,0,1.5],[10,0,1.5]]'
+```
+
+Site overrides replace the entire default sampling transect. Sparse overrides
+can make a threshold crossed between two points appear at the nearer point.
+
+Indoor accumulation requires an explicit enclosure definition through
+`H2STATION_HYRAM_INDOOR_JSON`; no enclosure geometry is invented. A site-specific
+backend can instead be selected with
+`H2STATION_HYRAM_EVALUATOR=module:function`.
+
+The digital-twin SAGA panel and selected-sensor follow-up questions use dedicated
+`/direct` API routes. The simulator first evaluates the current sensor state,
+then sends the operator's actual question and its calculated context to SAGA's
+single-completion LLM endpoint. This bypasses SAGA's multi-stage RAG/review
+pipeline but retains free-form question answering. The operator can manually
+select Service Hub or Groq. Groq's direct model defaults to Qwen with reasoning
+disabled; Service Hub defaults to the non-reasoning Llama instruct model. If the selected LLM is
+unavailable, the interface labels the connection error and retains a local
+sensor-based fallback answer. The older analysis API remains available for
+existing integrations, but the digital-twin interface does not call it.
+
+The direct-answer numeric guard normalizes equivalent value/unit spellings and
+shared-unit ranges before filtering. Its provider-free 5-case regression is
+documented in
+[`research/SAGA_MEASUREMENT_GUARD_REGRESSION_2026_10_08.md`](research/SAGA_MEASUREMENT_GUARD_REGRESSION_2026_10_08.md);
+this verifies filter behavior only, not response correctness or operator benefit.
+
+Consequence evaluation remains in the direct path. An active warning/critical
+state automatically evaluates relevant nodes before building the answer. Normal
+operation only evaluates consequences when the operator explicitly requests an
+impact or uses **센서 기준 가상 평가**. The calculations use current GOOD-quality
+pressure and temperature readings. An active leak uses its current orifice size
+and flow; a hypothetical case uses a 1 mm horizontal release at 1 m height and
+101325 Pa ambient pressure. The calculated result, sensor tags, and assumptions
+are passed to both the direct state endpoint and the one-pass LLM. Reported distance is the farthest sampled
+point exceeding 5 kW/m² or 5 kPa, not a validated site safety boundary. Missing
+sensor pairs or an unavailable backend never produce an invented distance.
+
+## Engineering status
+
+This is a modeling and monitoring prototype, not a certified controller. Reference
+scenario dimensions and thermal parameters are illustrative until calibrated against
+traceable equipment and test data. SAE J2601 tables remain licensed external inputs.
+The complete modeling basis, literature, limitations, and validation plan are in
+`docs/`.
+
+The partial-station boundary experiment is documented in
+[`docs/PARTIAL_STATION_VALIDATION.md`](docs/PARTIAL_STATION_VALIDATION.md).
+It is a development diagnostic with an explicit upstream-pressure assumption;
+it does not upgrade the full-station validation claim.
+
+The current public-data intake lead is documented in
+[`research/NBSDC_HEAVY_VEHICLE_FAST_REFUELING_ACCESS_RECHECK_2026_10_06.md`](research/NBSDC_HEAVY_VEHICLE_FAST_REFUELING_ACCESS_RECHECK_2026_10_06.md).
+Its numerical files require an approved portal request. Once a rights-cleared
+workbook or CSV export is obtained, the explicit-unit loader in
+[`src/h2station/nbsdc_ingest.py`](src/h2station/nbsdc_ingest.py) can produce
+in-memory pressure, temperature and flow traces without publishing raw rows.
+The test-cylinder data remains a component/protocol candidate until its mapping
+to a vehicle-side validation contract is independently confirmed.
+
+For owner-held full-loop logger data, the controlled exporter accepts CSV, XLSX,
+and XLSM sources.  It offers a header-only preflight that does not read
+measurement rows, then writes only canonical columns and relative time to a
+directory outside this repository.  See
+[`research/CONTROLLED_FULL_LOOP_XLSX_INTAKE.md`](research/CONTROLLED_FULL_LOOP_XLSX_INTAKE.md).