Tip

1. Need help? Please let us know in the UMEP Community.

2. Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).

3. Please cite SUEWS with proper information from our Zenodo page.

3. SUEWS Tutorials

SUEWS is an urban climate model delivered through SuPy, a comprehensive Python interface. These tutorials provide a complete learning path from your first simulation to advanced urban climate research.

3.1. Python/SuPy Tutorials (Recommended)

The modern SUEWS interface uses Python and provides the most capable and user-friendly experience:

• 3.1.1. SUEWS Quick Start Tutorial
• 3.1.2. Set up SuPy for Your Own Site
• 3.1.3. Impact Studies Using SuPy
• 3.1.4. SUEWSSimulation Tutorial

Installation:

# Install SuPy (includes SUEWS)
pip install supy

Key Features: - Modern YAML configuration: Type-safe, hierarchical parameter organisation - pandas integration: Powerful data analysis and visualisation - Interactive notebooks: Hands-on learning with immediate results - Parallel processing: Efficient multi-site and scenario analysis - External model coupling: Integration with other atmospheric models (see Integration and Complementary Tools)

Scientific Foundation: All SuPy results maintain the scientific rigour of SUEWS (see SUEWS publications and Parameterisations and sub-models within SUEWS), enhanced by the Python scientific ecosystem.

3.2. Advanced Examples

For experienced users working with custom parameterisations and model modifications:

Data Preparation: - Preparing input forcing data - How to format meteorological data for SUEWS simulations from weather stations, reanalysis datasets, and custom sources

Physics Customisation: - Adding custom OHM coefficients - How to derive and implement surface-specific storage heat flux coefficients - Custom surface properties - Modifying land cover parameters for specialised urban surfaces - Multi-site parameter sensitivity - Systematic parameter variation across multiple locations

Model Development: - Fortran module development - Adding new physics modules to the SUEWS core - Output variable customisation - Creating custom diagnostic variables and output groups

3.3. Additional Data Analysis Tools

• Data structures: Key IO Data Structures in SuPy - Understanding SuPy’s pandas-based data organisation

• API reference: Python API Reference - Complete function documentation

3.4. Legacy UMEP/QGIS Tutorials

For users working with the legacy table-based SUEWS interface through UMEP/QGIS:

Note

These tutorials use the legacy table-based approach. New users should use the Python/SuPy tutorials above.

Topic	Application	Interface
IntroductionToSuews	Energy, water and radiation fluxes for one location	UMEP/QGIS
SUEWSAdvanced	Energy, water and radiation fluxes for one location	UMEP/QGIS
SUEWSSpatial	Energy, water and radiation fluxes for spatial grid	UMEP/QGIS
SUEWSWUDAPT	Making use of WUDAPT local climate zones	UMEP/QGIS

3.5. Migration from Legacy SUEWS

If you’re transitioning from table-based SUEWS to modern SuPy:

1. Use the conversion tool: suews-convert -f 2024a -t 2025a -i legacy_input_dir/ -o config.yml

2. Follow the migration guide: Transitioning to YAML-based Configuration

3. Start with sample data: The SUEWS Quick Start Tutorial tutorial shows modern approaches