ventpy 0.1.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.
- ventpy-0.1.0/.github/workflows/release.yml +48 -0
- ventpy-0.1.0/.gitignore +42 -0
- ventpy-0.1.0/CMakeLists.txt +106 -0
- ventpy-0.1.0/LICENSE +21 -0
- ventpy-0.1.0/PKG-INFO +259 -0
- ventpy-0.1.0/README.es.md +234 -0
- ventpy-0.1.0/README.md +234 -0
- ventpy-0.1.0/bindings/bindings.cpp +658 -0
- ventpy-0.1.0/include/ventpy/atmosphere.hpp +310 -0
- ventpy-0.1.0/include/ventpy/caudal_equipo.hpp +404 -0
- ventpy-0.1.0/include/ventpy/caudal_explosivos.hpp +296 -0
- ventpy-0.1.0/include/ventpy/caudal_fugas.hpp +237 -0
- ventpy-0.1.0/include/ventpy/caudal_personal.hpp +289 -0
- ventpy-0.1.0/include/ventpy/governor.hpp +345 -0
- ventpy-0.1.0/include/ventpy/normativa.hpp +136 -0
- ventpy-0.1.0/include/ventpy/types.hpp +526 -0
- ventpy-0.1.0/include/ventpy/validation.hpp +127 -0
- ventpy-0.1.0/pyproject.toml +47 -0
- ventpy-0.1.0/python/ventpy/__init__.py +181 -0
- ventpy-0.1.0/python/ventpy/visualization.py +825 -0
- ventpy-0.1.0/tests/cpp/test_caudal_equipo.cpp +105 -0
- ventpy-0.1.0/tests/cpp/test_caudal_explosivos.cpp +109 -0
- ventpy-0.1.0/tests/cpp/test_caudal_fugas.cpp +76 -0
- ventpy-0.1.0/tests/cpp/test_caudal_personal.cpp +106 -0
- ventpy-0.1.0/tests/cpp/test_governor.cpp +171 -0
- ventpy-0.1.0/tests/cpp/test_validation.cpp +95 -0
- ventpy-0.1.0/tests/python/test_ventpy.py +595 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
name: Build & publish
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags: ["v*"]
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
build_wheels:
|
|
10
|
+
name: Wheels on ${{ matrix.os }}
|
|
11
|
+
runs-on: ${{ matrix.os }}
|
|
12
|
+
strategy:
|
|
13
|
+
fail-fast: false
|
|
14
|
+
matrix:
|
|
15
|
+
os: [ubuntu-latest, windows-latest, macos-latest]
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: pypa/cibuildwheel@v2.21
|
|
19
|
+
- uses: actions/upload-artifact@v4
|
|
20
|
+
with:
|
|
21
|
+
name: wheels-${{ matrix.os }}
|
|
22
|
+
path: wheelhouse/*.whl
|
|
23
|
+
|
|
24
|
+
build_sdist:
|
|
25
|
+
name: Source distribution
|
|
26
|
+
runs-on: ubuntu-latest
|
|
27
|
+
steps:
|
|
28
|
+
- uses: actions/checkout@v4
|
|
29
|
+
- run: pipx run build --sdist
|
|
30
|
+
- uses: actions/upload-artifact@v4
|
|
31
|
+
with:
|
|
32
|
+
name: sdist
|
|
33
|
+
path: dist/*.tar.gz
|
|
34
|
+
|
|
35
|
+
publish:
|
|
36
|
+
name: Publish to PyPI
|
|
37
|
+
needs: [build_wheels, build_sdist]
|
|
38
|
+
runs-on: ubuntu-latest
|
|
39
|
+
if: startsWith(github.ref, 'refs/tags/v')
|
|
40
|
+
environment: pypi
|
|
41
|
+
permissions:
|
|
42
|
+
id-token: write # trusted publishing (sin token en secrets)
|
|
43
|
+
steps:
|
|
44
|
+
- uses: actions/download-artifact@v4
|
|
45
|
+
with:
|
|
46
|
+
path: dist
|
|
47
|
+
merge-multiple: true
|
|
48
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
ventpy-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Build artifacts
|
|
2
|
+
build/
|
|
3
|
+
_build/
|
|
4
|
+
dist/
|
|
5
|
+
wheelhouse/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
*.so
|
|
8
|
+
*.pyd
|
|
9
|
+
*.dll
|
|
10
|
+
|
|
11
|
+
# CMake
|
|
12
|
+
CMakeFiles/
|
|
13
|
+
CMakeCache.txt
|
|
14
|
+
cmake_install.cmake
|
|
15
|
+
compile_commands.json
|
|
16
|
+
|
|
17
|
+
# Python caches and virtual environments
|
|
18
|
+
__pycache__/
|
|
19
|
+
*.pyc
|
|
20
|
+
.pytest_cache/
|
|
21
|
+
.mypy_cache/
|
|
22
|
+
.ruff_cache/
|
|
23
|
+
.venv/
|
|
24
|
+
venv/
|
|
25
|
+
env/
|
|
26
|
+
|
|
27
|
+
# IDE and editor state
|
|
28
|
+
.vs/
|
|
29
|
+
.vscode/
|
|
30
|
+
.idea/
|
|
31
|
+
*.sln
|
|
32
|
+
*.vcxproj*
|
|
33
|
+
|
|
34
|
+
# Internal agent and working documentation
|
|
35
|
+
CLAUDE/
|
|
36
|
+
CLAUDE.md
|
|
37
|
+
docs/
|
|
38
|
+
AGENT_NOTES.md
|
|
39
|
+
|
|
40
|
+
# OS files
|
|
41
|
+
.DS_Store
|
|
42
|
+
Thumbs.db
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
cmake_minimum_required(VERSION 3.20)
|
|
2
|
+
project(ventpy
|
|
3
|
+
VERSION 0.1.0
|
|
4
|
+
DESCRIPTION "High-performance mine ventilation calculation library"
|
|
5
|
+
LANGUAGES CXX
|
|
6
|
+
)
|
|
7
|
+
|
|
8
|
+
# ============================================================================
|
|
9
|
+
# C++20 obligatorio
|
|
10
|
+
# ============================================================================
|
|
11
|
+
set(CMAKE_CXX_STANDARD 20)
|
|
12
|
+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
|
|
13
|
+
set(CMAKE_CXX_EXTENSIONS OFF)
|
|
14
|
+
|
|
15
|
+
# Export compile_commands.json para LSP/IDEs
|
|
16
|
+
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
|
|
17
|
+
|
|
18
|
+
# ============================================================================
|
|
19
|
+
# Header-only core library (interfaz)
|
|
20
|
+
# ============================================================================
|
|
21
|
+
add_library(ventpy_core INTERFACE)
|
|
22
|
+
target_include_directories(ventpy_core INTERFACE
|
|
23
|
+
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
|
|
24
|
+
$<INSTALL_INTERFACE:include>
|
|
25
|
+
)
|
|
26
|
+
target_compile_features(ventpy_core INTERFACE cxx_std_20)
|
|
27
|
+
|
|
28
|
+
# ============================================================================
|
|
29
|
+
# Python bindings (nanobind via scikit-build-core)
|
|
30
|
+
# ============================================================================
|
|
31
|
+
option(VENTPY_BUILD_PYTHON "Build Python bindings" ON)
|
|
32
|
+
|
|
33
|
+
if(VENTPY_BUILD_PYTHON)
|
|
34
|
+
# Buscar Python y nanobind
|
|
35
|
+
find_package(Python 3.9
|
|
36
|
+
REQUIRED COMPONENTS Interpreter Development.Module
|
|
37
|
+
OPTIONAL_COMPONENTS Development.SABIModule
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
# nanobind: descargado via pip (nanobind es un paquete Python)
|
|
41
|
+
execute_process(
|
|
42
|
+
COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
|
|
43
|
+
OUTPUT_STRIP_TRAILING_WHITESPACE
|
|
44
|
+
OUTPUT_VARIABLE NB_DIR
|
|
45
|
+
RESULT_VARIABLE NB_RESULT
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
if(NB_RESULT EQUAL 0 AND EXISTS "${NB_DIR}")
|
|
49
|
+
list(APPEND CMAKE_PREFIX_PATH "${NB_DIR}")
|
|
50
|
+
find_package(nanobind CONFIG REQUIRED)
|
|
51
|
+
|
|
52
|
+
nanobind_add_module(_ventpy_core
|
|
53
|
+
STABLE_ABI
|
|
54
|
+
NB_STATIC
|
|
55
|
+
bindings/bindings.cpp
|
|
56
|
+
)
|
|
57
|
+
target_link_libraries(_ventpy_core PRIVATE ventpy_core)
|
|
58
|
+
|
|
59
|
+
# Instalar el módulo en el paquete Python.
|
|
60
|
+
# En Windows el módulo puede instalarse como RUNTIME (.pyd).
|
|
61
|
+
install(TARGETS _ventpy_core
|
|
62
|
+
LIBRARY DESTINATION ventpy
|
|
63
|
+
RUNTIME DESTINATION ventpy
|
|
64
|
+
ARCHIVE DESTINATION ventpy
|
|
65
|
+
)
|
|
66
|
+
else()
|
|
67
|
+
message(FATAL_ERROR
|
|
68
|
+
"nanobind not found, so the Python package would be incomplete.\n"
|
|
69
|
+
"Install with: pip install nanobind"
|
|
70
|
+
)
|
|
71
|
+
endif()
|
|
72
|
+
endif()
|
|
73
|
+
|
|
74
|
+
# ============================================================================
|
|
75
|
+
# C++ Tests (Google Test)
|
|
76
|
+
# ============================================================================
|
|
77
|
+
option(VENTPY_BUILD_TESTS "Build C++ unit tests" OFF)
|
|
78
|
+
|
|
79
|
+
if(VENTPY_BUILD_TESTS)
|
|
80
|
+
enable_testing()
|
|
81
|
+
|
|
82
|
+
include(FetchContent)
|
|
83
|
+
FetchContent_Declare(
|
|
84
|
+
googletest
|
|
85
|
+
URL https://github.com/google/googletest/archive/refs/tags/v1.14.0.zip
|
|
86
|
+
)
|
|
87
|
+
# Para Windows: evitar sobreescribir /MD con /MT
|
|
88
|
+
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
|
|
89
|
+
FetchContent_MakeAvailable(googletest)
|
|
90
|
+
|
|
91
|
+
add_executable(ventpy_tests
|
|
92
|
+
tests/cpp/test_validation.cpp
|
|
93
|
+
tests/cpp/test_caudal_personal.cpp
|
|
94
|
+
tests/cpp/test_caudal_equipo.cpp
|
|
95
|
+
tests/cpp/test_caudal_explosivos.cpp
|
|
96
|
+
tests/cpp/test_caudal_fugas.cpp
|
|
97
|
+
tests/cpp/test_governor.cpp
|
|
98
|
+
)
|
|
99
|
+
target_link_libraries(ventpy_tests PRIVATE
|
|
100
|
+
ventpy_core
|
|
101
|
+
GTest::gtest_main
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
include(GoogleTest)
|
|
105
|
+
gtest_discover_tests(ventpy_tests)
|
|
106
|
+
endif()
|
ventpy-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 VentPy Project
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
ventpy-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,259 @@
|
|
|
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
|
+
# VentPy
|
|
27
|
+
|
|
28
|
+
[English](README.md) | [Español](README.es.md)
|
|
29
|
+
|
|
30
|
+
High-performance underground mine ventilation calculations for Python, backed by a C++20 core.
|
|
31
|
+
|
|
32
|
+
VentPy helps mining engineers estimate ventilation demand for underground operations using an auditable API oriented around the Peruvian regulatory framework `DS 024-2016-EM / DS 023-2017-EM`.
|
|
33
|
+
|
|
34
|
+
## What VentPy Does
|
|
35
|
+
|
|
36
|
+
VentPy provides calculation tools for:
|
|
37
|
+
|
|
38
|
+
- Personnel-based airflow demand
|
|
39
|
+
- Diesel fleet airflow demand
|
|
40
|
+
- Blasting gas dilution airflow
|
|
41
|
+
- Atmospheric corrections at altitude
|
|
42
|
+
- Leakage adjustments for ducted ventilation
|
|
43
|
+
- Consolidated ventilation demand with governing-factor selection
|
|
44
|
+
- Optional visualization and HTML reporting helpers in Python
|
|
45
|
+
|
|
46
|
+
The library is designed for engineering workflows where performance, reproducibility, and traceability matter.
|
|
47
|
+
|
|
48
|
+
## Why This Library Exists
|
|
49
|
+
|
|
50
|
+
Mine ventilation calculations are often implemented in spreadsheets that become difficult to validate, reuse, or integrate into larger workflows. VentPy moves those calculations into a typed, testable library with:
|
|
51
|
+
|
|
52
|
+
- A C++ core for predictable performance
|
|
53
|
+
- Python bindings for scripting, analysis, and integration
|
|
54
|
+
- Explicit result objects instead of opaque spreadsheet formulas
|
|
55
|
+
- Domain-oriented inputs for personnel, diesel equipment, blasting, atmosphere, and leakage
|
|
56
|
+
|
|
57
|
+
## Regulatory Scope
|
|
58
|
+
|
|
59
|
+
Current defaults are based on:
|
|
60
|
+
|
|
61
|
+
- `DS 024-2016-EM`
|
|
62
|
+
- `DS 023-2017-EM`
|
|
63
|
+
|
|
64
|
+
The default `RegulatoryConfig` reflects this Peruvian framework, while still allowing stricter corporate parameters to be injected when needed.
|
|
65
|
+
|
|
66
|
+
## Project Status
|
|
67
|
+
|
|
68
|
+
VentPy is currently in `alpha`.
|
|
69
|
+
|
|
70
|
+
Implemented and exposed today:
|
|
71
|
+
|
|
72
|
+
- Personnel flow calculations
|
|
73
|
+
- Diesel flow calculations
|
|
74
|
+
- Blasting flow calculations
|
|
75
|
+
- Atmospheric correction utilities
|
|
76
|
+
- Integrated ventilation governor
|
|
77
|
+
- Python visualization helpers
|
|
78
|
+
|
|
79
|
+
Additional result types for dust, thermal, and leakage are already part of the public model, but the practical maturity of each workflow should be validated against your engineering use case before operational adoption.
|
|
80
|
+
|
|
81
|
+
## Installation
|
|
82
|
+
|
|
83
|
+
VentPy currently builds from source.
|
|
84
|
+
|
|
85
|
+
### Requirements
|
|
86
|
+
|
|
87
|
+
- Python `3.9+`
|
|
88
|
+
- CMake `3.20+`
|
|
89
|
+
- A compiler with `C++20` support
|
|
90
|
+
|
|
91
|
+
### Install in a Virtual Environment
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
python -m venv .venv
|
|
95
|
+
.venv\Scripts\activate
|
|
96
|
+
python -m pip install --upgrade pip
|
|
97
|
+
pip install .
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
For development:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
pip install -e .[test,viz]
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Quick Start
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
import ventpy
|
|
110
|
+
|
|
111
|
+
config = ventpy.RegulatoryConfig()
|
|
112
|
+
governor = ventpy.VentilationGovernor(config)
|
|
113
|
+
|
|
114
|
+
inp = ventpy.VentilationInput()
|
|
115
|
+
inp.num_workers = 15
|
|
116
|
+
inp.altitude_masl = 4200.0
|
|
117
|
+
|
|
118
|
+
result = governor.calculate_total_demand(inp)
|
|
119
|
+
|
|
120
|
+
print(f"Q_total = {result.q_total_m3min} m3/min")
|
|
121
|
+
print(f"Q_total = {result.q_total_cfm:.1f} cfm")
|
|
122
|
+
print(f"Governing factor = {result.governing_factor}")
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Example With Diesel Fleet and Blasting
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
import ventpy
|
|
129
|
+
|
|
130
|
+
config = ventpy.RegulatoryConfig()
|
|
131
|
+
governor = ventpy.VentilationGovernor(config)
|
|
132
|
+
|
|
133
|
+
inp = ventpy.VentilationInput()
|
|
134
|
+
inp.zone_type = ventpy.ZoneType.DevelopmentFace
|
|
135
|
+
inp.face_area_m2 = 15.0
|
|
136
|
+
inp.face_length_m = 120.0
|
|
137
|
+
inp.safety_factor = 1.10
|
|
138
|
+
inp.simultaneity_factor = 0.85
|
|
139
|
+
|
|
140
|
+
inp.atmospheric = ventpy.AtmosphericParams()
|
|
141
|
+
inp.atmospheric.altitude_masl = 4200.0
|
|
142
|
+
inp.atmospheric.dry_bulb_temp_c = 22.0
|
|
143
|
+
|
|
144
|
+
inp.personnel = ventpy.PersonnelParams()
|
|
145
|
+
inp.personnel.num_workers = 12
|
|
146
|
+
inp.personnel.activity = ventpy.ActivityLevel.Moderate
|
|
147
|
+
|
|
148
|
+
fleet = ventpy.DieselFleet()
|
|
149
|
+
fleet.add_equipment("Scooptram ST1030", 180.0, 0.88, 0.75)
|
|
150
|
+
inp.diesel_fleet = fleet
|
|
151
|
+
|
|
152
|
+
blast = ventpy.BlastingParams()
|
|
153
|
+
blast.explosive_kg = 50.0
|
|
154
|
+
blast.explosive_type = ventpy.ExplosiveType.ANFO
|
|
155
|
+
blast.dilution_time_min = 30.0
|
|
156
|
+
blast.face_area_m2 = 15.0
|
|
157
|
+
blast.face_length_m = 120.0
|
|
158
|
+
inp.blasting_params = blast
|
|
159
|
+
|
|
160
|
+
result = governor.calculate_total_demand(inp)
|
|
161
|
+
|
|
162
|
+
print(result.q_personnel_m3min)
|
|
163
|
+
print(result.q_diesel_m3min)
|
|
164
|
+
print(result.q_blasting_m3min)
|
|
165
|
+
print(result.q_total_m3min)
|
|
166
|
+
print(result.velocity_at_face_mps)
|
|
167
|
+
print(result.warnings)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Core API
|
|
171
|
+
|
|
172
|
+
Main entry points:
|
|
173
|
+
|
|
174
|
+
- `RegulatoryConfig`
|
|
175
|
+
- `VentilationGovernor`
|
|
176
|
+
- `VentilationInput`
|
|
177
|
+
- `DieselFleet`
|
|
178
|
+
- `AtmosphericParams`
|
|
179
|
+
- `PersonnelParams`
|
|
180
|
+
- `BlastingParams`
|
|
181
|
+
|
|
182
|
+
Direct calculators:
|
|
183
|
+
|
|
184
|
+
- `calculate_personnel_flow(...)`
|
|
185
|
+
- `calculate_diesel_flow(...)`
|
|
186
|
+
- `calculate_blasting_flow(...)`
|
|
187
|
+
- `calculate_atmospheric_corrections(...)`
|
|
188
|
+
|
|
189
|
+
Useful utilities:
|
|
190
|
+
|
|
191
|
+
- `calculate_pressure_kpa(...)`
|
|
192
|
+
- `calculate_density_kg_m3(...)`
|
|
193
|
+
- `calculate_volume_correction_factor(...)`
|
|
194
|
+
- `calculate_diesel_derate_factor(...)`
|
|
195
|
+
- `get_min_velocity(...)`
|
|
196
|
+
- `safety_ceil(...)`
|
|
197
|
+
|
|
198
|
+
## Visualization
|
|
199
|
+
|
|
200
|
+
VentPy includes a Python visualization module intended for quick engineering communication and reporting.
|
|
201
|
+
|
|
202
|
+
Available helpers include:
|
|
203
|
+
|
|
204
|
+
- `plot_flow_comparison(...)`
|
|
205
|
+
- `plot_flow_breakdown(...)`
|
|
206
|
+
- `create_dashboard(...)`
|
|
207
|
+
- `generate_html_report(...)`
|
|
208
|
+
|
|
209
|
+
Example:
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
from ventpy import visualization as viz
|
|
213
|
+
|
|
214
|
+
html = viz.generate_html_report(
|
|
215
|
+
{
|
|
216
|
+
"q_personnel_m3min": 45.0,
|
|
217
|
+
"q_diesel_m3min": 267.0,
|
|
218
|
+
"q_blasting_m3min": 50.0,
|
|
219
|
+
"q_dust_m3min": 0.0,
|
|
220
|
+
"q_thermal_m3min": 0.0,
|
|
221
|
+
"q_leakage_m3min": 50.0,
|
|
222
|
+
"q_governing_m3min": 267.0,
|
|
223
|
+
"q_total_m3min": 317.0,
|
|
224
|
+
},
|
|
225
|
+
include_charts=False,
|
|
226
|
+
)
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
If you want chart rendering, install `matplotlib` in your environment.
|
|
230
|
+
The optional visualization dependency set can be installed with `pip install -e .[viz]`.
|
|
231
|
+
|
|
232
|
+
## Development
|
|
233
|
+
|
|
234
|
+
Run Python tests with:
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
pytest
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
The project also contains C++ tests that can be enabled through CMake when needed.
|
|
241
|
+
|
|
242
|
+
## Repository Layout
|
|
243
|
+
|
|
244
|
+
```text
|
|
245
|
+
include/ C++ headers for the calculation core
|
|
246
|
+
bindings/ nanobind Python bindings
|
|
247
|
+
python/ventpy/ Python package and visualization helpers
|
|
248
|
+
tests/ Python and C++ tests
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
## Engineering Disclaimer
|
|
252
|
+
|
|
253
|
+
VentPy is a calculation library, not a substitute for engineering judgment, ventilation surveys, field measurements, or regulatory review.
|
|
254
|
+
|
|
255
|
+
Use it as a computational aid. Final ventilation design decisions remain the responsibility of the qualified engineer of record.
|
|
256
|
+
|
|
257
|
+
## License
|
|
258
|
+
|
|
259
|
+
MIT
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# VentPy
|
|
2
|
+
|
|
3
|
+
[English](README.md) | [Español](README.es.md)
|
|
4
|
+
|
|
5
|
+
Calculos de ventilacion subterranea de alto rendimiento para Python, respaldados por un nucleo en C++20.
|
|
6
|
+
|
|
7
|
+
VentPy ayuda a ingenieros de minas a estimar la demanda de ventilacion en operaciones subterraneas mediante una API auditable orientada al marco regulatorio peruano `DS 024-2016-EM / DS 023-2017-EM`.
|
|
8
|
+
|
|
9
|
+
## Que Hace VentPy
|
|
10
|
+
|
|
11
|
+
VentPy proporciona herramientas de calculo para:
|
|
12
|
+
|
|
13
|
+
- Demanda de caudal por personal
|
|
14
|
+
- Demanda de caudal por flota diesel
|
|
15
|
+
- Dilucion de gases de voladura
|
|
16
|
+
- Correcciones atmosfericas por altitud
|
|
17
|
+
- Ajustes por fugas en ventilacion con ductos
|
|
18
|
+
- Demanda consolidada de ventilacion con seleccion del factor gobernante
|
|
19
|
+
- Ayudas opcionales de visualizacion y reportes HTML en Python
|
|
20
|
+
|
|
21
|
+
La libreria esta orientada a flujos de trabajo de ingenieria donde importan el rendimiento, la reproducibilidad y la trazabilidad.
|
|
22
|
+
|
|
23
|
+
## Por Que Existe Esta Libreria
|
|
24
|
+
|
|
25
|
+
Los calculos de ventilacion de mina suelen implementarse en hojas de calculo que se vuelven dificiles de validar, reutilizar o integrar en flujos de trabajo mayores. VentPy traslada esos calculos a una libreria tipada y testeable con:
|
|
26
|
+
|
|
27
|
+
- Un nucleo en C++ para rendimiento predecible
|
|
28
|
+
- Bindings de Python para scripting, analisis e integracion
|
|
29
|
+
- Objetos de resultado explicitos en lugar de formulas opacas en hojas de calculo
|
|
30
|
+
- Entradas orientadas al dominio para personal, equipos diesel, voladura, atmosfera y fugas
|
|
31
|
+
|
|
32
|
+
## Alcance Regulatorio
|
|
33
|
+
|
|
34
|
+
Los valores por defecto actuales se basan en:
|
|
35
|
+
|
|
36
|
+
- `DS 024-2016-EM`
|
|
37
|
+
- `DS 023-2017-EM`
|
|
38
|
+
|
|
39
|
+
La `RegulatoryConfig` por defecto refleja este marco peruano, pero permite inyectar parametros corporativos mas exigentes cuando sea necesario.
|
|
40
|
+
|
|
41
|
+
## Estado Del Proyecto
|
|
42
|
+
|
|
43
|
+
VentPy se encuentra actualmente en estado `alpha`.
|
|
44
|
+
|
|
45
|
+
Implementado y expuesto hoy:
|
|
46
|
+
|
|
47
|
+
- Calculos de caudal por personal
|
|
48
|
+
- Calculos de caudal por equipos diesel
|
|
49
|
+
- Calculos de caudal por explosivos
|
|
50
|
+
- Utilidades de correccion atmosferica
|
|
51
|
+
- Governor integrado de demanda de ventilacion
|
|
52
|
+
- Ayudas de visualizacion en Python
|
|
53
|
+
|
|
54
|
+
Los tipos de resultado para polvo, termica y fugas ya forman parte del modelo publico, pero la madurez practica de cada flujo debe validarse frente a tu caso de uso de ingenieria antes de una adopcion operativa.
|
|
55
|
+
|
|
56
|
+
## Instalacion
|
|
57
|
+
|
|
58
|
+
VentPy se construye actualmente desde codigo fuente.
|
|
59
|
+
|
|
60
|
+
### Requisitos
|
|
61
|
+
|
|
62
|
+
- Python `3.9+`
|
|
63
|
+
- CMake `3.20+`
|
|
64
|
+
- Un compilador con soporte `C++20`
|
|
65
|
+
|
|
66
|
+
### Instalacion En Un Entorno Virtual
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
python -m venv .venv
|
|
70
|
+
.venv\Scripts\activate
|
|
71
|
+
python -m pip install --upgrade pip
|
|
72
|
+
pip install .
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Para desarrollo:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
pip install -e .[test,viz]
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Inicio Rapido
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
import ventpy
|
|
85
|
+
|
|
86
|
+
config = ventpy.RegulatoryConfig()
|
|
87
|
+
governor = ventpy.VentilationGovernor(config)
|
|
88
|
+
|
|
89
|
+
inp = ventpy.VentilationInput()
|
|
90
|
+
inp.num_workers = 15
|
|
91
|
+
inp.altitude_masl = 4200.0
|
|
92
|
+
|
|
93
|
+
result = governor.calculate_total_demand(inp)
|
|
94
|
+
|
|
95
|
+
print(f"Q_total = {result.q_total_m3min} m3/min")
|
|
96
|
+
print(f"Q_total = {result.q_total_cfm:.1f} cfm")
|
|
97
|
+
print(f"Factor gobernante = {result.governing_factor}")
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## Ejemplo Con Flota Diesel Y Voladura
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
import ventpy
|
|
104
|
+
|
|
105
|
+
config = ventpy.RegulatoryConfig()
|
|
106
|
+
governor = ventpy.VentilationGovernor(config)
|
|
107
|
+
|
|
108
|
+
inp = ventpy.VentilationInput()
|
|
109
|
+
inp.zone_type = ventpy.ZoneType.DevelopmentFace
|
|
110
|
+
inp.face_area_m2 = 15.0
|
|
111
|
+
inp.face_length_m = 120.0
|
|
112
|
+
inp.safety_factor = 1.10
|
|
113
|
+
inp.simultaneity_factor = 0.85
|
|
114
|
+
|
|
115
|
+
inp.atmospheric = ventpy.AtmosphericParams()
|
|
116
|
+
inp.atmospheric.altitude_masl = 4200.0
|
|
117
|
+
inp.atmospheric.dry_bulb_temp_c = 22.0
|
|
118
|
+
|
|
119
|
+
inp.personnel = ventpy.PersonnelParams()
|
|
120
|
+
inp.personnel.num_workers = 12
|
|
121
|
+
inp.personnel.activity = ventpy.ActivityLevel.Moderate
|
|
122
|
+
|
|
123
|
+
fleet = ventpy.DieselFleet()
|
|
124
|
+
fleet.add_equipment("Scooptram ST1030", 180.0, 0.88, 0.75)
|
|
125
|
+
inp.diesel_fleet = fleet
|
|
126
|
+
|
|
127
|
+
blast = ventpy.BlastingParams()
|
|
128
|
+
blast.explosive_kg = 50.0
|
|
129
|
+
blast.explosive_type = ventpy.ExplosiveType.ANFO
|
|
130
|
+
blast.dilution_time_min = 30.0
|
|
131
|
+
blast.face_area_m2 = 15.0
|
|
132
|
+
blast.face_length_m = 120.0
|
|
133
|
+
inp.blasting_params = blast
|
|
134
|
+
|
|
135
|
+
result = governor.calculate_total_demand(inp)
|
|
136
|
+
|
|
137
|
+
print(result.q_personnel_m3min)
|
|
138
|
+
print(result.q_diesel_m3min)
|
|
139
|
+
print(result.q_blasting_m3min)
|
|
140
|
+
print(result.q_total_m3min)
|
|
141
|
+
print(result.velocity_at_face_mps)
|
|
142
|
+
print(result.warnings)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## API Principal
|
|
146
|
+
|
|
147
|
+
Puntos de entrada principales:
|
|
148
|
+
|
|
149
|
+
- `RegulatoryConfig`
|
|
150
|
+
- `VentilationGovernor`
|
|
151
|
+
- `VentilationInput`
|
|
152
|
+
- `DieselFleet`
|
|
153
|
+
- `AtmosphericParams`
|
|
154
|
+
- `PersonnelParams`
|
|
155
|
+
- `BlastingParams`
|
|
156
|
+
|
|
157
|
+
Calculadores directos:
|
|
158
|
+
|
|
159
|
+
- `calculate_personnel_flow(...)`
|
|
160
|
+
- `calculate_diesel_flow(...)`
|
|
161
|
+
- `calculate_blasting_flow(...)`
|
|
162
|
+
- `calculate_atmospheric_corrections(...)`
|
|
163
|
+
|
|
164
|
+
Utilidades relevantes:
|
|
165
|
+
|
|
166
|
+
- `calculate_pressure_kpa(...)`
|
|
167
|
+
- `calculate_density_kg_m3(...)`
|
|
168
|
+
- `calculate_volume_correction_factor(...)`
|
|
169
|
+
- `calculate_diesel_derate_factor(...)`
|
|
170
|
+
- `get_min_velocity(...)`
|
|
171
|
+
- `safety_ceil(...)`
|
|
172
|
+
|
|
173
|
+
## Visualizacion
|
|
174
|
+
|
|
175
|
+
VentPy incluye un modulo de visualizacion en Python orientado a comunicacion tecnica y reporte rapido.
|
|
176
|
+
|
|
177
|
+
Entre las ayudas disponibles se incluyen:
|
|
178
|
+
|
|
179
|
+
- `plot_flow_comparison(...)`
|
|
180
|
+
- `plot_flow_breakdown(...)`
|
|
181
|
+
- `create_dashboard(...)`
|
|
182
|
+
- `generate_html_report(...)`
|
|
183
|
+
|
|
184
|
+
Ejemplo:
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
from ventpy import visualization as viz
|
|
188
|
+
|
|
189
|
+
html = viz.generate_html_report(
|
|
190
|
+
{
|
|
191
|
+
"q_personnel_m3min": 45.0,
|
|
192
|
+
"q_diesel_m3min": 267.0,
|
|
193
|
+
"q_blasting_m3min": 50.0,
|
|
194
|
+
"q_dust_m3min": 0.0,
|
|
195
|
+
"q_thermal_m3min": 0.0,
|
|
196
|
+
"q_leakage_m3min": 50.0,
|
|
197
|
+
"q_governing_m3min": 267.0,
|
|
198
|
+
"q_total_m3min": 317.0,
|
|
199
|
+
},
|
|
200
|
+
include_charts=False,
|
|
201
|
+
)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Si necesitas renderizado de graficos, instala `matplotlib` en tu entorno.
|
|
205
|
+
El conjunto opcional de dependencias de visualizacion puede instalarse con `pip install -e .[viz]`.
|
|
206
|
+
|
|
207
|
+
## Desarrollo
|
|
208
|
+
|
|
209
|
+
Ejecuta las pruebas de Python con:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
pytest
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
El proyecto tambien contiene pruebas C++ que pueden habilitarse mediante CMake cuando sea necesario.
|
|
216
|
+
|
|
217
|
+
## Estructura Del Repositorio
|
|
218
|
+
|
|
219
|
+
```text
|
|
220
|
+
include/ Cabeceras C++ del nucleo de calculo
|
|
221
|
+
bindings/ Bindings de Python con nanobind
|
|
222
|
+
python/ventpy/ Paquete Python y ayudas de visualizacion
|
|
223
|
+
tests/ Pruebas Python y C++
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Descargo De Ingenieria
|
|
227
|
+
|
|
228
|
+
VentPy es una libreria de calculo, no un sustituto del criterio ingenieril, los aforos de ventilacion, las mediciones de campo ni la revision regulatoria.
|
|
229
|
+
|
|
230
|
+
Usalo como apoyo computacional. Las decisiones finales de diseno de ventilacion siguen siendo responsabilidad del ingeniero competente a cargo.
|
|
231
|
+
|
|
232
|
+
## Licencia
|
|
233
|
+
|
|
234
|
+
MIT
|