Metadata-Version: 2.1
Name: supy
Version: 2026.6.5
Summary: The SUEWS model that speaks Python
Author-Email: Dr Ting Sun <ting.sun@ucl.ac.uk>
License: GPL-V3.0
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Requires-Dist: pandas
Requires-Dist: numpy>=1.22
Requires-Dist: scipy<1.15; python_version >= "3.11" and python_version < "3.13" and platform_system == "Linux"
Requires-Dist: scipy; python_version < "3.11" or python_version >= "3.13" or platform_system != "Linux"
Requires-Dist: pydantic>=2.12
Requires-Dist: pyyaml
Requires-Dist: f90nml
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: chardet
Requires-Dist: click
Requires-Dist: pyarrow<21,>=20; python_version < "3.14" and platform_system == "Linux"
Requires-Dist: pyarrow>=20; python_version < "3.14" and platform_system != "Linux"
Requires-Dist: pyarrow>=22; python_version >= "3.14"
Requires-Dist: atmosp
Requires-Dist: scikit-learn
Requires-Dist: lmfit
Requires-Dist: cdsapi
Requires-Dist: tzfpy>=1.0.0
Requires-Dist: pytz
Requires-Dist: jsonschema
Requires-Dist: rich
Requires-Dist: packaging
Provides-Extra: tmy
Requires-Dist: pvlib; extra == "tmy"
Requires-Dist: metpy; extra == "tmy"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: fprettify; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: pybtex; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex<3,>=2.6; extra == "docs"
Requires-Dist: sphinx-design>=0.7.0; python_version >= "3.11" and extra == "docs"
Requires-Dist: sphinx-last-updated-by-git; extra == "docs"
Requires-Dist: sphinx-click; extra == "docs"
Requires-Dist: sphinx-gallery>=0.16.0; extra == "docs"
Requires-Dist: docutils<0.22,>=0.21; extra == "docs"
Requires-Dist: jinja2>=3.0; extra == "docs"
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/UMEP-dev/SUEWS/master/docs/source/_static/suews-logo-stacked-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/UMEP-dev/SUEWS/master/docs/source/_static/suews-logo-stacked-light.svg">
    <img alt="SUEWS" src="https://raw.githubusercontent.com/UMEP-dev/SUEWS/master/docs/source/_static/suews-logo-stacked-light.svg" width="200">
  </picture>
</p>

<p align="center">
  <strong>Surface Urban Energy and Water Balance Scheme</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/supy/"><img alt="PyPI" src="https://img.shields.io/pypi/v/supy?color=%23F7B538"></a>
  <a href="https://docs.suews.io"><img alt="Documentation" src="https://img.shields.io/badge/docs-suews.io-blue"></a>
  <a href="https://github.com/UMEP-dev/SUEWS/blob/master/LICENSE"><img alt="License: MPL-2.0" src="https://img.shields.io/badge/license-MPL--2.0-green"></a>
  <a href="https://github.com/UMEP-dev/SUEWS/actions/workflows/build-publish_to_pypi.yml"><img alt="CI" src="https://github.com/UMEP-dev/SUEWS/actions/workflows/build-publish_to_pypi.yml/badge.svg"></a>
  <a href="https://doi.org/10.5281/zenodo.5721639"><img alt="DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.5721639.svg"></a>
</p>

---

## What is SUEWS?

SUEWS is a neighbourhood/local-scale urban land surface model that simulates the urban radiation, energy and water balances using commonly measured meteorological variables and surface cover information. It uses an evaporation-interception approach (Grimmond and Oke, 1991), similar to that used in forests, to model evaporation from urban surfaces.

The model represents seven surface types -- paved, buildings, evergreen trees/shrubs, deciduous trees/shrubs, grass, bare soil and water -- and tracks the running water balance of the canopy, soil moisture, and horizontal water movement above and below ground.

**SuPy** (SUEWS in Python) provides the modern interface, wrapping a Fortran physics engine and integrating with the scientific Python ecosystem (pandas, NumPy, matplotlib).

## Key Features

* **Energy balance**: net all-wave radiation, sensible and latent heat fluxes, storage heat flux, anthropogenic heat
* **Water balance**: soil moisture, infiltration, runoff, drainage, irrigation demand
* **Radiation schemes**: NARP, SPARTACUS-Surface (3D), BEERS (mean radiant temperature)
* **Storage heat schemes**: OHM, AnOHM, ESTM, EHC (explicit heat conduction)
* **Building energy**: STEBBS (Simple Thermal Energy Balance for Building Scheme)
* **Python API**: YAML configuration, pandas DataFrames, programmatic simulations
* **CLI tools**: `suews-run`, `suews-validate`, `suews-convert`, `suews-schema`

## Quick Start

```bash
pip install supy
```

**Run from the command line:**

```bash
suews-run /path/to/config.yml
```

**Or use the Python API:**

```python
from supy import SUEWSSimulation

sim = SUEWSSimulation.from_sample_data()
sim.run()
print(sim.output.summary())
```

Full documentation: **[docs.suews.io](https://docs.suews.io)**

## Documentation

* **[Getting Started](https://docs.suews.io/stable/workflow.html)** -- installation and first simulation
* **[Tutorials](https://docs.suews.io/stable/auto_examples/index.html)** -- hands-on guides with sample data
* **[Input/Output Reference](https://docs.suews.io/stable/inputs/index.html)** -- configuration and data formats
* **[Scientific Background](https://docs.suews.io/stable/parameterisations-and-sub-models.html)** -- physics schemes and parameterisations
* **[Community Forum](https://community.suews.io)** -- questions, discussion, and support

## Citation

If you use SUEWS in your research, please cite:

* Jarvi L, Grimmond CSB, Christen A (2011) The Surface Urban Energy and Water Balance Scheme (SUEWS): Evaluation in Los Angeles and Vancouver. *J. Hydrol.*, 411, 219-237.
* Ward HC, Kotthaus S, Jarvi L, Grimmond CSB (2016) Surface Urban Energy and Water Balance Scheme (SUEWS): Development and evaluation at two UK sites. *Urban Climate*, 18, 1-32.

See [`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.

## Contributing

We welcome contributions from people who engage with the project. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines. New contributors are encouraged to start on the [Community Forum](https://community.suews.io).

## Development

```bash
git clone https://github.com/UMEP-dev/SUEWS.git && cd SUEWS
uv venv && source .venv/bin/activate
make dev && make test
```

* **[Onboarding Guide](dev-ref/onboarding-guide.md)** -- developer workflow and best practices
* **[Building Locally](dev-ref/building-locally.md)** -- prerequisites, build commands, project structure
* **[Coding Guidelines](dev-ref/CODING_GUIDELINES.md)** -- style conventions and formatting tools

## Licence

[Mozilla Public License 2.0](LICENSE)
