ventpy 0.1.0__tar.gz → 0.2.0__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 (75) hide show
  1. ventpy-0.2.0/.github/ISSUE_TEMPLATE/norma-pais.md +35 -0
  2. ventpy-0.2.0/.github/ISSUE_TEMPLATE/numero-incorrecto.md +26 -0
  3. ventpy-0.2.0/.github/workflows/tests.yml +120 -0
  4. {ventpy-0.1.0 → ventpy-0.2.0}/.gitignore +6 -0
  5. ventpy-0.2.0/CHANGELOG.md +77 -0
  6. {ventpy-0.1.0 → ventpy-0.2.0}/CMakeLists.txt +9 -0
  7. ventpy-0.2.0/CONTRIBUTING.md +107 -0
  8. ventpy-0.1.0/README.md → ventpy-0.2.0/PKG-INFO +54 -0
  9. {ventpy-0.1.0 → ventpy-0.2.0}/README.es.md +28 -0
  10. ventpy-0.1.0/PKG-INFO → ventpy-0.2.0/README.md +28 -25
  11. ventpy-0.2.0/ROADMAP.md +65 -0
  12. ventpy-0.2.0/bindings/bindings.cpp +1478 -0
  13. ventpy-0.2.0/examples/01-demanda-peru/README.md +91 -0
  14. ventpy-0.2.0/examples/01-demanda-peru/input.json +20 -0
  15. ventpy-0.2.0/examples/01-demanda-peru/run.py +87 -0
  16. ventpy-0.2.0/examples/02-preset-chile/README.md +63 -0
  17. ventpy-0.2.0/examples/02-preset-chile/input.json +12 -0
  18. ventpy-0.2.0/examples/02-preset-chile/run.py +60 -0
  19. ventpy-0.2.0/examples/03-cobertura-levantamiento/README.md +70 -0
  20. ventpy-0.2.0/examples/03-cobertura-levantamiento/input.json +26 -0
  21. ventpy-0.2.0/examples/03-cobertura-levantamiento/run.py +75 -0
  22. ventpy-0.2.0/examples/04-red-ventilador/README.md +76 -0
  23. ventpy-0.2.0/examples/04-red-ventilador/input.json +23 -0
  24. ventpy-0.2.0/examples/04-red-ventilador/run.py +80 -0
  25. ventpy-0.2.0/examples/05-ducto-seleccion/README.md +62 -0
  26. ventpy-0.2.0/examples/05-ducto-seleccion/run.py +79 -0
  27. ventpy-0.2.0/include/ventpy/atkinson.hpp +222 -0
  28. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/caudal_explosivos.hpp +7 -2
  29. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/caudal_personal.hpp +13 -5
  30. ventpy-0.2.0/include/ventpy/caudal_polvo.hpp +94 -0
  31. ventpy-0.2.0/include/ventpy/caudal_termico.hpp +218 -0
  32. ventpy-0.2.0/include/ventpy/cobertura.hpp +271 -0
  33. ventpy-0.2.0/include/ventpy/ducto.hpp +165 -0
  34. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/governor.hpp +29 -0
  35. ventpy-0.2.0/include/ventpy/limites_gases.hpp +130 -0
  36. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/normativa.hpp +94 -5
  37. ventpy-0.2.0/include/ventpy/red.hpp +336 -0
  38. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/types.hpp +371 -24
  39. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/validation.hpp +31 -3
  40. ventpy-0.2.0/include/ventpy/ventilador.hpp +316 -0
  41. {ventpy-0.1.0 → ventpy-0.2.0}/pyproject.toml +15 -7
  42. {ventpy-0.1.0 → ventpy-0.2.0}/python/ventpy/__init__.py +128 -18
  43. ventpy-0.2.0/python/ventpy/cli.py +857 -0
  44. ventpy-0.2.0/tests/cpp/test_atkinson.cpp +218 -0
  45. {ventpy-0.1.0 → ventpy-0.2.0}/tests/cpp/test_caudal_equipo.cpp +7 -6
  46. {ventpy-0.1.0 → ventpy-0.2.0}/tests/cpp/test_caudal_explosivos.cpp +30 -16
  47. {ventpy-0.1.0 → ventpy-0.2.0}/tests/cpp/test_caudal_fugas.cpp +6 -6
  48. {ventpy-0.1.0 → ventpy-0.2.0}/tests/cpp/test_caudal_personal.cpp +37 -23
  49. ventpy-0.2.0/tests/cpp/test_caudal_polvo.cpp +120 -0
  50. ventpy-0.2.0/tests/cpp/test_caudal_termico.cpp +275 -0
  51. ventpy-0.2.0/tests/cpp/test_cobertura.cpp +482 -0
  52. ventpy-0.2.0/tests/cpp/test_ducto.cpp +158 -0
  53. ventpy-0.2.0/tests/cpp/test_governor.cpp +379 -0
  54. ventpy-0.2.0/tests/cpp/test_limites_gases.cpp +151 -0
  55. ventpy-0.2.0/tests/cpp/test_normativa.cpp +161 -0
  56. ventpy-0.2.0/tests/cpp/test_red.cpp +261 -0
  57. {ventpy-0.1.0 → ventpy-0.2.0}/tests/cpp/test_validation.cpp +29 -0
  58. ventpy-0.2.0/tests/cpp/test_ventilador.cpp +288 -0
  59. ventpy-0.2.0/tests/python/test_cli.py +498 -0
  60. ventpy-0.2.0/tests/python/test_cobertura.py +185 -0
  61. ventpy-0.2.0/tests/python/test_escala.py +156 -0
  62. ventpy-0.2.0/tests/python/test_examples.py +106 -0
  63. ventpy-0.2.0/tests/python/test_multinorma.py +42 -0
  64. ventpy-0.2.0/tests/python/test_polvo_termico.py +141 -0
  65. ventpy-0.2.0/tests/python/test_properties.py +327 -0
  66. ventpy-0.2.0/tests/python/test_red_ventilacion.py +367 -0
  67. {ventpy-0.1.0 → ventpy-0.2.0}/tests/python/test_ventpy.py +6 -4
  68. ventpy-0.1.0/bindings/bindings.cpp +0 -658
  69. ventpy-0.1.0/tests/cpp/test_governor.cpp +0 -171
  70. {ventpy-0.1.0 → ventpy-0.2.0}/.github/workflows/release.yml +0 -0
  71. {ventpy-0.1.0 → ventpy-0.2.0}/LICENSE +0 -0
  72. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/atmosphere.hpp +0 -0
  73. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/caudal_equipo.hpp +0 -0
  74. {ventpy-0.1.0 → ventpy-0.2.0}/include/ventpy/caudal_fugas.hpp +0 -0
  75. {ventpy-0.1.0 → ventpy-0.2.0}/python/ventpy/visualization.py +0 -0
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: "🌎 Agregar la norma de un país"
3
+ about: "Aporta los valores normativos de ventilación de tu país (no necesitas programar)"
4
+ title: "[Norma] Agregar <PAÍS> — <NORMA>"
5
+ labels: ["norma", "buena primera tarea", "help wanted"]
6
+ ---
7
+
8
+ ## País y norma
9
+
10
+ - **País:**
11
+ - **Norma / reglamento:** (ej. Chile · DS 132, Reglamento de Seguridad Minera)
12
+ - **Enlace oficial:**
13
+
14
+ ## Valores normativos
15
+
16
+ > Pon el que sepas y deja el resto en blanco. **Un aporte parcial también sirve.**
17
+ > Lo importante es la **cita del artículo** de cada valor.
18
+
19
+ | Parámetro | Valor | Unidad | Artículo |
20
+ |---|---|---|---|
21
+ | Caudal mínimo por persona | | m³/min | |
22
+ | Factor por equipo diésel | | m³/min por HP (o kW) | |
23
+ | Dilución post-voladura (tiempo) | | min | |
24
+ | Velocidad mínima del aire | | m/s | |
25
+ | Velocidad máxima del aire | | m/s | |
26
+ | Factor de fugas | | % | |
27
+
28
+ ## ¿Algo distinto en tu país?
29
+
30
+ ¿Hay algún requisito que la norma peruana no tiene (altitud, temperatura, gases específicos)?
31
+
32
+ ## ¿Puedes probarlo?
33
+
34
+ - [ ] Tengo un caso real de mi país para usarlo como test
35
+ - [ ] Solo aporto los valores; que alguien más lo implemente
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: "🔢 Un resultado no calza con mi experiencia"
3
+ about: "Reporta un cálculo que no coincide con la práctica en campo"
4
+ title: "[Cálculo] <qué calculaste> da <X>, esperaba <Y>"
5
+ labels: ["bug", "necesita verificación"]
6
+ ---
7
+
8
+ ## Qué calculaste
9
+
10
+ ```python
11
+ # pega aquí tu código
12
+ ```
13
+
14
+ ## Qué salió vs. qué esperabas
15
+
16
+ - **VentPy devolvió:**
17
+ - **Esperaba:** (y por qué — norma, experiencia de campo, otro software)
18
+
19
+ ## Contexto de la operación
20
+
21
+ - Tipo: superficial / subterránea
22
+ - País y norma aplicable:
23
+ - Datos relevantes (personal, equipos diésel, sección de labor, etc.):
24
+
25
+ > Aunque no estés seguro, repórtalo. Un número mal calculado en ventilación es un tema de
26
+ > **seguridad**: preferimos revisar de más.
@@ -0,0 +1,120 @@
1
+ name: Tests
2
+
3
+ on:
4
+ push:
5
+ branches: [master]
6
+ pull_request:
7
+ workflow_dispatch:
8
+
9
+ concurrency:
10
+ group: ${{ github.workflow }}-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ jobs:
14
+ # Suite C++ en las tres plataformas y en ambas configuraciones. Debug y
15
+ # Release se ejecutan por separado porque la optimizacion puede alterar el
16
+ # comportamiento en coma flotante, y varias pruebas verifican fronteras
17
+ # normativas exactas.
18
+ cpp:
19
+ name: C++ ${{ matrix.os }} / ${{ matrix.build_type }}
20
+ runs-on: ${{ matrix.os }}
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ os: [ubuntu-latest, macos-latest, windows-latest]
25
+ build_type: [Debug, Release]
26
+ steps:
27
+ - uses: actions/checkout@v4
28
+ - name: Configurar
29
+ run: cmake -S . -B build -DVENTPY_BUILD_TESTS=ON -DVENTPY_BUILD_PYTHON=OFF -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
30
+ - name: Compilar
31
+ run: cmake --build build --config ${{ matrix.build_type }} --parallel
32
+ - name: Ejecutar pruebas
33
+ run: ctest --test-dir build -C ${{ matrix.build_type }} --output-on-failure
34
+
35
+ # AddressSanitizer y UndefinedBehaviorSanitizer. El compilador de Windows no
36
+ # ofrece UBSan, de modo que este trabajo es el unico lugar donde se detecta
37
+ # comportamiento indefinido (lecturas sin inicializar, desbordes, division
38
+ # entre cero, conversiones invalidas).
39
+ sanitizers:
40
+ name: Sanitizers (ASan + UBSan)
41
+ runs-on: ubuntu-latest
42
+ steps:
43
+ - uses: actions/checkout@v4
44
+ - name: Configurar con sanitizers
45
+ env:
46
+ FLAGS: -fsanitize=address,undefined -fno-omit-frame-pointer -fno-sanitize-recover=undefined -g -O1
47
+ run: |
48
+ cmake -S . -B build-san \
49
+ -DVENTPY_BUILD_TESTS=ON -DVENTPY_BUILD_PYTHON=OFF \
50
+ -DCMAKE_BUILD_TYPE=RelWithDebInfo \
51
+ -DCMAKE_CXX_FLAGS="$FLAGS" -DCMAKE_EXE_LINKER_FLAGS="$FLAGS"
52
+ - name: Compilar
53
+ run: cmake --build build-san --parallel
54
+ - name: Ejecutar pruebas bajo sanitizers
55
+ env:
56
+ ASAN_OPTIONS: detect_leaks=1:abort_on_error=1:strict_string_checks=1
57
+ UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1
58
+ run: ctest --test-dir build-san --output-on-failure
59
+
60
+ # Cobertura de lineas y ramas del nucleo. El umbral evita que la cobertura
61
+ # caiga sin que nadie lo note; se mide solo include/ventpy (la libreria),
62
+ # excluyendo pruebas y dependencias externas.
63
+ coverage:
64
+ name: Cobertura
65
+ runs-on: ubuntu-latest
66
+ steps:
67
+ - uses: actions/checkout@v4
68
+ - name: Instalar lcov
69
+ run: sudo apt-get update && sudo apt-get install -y lcov
70
+ - name: Configurar con instrumentacion
71
+ run: |
72
+ cmake -S . -B build-cov \
73
+ -DVENTPY_BUILD_TESTS=ON -DVENTPY_BUILD_PYTHON=OFF \
74
+ -DCMAKE_BUILD_TYPE=Debug \
75
+ -DCMAKE_CXX_FLAGS="--coverage -O0 -g" \
76
+ -DCMAKE_EXE_LINKER_FLAGS="--coverage"
77
+ - name: Compilar y ejecutar
78
+ run: |
79
+ cmake --build build-cov --parallel
80
+ ctest --test-dir build-cov --output-on-failure
81
+ - name: Medir y comprobar umbral
82
+ run: |
83
+ lcov --capture --directory build-cov --output-file cov.info \
84
+ --rc branch_coverage=1 --ignore-errors mismatch,gcov,source
85
+ lcov --extract cov.info "*/include/ventpy/*" --output-file cov-core.info \
86
+ --rc branch_coverage=1 --ignore-errors unused
87
+ lcov --list cov-core.info --rc branch_coverage=1
88
+ LINES=$(lcov --summary cov-core.info --rc branch_coverage=1 2>&1 | grep -oP 'lines\.+: \K[0-9.]+')
89
+ echo "Cobertura de lineas del nucleo: $LINES %"
90
+ awk -v v="$LINES" 'BEGIN { if (v+0 < 85.0) { print "Por debajo del umbral (85%)"; exit 1 } }'
91
+ - uses: actions/upload-artifact@v4
92
+ if: always()
93
+ with:
94
+ name: cobertura
95
+ path: cov-core.info
96
+
97
+ # Suite Python contra la extension compilada, en las tres plataformas.
98
+ # Incluye las pruebas basadas en propiedades, que generan sus propios casos.
99
+ python:
100
+ name: Python ${{ matrix.os }}
101
+ runs-on: ${{ matrix.os }}
102
+ strategy:
103
+ fail-fast: false
104
+ matrix:
105
+ os: [ubuntu-latest, macos-latest, windows-latest]
106
+ steps:
107
+ - uses: actions/checkout@v4
108
+ - uses: actions/setup-python@v5
109
+ with:
110
+ python-version: "3.12"
111
+ - name: Instalar el paquete con sus extras de prueba
112
+ run: python -m pip install --upgrade pip && python -m pip install ".[test]"
113
+ - name: Ejecutar la suite
114
+ run: python -m pytest tests/python -q
115
+ - name: Ejecutar las pruebas de escala
116
+ run: python -m pytest tests/python -q -m slow
117
+ - name: Comprobar la interfaz de linea de comandos
118
+ run: |
119
+ ventpy --help
120
+ ventpy lmp --norma peru
@@ -1,5 +1,7 @@
1
1
  # Build artifacts
2
2
  build/
3
+ build-tests/
4
+ build-release/
3
5
  _build/
4
6
  dist/
5
7
  wheelhouse/
@@ -37,6 +39,10 @@ CLAUDE.md
37
39
  docs/
38
40
  AGENT_NOTES.md
39
41
 
42
+ # Local agent tooling state (not part of the published package)
43
+ .claude/
44
+ .superpowers/
45
+
40
46
  # OS files
41
47
  .DS_Store
42
48
  Thumbs.db
@@ -0,0 +1,77 @@
1
+ # Registro de cambios
2
+
3
+ Todas las versiones publicadas de VentPy. El formato sigue
4
+ [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/) y el versionado es
5
+ [semántico](https://semver.org/lang/es/).
6
+
7
+ ## [0.2.0] — 2026-08-20
8
+
9
+ ### ⚠️ Los resultados cambian respecto de 0.1.0
10
+
11
+ Esta versión corrige tres citas normativas del núcleo. **Un cálculo hecho con
12
+ 0.1.0 puede quedar por debajo del mínimo legal**, así que conviene rehacer los
13
+ que se hayan emitido con esa versión.
14
+
15
+ | Corrección | 0.1.0 | 0.2.0 |
16
+ |---|---|---|
17
+ | Escala de caudal por persona (DS 024-2016-EM, **Art. 247**) | 3/4/5 m³/min con umbrales de 3.000 y 4.000 msnm | **3/4/5/6** m³/min con umbrales de **1.500, 3.000 y 4.000** msnm, que es el texto vigente del artículo |
18
+ | Polvo respirable | citado como "Art. 103-107" | **Art. 111**: límite de 3 mg/m³ para jornada de 8 h, con paralización de la labor si se supera |
19
+ | Temperatura efectiva máxima | citada como "Art. 240: 30 °C" | No existe en la norma vigente (proviene del derogado DS 055-2010-EM). El criterio normativo real es el **Art. 252 lit. d** (velocidad mínima de 30 m/min con temperatura seca entre 24 y 29 °C) y la remisión del **Art. 104 / Anexo 13** para estrés térmico |
20
+
21
+ El efecto práctico de la primera corrección: toda mina por encima de 1.500 msnm
22
+ exige más aire por persona del que 0.1.0 calculaba.
23
+
24
+ ### Cambio incompatible
25
+
26
+ - El constructor de `RegulatoryConfig` pasa de 10 a 12 parámetros por el tercer
27
+ umbral de altitud del Art. 247. Quien use los preajustes
28
+ (`RegulatoryConfig.peru()`, `.chile()`, `.for_standard()`) no necesita
29
+ cambiar nada; solo afecta a quien construya la configuración parámetro a
30
+ parámetro.
31
+
32
+ ### Nuevas capacidades
33
+
34
+ - **Multi-norma.** Preajustes por país mediante `peru()`, `chile()` y
35
+ `for_standard()`. El preajuste chileno implementa el DS 132 (Art. 138:
36
+ 3 m³/min por persona sin escalón por altitud; Art. 132: 2,83 m³/min por HP
37
+ efectivo al freno).
38
+ - **Límites máximos permisibles de gases** consultables por norma
39
+ (`gas_limits`, `lmp_for`): Perú (DS 024, Anexo 15) y Chile (DS 594 / DS 132),
40
+ con la cita de cada valor. Un gas no regulado por la norma lanza una
41
+ excepción en vez de devolver un valor por omisión.
42
+ - **Cobertura y déficit de ventilación** (Art. 252, literales f y g): compara
43
+ el caudal medido en campo, directo o por estaciones de aforo, contra el
44
+ requerido, por labor y para la mina completa, con verificación de la
45
+ velocidad del aire del Art. 248.
46
+ - **Red de ventilación**: resistencias de Atkinson con corrección por densidad
47
+ y pérdidas por choque, dimensionamiento de ducto con criterio técnico y
48
+ económico, balance de red por el método de Hardy Cross con detección
49
+ automática de mallas, y curva de ventilador con punto de operación y margen
50
+ de entrada en pérdida.
51
+ - **Polvo respirable y carga térmica** integrados al cálculo consolidado.
52
+ - **Interfaz de línea de comandos** `ventpy` con cinco subcomandos sobre
53
+ archivos JSON y códigos de salida pensados para automatización: 0 correcto,
54
+ 1 error de entrada y 2 resultado no confiable.
55
+ - **Ejemplos resueltos** en `examples/`, cada uno con su comando, la salida
56
+ esperada y el artículo que lo sustenta.
57
+
58
+ ### Correcciones
59
+
60
+ - El solver de red rechaza resistencias no finitas. Un valor infinito se
61
+ aceptaba y el balance devolvía caudales inválidos marcados como convergidos.
62
+ - Las funciones de validación rechazan NaN e infinito en todos sus parámetros.
63
+ - El cálculo simplificado de gases de voladura recupera la advertencia por
64
+ exceder el tiempo máximo de dilución del Art. 243.
65
+
66
+ ### Interno
67
+
68
+ - La suite pasó de 55 a 197 pruebas en C++ y 151 en Python, incluidas pruebas
69
+ basadas en propiedades y de escala hasta 500 ramales.
70
+ - Integración continua en Linux, macOS y Windows, con analizadores dinámicos
71
+ de memoria y comportamiento indefinido, y medición de cobertura.
72
+
73
+ ## [0.1.0] — 2026-08-16
74
+
75
+ - Primera versión publicada: cálculo de demanda de ventilación según
76
+ DS 024-2016-EM (personal, equipos diésel, explosivos y fugas), correcciones
77
+ atmosféricas por altitud y visualización opcional.
@@ -94,7 +94,16 @@ if(VENTPY_BUILD_TESTS)
94
94
  tests/cpp/test_caudal_equipo.cpp
95
95
  tests/cpp/test_caudal_explosivos.cpp
96
96
  tests/cpp/test_caudal_fugas.cpp
97
+ tests/cpp/test_caudal_polvo.cpp
98
+ tests/cpp/test_caudal_termico.cpp
97
99
  tests/cpp/test_governor.cpp
100
+ tests/cpp/test_normativa.cpp
101
+ tests/cpp/test_limites_gases.cpp
102
+ tests/cpp/test_cobertura.cpp
103
+ tests/cpp/test_atkinson.cpp
104
+ tests/cpp/test_ducto.cpp
105
+ tests/cpp/test_red.cpp
106
+ tests/cpp/test_ventilador.cpp
98
107
  )
99
108
  target_link_libraries(ventpy_tests PRIVATE
100
109
  ventpy_core
@@ -0,0 +1,107 @@
1
+ # Contributing to VentPy · Cómo contribuir a VentPy
2
+
3
+ VentPy is an open-source library for **mine ventilation calculations**. It started with the
4
+ Peruvian standard (DS 024-2016-EM) and is growing toward **multi-standard support across Latin
5
+ America**: Chile, Colombia and Mexico.
6
+
7
+ > 🇪🇸 **Este documento está en inglés y español.** Baja para la versión en español.
8
+ > **No necesitas ser programador experto.** Si eres ingeniero de minas y conoces la norma de tu
9
+ > país, ya tienes lo más difícil: el conocimiento del dominio.
10
+
11
+ ---
12
+
13
+ ## English
14
+
15
+ ### Ways to contribute
16
+
17
+ You do **not** need to write C++ to help. In order of how much we need it:
18
+
19
+ 1. **Add a national standard.** You know your country's ventilation regulation? That's the
20
+ contribution we need most. See `ROADMAP.md` for the open standards.
21
+ 2. **Worked examples.** A real (anonymised) ventilation case with its numbers, as a test.
22
+ 3. **Documentation.** Fix an unclear paragraph, translate, add a diagram.
23
+ 4. **Report a wrong number.** If a result doesn't match your field experience, open an issue.
24
+ A bug report with the expected value is a genuine contribution.
25
+ 5. **Code.** Python API, plots, CLI, performance.
26
+
27
+ ### First contribution, step by step
28
+
29
+ ```bash
30
+ # 1. Fork the repo on GitHub, then:
31
+ git clone https://github.com/YOUR-USER/VentPy.git
32
+ cd VentPy
33
+
34
+ # 2. Install in editable mode with test extras
35
+ pip install -e ".[test,viz]"
36
+
37
+ # 3. Run the tests (should be green before you change anything)
38
+ pytest tests/python -q
39
+
40
+ # 4. Create a branch, make your change, run tests again
41
+ git checkout -b add-chile-standard
42
+ pytest tests/python -q
43
+
44
+ # 5. Commit and open a Pull Request
45
+ ```
46
+
47
+ ### Ground rules
48
+
49
+ - **Cite the regulation.** Any constant must reference its article: `DS 024-2016-EM, Art. 247`.
50
+ Numbers without a source will not be merged — this library is used for **safety** decisions.
51
+ - **Add a test** for every new behaviour. If you're unsure how, open the PR anyway and ask.
52
+ - **Be conservative in the docs.** Never claim more precision than the method actually has.
53
+ - Small PRs are better than big ones. One standard, one PR.
54
+
55
+ ### Questions?
56
+
57
+ Open an issue with the `question` label. There are no stupid questions — if something wasn't
58
+ clear to you, it wasn't clear enough.
59
+
60
+ ---
61
+
62
+ ## Español
63
+
64
+ ### Formas de contribuir
65
+
66
+ **No necesitas escribir C++.** En orden de lo que más falta:
67
+
68
+ 1. **Agregar la norma de tu país.** ¿Conoces el reglamento de ventilación de Chile, Colombia o
69
+ México? Esa es la contribución que más necesitamos. Mira `ROADMAP.md`.
70
+ 2. **Casos resueltos.** Un caso real de ventilación (anonimizado) con sus números, como test.
71
+ 3. **Documentación.** Corregir un párrafo confuso, traducir, agregar un diagrama.
72
+ 4. **Reportar un número equivocado.** Si un resultado no calza con tu experiencia en campo,
73
+ abre un issue. Un reporte con el valor esperado ya es una contribución real.
74
+ 5. **Código.** API de Python, gráficos, línea de comandos, rendimiento.
75
+
76
+ ### Tu primera contribución, paso a paso
77
+
78
+ ```bash
79
+ # 1. Haz fork del repo en GitHub, luego:
80
+ git clone https://github.com/TU-USUARIO/VentPy.git
81
+ cd VentPy
82
+
83
+ # 2. Instala en modo editable con extras de test
84
+ pip install -e ".[test,viz]"
85
+
86
+ # 3. Corre los tests (deben pasar antes de que toques nada)
87
+ pytest tests/python -q
88
+
89
+ # 4. Crea una rama, haz tu cambio, corre los tests otra vez
90
+ git checkout -b agregar-norma-chile
91
+ pytest tests/python -q
92
+
93
+ # 5. Commitea y abre un Pull Request
94
+ ```
95
+
96
+ ### Reglas de la casa
97
+
98
+ - **Cita la norma.** Toda constante debe referenciar su artículo: `DS 024-2016-EM, Art. 247`.
99
+ Un número sin fuente no se mergea — esta librería se usa para decisiones de **seguridad**.
100
+ - **Agrega un test** por cada comportamiento nuevo. Si no sabes cómo, abre el PR igual y pregunta.
101
+ - **Sé conservador en la documentación.** Nunca afirmes más precisión de la que el método tiene.
102
+ - Mejor PRs chicos que grandes. Una norma, un PR.
103
+
104
+ ### ¿Dudas?
105
+
106
+ Abre un issue con la etiqueta `question`. No hay preguntas tontas: si algo no te quedó claro,
107
+ es que no estaba lo bastante claro.
@@ -1,3 +1,29 @@
1
+ Metadata-Version: 2.4
2
+ Name: ventpy
3
+ Version: 0.2.0
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: Repository, https://github.com/Miqueas7/VentPy
17
+ Project-URL: Issues, https://github.com/Miqueas7/VentPy/issues
18
+ Requires-Python: >=3.9
19
+ Provides-Extra: test
20
+ Requires-Dist: pytest>=7.0; extra == "test"
21
+ Requires-Dist: hypothesis>=6.0; extra == "test"
22
+ Provides-Extra: viz
23
+ Requires-Dist: matplotlib>=3.7; extra == "viz"
24
+ Requires-Dist: numpy>=1.24; extra == "viz"
25
+ Description-Content-Type: text/markdown
26
+
1
27
  # VentPy
2
28
 
3
29
  [English](README.md) | [Español](README.es.md)
@@ -78,6 +104,34 @@ For development:
78
104
  pip install -e .[test,viz]
79
105
  ```
80
106
 
107
+ ## CLI and Examples
108
+
109
+ Installing VentPy also installs the `ventpy` command, a thin presentation
110
+ layer over the same public API (no calculation logic of its own) with 5
111
+ subcommands:
112
+
113
+ - `ventpy demanda <archivo.json> [--norma peru|chile] [--json]` — total ventilation demand for a zone/face
114
+ - `ventpy lmp [--norma peru|chile] [--gas GAS] [--json]` — permissible exposure limits (LMP) for regulated gases
115
+ - `ventpy cobertura <archivo.json> [--norma peru|chile] [--json]` — coverage/deficit analysis of a zone survey
116
+ - `ventpy red <archivo.json> [--json]` — ventilation network balance (Hardy Cross)
117
+ - `ventpy ventilador <archivo.json> [--json]` — fan operating point (standalone or coupled to a network)
118
+
119
+ Exit codes are meaningful: `0` success, `1` invalid input, `2` a
120
+ calculated-but-unreliable result (e.g. a network that did not converge, a
121
+ zone in deficit, or a fan operating point outside its catalog curve) — see
122
+ each subcommand's help (`ventpy <subcommand> -h`).
123
+
124
+ Five worked, self-verifying examples (each `run.py` asserts its own
125
+ documented numbers) live under [`examples/`](examples/), one per JSON input
126
+ schema plus a duct-sizing case that only uses the API (no CLI subcommand
127
+ for it yet):
128
+
129
+ - [`examples/01-demanda-peru`](examples/01-demanda-peru/) — diesel-limited demand, Peru preset
130
+ - [`examples/02-preset-chile`](examples/02-preset-chile/) — same case with `--norma chile`
131
+ - [`examples/03-cobertura-levantamiento`](examples/03-cobertura-levantamiento/) — 2-zone survey, one zone in deficit (`exit 2`)
132
+ - [`examples/04-red-ventilador`](examples/04-red-ventilador/) — fan coupled to a parallel-mesh network
133
+ - [`examples/05-ducto-seleccion`](examples/05-ducto-seleccion/) — duct sizing, technical vs. economic criterion (API only)
134
+
81
135
  ## Quick Start
82
136
 
83
137
  ```python
@@ -78,6 +78,34 @@ Para desarrollo:
78
78
  pip install -e .[test,viz]
79
79
  ```
80
80
 
81
+ ## CLI Y Ejemplos
82
+
83
+ Instalar VentPy tambien instala el comando `ventpy`, una capa de
84
+ presentacion delgada sobre la misma API publica (sin logica de calculo
85
+ propia) con 5 subcomandos:
86
+
87
+ - `ventpy demanda <archivo.json> [--norma peru|chile] [--json]` — demanda total de ventilacion de una zona/frente
88
+ - `ventpy lmp [--norma peru|chile] [--gas GAS] [--json]` — limites maximos permisibles (LMP) de gases regulados
89
+ - `ventpy cobertura <archivo.json> [--norma peru|chile] [--json]` — analisis de deficit/cobertura de un levantamiento de zonas
90
+ - `ventpy red <archivo.json> [--json]` — balance de una red de ventilacion (Hardy Cross)
91
+ - `ventpy ventilador <archivo.json> [--json]` — punto de operacion de un ventilador (independiente o acoplado a una red)
92
+
93
+ Los exit codes son significativos: `0` exito, `1` entrada invalida, `2` un
94
+ resultado calculado pero no confiable (ej. una red que no convergio, una
95
+ zona en deficit, o un punto de operacion de ventilador fuera de su curva
96
+ de catalogo) — ver la ayuda de cada subcomando (`ventpy <subcomando> -h`).
97
+
98
+ Cinco ejemplos resueltos y auto-verificables (cada `run.py` afirma sus
99
+ propios numeros documentados) viven en [`examples/`](examples/), uno por
100
+ esquema de entrada JSON mas un caso de dimensionamiento de ductos que solo
101
+ usa la API (sin subcomando CLI todavia):
102
+
103
+ - [`examples/01-demanda-peru`](examples/01-demanda-peru/) — demanda limitada por diesel, preset Peru
104
+ - [`examples/02-preset-chile`](examples/02-preset-chile/) — mismo caso con `--norma chile`
105
+ - [`examples/03-cobertura-levantamiento`](examples/03-cobertura-levantamiento/) — levantamiento de 2 zonas, una en deficit (`exit 2`)
106
+ - [`examples/04-red-ventilador`](examples/04-red-ventilador/) — ventilador acoplado a una red de malla paralela
107
+ - [`examples/05-ducto-seleccion`](examples/05-ducto-seleccion/) — dimensionamiento de ducto, criterio tecnico vs. economico (solo API)
108
+
81
109
  ## Inicio Rapido
82
110
 
83
111
  ```python
@@ -1,28 +1,3 @@
1
- Metadata-Version: 2.4
2
- Name: ventpy
3
- Version: 0.1.0
4
- Summary: High-performance mine ventilation calculation library (DS 024-2016-EM, Peru)
5
- Keywords: mining,ventilation,safety,DS024,engineering
6
- Author-Email: Miqueas Quintanilla Ventura <miqueasq@gmail.com>
7
- License-Expression: MIT
8
- License-File: LICENSE
9
- Classifier: Development Status :: 3 - Alpha
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: Repository, https://github.com/Miqueas7/VentPy
17
- Project-URL: Issues, https://github.com/Miqueas7/VentPy/issues
18
- Requires-Python: >=3.9
19
- Provides-Extra: test
20
- Requires-Dist: pytest>=7.0; extra == "test"
21
- Provides-Extra: viz
22
- Requires-Dist: matplotlib>=3.7; extra == "viz"
23
- Requires-Dist: numpy>=1.24; extra == "viz"
24
- Description-Content-Type: text/markdown
25
-
26
1
  # VentPy
27
2
 
28
3
  [English](README.md) | [Español](README.es.md)
@@ -103,6 +78,34 @@ For development:
103
78
  pip install -e .[test,viz]
104
79
  ```
105
80
 
81
+ ## CLI and Examples
82
+
83
+ Installing VentPy also installs the `ventpy` command, a thin presentation
84
+ layer over the same public API (no calculation logic of its own) with 5
85
+ subcommands:
86
+
87
+ - `ventpy demanda <archivo.json> [--norma peru|chile] [--json]` — total ventilation demand for a zone/face
88
+ - `ventpy lmp [--norma peru|chile] [--gas GAS] [--json]` — permissible exposure limits (LMP) for regulated gases
89
+ - `ventpy cobertura <archivo.json> [--norma peru|chile] [--json]` — coverage/deficit analysis of a zone survey
90
+ - `ventpy red <archivo.json> [--json]` — ventilation network balance (Hardy Cross)
91
+ - `ventpy ventilador <archivo.json> [--json]` — fan operating point (standalone or coupled to a network)
92
+
93
+ Exit codes are meaningful: `0` success, `1` invalid input, `2` a
94
+ calculated-but-unreliable result (e.g. a network that did not converge, a
95
+ zone in deficit, or a fan operating point outside its catalog curve) — see
96
+ each subcommand's help (`ventpy <subcommand> -h`).
97
+
98
+ Five worked, self-verifying examples (each `run.py` asserts its own
99
+ documented numbers) live under [`examples/`](examples/), one per JSON input
100
+ schema plus a duct-sizing case that only uses the API (no CLI subcommand
101
+ for it yet):
102
+
103
+ - [`examples/01-demanda-peru`](examples/01-demanda-peru/) — diesel-limited demand, Peru preset
104
+ - [`examples/02-preset-chile`](examples/02-preset-chile/) — same case with `--norma chile`
105
+ - [`examples/03-cobertura-levantamiento`](examples/03-cobertura-levantamiento/) — 2-zone survey, one zone in deficit (`exit 2`)
106
+ - [`examples/04-red-ventilador`](examples/04-red-ventilador/) — fan coupled to a parallel-mesh network
107
+ - [`examples/05-ducto-seleccion`](examples/05-ducto-seleccion/) — duct sizing, technical vs. economic criterion (API only)
108
+
106
109
  ## Quick Start
107
110
 
108
111
  ```python
@@ -0,0 +1,65 @@
1
+ # Roadmap · VentPy
2
+
3
+ VentPy nació con la norma peruana (**DS 024-2016-EM**). El objetivo es que sirva en toda
4
+ Latinoamérica y cubra el cálculo de ventilación completo.
5
+
6
+ > **¿Quieres contribuir?** Lee [`CONTRIBUTING.md`](CONTRIBUTING.md). Las tareas marcadas
7
+ > **`buena primera tarea`** están pensadas para quien nunca ha contribuido a open source:
8
+ > son de conocimiento del dominio, no de programación avanzada.
9
+
10
+ ---
11
+
12
+ ## 1. Multi-norma — la prioridad
13
+
14
+ Hoy las constantes normativas están fijas a Perú. El diseño objetivo es un
15
+ `RegulatoryConfig` por país, seleccionable, con cada valor citando su artículo.
16
+
17
+ | País | Norma | Estado | Etiqueta |
18
+ |---|---|---|---|
19
+ | 🇵🇪 Perú | DS 024-2016-EM | ✅ implementado | — |
20
+ | 🇨🇱 Chile | DS 132 · Reglamento de Seguridad Minera | ⬜ **abierto** | `buena primera tarea` |
21
+ | 🇨🇴 Colombia | Decreto 1886 de 2015 | ⬜ **abierto** | `buena primera tarea` |
22
+ | 🇲🇽 México | NOM-023-STPS-2012 | ⬜ **abierto** | `buena primera tarea` |
23
+
24
+ **Qué implica agregar una norma** (esto es todo — no hay que tocar C++ avanzado):
25
+
26
+ 1. Ubicar en el reglamento los valores de: caudal mínimo por persona, factor por equipo
27
+ diésel (m³/min por HP o kW), tiempo/caudal de dilución post-voladura, velocidades
28
+ mínimas y máximas permitidas, y factor de fugas.
29
+ 2. Añadirlos como un preset de configuración, **citando el artículo de cada valor**.
30
+ 3. Escribir un test con un caso conocido de ese país.
31
+
32
+ Si no sabes programar en C++, **abre un issue con los valores y la cita del artículo** — eso
33
+ ya es la mitad del trabajo y alguien más lo integra.
34
+
35
+ ---
36
+
37
+ ## 2. Módulos por madurar
38
+
39
+ | Módulo | Estado |
40
+ |---|---|
41
+ | Personal, diésel, voladura, atmósfera, fugas, gobernador | ✅ maduro |
42
+ | **Polvo** (`dust`) | 🟡 modelo de resultado existe, implementación por madurar |
43
+ | **Térmico** (`thermal`) | 🟡 igual que polvo |
44
+
45
+ ---
46
+
47
+ ## 3. Buenas primeras tareas (no normativas)
48
+
49
+ - ⬜ **Ejemplos resueltos** en la documentación: un caso de mina superficial y uno subterránea,
50
+ con sus números, ejecutables como test. `buena primera tarea`
51
+ - ⬜ **Traducir el README** a inglés técnico revisado / portugués. `buena primera tarea`
52
+ - ⬜ **Interfaz de línea de comandos** (`ventpy calcular --personal 20 --diesel 300`).
53
+ - ⬜ **Gráficos**: mejorar `visualization` con un diagrama de red de ventilación.
54
+ - ⬜ **Reportar un número que no calce** con tu experiencia de campo (¡con el valor esperado!).
55
+ `buena primera tarea`
56
+
57
+ ---
58
+
59
+ ## 4. Cómo se decide
60
+
61
+ Este proyecto se usa para decisiones de **seguridad en minas**. Por eso:
62
+
63
+ - Ningún número entra sin su **referencia normativa**.
64
+ - La documentación es **conservadora**: si un módulo no está maduro, se dice.
65
+ - Se prefiere **rechazar un aporte** antes que publicar un cálculo que alguien use mal.