Metadata-Version: 2.4
Name: pyeldqm
Version: 0.1.3
Summary: Python-based real-time emergency leakage and dispersion quantification model
License: MIT
Project-URL: Homepage, https://github.com/SIHPCC/pyeldqm
Project-URL: Issues, https://github.com/SIHPCC/pyeldqm/issues
Keywords: dispersion,emergency,hazmat,chemical,AEGL,ALOHA,atmospheric,consequence-modelling
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: <3.15,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Requires-Dist: matplotlib>=3.3
Requires-Dist: scikit-image>=0.19
Requires-Dist: scikit-learn>=1.0
Requires-Dist: PyYAML>=5.4
Requires-Dist: pandas>=1.3
Requires-Dist: pytz>=2021.1
Requires-Dist: timezonefinder>=5.2
Requires-Dist: requests>=2.25
Requires-Dist: pyowm>=3.0
Requires-Dist: geopy>=2.2
Requires-Dist: pyproj>=3.0
Requires-Dist: networkx>=2.6
Requires-Dist: osmnx>=1.3
Requires-Dist: geopandas>=0.9
Requires-Dist: rasterio>=1.2
Requires-Dist: elevation>=1.0
Requires-Dist: folium>=0.14
Requires-Dist: branca>=0.6
Requires-Dist: shapely>=1.7
Requires-Dist: plotly>=5.17
Requires-Dist: dash>=2.14
Requires-Dist: dash-bootstrap-components>=1.5
Dynamic: license-file


<p align="center"><img src="docs/images/pyELDQM_logo_v0.1.png" alt="pyELDQM logo" width="100%" style="max-width: 1200px; height: auto;" /></p>

[![CI](https://github.com/SIHPCC/pyeldqm/actions/workflows/ci.yml/badge.svg)](https://github.com/SIHPCC/pyeldqm/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pyeldqm.svg)](https://pypi.org/project/pyeldqm/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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.

```bash
# 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)

```bash
# 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

```bash
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

```bash
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 1 – Install Python extension](docs/images/setup_step1_install_python.png)

---

**Step 2 — Open a terminal**

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

![Step 2 – Open terminal](docs/images/setup_step2_open_terminal.png)

---

**Step 3 — Create a virtual environment and install pyELDQM**

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

![Step 3 – Create environment and install](docs/images/setup_step3_install_pyeldqm.png)

---

**Step 4 — Launch the dashboard**

```cmd
pyeldqm-app
```

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

![Step 4 – Run pyeldqm-app](docs/images/setup_step4_run_app.png)

---

**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.

![Step 5 – Dashboard](docs/images/setup_step5_dashboard.png)

---

> **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

```python
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"])
```

```python
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"])
```

```python
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 |
|---|---|
| ![Threat Zones](docs/images/threat_zones.png) | Chemical Threat Zones|
| ![PAR Analysis](docs/images/par_analysis.png) | Population At Risk analysis |
| ![Emergency Routes](docs/images/emergency_routes.png) | Emergency route optimization |
| ![Sensor Placement](docs/images/sensor_placement.png) | Sensor network optimization |
| ![Health Impact](docs/images/health_impact.png) | Health impact threshold zones |
| ![Shelter Status](docs/images/shelter_status.png) | Shelter-in-place vs evacuation guidance |

---

## Running tests

```bash
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](CONTRIBUTING.md) for setup instructions, coding standards, and the
pull-request workflow.

---

## License

MIT — see [LICENSE](LICENSE).

