SUEWS: Surface Urban Energy and Water Balance Scheme

SUEWS: Surface Urban Energy and Water Balance Scheme#

What is SUEWS?#

Surface Urban Energy and Water Balance Scheme (SUEWS) [Järvi et al., 2011, Ward et al., 2016] is a neighbourhood/local-scale urban land surface model delivered through SuPy, a comprehensive Python interface that integrates seamlessly with the scientific Python ecosystem.

SUEWS simulates the urban radiation, energy and water balances using only commonly measured meteorological variables and information about the surface cover. The model utilises an evaporation-interception approach [Grimmond and Oke, 1991], similar to that used in forests, to model evaporation from urban surfaces.

SuPy (SUEWS in Python) [Sun and Grimmond, 2019] provides the modern interface for SUEWS with powerful data analysis capabilities, interactive configuration tools, and seamless integration with pandas, matplotlib, and the broader scientific Python stack.

The model uses seven surface types: paved, buildings, evergreen trees/shrubs, deciduous trees/shrubs, grass, bare soil and water. The surface state for each surface type at each time step is calculated from the running water balance of the canopy where the evaporation is calculated from the Penman-Monteith equation. The soil moisture below each surface type (excluding water) is taken into account. Horizontal movement of water above and below ground level is allowed.

Fig. 2 The seven surface types considered in SUEWS#

How to get SUEWS?#

Modern Python Interface (Recommended):

# Install SuPy (includes SUEWS)
pip install supy

Alternative Installation:

For legacy table-based workflows, please follow the guidance in Installation to get SUEWS.

How to use SUEWS?#

Quick Start (Recommended):

Get started immediately with the Getting Started guide, which provides an interactive tutorial using sample data and modern Python tools.

For new users:

Install SuPy: pip install supy
Follow tutorials: Start with SUEWS Tutorials for hands-on learning
Configure your site: Use the Getting Started guide and YAML tools
Explore advanced features: Multi-site studies, climate impacts, model coupling

For existing users:

Migration guide: Transition from table-based inputs to modern YAML configuration
Version changes: See Version 2026.1.28 (released on 28 January 2026) for updates in this version
Legacy support: The SUEWS Format Converter helps convert existing input files

Scientific Background:

Before performing SUEWS simulations, users should understand the physical principles and review input requirements for their specific application.

How to get help in using SUEWS?#

Please let us know in the SUEWS Community. The developers and other users are willing to help you.

How has SUEWS been used?#

The scientific details and application examples of SUEWS can be found in:

SUEWS-related Publications - Core SUEWS publications from the development team describing model physics and validation
Community Publications - Publications from the SUEWS user community showcasing diverse applications

How to cite SUEWS?#

When using SUEWS in your research, please cite it appropriately:

For the software/model:

Use the CITATION.cff file in our GitHub repository for software citations
Visit our Zenodo repository for DOI-based citations with version tracking

For scientific background:

See SUEWS-related Publications for core SUEWS papers describing the model’s development and validation
Check Community Publications to see how others have cited and used SUEWS in their work

How to support SUEWS?#

Cite SUEWS appropriately in your work.
Contribute to the development.
Report issues via the GitHub page.
Provide suggestions and feedback.