pythermalcomfort

pythermalcomfort is a Python toolkit for computing thermal comfort indices, heat/cold stress metrics, and thermophysiological responses. Its implementations adhere to international standards and peer-reviewed research, offering researchers, engineers, and building scientists reliable, standards-compliant calculations without the burden of implementing them manually.

Important

When pythermalcomfort informs published work, please cite it as:

Tartarini, F., Schiavon, S., 2020.
pythermalcomfort: A Python package for thermal comfort research.
SoftwareX 12, 100578.
https://doi.org/10.1016/j.softx.2020.100578

Key Features

• Thermal Comfort Models – PMV/PPD, adaptive comfort assessments, SET, and more bundled into a single API surface.
• Heat & Cold Stress Indices – UTCI, Heat Index, Wind Chill, Humidex, and other commonly-referenced metrics.
• Thermophysiological Modeling – two-node (Gagge) and multinode (JOS-3) models for estimating core/skin temperatures and skin wettedness.
• Standards Compliance – Calculations based on ASHRAE 55, ISO 7730, EN 16798, and supporting references.
• Vectorized Inputs – Accepts scalars, lists, or NumPy arrays; most functions broadcast across input arrays automatically.
• Pythonic API – Simple, documented entry points that plug into analysis workflows and pipelines.
• Rich Documentation – Tutorials, examples, and reference guides for each supported model and index.
• Active Development – Frequent releases, new features, and responsive issue resolution.
• Open Source – MIT licensed and developed transparently on GitHub.

Why Choose pythermalcomfort?

• Precision – Accurate evaluations of comfort and stress that engineers can trust.
• Efficiency – Eliminates repetitive code so teams can focus on insights, not implementation details.
• Versatility – Useful in building science, HVAC design, biometeorology, sports science, and thermal physiology.
• Evidence-Based Decisions – Supports data-driven HVAC sizing, occupant comfort strategies, and performance benchmarking.

Installation

Install from PyPI:

pip install pythermalcomfort

For alternative installation instructions, including development builds and optional dependencies, see the official docs.

Requirements

• Python 3.10+
• NumPy, SciPy, Numba, setuptools (installed automatically)
• Optional: pandas, Matplotlib, or other plotting libraries for examples and visualizations

Quick Start

A few lines are all you need to get started:

from pythermalcomfort.models import pmv_ppd_iso, utci

# Calculate PMV and PPD using ISO 7730 standard
result = pmv_ppd_iso(
    tdb=25,   # dry-bulb temperature in °C
    tr=25,    # mean radiant temperature in °C
    vr=0.1,   # relative air speed in m/s
    rh=50,    # relative humidity in %
    met=1.4,  # metabolic rate in met
    clo=0.5,  # clothing insulation in clo
    model="7730-2005",
)
print(f"PMV: {result.pmv}, PPD: {result.ppd}")

# Calculate UTCI for heat stress assessment
result = utci(tdb=30, tr=30, v=0.5, rh=50)
print(result.utci)

# Most functions also accept arrays for bulk calculations
result = utci(tdb=[28, 30, 35], tr=[28, 30, 35], v=0.5, rh=50)
print(result.utci)

For a full list of models and indices, see the API reference.

Support pythermalcomfort

Maintaining an open-source scientific package takes time. You can help by:

• Sponsoring on GitHub
• Submitting code, docs, or tests via a pull request
• Reporting reproducible bugs or feature requests in the issue tracker
• Assisting with testing, translations, or PR reviews
• Starring or sharing the project to raise awareness

Contributions

We welcome all contributions. Please read the contributing guide before you start.

Quick checklist

• Open an issue when planning large changes to align on scope.
• Fork the repo and create a feature branch.
• Add or update tests for new behavior.
• Run linters/formatters and fix the reported issues.
• Update docs or the changelog when the public API changes.
• Submit clear, focused PRs with related issues linked.

Common commands

# clone your fork and add upstream remote
git clone git@github.com:your-username/pythermalcomfort.git
cd pythermalcomfort
git remote add upstream git@github.com:pythermalcomfort/pythermalcomfort.git
git fetch upstream

# create a branch and work on it
git checkout -b Feature/awesome-feature
tox  # run the full matrix (slow)
tox -e py312  # run a single env
pytest -k test_name_fragment

# fix linting/formatting
ruff check --fix
ruff format
docformatter --in-place --wrap-summaries 88 --wrap-descriptions 88 pythermalcomfort/*.py

# commit and push
git add .
git commit -m "feat: short description of change"
git push origin Feature/awesome-feature

Release process

Releases are tag-driven and published via GitHub Actions Trusted Publishing (OIDC — no PYPI_API_TOKEN or TEST_PYPI_API_TOKEN secret is required).

The standard cycle is:

1. Develop and test a release candidate on development → TestPyPI.
2. Merge development → master via pull request.
3. Finalize the version on master → PyPI.

Step 1 — pre-release on development (TestPyPI)

git checkout development
git pull --ff-only
git fetch --tags --prune

# Start the RC cycle for the next patch release (e.g. 3.9.8 → 3.9.9rc1):
bump-my-version bump patch

# Push the bump commit and tag — this triggers tests + TestPyPI deploy:
git push
git push --tags

If the RC needs additional fixes, make the commits then create another RC:

bump-my-version bump pre_n    # e.g. 3.9.9rc1 → 3.9.9rc2
git push
git push --tags

Step 2 — open and merge a pull request from development to master

CI runs the full test suite on the PR. Once it passes, merge via GitHub.

Step 3 — finalize on master (PyPI)

git checkout master
git pull --ff-only
git fetch --tags --prune

# Strip the rc suffix to produce the stable version.
# Replace X.Y.Z with the target version (e.g. 3.9.9):
bump-my-version bump --new-version X.Y.Z patch

# Push the bump commit and tag — this triggers tests + PyPI deploy:
git push
git push --tags

Rules:

• All RC tags (vX.Y.ZrcN) must be pushed from development.
• All stable tags (vX.Y.Z) must be pushed from master after merging.
• Tag format: vX.Y.Z for stable, vX.Y.ZrcN for pre-release.
• Do not push a stable tag before the corresponding development → master PR has been merged; the CI deploy job will reject it.

Getting Help

• Open an issue on GitHub with a minimal reproduction in the issue tracker.
• Ask questions in PR comments for implementation guidance.
• Review the contribution guidelines for testing, documentation, and changelog expectations.
• Consult the API reference and examples at https://pythermalcomfort.readthedocs.io/en/latest/

Changelog

A full list of changes per release is available in the CHANGELOG.

License

pythermalcomfort is released under the MIT License.

Stats

Documentation
License
Downloads
Tests
Package