VentPy

English | Español

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.

Start here: Installation · First calculation · The auditable result · Worked examples · Engineering criteria

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

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.

What VentPy Does

Personnel-based airflow demand (DS 024-2016-EM, Art. 247 altitude scale / DS 132, Art. 138)
Diesel fleet airflow demand, including CO/NOx dilution by engine emission tier
Blasting gas dilution airflow
Respirable dust and thermal-load airflow, integrated into the consolidated demand
Leakage adjustments for ducted ventilation
Atmospheric corrections at altitude (pressure, density, oxygen partial pressure)
Consolidated ventilation demand with governing-factor selection (VentilationGovernor)
Coverage/deficit analysis: measured airflow vs. required, by zone and for the whole mine
Atkinson airway resistance and duct sizing (technical and economic criteria)
Ventilation network balance by the Hardy Cross method, with automatic mesh detection
Fan curve, operating point and stall margin, standalone or coupled to a network
Permissible exposure limits (LMP) for regulated gases, by standard
A ventpy command-line interface and optional visualization/HTML reporting helpers

Multi-Standard Support

VentPy ships official presets for two regulatory frameworks, each constant citing its article:

import ventpy

peru = ventpy.calculate_personnel_flow(15, 4200.0, ventpy.RegulatoryConfig.peru())
chile = ventpy.calculate_personnel_flow(15, 4200.0, ventpy.RegulatoryConfig.chile())

print(f"Peru:  {peru.q_personnel} m3/min ({peru.flow_per_person_base} m3/min/person)")
print(f"Chile: {chile.q_personnel} m3/min ({chile.flow_per_person_base} m3/min/person)")

Output:

Peru:  90.0 m3/min (6.0 m3/min/person)
Chile: 45.0 m3/min (3.0 m3/min/person)

RegulatoryConfig.peru() — DS 024-2016-EM / DS 023-2017-EM.
RegulatoryConfig.chile() — DS 132, Reglamento de Seguridad Minera (gas limits also draw on DS 594).
RegulatoryConfig.for_standard(standard) — builds either preset from a RegulatoryStandard enum member; used internally by the CLI's --norma peru|chile flag.

Adding another country's standard is the contribution VentPy needs most — see Contributing.

Project Status

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.

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.

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.

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.

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.

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.

Installation

pip install ventpy

Prebuilt wheels are published for Python 3.9 to 3.13 on Linux, macOS and Windows, so no compiler or CMake is required.

For chart rendering and HTML report generation, install the visualization extra:

pip install ventpy[viz]

Quick Start

import ventpy

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

inp = ventpy.VentilationInput()
inp.zone_type = ventpy.ZoneType.DevelopmentFace
inp.num_workers = 15
inp.altitude_masl = 4200.0

result = governor.calculate_total_demand(inp)

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

Output:

Q_total = 207.0 m3/min
Q_total = 7310.1 cfm
Governing factor = personnel (Q_Per)

Five worked, self-verifying examples (each run.py asserts its own documented numbers) live under examples/, covering diesel-limited demand, the Chilean preset, coverage/deficit, a fan coupled to a network, and duct sizing.

Command Line Interface

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:

ventpy demanda <file.json> [--norma peru|chile] [--json] — total ventilation demand for a zone/face
ventpy lmp [--norma peru|chile] [--gas GAS] [--json] — permissible exposure limits (LMP) for regulated gases
ventpy cobertura <file.json> [--norma peru|chile] [--json] — coverage/deficit analysis of a zone survey
ventpy red <file.json> [--json] — ventilation network balance (Hardy Cross)
ventpy ventilador <file.json> [--json] — fan operating point (standalone or coupled to a network)

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).

$ ventpy lmp --norma peru --gas CO
standard: DS024_Peru
gas: CO
unit: PPM
twa_8h: 25.0
stel: None
ceiling: None
floor_min: None
regulation_ref: DS 024-2016-EM, Anexo 15, fila 33 (via Art. 246)

Core API

VentPy exposes 87 public names (ventpy.__all__). Main entry points:

RegulatoryConfig (.peru(), .chile(), .for_standard(...))
VentilationGovernor, VentilationInput
DieselFleet, AtmosphericParams, PersonnelParams, BlastingParams, DustParams, ThermalParams

Direct calculators:

calculate_personnel_flow, calculate_diesel_flow, calculate_blasting_flow, calculate_dust_flow, calculate_thermal_flow, calculate_atmospheric_corrections

Network, duct and fan:

AtkinsonCalculator, DuctSizingCalculator, NetworkSolver, FanCalculator

Coverage and gas limits:

CoverageCalculator, gas_limits(standard), lmp_for(standard, gas)

Utilities:

calculate_pressure_kpa, calculate_density_kg_m3, calculate_volume_correction_factor, calculate_diesel_derate_factor, get_min_velocity, safety_ceil, safety_ceil_decimals

Visualization

VentPy includes a Python visualization module for quick engineering communication and reporting: plot_flow_comparison, plot_flow_breakdown, create_dashboard, generate_html_report.

from ventpy import visualization as viz

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

Chart rendering requires matplotlib, included in the viz extra (pip install ventpy[viz]).

Contributing

See 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 for the full version history.

Engineering Disclaimer

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

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

License

MIT — see LICENSE.

Development Status
- 4 - Beta
Intended Audience
- Science/Research
Programming Language
Topic
- Scientific/Engineering

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ventpy-0.2.1.tar.gz (169.6 kB view details)

Uploaded Aug 20, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ventpy-0.2.1-cp313-cp313-win_amd64.whl (227.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.13Windows x86-64

ventpy-0.2.1-cp313-cp313-win32.whl (202.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.13Windows x86

ventpy-0.2.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (243.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

ventpy-0.2.1-cp313-cp313-manylinux_2_17_i686.manylinux2014_i686.whl (255.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.13manylinux: glibc 2.17+ i686

ventpy-0.2.1-cp313-cp313-macosx_11_0_arm64.whl (197.3 kB view details)

Uploaded Aug 20, 2026 CPython 3.13macOS 11.0+ ARM64

ventpy-0.2.1-cp312-cp312-win_amd64.whl (227.8 kB view details)

Uploaded Aug 20, 2026 CPython 3.12Windows x86-64

ventpy-0.2.1-cp312-cp312-win32.whl (202.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.12Windows x86

ventpy-0.2.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (243.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

ventpy-0.2.1-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl (255.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.12manylinux: glibc 2.17+ i686

ventpy-0.2.1-cp312-cp312-macosx_11_0_arm64.whl (197.3 kB view details)

Uploaded Aug 20, 2026 CPython 3.12macOS 11.0+ ARM64

ventpy-0.2.1-cp311-cp311-win_amd64.whl (229.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.11Windows x86-64

ventpy-0.2.1-cp311-cp311-win32.whl (204.3 kB view details)

Uploaded Aug 20, 2026 CPython 3.11Windows x86

ventpy-0.2.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (246.4 kB view details)

Uploaded Aug 20, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

ventpy-0.2.1-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl (259.6 kB view details)

Uploaded Aug 20, 2026 CPython 3.11manylinux: glibc 2.17+ i686

ventpy-0.2.1-cp311-cp311-macosx_11_0_arm64.whl (198.9 kB view details)

Uploaded Aug 20, 2026 CPython 3.11macOS 11.0+ ARM64

ventpy-0.2.1-cp310-cp310-win_amd64.whl (229.1 kB view details)

Uploaded Aug 20, 2026 CPython 3.10Windows x86-64

ventpy-0.2.1-cp310-cp310-win32.whl (204.1 kB view details)

Uploaded Aug 20, 2026 CPython 3.10Windows x86

ventpy-0.2.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (246.5 kB view details)

Uploaded Aug 20, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

ventpy-0.2.1-cp310-cp310-manylinux_2_17_i686.manylinux2014_i686.whl (259.6 kB view details)

Uploaded Aug 20, 2026 CPython 3.10manylinux: glibc 2.17+ i686

ventpy-0.2.1-cp310-cp310-macosx_11_0_arm64.whl (198.9 kB view details)

Uploaded Aug 20, 2026 CPython 3.10macOS 11.0+ ARM64

ventpy-0.2.1-cp39-cp39-win_amd64.whl (230.0 kB view details)

Uploaded Aug 20, 2026 CPython 3.9Windows x86-64

ventpy-0.2.1-cp39-cp39-win32.whl (204.6 kB view details)

Uploaded Aug 20, 2026 CPython 3.9Windows x86

ventpy-0.2.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (246.7 kB view details)

Uploaded Aug 20, 2026 CPython 3.9manylinux: glibc 2.17+ x86-64

ventpy-0.2.1-cp39-cp39-manylinux_2_17_i686.manylinux2014_i686.whl (259.9 kB view details)

Uploaded Aug 20, 2026 CPython 3.9manylinux: glibc 2.17+ i686

ventpy-0.2.1-cp39-cp39-macosx_11_0_arm64.whl (199.2 kB view details)

Uploaded Aug 20, 2026 CPython 3.9macOS 11.0+ ARM64

File details

Details for the file ventpy-0.2.1.tar.gz.

File metadata

Download URL: ventpy-0.2.1.tar.gz
Upload date: Aug 20, 2026
Size: 169.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ventpy-0.2.1.tar.gz
Algorithm	Hash digest
SHA256	`edccbe9f341fd897bdf11ed2145daccb7649eecdbf13412d2baefeaba33875af`
MD5	`debd6c56e5ae4590adab9d574c8c1622`
BLAKE2b-256	`003db6d89dfcfecf990fb7bb0fe98b033e33f0319c4ad5194c57a85dc0457b9a`

Algorithm	Hash digest
SHA256	`8b1315eb4a319b92be389686dde3e1be85f6fa095572bf939fd0567e891d9523`
MD5	`1f9c98677198375a187cb3e9de6eb08c`
BLAKE2b-256	`7e338cadfd8cb18fc83f7f48def25ddb5efa0bff583565f35ae36a633233706e`

Algorithm	Hash digest
SHA256	`7b179544f9146fa5f91dc56bbdfcbf98c2ffadbcecea4fe9db6a9c290f2f1783`
MD5	`51c8e563ece6c611e8287f0b5d9cd60e`
BLAKE2b-256	`5cc368b71f1649dfa20ca622f5588ac936a5fc57e95c8fcc559fc03278f84a3e`

Algorithm	Hash digest
SHA256	`e07386ccffee576678ac434fd7d7d695fb5103c4ec58093bd25e0e81f3d3b5e7`
MD5	`e6b08a16dca08e55f39cedc8442f0ed7`
BLAKE2b-256	`458440a498decea4c707a3cfb812f308d7cb13f627ca167170e98170b8799b61`

Algorithm	Hash digest
SHA256	`f8931acbe87bb68e0b88a6a817029f1cc6c3029e9623b4fce4d52c13dca28170`
MD5	`05de381c36276bf9400323fc9f0ef468`
BLAKE2b-256	`dacefe2e8e92edc85b7c6de04464193e525b03077fb68e6bc1cac5cfca601a9c`

Algorithm	Hash digest
SHA256	`a31a738198d651a45cabfd97ffcc83802ec7b16f040772ef8e430f7c591312f2`
MD5	`06b4441cf52e86efc263a3771826820c`
BLAKE2b-256	`d40255fbd6fd75ea2b1da4bb6f35e99786592450e9c822144021d92f8425ffad`

Algorithm	Hash digest
SHA256	`5df244ac20cacc7306f4aee80ce8001c1c15b7d9267a2610aea7e7cbd9e3fa8c`
MD5	`99970e451e2b2f893287000b99ce484d`
BLAKE2b-256	`3d9a541b158345db7c7c75d2f385fa495ccfdd2e4d3a5c7777df72193df55bc3`

Algorithm	Hash digest
SHA256	`d96eb94ededa5e6d62c9eec0c907a0e5b2e4352602f9111afd7d389fe56f0440`
MD5	`2d56324804dc7fb95877a29dd63e97f2`
BLAKE2b-256	`216a3113ec6fe91f39e840799e0c24dd6ee5111cc2bfe1cd0be64fcd42dee8f0`

Algorithm	Hash digest
SHA256	`180d2d0337b88f4b187b68df8759d6fa9fe2627e0b44f6b18e7e14a4faad187e`
MD5	`bd3565e3c45d69b51aba4451b0d5e59f`
BLAKE2b-256	`4a6bc5f82b44b9b57c559b0b66a545c3a3bb2cf3c1109f85ed391d94e03b55f7`

Algorithm	Hash digest
SHA256	`7eefe724deee5d5ce8d21264b8dbe1eefa6179c683e8b89f5e823a6e3d2b323a`
MD5	`5052f5d1be4fc370d0fa371124f80774`
BLAKE2b-256	`845a82a501ea80b40a4c29fbfb7089308e106111e469f5acf5a3839cdf201222`

Algorithm	Hash digest
SHA256	`c8b47baf69dce306dddfd182347e8786d69bc7eaf0669c44788f4fe19362a213`
MD5	`53d24db59b408edcd640f51f2d70eee8`
BLAKE2b-256	`d43a2a48e6a1f3c02425435afd09dc9707cfa089bf124c5c9de117ab4d9a8c5b`

Algorithm	Hash digest
SHA256	`bd73354cb8ade50c8cb8839beddd0d0c9febf320cfb9cccd78d40f199295ab30`
MD5	`477e54a83d56656759ec9f27143a6e7b`
BLAKE2b-256	`6774483deea9abad3358560e1a821fca16a144371afea7b28a2974b2f6df74e1`

Algorithm	Hash digest
SHA256	`79f6d6337b3f2908a16408bf79f25a089c74d260942b13086b14e0829ec7bf1e`
MD5	`cb215d8181888b13cf7b7236ae14ac9b`
BLAKE2b-256	`069d1c295170ecd0669e8994827b9fea1b7e9e9a3051de51975812c02dbf0a38`

Algorithm	Hash digest
SHA256	`b181c47842e8582fbc102a9679e2ab1d20b8d6d48ffc64c6c8e17360ff4a805a`
MD5	`57276514c026418c022819c002ce0324`
BLAKE2b-256	`396f3130dd2a316adbc10061321ff36b93c76018c70861669c46d4038761f8e1`

Algorithm	Hash digest
SHA256	`5b178d4c8c87834c8b3556bfa5d48508e9afb812abeb7980d7c68cfdf2d60186`
MD5	`03eae91651886a891edcee6ddfcd201a`
BLAKE2b-256	`59d78ac1b942463ab903c1a7f60f65be971858beb469efacfca59e0f2bf5ec1b`

Algorithm	Hash digest
SHA256	`ed316ecd10bfd001c7e491b050163b4e6b6ac6faab77216310d8325af48adde8`
MD5	`4f8da85342a8eef8581e4e920d89fc82`
BLAKE2b-256	`26ca99596457a48fc7d1eb6b59ab212d678c403901b845bfae2996fba77df15e`

Algorithm	Hash digest
SHA256	`c4a327c7f8d56fc08bd8d9ea767837a5ccc8d7ca92fd1c7b929c013e634ed8c2`
MD5	`a483a1c03e3fa570b8c341d3043de964`
BLAKE2b-256	`4d128bebed1fe3e6d4bd4e7c754ad58dec1a60dabc2fd707cb400e982c0fff65`

Algorithm	Hash digest
SHA256	`e09523ec8f334b5ced13b3c505b29ae60d3b9f6aee33833bbf68db0fbda62f7b`
MD5	`6bda02f45240e83c80f4c7317c7690f5`
BLAKE2b-256	`8593e4517fc0c379d715f4103348f95797fc5bac57b214a29ec8911f171ea075`

Algorithm	Hash digest
SHA256	`146c5682a516a8e6ea159df725ddfaa727bc2569b65fe499436e871f4fc437ff`
MD5	`bf6066ea480bbd619b5320009185c73c`
BLAKE2b-256	`3213febe978ff7e384d129750979388fcfa11f74e013a73a40b22ddcb9604c00`

Algorithm	Hash digest
SHA256	`fe3ba1f54aef02d45517954a3fc6e2cb95c0a45029ad73cb6beb9523ee1510d7`
MD5	`beff90bac3d09cfde91cb12e6979d17d`
BLAKE2b-256	`df9d7e683fea02f7e2eee0ba23adb142b17982dc302df61d6c0d9f6c98ea4dc7`

Algorithm	Hash digest
SHA256	`aec7ef8db2616d43aeb1041e381b95976fe196771ce4dcaea9b1f75111ea0f41`
MD5	`9ccc3e9ab054a14f5eda15222c90d73b`
BLAKE2b-256	`ac0c884f7025cfe867e61dc2771c8fa62b56c4aaebcc91b0d903949b31cc0cbf`

ventpy 0.2.1

VentPy

What VentPy Does

Multi-Standard Support

Project Status

Installation

Quick Start

Command Line Interface

Core API

Visualization

Contributing

Engineering Disclaimer

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

Algorithm	Hash digest
SHA256	`2971c86d0280a6179ef32027ef9ab40a26a322b15effa9ccaef5338e40a1f1c4`
MD5	`691b5a88e5f4f84ebb9043f04ad27a7c`
BLAKE2b-256	`957d5651edc287d37fb81863924349bbe7f4369582a8f43d17776cfba3aceae2`

Algorithm	Hash digest
SHA256	`c18ee0d92c34f2fe1eb74152fc942d6d858370655b1a1803e431d49e470ea9a2`
MD5	`2b2807601c3a7b91d57b21cceb06dd3f`
BLAKE2b-256	`6d7ad0f4ebe67c8ed3d58d36db2ff33839bd1b4bc5e240dfa1547600a4001979`

Algorithm	Hash digest
SHA256	`db9b280053dced906ce98f9e48676dc4071e18ac591804e93df2bbc5067b3697`
MD5	`4819cc5fe1522e0975505a6899486edc`
BLAKE2b-256	`8dc7b04dfec19edd8e77cddce8a7d6af81baa20f71e194bae705fd83ca76794b`

Algorithm	Hash digest
SHA256	`fd0594ee9574a59527c9e7d727d6bcf52ac6938a8ab3f43665951c30a6ca4832`
MD5	`12b63f671cb1cc03052a2604009657df`
BLAKE2b-256	`c2e3b5caf3e8c8eac798c952f5d716fe738084eeabbc95ac745d9d626c240961`

Algorithm	Hash digest
SHA256	`e80f292029ae20f33e0ddb6d2faec1fc0e947f1f95fddbecfde690adff7e826e`
MD5	`8bf4721743b724e28d08faebdae41fe5`
BLAKE2b-256	`95f8c706f8763312335e72353aee6df119fbb604f69f333df31237a7e6a6b4ca`