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.
Files changed (78) hide show
  1. {ventpy-0.2.0 → ventpy-0.2.1}/CHANGELOG.md +45 -0
  2. {ventpy-0.2.0 → ventpy-0.2.1}/CMakeLists.txt +2 -1
  3. ventpy-0.2.1/PKG-INFO +228 -0
  4. ventpy-0.2.1/README.es.md +201 -0
  5. ventpy-0.2.1/README.md +201 -0
  6. {ventpy-0.2.0 → ventpy-0.2.1}/bindings/bindings.cpp +4 -2
  7. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_equipo.hpp +10 -4
  8. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_explosivos.hpp +14 -4
  9. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_personal.hpp +31 -16
  10. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_polvo.hpp +20 -11
  11. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_termico.hpp +23 -24
  12. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/cobertura.hpp +34 -16
  13. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/normativa.hpp +184 -0
  14. {ventpy-0.2.0 → ventpy-0.2.1}/pyproject.toml +2 -1
  15. {ventpy-0.2.0 → ventpy-0.2.1}/python/ventpy/__init__.py +1 -1
  16. ventpy-0.2.1/tests/cpp/test_citas_normativas.cpp +460 -0
  17. ventpy-0.2.1/tests/python/test_citas_normativas.py +284 -0
  18. ventpy-0.2.0/PKG-INFO +0 -288
  19. ventpy-0.2.0/README.es.md +0 -262
  20. ventpy-0.2.0/README.md +0 -262
  21. {ventpy-0.2.0 → ventpy-0.2.1}/.github/ISSUE_TEMPLATE/norma-pais.md +0 -0
  22. {ventpy-0.2.0 → ventpy-0.2.1}/.github/ISSUE_TEMPLATE/numero-incorrecto.md +0 -0
  23. {ventpy-0.2.0 → ventpy-0.2.1}/.github/workflows/release.yml +0 -0
  24. {ventpy-0.2.0 → ventpy-0.2.1}/.github/workflows/tests.yml +0 -0
  25. {ventpy-0.2.0 → ventpy-0.2.1}/.gitignore +0 -0
  26. {ventpy-0.2.0 → ventpy-0.2.1}/CONTRIBUTING.md +0 -0
  27. {ventpy-0.2.0 → ventpy-0.2.1}/LICENSE +0 -0
  28. {ventpy-0.2.0 → ventpy-0.2.1}/ROADMAP.md +0 -0
  29. {ventpy-0.2.0 → ventpy-0.2.1}/examples/01-demanda-peru/README.md +0 -0
  30. {ventpy-0.2.0 → ventpy-0.2.1}/examples/01-demanda-peru/input.json +0 -0
  31. {ventpy-0.2.0 → ventpy-0.2.1}/examples/01-demanda-peru/run.py +0 -0
  32. {ventpy-0.2.0 → ventpy-0.2.1}/examples/02-preset-chile/README.md +0 -0
  33. {ventpy-0.2.0 → ventpy-0.2.1}/examples/02-preset-chile/input.json +0 -0
  34. {ventpy-0.2.0 → ventpy-0.2.1}/examples/02-preset-chile/run.py +0 -0
  35. {ventpy-0.2.0 → ventpy-0.2.1}/examples/03-cobertura-levantamiento/README.md +0 -0
  36. {ventpy-0.2.0 → ventpy-0.2.1}/examples/03-cobertura-levantamiento/input.json +0 -0
  37. {ventpy-0.2.0 → ventpy-0.2.1}/examples/03-cobertura-levantamiento/run.py +0 -0
  38. {ventpy-0.2.0 → ventpy-0.2.1}/examples/04-red-ventilador/README.md +0 -0
  39. {ventpy-0.2.0 → ventpy-0.2.1}/examples/04-red-ventilador/input.json +0 -0
  40. {ventpy-0.2.0 → ventpy-0.2.1}/examples/04-red-ventilador/run.py +0 -0
  41. {ventpy-0.2.0 → ventpy-0.2.1}/examples/05-ducto-seleccion/README.md +0 -0
  42. {ventpy-0.2.0 → ventpy-0.2.1}/examples/05-ducto-seleccion/run.py +0 -0
  43. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/atkinson.hpp +0 -0
  44. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/atmosphere.hpp +0 -0
  45. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/caudal_fugas.hpp +0 -0
  46. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/ducto.hpp +0 -0
  47. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/governor.hpp +0 -0
  48. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/limites_gases.hpp +0 -0
  49. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/red.hpp +0 -0
  50. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/types.hpp +0 -0
  51. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/validation.hpp +0 -0
  52. {ventpy-0.2.0 → ventpy-0.2.1}/include/ventpy/ventilador.hpp +0 -0
  53. {ventpy-0.2.0 → ventpy-0.2.1}/python/ventpy/cli.py +0 -0
  54. {ventpy-0.2.0 → ventpy-0.2.1}/python/ventpy/visualization.py +0 -0
  55. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_atkinson.cpp +0 -0
  56. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_equipo.cpp +0 -0
  57. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_explosivos.cpp +0 -0
  58. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_fugas.cpp +0 -0
  59. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_personal.cpp +0 -0
  60. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_polvo.cpp +0 -0
  61. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_caudal_termico.cpp +0 -0
  62. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_cobertura.cpp +0 -0
  63. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_ducto.cpp +0 -0
  64. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_governor.cpp +0 -0
  65. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_limites_gases.cpp +0 -0
  66. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_normativa.cpp +0 -0
  67. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_red.cpp +0 -0
  68. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_validation.cpp +0 -0
  69. {ventpy-0.2.0 → ventpy-0.2.1}/tests/cpp/test_ventilador.cpp +0 -0
  70. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_cli.py +0 -0
  71. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_cobertura.py +0 -0
  72. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_escala.py +0 -0
  73. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_examples.py +0 -0
  74. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_multinorma.py +0 -0
  75. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_polvo_termico.py +0 -0
  76. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_properties.py +0 -0
  77. {ventpy-0.2.0 → ventpy-0.2.1}/tests/python/test_red_ventilacion.py +0 -0
  78. {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.0
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
+ [![PyPI version](https://img.shields.io/pypi/v/ventpy)](https://pypi.org/project/ventpy/)
33
+ [![Python versions](https://img.shields.io/pypi/pyversions/ventpy)](https://pypi.org/project/ventpy/)
34
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Miqueas7/VentPy/blob/master/LICENSE)
35
+ [![Tests](https://img.shields.io/github/actions/workflow/status/Miqueas7/VentPy/tests.yml?branch=master&label=tests)](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
+ [![PyPI version](https://img.shields.io/pypi/v/ventpy)](https://pypi.org/project/ventpy/)
6
+ [![Python versions](https://img.shields.io/pypi/pyversions/ventpy)](https://pypi.org/project/ventpy/)
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Miqueas7/VentPy/blob/master/LICENSE)
8
+ [![Tests](https://img.shields.io/github/actions/workflow/status/Miqueas7/VentPy/tests.yml?branch=master&label=tests)](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).