ventpy 0.2.0__tar.gz → 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {ventpy-0.2.0 → ventpy-0.2.1}/CHANGELOG.md +45 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/CMakeLists.txt +2 -1
- ventpy-0.2.1/PKG-INFO +228 -0
- ventpy-0.2.1/README.es.md +201 -0
- ventpy-0.2.1/README.md +201 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/bindings/bindings.cpp +4 -2
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_equipo.hpp +10 -4
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_explosivos.hpp +14 -4
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_personal.hpp +31 -16
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_polvo.hpp +20 -11
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_termico.hpp +23 -24
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/cobertura.hpp +34 -16
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/normativa.hpp +184 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/pyproject.toml +2 -1
- {ventpy-0.2.0 → ventpy-0.2.1}/python/ventpy/__init__.py +1 -1
- ventpy-0.2.1/tests/cpp/test_citas_normativas.cpp +460 -0
- ventpy-0.2.1/tests/python/test_citas_normativas.py +284 -0
- ventpy-0.2.0/PKG-INFO +0 -288
- ventpy-0.2.0/README.es.md +0 -262
- ventpy-0.2.0/README.md +0 -262
- {ventpy-0.2.0 → ventpy-0.2.1}/.github/ISSUE_TEMPLATE/norma-pais.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/.github/ISSUE_TEMPLATE/numero-incorrecto.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/.github/workflows/release.yml +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/.github/workflows/tests.yml +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/.gitignore +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/CONTRIBUTING.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/LICENSE +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/ROADMAP.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/01-demanda-peru/README.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/01-demanda-peru/input.json +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/01-demanda-peru/run.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/02-preset-chile/README.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/02-preset-chile/input.json +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/02-preset-chile/run.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/03-cobertura-levantamiento/README.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/03-cobertura-levantamiento/input.json +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/03-cobertura-levantamiento/run.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/04-red-ventilador/README.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/04-red-ventilador/input.json +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/04-red-ventilador/run.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/05-ducto-seleccion/README.md +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/examples/05-ducto-seleccion/run.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/atkinson.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/atmosphere.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_fugas.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/ducto.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/governor.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/limites_gases.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/red.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/types.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/validation.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/ventilador.hpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/python/ventpy/cli.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/python/ventpy/visualization.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_atkinson.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_equipo.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_explosivos.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_fugas.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_personal.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_polvo.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_termico.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_cobertura.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_ducto.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_governor.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_limites_gases.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_normativa.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_red.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_validation.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_ventilador.cpp +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_cli.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_cobertura.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_escala.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_examples.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_multinorma.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_polvo_termico.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_properties.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_red_ventilacion.py +0 -0
- {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_ventpy.py +0 -0
|
@@ -4,6 +4,51 @@ Todas las versiones publicadas de VentPy. El formato sigue
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el versionado es
|
|
5
5
|
[semántico](https://semver.org/lang/es/).
|
|
6
6
|
|
|
7
|
+
## [0.2.1] — 2026-08-20
|
|
8
|
+
|
|
9
|
+
### La cita normativa sigue a la norma configurada
|
|
10
|
+
|
|
11
|
+
Hasta 0.2.0 la referencia legal de cada resultado estaba escrita como literal
|
|
12
|
+
peruano dentro de cada calculador y no consultaba la norma de la
|
|
13
|
+
configuración. Con `RegulatoryConfig.chile()` los caudales eran correctos,
|
|
14
|
+
pero la cita que los acompañaba era el DS 024-2016-EM peruano.
|
|
15
|
+
|
|
16
|
+
**A quién afecta:** a quien haya emitido informes con el preajuste chileno. Los
|
|
17
|
+
números no cambian —ni uno solo—; lo que cambia es el respaldo legal impreso
|
|
18
|
+
junto a ellos. Conviene reemitir esos informes: citaban el reglamento peruano
|
|
19
|
+
en una faena chilena.
|
|
20
|
+
|
|
21
|
+
| Resultado | Perú (DS 024) | Chile (DS 132) |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| Caudal por persona | Art. 236, con la escala por altitud del Art. 247 | **Art. 138**, sin escala por altitud |
|
|
24
|
+
| Caudal por HP diésel | Art. 246 | **Art. 132** |
|
|
25
|
+
| Dilución tras voladura | Art. 243-244 | **Arts. 156, 571 y 585** (reingreso). El DS 132 no fija tiempo de dilución ni volumen de gases por kg: son criterio de ingeniería, y la cita lo dice |
|
|
26
|
+
| Polvo respirable | Art. 111 | Sin límite verificado: la cita declara el vacío y atribuye la concentración objetivo a criterio de ingeniería |
|
|
27
|
+
| Carga térmica | Art. 252 lit. d | Sin criterio verificado: el piso de 30 m/min se mantiene —el caudal es el mismo— pero la cita lo declara criterio de ingeniería |
|
|
28
|
+
| Cobertura y velocidad del aire | Art. 252 lit. f/g y Art. 248 | Sin régimen ni límites verificados: la cita declara el vacío y remite a los umbrales configurados |
|
|
29
|
+
|
|
30
|
+
Donde el DS 132 no regula un concepto, la cita lo dice explícitamente en vez de
|
|
31
|
+
trasladar el artículo peruano. Ningún artículo chileno se cita sin verificar
|
|
32
|
+
contra el texto vigente (LeyChile idNorma=221064, versión 09-abr-2024).
|
|
33
|
+
|
|
34
|
+
### Cambios
|
|
35
|
+
|
|
36
|
+
- Nueva función `regulation_reference(topic, config)` en `normativa.hpp`: único
|
|
37
|
+
lugar del núcleo donde vive el texto de una cita. Cada calculador la consulta
|
|
38
|
+
en lugar de llevar su propio literal.
|
|
39
|
+
- `CoverageCalculator.compare_zone` acepta un cuarto argumento `config` que fija
|
|
40
|
+
la norma de la cita. Su valor por defecto es el preajuste peruano, igual que
|
|
41
|
+
el constructor por defecto de `RegulatoryConfig`; el código existente no
|
|
42
|
+
cambia de comportamiento. `analyze_survey` propaga la configuración que ya
|
|
43
|
+
recibía.
|
|
44
|
+
- Las advertencias de sílice, de concentración de polvo sobre el umbral, de
|
|
45
|
+
estrés térmico y de velocidad fuera de rango también siguen la norma activa.
|
|
46
|
+
|
|
47
|
+
### Versiones
|
|
48
|
+
|
|
49
|
+
- `CMakeLists.txt` declaraba 0.1.0 mientras `pyproject.toml` y el paquete
|
|
50
|
+
Python declaraban 0.2.0. Las tres quedan en 0.2.1.
|
|
51
|
+
|
|
7
52
|
## [0.2.0] — 2026-08-20
|
|
8
53
|
|
|
9
54
|
### ⚠️ Los resultados cambian respecto de 0.1.0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
cmake_minimum_required(VERSION 3.20)
|
|
2
2
|
project(ventpy
|
|
3
|
-
VERSION 0.1
|
|
3
|
+
VERSION 0.2.1
|
|
4
4
|
DESCRIPTION "High-performance mine ventilation calculation library"
|
|
5
5
|
LANGUAGES CXX
|
|
6
6
|
)
|
|
@@ -98,6 +98,7 @@ if(VENTPY_BUILD_TESTS)
|
|
|
98
98
|
tests/cpp/test_caudal_termico.cpp
|
|
99
99
|
tests/cpp/test_governor.cpp
|
|
100
100
|
tests/cpp/test_normativa.cpp
|
|
101
|
+
tests/cpp/test_citas_normativas.cpp
|
|
101
102
|
tests/cpp/test_limites_gases.cpp
|
|
102
103
|
tests/cpp/test_cobertura.cpp
|
|
103
104
|
tests/cpp/test_atkinson.cpp
|
ventpy-0.2.1/PKG-INFO
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ventpy
|
|
3
|
+
Version: 0.2.1
|
|
4
|
+
Summary: High-performance mine ventilation library: airflow demand, coverage, network solving and fan selection (Peru DS 024, Chile DS 132)
|
|
5
|
+
Keywords: mining,ventilation,safety,DS024,DS132,hardy-cross,atkinson,ventilation-network,engineering
|
|
6
|
+
Author-Email: Miqueas Quintanilla Ventura <miqueasq@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Science/Research
|
|
11
|
+
Classifier: Topic :: Scientific/Engineering
|
|
12
|
+
Classifier: Programming Language :: C++
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Project-URL: Homepage, https://github.com/Miqueas7/VentPy
|
|
16
|
+
Project-URL: Documentation, https://miqueas.dev/ventpy
|
|
17
|
+
Project-URL: Repository, https://github.com/Miqueas7/VentPy
|
|
18
|
+
Project-URL: Issues, https://github.com/Miqueas7/VentPy/issues
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Provides-Extra: test
|
|
21
|
+
Requires-Dist: pytest>=7.0; extra == "test"
|
|
22
|
+
Requires-Dist: hypothesis>=6.0; extra == "test"
|
|
23
|
+
Provides-Extra: viz
|
|
24
|
+
Requires-Dist: matplotlib>=3.7; extra == "viz"
|
|
25
|
+
Requires-Dist: numpy>=1.24; extra == "viz"
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# VentPy
|
|
29
|
+
|
|
30
|
+
[English](https://github.com/Miqueas7/VentPy/blob/master/README.md) | [Español](https://github.com/Miqueas7/VentPy/blob/master/README.es.md)
|
|
31
|
+
|
|
32
|
+
[](https://pypi.org/project/ventpy/)
|
|
33
|
+
[](https://pypi.org/project/ventpy/)
|
|
34
|
+
[](https://github.com/Miqueas7/VentPy/blob/master/LICENSE)
|
|
35
|
+
[](https://github.com/Miqueas7/VentPy/actions/workflows/tests.yml)
|
|
36
|
+
|
|
37
|
+
> **Documentation:** **https://miqueas.dev/ventpy** — bilingual, with worked examples, the regulatory tables generated from the library itself, and the article-to-code-to-test traceability matrix.
|
|
38
|
+
>
|
|
39
|
+
> Start here: [Installation](https://miqueas.dev/ventpy/en/guia/instalacion/) · [First calculation](https://miqueas.dev/ventpy/en/guia/primer-calculo/) · [The auditable result](https://miqueas.dev/ventpy/en/guia/resultado-auditable/) · [Worked examples](https://miqueas.dev/ventpy/en/casos/demanda/) · [Engineering criteria](https://miqueas.dev/ventpy/en/fundamento/criterios/)
|
|
40
|
+
|
|
41
|
+
High-performance underground mine ventilation calculations for Python, backed by a C++20 core.
|
|
42
|
+
|
|
43
|
+
VentPy helps mining engineers estimate ventilation demand for underground operations through an auditable API covering personnel, diesel fleets, blasting, dust, thermal load, atmospheric corrections, duct/network design and fan selection, currently under the Peruvian (`DS 024-2016-EM` / `DS 023-2017-EM`) and Chilean (`DS 132` / `DS 594`) regulatory frameworks. Calculations run in a typed, tested C++ core instead of a spreadsheet: every result carries its governing criterion and its regulatory citation, not just a number.
|
|
44
|
+
|
|
45
|
+
## What VentPy Does
|
|
46
|
+
|
|
47
|
+
- Personnel-based airflow demand (`DS 024-2016-EM, Art. 247` altitude scale / `DS 132, Art. 138`)
|
|
48
|
+
- Diesel fleet airflow demand, including CO/NOx dilution by engine emission tier
|
|
49
|
+
- Blasting gas dilution airflow
|
|
50
|
+
- Respirable dust and thermal-load airflow, integrated into the consolidated demand
|
|
51
|
+
- Leakage adjustments for ducted ventilation
|
|
52
|
+
- Atmospheric corrections at altitude (pressure, density, oxygen partial pressure)
|
|
53
|
+
- Consolidated ventilation demand with governing-factor selection (`VentilationGovernor`)
|
|
54
|
+
- Coverage/deficit analysis: measured airflow vs. required, by zone and for the whole mine
|
|
55
|
+
- Atkinson airway resistance and duct sizing (technical and economic criteria)
|
|
56
|
+
- Ventilation network balance by the Hardy Cross method, with automatic mesh detection
|
|
57
|
+
- Fan curve, operating point and stall margin, standalone or coupled to a network
|
|
58
|
+
- Permissible exposure limits (LMP) for regulated gases, by standard
|
|
59
|
+
- A `ventpy` command-line interface and optional visualization/HTML reporting helpers
|
|
60
|
+
|
|
61
|
+
## Multi-Standard Support
|
|
62
|
+
|
|
63
|
+
VentPy ships official presets for two regulatory frameworks, each constant citing its article:
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import ventpy
|
|
67
|
+
|
|
68
|
+
peru = ventpy.calculate_personnel_flow(15, 4200.0, ventpy.RegulatoryConfig.peru())
|
|
69
|
+
chile = ventpy.calculate_personnel_flow(15, 4200.0, ventpy.RegulatoryConfig.chile())
|
|
70
|
+
|
|
71
|
+
print(f"Peru: {peru.q_personnel} m3/min ({peru.flow_per_person_base} m3/min/person)")
|
|
72
|
+
print(f"Chile: {chile.q_personnel} m3/min ({chile.flow_per_person_base} m3/min/person)")
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Output:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
Peru: 90.0 m3/min (6.0 m3/min/person)
|
|
79
|
+
Chile: 45.0 m3/min (3.0 m3/min/person)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
- `RegulatoryConfig.peru()` — `DS 024-2016-EM` / `DS 023-2017-EM`.
|
|
83
|
+
- `RegulatoryConfig.chile()` — `DS 132`, Reglamento de Seguridad Minera (gas limits also draw on `DS 594`).
|
|
84
|
+
- `RegulatoryConfig.for_standard(standard)` — builds either preset from a `RegulatoryStandard` enum member; used internally by the CLI's `--norma peru|chile` flag.
|
|
85
|
+
|
|
86
|
+
Adding another country's standard is the contribution VentPy needs most — see [Contributing](#contributing).
|
|
87
|
+
|
|
88
|
+
## Project Status
|
|
89
|
+
|
|
90
|
+
VentPy is in **beta**. Personnel, diesel, blasting, dust, thermal, coverage, network, fan and atmospheric calculations are implemented, tested (219 C++ tests and 176 Python tests, including property-based and 500-branch scale tests) and exposed to Python for both presets.
|
|
91
|
+
|
|
92
|
+
> **Citations changed in 0.2.1 — the numbers did not.** Until 0.2.0, every result cited the Peruvian framework even when built with `RegulatoryConfig.chile()`: the airflow was correct, the legal reference printed next to it was not. From 0.2.1 the citation follows the configured standard, and where `DS 132` does not regulate a concept the citation says so explicitly instead of borrowing a Peruvian article. If you issued reports using the Chilean preset, reissue them.
|
|
93
|
+
|
|
94
|
+
> **Results changed between 0.1.0 and 0.2.0.** Version 0.2.0 corrects three normative citations in the core. If you calculated anything with 0.1.0, recompute it, especially above 1,500 masl.
|
|
95
|
+
>
|
|
96
|
+
> - **Personnel airflow scale** (`DS 024-2016-EM, Art. 247`): now 3/4/5/6 m³/min per person with thresholds at 1,500 / 3,000 / 4,000 masl, matching the article's actual text. 0.1.0 used a 3/4/5 scale with thresholds at 3,000 and 4,000 masl only, and under-counted every mine above 1,500 masl.
|
|
97
|
+
> - **Respirable dust**: the correct citation is `Art. 111` (3 mg/m³ limit for an 8-hour shift, with mandatory work stoppage above it), not "Art. 103-107" as previously cited.
|
|
98
|
+
> - **Maximum effective temperature**: the "Art. 240: 30°C" citation does not exist in the current regulation, it came from the repealed `DS 055-2010-EM`. The applicable rule is `Art. 252.d` (30 m/min minimum velocity between 24-29°C dry bulb) plus `Art. 104` / Annex 13 for heat stress.
|
|
99
|
+
|
|
100
|
+
## Installation
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
pip install ventpy
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Prebuilt wheels are published for Python 3.9 to 3.13 on Linux, macOS and Windows, so no compiler or CMake is required.
|
|
107
|
+
|
|
108
|
+
For chart rendering and HTML report generation, install the visualization extra:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
pip install ventpy[viz]
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Quick Start
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
import ventpy
|
|
118
|
+
|
|
119
|
+
config = ventpy.RegulatoryConfig.peru()
|
|
120
|
+
governor = ventpy.VentilationGovernor(config)
|
|
121
|
+
|
|
122
|
+
inp = ventpy.VentilationInput()
|
|
123
|
+
inp.zone_type = ventpy.ZoneType.DevelopmentFace
|
|
124
|
+
inp.num_workers = 15
|
|
125
|
+
inp.altitude_masl = 4200.0
|
|
126
|
+
|
|
127
|
+
result = governor.calculate_total_demand(inp)
|
|
128
|
+
|
|
129
|
+
print(f"Q_total = {result.q_total_m3min} m3/min")
|
|
130
|
+
print(f"Q_total = {result.q_total_cfm:.1f} cfm")
|
|
131
|
+
print(f"Governing factor = {result.governing_factor}")
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Output:
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
Q_total = 207.0 m3/min
|
|
138
|
+
Q_total = 7310.1 cfm
|
|
139
|
+
Governing factor = personnel (Q_Per)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Five worked, self-verifying examples (each `run.py` asserts its own documented numbers) live under [`examples/`](https://github.com/Miqueas7/VentPy/tree/master/examples/), covering diesel-limited demand, the Chilean preset, coverage/deficit, a fan coupled to a network, and duct sizing.
|
|
143
|
+
|
|
144
|
+
## Command Line Interface
|
|
145
|
+
|
|
146
|
+
Installing VentPy also installs the `ventpy` command, a thin presentation layer over the same public API (no calculation logic of its own) with 5 subcommands:
|
|
147
|
+
|
|
148
|
+
- `ventpy demanda <file.json> [--norma peru|chile] [--json]` — total ventilation demand for a zone/face
|
|
149
|
+
- `ventpy lmp [--norma peru|chile] [--gas GAS] [--json]` — permissible exposure limits (LMP) for regulated gases
|
|
150
|
+
- `ventpy cobertura <file.json> [--norma peru|chile] [--json]` — coverage/deficit analysis of a zone survey
|
|
151
|
+
- `ventpy red <file.json> [--json]` — ventilation network balance (Hardy Cross)
|
|
152
|
+
- `ventpy ventilador <file.json> [--json]` — fan operating point (standalone or coupled to a network)
|
|
153
|
+
|
|
154
|
+
Exit codes are meaningful: `0` success, `1` invalid input, `2` a calculated-but-unreliable result (a network that did not converge, a zone in deficit, a fan operating point outside its catalog curve). See each subcommand's help (`ventpy <subcommand> -h`).
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
$ ventpy lmp --norma peru --gas CO
|
|
158
|
+
standard: DS024_Peru
|
|
159
|
+
gas: CO
|
|
160
|
+
unit: PPM
|
|
161
|
+
twa_8h: 25.0
|
|
162
|
+
stel: None
|
|
163
|
+
ceiling: None
|
|
164
|
+
floor_min: None
|
|
165
|
+
regulation_ref: DS 024-2016-EM, Anexo 15, fila 33 (via Art. 246)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## Core API
|
|
169
|
+
|
|
170
|
+
VentPy exposes 87 public names (`ventpy.__all__`). Main entry points:
|
|
171
|
+
|
|
172
|
+
- `RegulatoryConfig` (`.peru()`, `.chile()`, `.for_standard(...)`)
|
|
173
|
+
- `VentilationGovernor`, `VentilationInput`
|
|
174
|
+
- `DieselFleet`, `AtmosphericParams`, `PersonnelParams`, `BlastingParams`, `DustParams`, `ThermalParams`
|
|
175
|
+
|
|
176
|
+
Direct calculators:
|
|
177
|
+
|
|
178
|
+
- `calculate_personnel_flow`, `calculate_diesel_flow`, `calculate_blasting_flow`, `calculate_dust_flow`, `calculate_thermal_flow`, `calculate_atmospheric_corrections`
|
|
179
|
+
|
|
180
|
+
Network, duct and fan:
|
|
181
|
+
|
|
182
|
+
- `AtkinsonCalculator`, `DuctSizingCalculator`, `NetworkSolver`, `FanCalculator`
|
|
183
|
+
|
|
184
|
+
Coverage and gas limits:
|
|
185
|
+
|
|
186
|
+
- `CoverageCalculator`, `gas_limits(standard)`, `lmp_for(standard, gas)`
|
|
187
|
+
|
|
188
|
+
Utilities:
|
|
189
|
+
|
|
190
|
+
- `calculate_pressure_kpa`, `calculate_density_kg_m3`, `calculate_volume_correction_factor`, `calculate_diesel_derate_factor`, `get_min_velocity`, `safety_ceil`, `safety_ceil_decimals`
|
|
191
|
+
|
|
192
|
+
## Visualization
|
|
193
|
+
|
|
194
|
+
VentPy includes a Python visualization module for quick engineering communication and reporting: `plot_flow_comparison`, `plot_flow_breakdown`, `create_dashboard`, `generate_html_report`.
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
from ventpy import visualization as viz
|
|
198
|
+
|
|
199
|
+
html = viz.generate_html_report(
|
|
200
|
+
{
|
|
201
|
+
"q_personnel_m3min": 45.0,
|
|
202
|
+
"q_diesel_m3min": 267.0,
|
|
203
|
+
"q_blasting_m3min": 50.0,
|
|
204
|
+
"q_dust_m3min": 0.0,
|
|
205
|
+
"q_thermal_m3min": 0.0,
|
|
206
|
+
"q_leakage_m3min": 50.0,
|
|
207
|
+
"q_governing_m3min": 267.0,
|
|
208
|
+
"q_total_m3min": 317.0,
|
|
209
|
+
},
|
|
210
|
+
include_charts=False,
|
|
211
|
+
)
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Chart rendering requires `matplotlib`, included in the `viz` extra (`pip install ventpy[viz]`).
|
|
215
|
+
|
|
216
|
+
## Contributing
|
|
217
|
+
|
|
218
|
+
See [`CONTRIBUTING.md`](https://github.com/Miqueas7/VentPy/blob/master/CONTRIBUTING.md). The most-requested contribution is adding another country's regulatory standard, following the Chilean preset pattern (`RegulatoryConfig::chile()`): locate the values in the regulation, cite each article, add a preset, and add a test with a known case. See [`CHANGELOG.md`](https://github.com/Miqueas7/VentPy/blob/master/CHANGELOG.md) for the full version history.
|
|
219
|
+
|
|
220
|
+
## Engineering Disclaimer
|
|
221
|
+
|
|
222
|
+
VentPy is a calculation library, not a substitute for engineering judgment, ventilation surveys, field measurements, or regulatory review.
|
|
223
|
+
|
|
224
|
+
Use it as a computational aid. Final ventilation design decisions remain the responsibility of the qualified engineer of record.
|
|
225
|
+
|
|
226
|
+
## License
|
|
227
|
+
|
|
228
|
+
MIT — see [`LICENSE`](https://github.com/Miqueas7/VentPy/blob/master/LICENSE).
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# VentPy
|
|
2
|
+
|
|
3
|
+
[English](https://github.com/Miqueas7/VentPy/blob/master/README.md) | [Español](https://github.com/Miqueas7/VentPy/blob/master/README.es.md)
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/ventpy/)
|
|
6
|
+
[](https://pypi.org/project/ventpy/)
|
|
7
|
+
[](https://github.com/Miqueas7/VentPy/blob/master/LICENSE)
|
|
8
|
+
[](https://github.com/Miqueas7/VentPy/actions/workflows/tests.yml)
|
|
9
|
+
|
|
10
|
+
> **Documentación:** **https://miqueas.dev/ventpy** — bilingüe, con casos resueltos, las tablas normativas generadas desde la propia librería y la matriz de trazabilidad que cruza cada artículo con su código y su prueba.
|
|
11
|
+
>
|
|
12
|
+
> Por dónde empezar: [Instalación](https://miqueas.dev/ventpy/guia/instalacion/) · [Primer cálculo](https://miqueas.dev/ventpy/guia/primer-calculo/) · [El resultado auditable](https://miqueas.dev/ventpy/guia/resultado-auditable/) · [Casos resueltos](https://miqueas.dev/ventpy/casos/demanda/) · [Criterios de ingeniería](https://miqueas.dev/ventpy/fundamento/criterios/)
|
|
13
|
+
|
|
14
|
+
Cálculos de ventilación subterránea de alto rendimiento para Python, respaldados por un núcleo en C++20.
|
|
15
|
+
|
|
16
|
+
VentPy ayuda a ingenieros de minas a estimar la demanda de ventilación en operaciones subterráneas mediante una API auditable que cubre personal, flotas diesel, voladura, polvo, carga térmica, correcciones atmosféricas, diseño de ductos/red y selección de ventilador, actualmente bajo los marcos regulatorios peruano (`DS 024-2016-EM` / `DS 023-2017-EM`) y chileno (`DS 132` / `DS 594`). Los cálculos corren en un núcleo C++ tipado y probado en vez de una hoja de cálculo: cada resultado trae su criterio gobernante y su cita normativa, no solo un número.
|
|
17
|
+
|
|
18
|
+
## Qué hace VentPy
|
|
19
|
+
|
|
20
|
+
- Demanda de caudal por personal (escala de `DS 024-2016-EM, Art. 247` por altitud / `DS 132, Art. 138`)
|
|
21
|
+
- Demanda de caudal por flota diesel, incluida la dilución de CO/NOx según el tier de emisión del motor
|
|
22
|
+
- Dilución de gases de voladura
|
|
23
|
+
- Caudal por polvo respirable y por carga térmica, integrados a la demanda consolidada
|
|
24
|
+
- Ajustes por fugas en ventilación con ductos
|
|
25
|
+
- Correcciones atmosféricas por altitud (presión, densidad, presión parcial de oxígeno)
|
|
26
|
+
- Demanda consolidada de ventilación con selección del factor gobernante (`VentilationGovernor`)
|
|
27
|
+
- Análisis de cobertura/déficit: caudal medido vs. requerido, por zona y para toda la mina
|
|
28
|
+
- Resistencia de Atkinson en labores y dimensionamiento de ducto (criterio técnico y económico)
|
|
29
|
+
- Balance de red de ventilación por el método de Hardy Cross, con detección automática de mallas
|
|
30
|
+
- Curva de ventilador, punto de operación y margen de stall, independiente o acoplado a una red
|
|
31
|
+
- Límites máximos permisibles (LMP) de gases regulados, por norma
|
|
32
|
+
- Una interfaz de línea de comandos `ventpy` y ayudas opcionales de visualización y reportes HTML
|
|
33
|
+
|
|
34
|
+
## Soporte multi-norma
|
|
35
|
+
|
|
36
|
+
VentPy trae preajustes oficiales para dos marcos regulatorios, cada constante citando su artículo:
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
import ventpy
|
|
40
|
+
|
|
41
|
+
peru = ventpy.calculate_personnel_flow(15, 4200.0, ventpy.RegulatoryConfig.peru())
|
|
42
|
+
chile = ventpy.calculate_personnel_flow(15, 4200.0, ventpy.RegulatoryConfig.chile())
|
|
43
|
+
|
|
44
|
+
print(f"Peru: {peru.q_personnel} m3/min ({peru.flow_per_person_base} m3/min/person)")
|
|
45
|
+
print(f"Chile: {chile.q_personnel} m3/min ({chile.flow_per_person_base} m3/min/person)")
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Salida:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
Peru: 90.0 m3/min (6.0 m3/min/person)
|
|
52
|
+
Chile: 45.0 m3/min (3.0 m3/min/person)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
- `RegulatoryConfig.peru()` — `DS 024-2016-EM` / `DS 023-2017-EM`.
|
|
56
|
+
- `RegulatoryConfig.chile()` — `DS 132`, Reglamento de Seguridad Minera (los límites de gases también usan el `DS 594`).
|
|
57
|
+
- `RegulatoryConfig.for_standard(standard)` — construye cualquiera de los dos preajustes a partir de un miembro del enum `RegulatoryStandard`; es lo que usa internamente el flag `--norma peru|chile` de la CLI.
|
|
58
|
+
|
|
59
|
+
Agregar la norma de otro país es la contribución que más necesita VentPy — ver [Contribuir](#contribuir).
|
|
60
|
+
|
|
61
|
+
## Estado del proyecto
|
|
62
|
+
|
|
63
|
+
VentPy se encuentra en **beta**. Los cálculos de personal, diesel, voladura, polvo, térmico, cobertura, red, ventilador y atmósfera están implementados, probados (219 pruebas en C++ y 176 en Python, incluidas pruebas basadas en propiedades y de escala hasta 500 ramales) y expuestos a Python para ambos preajustes.
|
|
64
|
+
|
|
65
|
+
> **En la 0.2.1 cambian las citas, no los números.** Hasta la 0.2.0, todo resultado citaba el marco peruano aunque se construyera con `RegulatoryConfig.chile()`: el caudal era correcto, pero la referencia legal impresa junto a él no. Desde la 0.2.1 la cita sigue a la norma configurada, y donde el `DS 132` no regula un concepto, la cita lo declara explícitamente en vez de tomar prestado un artículo peruano. Si emitiste informes con el preajuste chileno, conviene reemitirlos.
|
|
66
|
+
|
|
67
|
+
> **Los resultados cambian entre 0.1.0 y 0.2.0.** La versión 0.2.0 corrige tres citas normativas del núcleo. Si calculaste algo con 0.1.0, conviene rehacerlo, especialmente por encima de 1.500 msnm.
|
|
68
|
+
>
|
|
69
|
+
> - **Escala de caudal por persona** (`DS 024-2016-EM, Art. 247`): ahora es 3/4/5/6 m³/min por persona con umbrales en 1.500 / 3.000 / 4.000 msnm, que es el texto vigente del artículo. La 0.1.0 usaba una escala 3/4/5 con umbrales solo en 3.000 y 4.000 msnm, y calculaba de menos para toda mina por encima de 1.500 msnm.
|
|
70
|
+
> - **Polvo respirable**: la cita correcta es el `Art. 111` (límite de 3 mg/m³ para jornada de 8 h, con paralización obligatoria de la labor si se supera), no "Art. 103-107" como se citaba antes.
|
|
71
|
+
> - **Temperatura efectiva máxima**: la cita "Art. 240: 30 °C" no existe en la norma vigente, proviene del derogado `DS 055-2010-EM`. El criterio aplicable es el `Art. 252 lit. d` (velocidad mínima de 30 m/min con temperatura seca entre 24 y 29 °C) más el `Art. 104` / Anexo 13 para estrés térmico.
|
|
72
|
+
|
|
73
|
+
## Instalación
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
pip install ventpy
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Hay ruedas precompiladas para Python 3.9 a 3.13 en Linux, macOS y Windows, así que no se necesita compilador ni CMake.
|
|
80
|
+
|
|
81
|
+
Para renderizado de gráficos y generación de reportes HTML, instala el extra de visualización:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pip install ventpy[viz]
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Inicio rápido
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
import ventpy
|
|
91
|
+
|
|
92
|
+
config = ventpy.RegulatoryConfig.peru()
|
|
93
|
+
governor = ventpy.VentilationGovernor(config)
|
|
94
|
+
|
|
95
|
+
inp = ventpy.VentilationInput()
|
|
96
|
+
inp.zone_type = ventpy.ZoneType.DevelopmentFace
|
|
97
|
+
inp.num_workers = 15
|
|
98
|
+
inp.altitude_masl = 4200.0
|
|
99
|
+
|
|
100
|
+
result = governor.calculate_total_demand(inp)
|
|
101
|
+
|
|
102
|
+
print(f"Q_total = {result.q_total_m3min} m3/min")
|
|
103
|
+
print(f"Q_total = {result.q_total_cfm:.1f} cfm")
|
|
104
|
+
print(f"Governing factor = {result.governing_factor}")
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Salida:
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
Q_total = 207.0 m3/min
|
|
111
|
+
Q_total = 7310.1 cfm
|
|
112
|
+
Governing factor = personnel (Q_Per)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Cinco ejemplos resueltos y auto-verificables (cada `run.py` afirma sus propios números documentados) viven en [`examples/`](https://github.com/Miqueas7/VentPy/tree/master/examples/), cubriendo demanda limitada por diesel, el preajuste chileno, cobertura/déficit, un ventilador acoplado a una red, y dimensionamiento de ducto.
|
|
116
|
+
|
|
117
|
+
## Interfaz de línea de comandos
|
|
118
|
+
|
|
119
|
+
Instalar VentPy también instala el comando `ventpy`, una capa de presentación delgada sobre la misma API pública (sin lógica de cálculo propia) con 5 subcomandos:
|
|
120
|
+
|
|
121
|
+
- `ventpy demanda <archivo.json> [--norma peru|chile] [--json]` — demanda total de ventilación de una zona/frente
|
|
122
|
+
- `ventpy lmp [--norma peru|chile] [--gas GAS] [--json]` — límites máximos permisibles (LMP) de gases regulados
|
|
123
|
+
- `ventpy cobertura <archivo.json> [--norma peru|chile] [--json]` — análisis de déficit/cobertura de un levantamiento de zonas
|
|
124
|
+
- `ventpy red <archivo.json> [--json]` — balance de una red de ventilación (Hardy Cross)
|
|
125
|
+
- `ventpy ventilador <archivo.json> [--json]` — punto de operación de un ventilador (independiente o acoplado a una red)
|
|
126
|
+
|
|
127
|
+
Los códigos de salida son significativos: `0` éxito, `1` entrada inválida, `2` un resultado calculado pero no confiable (una red que no convergió, una zona en déficit, un punto de operación de ventilador fuera de su curva de catálogo). Ver la ayuda de cada subcomando (`ventpy <subcomando> -h`).
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
$ ventpy lmp --norma peru --gas CO
|
|
131
|
+
standard: DS024_Peru
|
|
132
|
+
gas: CO
|
|
133
|
+
unit: PPM
|
|
134
|
+
twa_8h: 25.0
|
|
135
|
+
stel: None
|
|
136
|
+
ceiling: None
|
|
137
|
+
floor_min: None
|
|
138
|
+
regulation_ref: DS 024-2016-EM, Anexo 15, fila 33 (via Art. 246)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## API principal
|
|
142
|
+
|
|
143
|
+
VentPy expone 87 nombres públicos (`ventpy.__all__`). Puntos de entrada principales:
|
|
144
|
+
|
|
145
|
+
- `RegulatoryConfig` (`.peru()`, `.chile()`, `.for_standard(...)`)
|
|
146
|
+
- `VentilationGovernor`, `VentilationInput`
|
|
147
|
+
- `DieselFleet`, `AtmosphericParams`, `PersonnelParams`, `BlastingParams`, `DustParams`, `ThermalParams`
|
|
148
|
+
|
|
149
|
+
Calculadores directos:
|
|
150
|
+
|
|
151
|
+
- `calculate_personnel_flow`, `calculate_diesel_flow`, `calculate_blasting_flow`, `calculate_dust_flow`, `calculate_thermal_flow`, `calculate_atmospheric_corrections`
|
|
152
|
+
|
|
153
|
+
Red, ducto y ventilador:
|
|
154
|
+
|
|
155
|
+
- `AtkinsonCalculator`, `DuctSizingCalculator`, `NetworkSolver`, `FanCalculator`
|
|
156
|
+
|
|
157
|
+
Cobertura y límites de gases:
|
|
158
|
+
|
|
159
|
+
- `CoverageCalculator`, `gas_limits(standard)`, `lmp_for(standard, gas)`
|
|
160
|
+
|
|
161
|
+
Utilidades:
|
|
162
|
+
|
|
163
|
+
- `calculate_pressure_kpa`, `calculate_density_kg_m3`, `calculate_volume_correction_factor`, `calculate_diesel_derate_factor`, `get_min_velocity`, `safety_ceil`, `safety_ceil_decimals`
|
|
164
|
+
|
|
165
|
+
## Visualización
|
|
166
|
+
|
|
167
|
+
VentPy incluye un módulo de visualización en Python para comunicación técnica y reporte rápido: `plot_flow_comparison`, `plot_flow_breakdown`, `create_dashboard`, `generate_html_report`.
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
from ventpy import visualization as viz
|
|
171
|
+
|
|
172
|
+
html = viz.generate_html_report(
|
|
173
|
+
{
|
|
174
|
+
"q_personnel_m3min": 45.0,
|
|
175
|
+
"q_diesel_m3min": 267.0,
|
|
176
|
+
"q_blasting_m3min": 50.0,
|
|
177
|
+
"q_dust_m3min": 0.0,
|
|
178
|
+
"q_thermal_m3min": 0.0,
|
|
179
|
+
"q_leakage_m3min": 50.0,
|
|
180
|
+
"q_governing_m3min": 267.0,
|
|
181
|
+
"q_total_m3min": 317.0,
|
|
182
|
+
},
|
|
183
|
+
include_charts=False,
|
|
184
|
+
)
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
El renderizado de gráficos requiere `matplotlib`, incluido en el extra `viz` (`pip install ventpy[viz]`).
|
|
188
|
+
|
|
189
|
+
## Contribuir
|
|
190
|
+
|
|
191
|
+
Ver [`CONTRIBUTING.md`](https://github.com/Miqueas7/VentPy/blob/master/CONTRIBUTING.md). La contribución más buscada es agregar la norma de otro país, siguiendo el patrón del preajuste chileno (`RegulatoryConfig::chile()`): ubicar los valores en el reglamento, citar cada artículo, agregar un preajuste y agregar un test con un caso conocido. Ver [`CHANGELOG.md`](https://github.com/Miqueas7/VentPy/blob/master/CHANGELOG.md) para el historial completo de versiones.
|
|
192
|
+
|
|
193
|
+
## Descargo de ingeniería
|
|
194
|
+
|
|
195
|
+
VentPy es una librería de cálculo, no un sustituto del criterio ingenieril, los aforos de ventilación, las mediciones de campo ni la revisión regulatoria.
|
|
196
|
+
|
|
197
|
+
Úsalo como apoyo computacional. Las decisiones finales de diseño de ventilación siguen siendo responsabilidad del ingeniero competente a cargo.
|
|
198
|
+
|
|
199
|
+
## Licencia
|
|
200
|
+
|
|
201
|
+
MIT — ver [`LICENSE`](https://github.com/Miqueas7/VentPy/blob/master/LICENSE).
|