pyeldqm 0.1.3

pyELDQM is an open-source, modular toolkit for real-time chemical emergency modelling. It provides Gaussian plume / puff dispersion, dense-gas (Britter-McQuaid), fire & explosion consequence models, PAR (Protective Action Recommendation) analysis, evacuation route optimisation, and an interactive Dash web application — all in pure Python.

Author: Dr. Zohaib Atiq Khan

Other Contributors:

• Dr. Muhammad Imran Rashid
• Mr. Muhammad Ahmad
• Ms. Aroosa Dilbar
• Mr. Muhammad Saleem Akhtar
• Ms. Fatima

---

Features

Module	Description
Dispersion	Gaussian plume/puff (single & multi-source), dense-gas Britter-McQuaid ODE
Source models	Gas pipeline leaks, pressurised tank gas/liquid/two-phase releases, puddle evaporation
Fire & explosion	Pool fire, jet fire thermal flux; flash-fire radius; BLEVE
Meteorology	Pasquill-Gifford stability classification, Monin-Obukhov / power-law wind profiles, solar insolation
Health thresholds	AEGL, ERPG, IDLH, PAC look-up from SQLite chemical database
Consequences	AEGL/ERPG hazard-zone footprints from dispersion output
PAR analysis	Shelter-in-place vs. evacuation decision support with population raster integration
Sensor placement	Coverage-optimised sensor network design
Evacuation routing	OpenStreetMap-based route optimisation (osmnx / networkx)
Web app	Interactive Dash 2 dashboard with real-time threat maps (Folium/Leaflet)

---

Installation

Recommended: Install pyELDQM inside a dedicated virtual environment to avoid package conflicts with other projects on your system.

# 1. Create and activate a virtual environment
python -m venv pyeldqm-env

# Windows
pyeldqm-env\Scripts\activate
# macOS / Linux
source pyeldqm-env/bin/activate

# 2. Install pyELDQM
pip install pyeldqm

Conda installation (local build)

# 1. Create and activate a conda environment
conda create -n pyeldqm python=3.14
conda activate pyeldqm

# 2a. Install published release from PyPI
pip install pyeldqm

# 2b. OR install from local source (development / editable)
pip install -e .

Important: Always use pip install -e . (note the -e flag) when installing from a cloned source tree. Omitting -e will cause a "unable to open database file" error and missing-module errors.

Development install

git clone https://github.com/SIHPCC/pyeldqm.git
cd pyeldqm
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e .

---

Quick start

Launch the web application

pyeldqm-app
# → http://localhost:8050

Environment variables (all optional):

Variable	Default	Description
PORT	8050	Listening port
HOST	localhost	Bind address
DEBUG	true	Dash debug mode

Step-by-step setup and launch (VS Code)

The screenshots below show the full workflow from a clean PC to a running dashboard.

Step 1 — Install the Python extension in VS Code

Open VS Code, go to the Extensions marketplace, search for Python (by Microsoft), and click Install.

---

Step 2 — Open a terminal

In VS Code go to Terminal → New Terminal (or press Ctrl+Shift+`).

---

Step 3 — Create a virtual environment and install pyELDQM

python -m venv env
env\Scripts\activate
pip install pyeldqm

---

Step 4 — Launch the dashboard

pyeldqm-app

The terminal will print the local URL (e.g. http://localhost:8050).

---

Step 5 — Open the dashboard in your browser

Navigate to the URL printed in the terminal. The pyELDQM dashboard opens with the Chemical Threat Zones tab active.

---

Save the screenshots: Place the five images from the guide above in docs/images/ using these exact filenames: setup_step1_install_python.png, setup_step2_open_terminal.png, setup_step3_install_pyeldqm.png, setup_step4_run_app.png, setup_step5_dashboard.png.

---

Run on Windows using the executable (.exe)

If you use the packaged one-file build (for example pyELDQM.exe), you can run the app without creating a Python environment on the target PC.

Download: The latest packaged Windows executable is intended to be distributed through GitHub Releases:

• Latest release page: https://github.com/SIHPCC/pyeldqm/releases/latest
• All releases: https://github.com/SIHPCC/pyeldqm/releases

Can I copy only the .exe file?

Yes. For the one-file PyInstaller build, you can copy only pyELDQM.exe to another Windows 64-bit PC and run it.

Requirements on the target PC

• Windows 64-bit (same architecture as build machine)
• Internet connection for Emergency Route optimization (OpenStreetMap network download)
• Any user input datasets you choose at runtime (for example GeoTIFF population raster files)
• Microsoft Visual C++ runtime may be required on some systems

How to run

1. Copy pyELDQM.exe to the target PC.
2. Double-click pyELDQM.exe.
3. Open the shown local URL in a browser (typically http://localhost:8050).

Notes

• First launch can be slower because one-file executables extract temporary runtime files.
• If port 8050 is busy, set the PORT environment variable before launching.

Python API

from pyeldqm.core.chemical_database import ChemicalDatabase

with ChemicalDatabase() as db:
    ammonia = db.get_chemical_by_name("AMMONIA")
    print(ammonia["cas_number"], ammonia["molecular_weight"])

from pyeldqm.core.meteorology.realtime_weather import get_weather

# Real-time weather (Open-Meteo)
weather = get_weather(source="open_meteo", latitude=24.9, longitude=67.1)
print(weather["wind_speed"], weather["wind_dir"], weather["temperature_K"])

import numpy as np
from pyeldqm.core.dispersion_models.gaussian_model import multi_source_concentration

# 2D local grid (meters)
x_vals = np.linspace(10, 2000, 200)
y_vals = np.linspace(-800, 800, 160)
X, Y = np.meshgrid(x_vals, y_vals)

# Multiple continuous release sources (g/s)
sources = [
    {"name": "A", "Q": 800, "x0": 0, "y0": 0, "h_s": 3.0, "wind_dir": 45.0},
    {"name": "B", "Q": 600, "x0": 250, "y0": -120, "h_s": 2.5, "wind_dir": 45.0},
]

C_total = multi_source_concentration(
    sources=sources,
    x_grid=X,
    y_grid=Y,
    z=1.5,
    t=600,
    t_r=600,
    U=5.0,
    stability_class="D",
    roughness="URBAN",
    mode="continuous",
    grid_wind_direction=45.0,
)
print(float(np.max(C_total)))

---

Scenario configuration (YAML)

Pre-built scenarios live in pyeldqm/configs/:

File	Scenario
base_config.yaml	Generic Gaussian dispersion
chlorine_pipeline_leak.yaml	Chlorine pipeline rupture
ammonia_tank_release.yaml	Pressurised ammonia tank release
lpg_bleve.yaml	LPG pool fire / BLEVE
realtime_monitoring.yaml	Live weather + multi-source

---

Project structure

pyELDQM/
|-- pyeldqm/                       # Python package root
|   |-- app/                       # Dash web application
|   |   |-- assets/
|   |   |-- callbacks/
|   |   |-- components/
|   |   |   `-- tabs/
|   |   |-- layout/
|   |   `-- utils/
|   |       `-- script_generator/
|   |-- core/                      # Scientific and modelling engine
|   |   |-- dispersion_models/
|   |   |-- evacuation/
|   |   |-- fire_models/
|   |   |-- geography/
|   |   |-- meteorology/
|   |   |-- population/
|   |   |-- protective_actions/
|   |   |-- source_models/
|   |   |   |-- gas_pipeline/
|   |   |   |-- puddle_evaporation/
|   |   |   `-- tank_release/
|   |   |-- utils/
|   |   `-- visualization/
|   |-- data/                      # Runtime/reference data
|   |   |-- chemicals_database/
|   |   |-- geographic_data/
|   |   |-- population/
|   |   |-- thermodynamics_data/
|   |   `-- weather_samples/
|   |-- configs/                   # Scenario YAML files
|   `-- validation/
|       `-- validation_scripts/
|-- examples/
|   |-- notebooks/
|   `-- scripts/
|-- docs/
|   `-- images/
|-- tests/
|-- cache/
|-- outputs/
|-- .github/
|   `-- workflows/
|-- run_app.py
|-- pyproject.toml
|-- MANIFEST.in
|-- requirements.txt
|-- CHANGELOG.md
|-- CONTRIBUTING.md
|-- README.md
`-- LICENSE

---

Gallery

Screenshot	Description
	Chemical Threat Zones
	Population At Risk analysis
	Emergency route optimization
	Sensor network optimization
	Health impact threshold zones
	Shelter-in-place vs evacuation guidance

---

Running tests

pytest tests/ --cov=core --cov-report=term-missing

The test suite covers dispersion utilities, meteorology, health thresholds, geographic constants, source models, fire models, and consequence models (~65 tests).

---

Contributing

See CONTRIBUTING.md for setup instructions, coding standards, and the pull-request workflow.

---

License

MIT — see LICENSE.