pyQES

PyPI version Python versions License: GPL v3 Platforms

Version: 2.3.1 · Python: ≥ 3.10 · License: GPL-3.0-only

Python bindings for the Quick Environmental Simulation (QES) C++ suite — QES-Winds, QES-Plume, and QES-Fire.

The C++ core lives in the qes-core git submodule (fork of UtahEFD/QES-Public, branch develop_pyqes). This repository ships the pybind11 wrappers, the pyQES package, examples, and GitHub Actions for wheels / PyPI.

GPU: NVIDIA GPU with Compute Capability 7.0+ (CUDA wheel on Linux). CPU builds work without CUDA.

Table of contents

Features

  • Run QES-Winds from Python (config / XML / JSON), with optional DEM / buildings preprocessing
  • Export wind magnitude to georeferenced GeoTIFF (pywinds.to_tif)
  • Run QES-Plume on winds + turbulence NetCDF fields
  • Run coupled QES-Fire (optional smoke plume)
  • Pydantic v2 config models, XML/JSON I/O, geospatial helpers
  • Prebuilt CPU wheels for Linux, macOS (arm64), and Windows; optional Linux CUDA wheel

Compatibility
Package version 2.3.1
Python 3.10 · 3.11 · 3.12 · 3.13
OS (CPU wheels) Linux x86_64 (manylinux_2_28) · macOS arm64 (deployment target 14.0+) · Windows AMD64
GPU wheel Linux CUDA (cp312), NVIDIA CC ≥ 7.0
Build system scikit-build-core ≥ 1.0 · CMake ≥ 3.18 · C++17 · pybind11 ≥ 2.12

Runtime dependencies

Extra Packages Role
(core) pydantic≥2, numpy Config models & arrays
geo rasterio, pyproj, geopandas DEM / buildings preprocessing, GeoTIFF export
io netCDF4 NetCDF helpers

Native libraries (from-source builds)

Boost (program-options, date-time, property-tree, optional), NetCDF-C++, GDAL — install via system packages or the included vcpkg manifest (vcpkg.json).

Installation

From PyPI

pip install pyqes

# optional extras
pip install "pyqes[geo]"      # geospatial preprocessing / GeoTIFF
pip install "pyqes[io]"       # NetCDF helpers
pip install "pyqes[geo,io]"   # both

# with uv
uv add pyqes
uv add "pyqes[geo,io]"

Verify:

import pyQES
print(pyQES.__version__)  # e.g. 2.3.1

From source

git clone --recursive https://github.com/rupeelab17/pyQES.git
cd pyQES

Native deps (Boost, NetCDF-C++, GDAL) — pick one:

# macOS (Homebrew)
brew install boost netcdf-cxx gdal

# Linux (Ubuntu / Debian)
sudo apt install libboost-all-dev libnetcdf-dev libnetcdf-c++4-dev \
  libnetcdf-cxx-legacy-dev libgdal-dev netcdf-bin cmake

# Debian Trixie (e.g. python:3.13-slim-trixie): libnetcdf-cxx-legacy-dev
# is not packaged — use only libnetcdf-dev and libnetcdf-c++4-dev:
# sudo apt install libboost-all-dev libnetcdf-dev libnetcdf-c++4-dev \
#   libgdal-dev netcdf-bin cmake

# Windows (vcpkg — recommended; needs Visual Studio / MSVC)
git clone https://github.com/microsoft/vcpkg.git
.\vcpkg\bootstrap-vcpkg.bat
$env:VCPKG_ROOT = (Resolve-Path .\vcpkg).Path
# CMAKE_ARGS is picked up by scikit-build-core / uv sync
$env:CMAKE_ARGS = "-DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"

Alternatively on any OS, use the repo vcpkg.json manifest (same toolchain as the CI wheels).

# Editable install + extras ([uv](https://docs.astral.sh/uv/))
uv sync --extra geo --extra io

Always clone or pull with submodules:

git pull --recurse-submodules
# or
git submodule update --init --recursive

Build from source

Requirements beyond Python:

  • C++17 compiler
  • CMake ≥ 3.18
  • Git with submodule support
  • Native libs: Boost, NetCDF-C++, GDAL (or vcpkg via the repo manifest)
# after clone --recursive
uv sync --extra geo --extra io
# or
pip install -e ".[geo,io]"

Wheels are built with cibuildwheel (see Continuous integration).

Quick start

From a QES XML file

from pyQES import pywinds

result = pywinds.run(
    xml="examples/umep_workflow/qes/umep_larochelle.xml",
    dem="examples/umep_workflow/DEM_clip.tif",
    buildings_src="examples/umep_workflow/buildings.shp",
    buildings_mask="examples/umep_workflow/mask.shp",
    solver="cpu",
    work_dir="/tmp/qes_out",
)
print(result.winds_out)

Sensor paths referenced in the XML (e.g. sensor_umep.xml) are resolved relative to the XML directory. Set auto_preprocess=False to use the file as-is without DEM / buildings preprocessing.

From a Python config

from pyQES import pywinds
from pyQES.util.config import WindsParameters, SensorParameters, TimeSeries

params = WindsParameters()
params.simulation_parameters.dem = "path/to/DEM.tif"
params.simulation_parameters.cell_size = (2.0, 2.0, 0.5)
params.simulation_parameters.halo_x = 40.0
params.simulation_parameters.halo_y = 40.0
params.simulation_parameters.domain_rotation = 0.0  # must be 0

sensor = SensorParameters(
    time_series=[TimeSeries(speed=3.0, direction=270.0, height=10.0, site_z0=0.24)]
)
result = pywinds.run(config=params, sensor=sensor, solver="cpu", work_dir="/tmp/qes_out")
print(result.winds_out)

# optional GeoTIFF of |V| at 1.5 m AGL (needs pyqes[geo,io])
tif = pywinds.to_tif(z=1.5)
print(tif)

pywinds.run accepts exactly one of config, xml, or json (or none, with keyword overrides). Solvers: "cpu" / "gpu" (or the QES integer code).

Package layout

Module Role
pyQES.pywinds QES-Winds — run(...), to_tif(...)
pyQES.pyplume QES-Plume — run(xml=..., winds_file=..., turb_file=...)
pyQES.pyfire Coupled QES-Fire — run(...) (+ optional plume_xml)
pyQES.util Pydantic config, XML/JSON I/O, paths, geo helpers, NetCDF→GeoTIFF
pyQES._winds / _plume / _fire / _util Compiled pybind11 extensions

Config models live in pyQES.util.config: WindsParameters, SimulationParameters, SensorParameters, TimeSeries, etc.

Examples

Sample La Rochelle / UMEP inputs: examples/umep_workflow/ (DEM, buildings, mask, QES XML).

uv run python examples/run_winds_demo.py
uv run python examples/run_winds_demo.py --speed 5 --direction 180
uv run python examples/umep_workflow/run_qeswinds.py
uv run python examples/umep_workflow/run_qeswinds_args.py --speed 5 --direction 180

Development

uv sync --extra geo --extra io

# lint / typecheck
uv run ruff check pyQES tests examples
uv run mypy

# fast unit tests (no full solver run)
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run pytest tests -m "not slow"

# end-to-end winds run (compiled extension + example data)
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run pytest tests -m slow

Dev tools (via [dependency-groups] dev): pytest, pytest-cov, ruff, mypy, plus the geo / io extras.

Continuous integration

Workflow Role
ci.yml Ruff, mypy, pure-Python pytest
wheels.yml CPU wheels — Linux / macOS / Windows · cp310–cp313 · sdist
cuda-build.yml Linux CUDA wheel (cp312)
publish.yml Publish to PyPI on v* tags

Updating the QES core

git submodule update --remote qes-core
git add qes-core
git commit -m "Bump qes-core"

Links
Homepage / source https://github.com/rupeelab17/pyQES
PyPI https://pypi.org/project/pyqes/
QES documentation https://qes-documentation.readthedocs.io/en/latest
QES core (submodule) https://github.com/rupeelab17/QES-Public
Upstream QES https://github.com/UtahEFD/QES-Public

License

GPL-3.0-only — see LICENSE.

QES core: see qes-core/LICENSE.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.5.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bbrangeo from gravatar.com bbrangeo

Credits

Author: QES / TIPEE

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU General Public License v3 (GPLv3) (GPL-3.0-only)

Requires

Python >=3.10

Provides Extra

geo io

Tags

QES CFD wind dispersion fire urban microclimate

Classifiers

Report project as malware

Download files

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

Source Distribution

pyqes-2.3.1.tar.gz (453.7 kB view details)

Uploaded Source

Built Distributions

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

pyqes-2.3.1-cp313-cp313-win_amd64.whl (20.7 MB view details)

Uploaded CPython 3.13Windows x86-64

pyqes-2.3.1-cp313-cp313-manylinux_2_28_x86_64.whl (77.8 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64

pyqes-2.3.1-cp313-cp313-macosx_14_0_arm64.whl (60.5 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

pyqes-2.3.1-cp312-cp312-win_amd64.whl (20.7 MB view details)

Uploaded CPython 3.12Windows x86-64

pyqes-2.3.1-cp312-cp312-manylinux_2_28_x86_64.whl (77.8 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

pyqes-2.3.1-cp312-cp312-macosx_14_0_arm64.whl (60.5 MB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

pyqes-2.3.1-cp311-cp311-win_amd64.whl (20.7 MB view details)

Uploaded CPython 3.11Windows x86-64

pyqes-2.3.1-cp311-cp311-manylinux_2_28_x86_64.whl (77.8 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

pyqes-2.3.1-cp311-cp311-macosx_14_0_arm64.whl (60.5 MB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

pyqes-2.3.1-cp310-cp310-win_amd64.whl (20.7 MB view details)

Uploaded CPython 3.10Windows x86-64

pyqes-2.3.1-cp310-cp310-manylinux_2_28_x86_64.whl (77.8 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

pyqes-2.3.1-cp310-cp310-macosx_14_0_arm64.whl (60.5 MB view details)

Uploaded CPython 3.10macOS 14.0+ ARM64

File details

Details for the file pyqes-2.3.1.tar.gz.

File metadata

  • Download URL: pyqes-2.3.1.tar.gz
  • Upload date:
  • Size: 453.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqes-2.3.1.tar.gz
Algorithm Hash digest
SHA256 5a4b7a12809a19d7af2113a8c1f73473cfacad3c3a744eae6a76350b72807bdd
MD5 01b1bc9cd7e971b5e1c10cc4c300e503
BLAKE2b-256 acf15bfecc9da898de3dc215ae816263ff8b22fec665acb12c2f5dc8242fadda

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1.tar.gz:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.3.1-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 20.7 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqes-2.3.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 2ba9a3599d4bf44f31eb277568888e709c1c4f9f228a8141495eb7ab93816446
MD5 c6bb1c7d2ca3ffb3ae451d6890055a45
BLAKE2b-256 46fa4dc18daa34a0942ca00b11237eea697cf00bd799d45fd2a8b8812eaffd3d

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp313-cp313-win_amd64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 15593ef21cbfd9bcb0f35dd4314e5c6c8fca44988ab4b4cb1d1fb8a2bd1bb87e
MD5 666a3c47f444fed07531c9e1fe63cb67
BLAKE2b-256 539c12c6c47f1cf1b6914bcfbdbd364178190a4f961b669f2b3e3ddfdd8cd9d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp313-cp313-manylinux_2_28_x86_64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 eac00826fdc8100c11835840a89c7ba7a8b5da2a1fc857fab312264161a34d91
MD5 c35252f8fe075dbc83307ac97d090949
BLAKE2b-256 26bfb012fe46bdabbaa1fd4326c687da07a3cbd6a50d18e55e94982c6ab398a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp313-cp313-macosx_14_0_arm64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.3.1-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 20.7 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqes-2.3.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b3dd4d14036b8a9f8e46fc13ce639337e6c95c1c9503a0f63f64c5e58a303161
MD5 5312772cd81a90cac36d663ad5a4fbcb
BLAKE2b-256 8d5d44916afc82b20719ff6ed841b9c556bff4227311d1acf49c02fa989112d3

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp312-cp312-win_amd64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5a5b981d5e53fe2464a25497e73500214425888e841e389da5e475fc9ba2222f
MD5 00b6c55506438cd762558c7efa29f40e
BLAKE2b-256 a729e1533df0bcaf2b28f74fae93206b3b4b56d799856a131e9b20865947cb7f

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp312-cp312-manylinux_2_28_x86_64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 82c3559c40012ac3b845168d52b5642f509a7c82c895ba96d173879771219859
MD5 f295670f6e57f0d856c4684a8b19bf3a
BLAKE2b-256 7fa4e891f2351c542d082fcfd05fc1bf19c57a47ac27703dfcff1056ff6aa81b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp312-cp312-macosx_14_0_arm64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.3.1-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 20.7 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqes-2.3.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 ecfb71ebef3a053913ed7d4862c30836198a19915790ed37a09f1e9498a31a9d
MD5 23189c201a895531b7186133b17e9b93
BLAKE2b-256 e23cbbc7db845f333d55d74e152bdd849334e61b990123deb5e948d820853c0e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp311-cp311-win_amd64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e3fca34ddd7e4ededc6a474cc400fc0038600d594a38e2dec67965101aef0d82
MD5 e9a999fc17b39b00bd5cdcc1dcd2cea3
BLAKE2b-256 78284aecc4e99ad579a271a9e501ad5ebdb49f128a487b613d01403ec5fc82df

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp311-cp311-manylinux_2_28_x86_64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 740c141f161b9aabaa7f311f5032171c8dbf65d6508c15150ec6c0a4652147af
MD5 54852fd251ecbfd212b1f6d6732beecb
BLAKE2b-256 d5ef1b05ee829309e0020f1c85ca68a8416352bb193a673d06536751297f8a1e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp311-cp311-macosx_14_0_arm64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.3.1-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 20.7 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for pyqes-2.3.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 eca1dfa42342ae0ceff63e8467987414649638ba1f27565b5c17a3cc1b4f24dd
MD5 68002259a1b2c847923882db15230d40
BLAKE2b-256 61dcfc695cba76f1389176ede7297745f5413ceca96be89ece87f3d8a81c9285

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp310-cp310-win_amd64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2952ff750d8d04d117ea0d782a0a19ce6bb2155bb02414c72310cbfaac18359f
MD5 dc4a977ac171866a2492afa298fb6dfc
BLAKE2b-256 741d04b023a06d3cc147fab42d2ecad00d8aa71dbe15765b42c3fc0c67d008e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp310-cp310-manylinux_2_28_x86_64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyqes-2.3.1-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.3.1-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a4b5119ee0952434426d9076cb12f798c4462e2ec1b8cb66b3f2d0b268b17a08
MD5 bdb6b26930fcb42e57556aca67046349
BLAKE2b-256 1e9c628e9c0efa17d1fceb663f72a1f1b7d931452b4479bb7c8a4537cfb0a7c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.3.1-cp310-cp310-macosx_14_0_arm64.whl:

Publisher: publish.yml on rupeelab17/pyQES

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page