Skip to main content

pyQES

PyPI version Python versions License: GPL v3 Platforms

Version: 2.4.0 · 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)
  • Export u/v arrow seeds as GeoJSON for MapLibre (pywinds.to_streamlines)
  • Export RK4 streamlines as GeoJSON LineStrings for MapLibre (pywinds.to_flowlines)
  • 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.4.0
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 & GeoJSON export
io netCDF4 NetCDF helpers (incl. windsOut.nc → GeoTIFF / GeoJSON)

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 / GeoJSON
pip install "pyqes[io]"       # NetCDF helpers
pip install "pyqes[geo,io]"   # both (needed for to_tif / to_streamlines / to_flowlines)
# with uv
uv add pyqes
uv add "pyqes[geo,io]"

Verify:

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

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
params.buildings_params.shp_file = "path/to/buildings.shp"

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)

# optional GeoJSON arrows (bearing + speed) for MapLibre icon-rotate
arrows = pywinds.to_streamlines(z=1.5, stride=4)
print(arrows)

# optional RK4 streamlines (LineStrings) for MapLibre symbol-placement:line
flowlines = pywinds.to_flowlines(z=1.5, seed_stride=8)
print(flowlines)

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(...), to_streamlines(...), to_flowlines(...)
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 / GeoJSON
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

From a WGS84 bbox (pymdurs / IGN)

Script: examples/pymdurs_workflow/run_from_bbox.py.

Downloads DEM, buildings and mask via pymdurs (France + network), then runs QES-Winds. Default cell size is 2.5 2.5 1 (finer grids on large bboxes may segfault). Optional flags: --to-tif (|V| GeoTIFF), --to-streamlines (arrow Points), --to-flowlines (RK4 LineStrings).

uv sync --extra geo --extra io
uv pip install pymdurs
uv run python examples/pymdurs_workflow/run_from_bbox.py --to-tif
uv run python examples/pymdurs_workflow/run_from_bbox.py \
  --bbox=-1.152704,46.181627,-1.139893,46.18699 --to-tif --to-streamlines --to-flowlines
# reuse previous IGN downloads in examples/pymdurs_workflow/output/
uv run python examples/pymdurs_workflow/run_from_bbox.py --skip-fetch --to-tif --to-flowlines

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.

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.4.0.tar.gz (459.8 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.4.0-cp313-cp313-win_amd64.whl (20.7 MB view details)

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64

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

Uploaded CPython 3.13macOS 14.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64

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

Uploaded CPython 3.12macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64

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

Uploaded CPython 3.11macOS 14.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

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

Uploaded CPython 3.10manylinux: glibc 2.28+ x86-64

pyqes-2.4.0-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.4.0.tar.gz.

File metadata

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

File hashes

Hashes for pyqes-2.4.0.tar.gz
Algorithm Hash digest
SHA256 12b1b29d9976cc3e0491d98d73c0833e53dc1fba0304d5f401639e0078e5b6d6
MD5 83e5eba626150147e04353ebe8ba1b72
BLAKE2b-256 b4f4fa03560703a1ab7af144ed4c65732b1708e574bca0b649e2f14c85626cc6

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0.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.4.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.4.0-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.4.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 18fd6fab862bf96dad38f40d87dbf09d38607bb8225a72478b7d9c57921032de
MD5 c44507928f479191f328b2813dc865f0
BLAKE2b-256 b7fdda5037d9a550e629f76ec6b57ad0dae376eca320677746fe928efac80f8f

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp313-cp313-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp313-cp313-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 10226b046ff29adb04589d855cf2c81ce6bbe977f79f8a179e78ddd61397c466
MD5 0f75250f6a0aa34b3fcd9fd9d2f41cc1
BLAKE2b-256 5e711ca6696e04aeab274844b915c00f67d9164f5fe2b12daf35322e7494cd56

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 57c37c0107ab998b522ead3c5a2f2cb5f89a49a417276440a15b03f068f6fe7d
MD5 0cac186709e63b2861c73235b12d0caf
BLAKE2b-256 8729504334a550d45481bdb06258651d4b024b021a2ddc4316107d030886c705

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.4.0-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.4.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 a37eecc26064c3aff714c255ce1ad01f417d1e3b85585ca8c3317a2488316c60
MD5 02472c6982176463da60c23e24d11d9c
BLAKE2b-256 3bd647190767311aa3692e1b77bc279bf57c5605f5bf17793b8a4c65d5de58e7

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp312-cp312-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp312-cp312-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8b9b342175489b9e4aeca290590fc786ff252cb14c80ec29021ef6c31ab4ffd9
MD5 04360fb4fc27de950f060118979aae86
BLAKE2b-256 442ffedd3112b4bb7d0fbdbaf0301001a70546e31b9a447c5558067db7e6bddc

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 77d28491f4ec6114b52277fbfc0b74a404bb035a26d65fdbc479fc951180f1fe
MD5 38f7ec1dc173772e73a6a068227c64a7
BLAKE2b-256 883ace6b49ca5aca23487601fa4e8cb9dd257fd65769fac78c40378ec3fc018b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.4.0-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.4.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 aae1622cb331591805174214d23d31b9b775b2a3eccb233309b845f55d3b1a20
MD5 7627b7c26aa25d0630172704b808feb4
BLAKE2b-256 4dff4ded934c5a17a1ee776e8c6f8fcbdf635390409e227a4655464c510ee63c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp311-cp311-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp311-cp311-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bc2d0d7c4eca5f77d25b75fddb61302b217b4d3f85e0dbd0fa1f4f5be97a233c
MD5 dfec0890804d97aae00e2f76e5a222a3
BLAKE2b-256 dc2e9c81aca2351329754c595e82c15b47deeafdb2f84c27b076f3f02c58e6d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a9ada5afa5e867fdb1653a61b3f41158f011e7489fe6346478dc3e7c9e2371a8
MD5 7ffd397beea685823b58ea96d3001967
BLAKE2b-256 e5b64bdea389ed403aff510f6be990a507294725cee9c16cbdf3299d41c21f26

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: pyqes-2.4.0-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.4.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 3cdc50c1131d137119edfbb9efac3608cb98b5dcd3c3ba9ddcc85ca5ea9ba6fe
MD5 93725c450b25128dd0201b1cb0aa8e17
BLAKE2b-256 358033eb1da7afff96b6ac7a8e6d6f2e3277207e2f1e0efd3b9cef01794b4c04

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp310-cp310-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp310-cp310-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6008c338d47a971f0580e7eb480dadfe3308948add96208e127e2b8c13cd39fe
MD5 94981e0a305741c9e2ffc4a2e1b50c7a
BLAKE2b-256 9056a787768fb9f1e3ddd279ea420633b8a1babdd8dc8246c0a65f239076e055

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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.4.0-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for pyqes-2.4.0-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 16f1e17b4a7fee785f8a4efdf19004584c48832d04f48fcc9b6f492dd8dd0c80
MD5 ae71cd49fcfc7ffb15cb1c58c31dc739
BLAKE2b-256 72e2dce71a963ffc3f23923b79a9b2edbd62d9f5a4ad7aa68b8eb5350354bac6

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyqes-2.4.0-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