SUEWS Python Tutorials

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.

SUEWS Python Tutorials#

These comprehensive tutorials guide you through SUEWS urban climate modelling using the modern Python interface. Each tutorial is a self-contained Jupyter notebook that combines executable code with detailed explanations and scientific context.

Tutorial Sequence#

Start here for your SUEWS learning journey:

Recommended Learning Path:

  1. [Quick Start](quick-start.ipynb) - Your first SUEWS simulation using built-in sample data

  2. [Setup Your Own Site](setup-own-site.ipynb) - Configure SUEWS for your research location

  3. [Impact Studies](impact-studies.ipynb) - Climate change and scenario analysis

Advanced Topics:

Prerequisites#

# Install SuPy (includes SUEWS)
pip install supy

Required Python packages (automatically installed with SuPy): - pandas: Data analysis and manipulation - numpy: Numerical computing - matplotlib: Plotting and visualization - xarray: Multi-dimensional data analysis

Recommended setup: - Jupyter notebooks: Interactive development environment - Python 3.8+: Modern Python with full SuPy compatibility

Configuration and Data Management#

Modern YAML Configuration

SUEWS uses YAML configuration files for type-safe, hierarchical parameter management:

# Example SUEWS configuration
model:
  control:
    tstep: 300
    start_date: "2015-01-01"
    end_date: "2015-12-31"

sites:
  - name: MyUrbanSite
    properties:
      lat: {value: 51.51}
      lng: {value: -0.12}
      land_cover:
        Paved: {value: 0.43}
        Buildings: {value: 0.38}

Configuration Tools: - Sample configurations: Available in tutorials directory - Migration tool: Convert legacy inputs with suews-convert to-yaml - Command-line wizard: A configuration wizard tool is in development

Data Integration: - Built-in sample data: SUEWSSimulation.from_sample_data() for immediate use - pandas DataFrames: Native integration for analysis and visualization - Multiple formats: Support for CSV, netCDF, and scientific data formats

Advanced Features#

Multi-Site Analysis: - Parallel processing for multiple urban sites - Comparative studies across different cities - Scenario analysis and sensitivity testing

Model Coupling: - Integration with WRF atmospheric model - Building energy model connections - Custom external model interfaces

Research Applications: - Urban heat island studies - Climate change impact assessment - Policy scenario analysis - Energy and water balance research

Getting Help#

Community Resources: - GitHub Repository: Issues and discussions - Mailing List: SUEWS community forum - Documentation: Complete API reference

Scientific Background: - Physics: Parameterisations and sub-models - Publications: Recent applications - Validation: Benchmark studies

Python Background for Urban Climate Science#

New to Python? These resources help you get started with scientific computing for urban climate research:

Essential Python Skills: - Python for Scientific Computing: Comprehensive scientific Python tutorial - Research Software Engineering: Best practices for scientific programming

Core Libraries Used in SUEWS:

pandas - Time series and data analysis (essential for SUEWS):
Jupyter Notebooks - Interactive development environment:
matplotlib - Scientific plotting and visualization:

Climate Data Analysis: - Pangeo Tutorial: Big data oceanography and climatology - Climate Data Analysis: Working with climate datasets - xarray Tutorial: Multi-dimensional scientific data

Installation and Environment Management:

# Install Jupyter for interactive development
pip install jupyter

# Launch Jupyter notebook server
jupyter notebook

# Or use JupyterLab (recommended)
pip install jupyterlab
jupyter lab

Quick Start for Climate Scientists:

If you’re familiar with MATLAB, R, or other scientific computing environments, focus on these pandas concepts that are heavily used in SUEWS:

  1. DataFrame indexing: .loc[] and .iloc[] for data selection

  2. Time series resampling: .resample() for temporal aggregation

  3. GroupBy operations: .groupby() for statistical analysis

  4. MultiIndex handling: Working with hierarchical data structures

  5. Plotting integration: .plot() method for quick visualizations

Ready to Start?

Jump directly into the [Quick Start Tutorial](quick-start.ipynb) - it includes explanations of each Python concept as you encounter it in real SUEWS applications.

Contents