Metadata-Version: 2.4
Name: ventpy
Version: 0.1.0
Summary: High-performance mine ventilation calculation library (DS 024-2016-EM, Peru)
Keywords: mining,ventilation,safety,DS024,engineering
Author-Email: Miqueas Quintanilla Ventura <miqueasq@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Project-URL: Homepage, https://github.com/Miqueas7/VentPy
Project-URL: Repository, https://github.com/Miqueas7/VentPy
Project-URL: Issues, https://github.com/Miqueas7/VentPy/issues
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Requires-Dist: numpy>=1.24; extra == "viz"
Description-Content-Type: text/markdown

# VentPy

[English](README.md) | [Español](README.es.md)

High-performance underground mine ventilation calculations for Python, backed by a C++20 core.

VentPy helps mining engineers estimate ventilation demand for underground operations using an auditable API oriented around the Peruvian regulatory framework `DS 024-2016-EM / DS 023-2017-EM`.

## What VentPy Does

VentPy provides calculation tools for:

- Personnel-based airflow demand
- Diesel fleet airflow demand
- Blasting gas dilution airflow
- Atmospheric corrections at altitude
- Leakage adjustments for ducted ventilation
- Consolidated ventilation demand with governing-factor selection
- Optional visualization and HTML reporting helpers in Python

The library is designed for engineering workflows where performance, reproducibility, and traceability matter.

## Why This Library Exists

Mine ventilation calculations are often implemented in spreadsheets that become difficult to validate, reuse, or integrate into larger workflows. VentPy moves those calculations into a typed, testable library with:

- A C++ core for predictable performance
- Python bindings for scripting, analysis, and integration
- Explicit result objects instead of opaque spreadsheet formulas
- Domain-oriented inputs for personnel, diesel equipment, blasting, atmosphere, and leakage

## Regulatory Scope

Current defaults are based on:

- `DS 024-2016-EM`
- `DS 023-2017-EM`

The default `RegulatoryConfig` reflects this Peruvian framework, while still allowing stricter corporate parameters to be injected when needed.

## Project Status

VentPy is currently in `alpha`.

Implemented and exposed today:

- Personnel flow calculations
- Diesel flow calculations
- Blasting flow calculations
- Atmospheric correction utilities
- Integrated ventilation governor
- Python visualization helpers

Additional result types for dust, thermal, and leakage are already part of the public model, but the practical maturity of each workflow should be validated against your engineering use case before operational adoption.

## Installation

VentPy currently builds from source.

### Requirements

- Python `3.9+`
- CMake `3.20+`
- A compiler with `C++20` support

### Install in a Virtual Environment

```bash
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
pip install .
```

For development:

```bash
pip install -e .[test,viz]
```

## Quick Start

```python
import ventpy

config = ventpy.RegulatoryConfig()
governor = ventpy.VentilationGovernor(config)

inp = ventpy.VentilationInput()
inp.num_workers = 15
inp.altitude_masl = 4200.0

result = governor.calculate_total_demand(inp)

print(f"Q_total = {result.q_total_m3min} m3/min")
print(f"Q_total = {result.q_total_cfm:.1f} cfm")
print(f"Governing factor = {result.governing_factor}")
```

## Example With Diesel Fleet and Blasting

```python
import ventpy

config = ventpy.RegulatoryConfig()
governor = ventpy.VentilationGovernor(config)

inp = ventpy.VentilationInput()
inp.zone_type = ventpy.ZoneType.DevelopmentFace
inp.face_area_m2 = 15.0
inp.face_length_m = 120.0
inp.safety_factor = 1.10
inp.simultaneity_factor = 0.85

inp.atmospheric = ventpy.AtmosphericParams()
inp.atmospheric.altitude_masl = 4200.0
inp.atmospheric.dry_bulb_temp_c = 22.0

inp.personnel = ventpy.PersonnelParams()
inp.personnel.num_workers = 12
inp.personnel.activity = ventpy.ActivityLevel.Moderate

fleet = ventpy.DieselFleet()
fleet.add_equipment("Scooptram ST1030", 180.0, 0.88, 0.75)
inp.diesel_fleet = fleet

blast = ventpy.BlastingParams()
blast.explosive_kg = 50.0
blast.explosive_type = ventpy.ExplosiveType.ANFO
blast.dilution_time_min = 30.0
blast.face_area_m2 = 15.0
blast.face_length_m = 120.0
inp.blasting_params = blast

result = governor.calculate_total_demand(inp)

print(result.q_personnel_m3min)
print(result.q_diesel_m3min)
print(result.q_blasting_m3min)
print(result.q_total_m3min)
print(result.velocity_at_face_mps)
print(result.warnings)
```

## Core API

Main entry points:

- `RegulatoryConfig`
- `VentilationGovernor`
- `VentilationInput`
- `DieselFleet`
- `AtmosphericParams`
- `PersonnelParams`
- `BlastingParams`

Direct calculators:

- `calculate_personnel_flow(...)`
- `calculate_diesel_flow(...)`
- `calculate_blasting_flow(...)`
- `calculate_atmospheric_corrections(...)`

Useful utilities:

- `calculate_pressure_kpa(...)`
- `calculate_density_kg_m3(...)`
- `calculate_volume_correction_factor(...)`
- `calculate_diesel_derate_factor(...)`
- `get_min_velocity(...)`
- `safety_ceil(...)`

## Visualization

VentPy includes a Python visualization module intended for quick engineering communication and reporting.

Available helpers include:

- `plot_flow_comparison(...)`
- `plot_flow_breakdown(...)`
- `create_dashboard(...)`
- `generate_html_report(...)`

Example:

```python
from ventpy import visualization as viz

html = viz.generate_html_report(
    {
        "q_personnel_m3min": 45.0,
        "q_diesel_m3min": 267.0,
        "q_blasting_m3min": 50.0,
        "q_dust_m3min": 0.0,
        "q_thermal_m3min": 0.0,
        "q_leakage_m3min": 50.0,
        "q_governing_m3min": 267.0,
        "q_total_m3min": 317.0,
    },
    include_charts=False,
)
```

If you want chart rendering, install `matplotlib` in your environment.
The optional visualization dependency set can be installed with `pip install -e .[viz]`.

## Development

Run Python tests with:

```bash
pytest
```

The project also contains C++ tests that can be enabled through CMake when needed.

## Repository Layout

```text
include/          C++ headers for the calculation core
bindings/         nanobind Python bindings
python/ventpy/    Python package and visualization helpers
tests/            Python and C++ tests
```

## Engineering Disclaimer

VentPy is a calculation library, not a substitute for engineering judgment, ventilation surveys, field measurements, or regulatory review.

Use it as a computational aid. Final ventilation design decisions remain the responsibility of the qualified engineer of record.

## License

MIT
