supy 2026.1.28

The SUEWS model that speaks Python

SUEWS - Surface Urban Energy and Water Balance Scheme

This is the SUEWS urban climate model repository.

Installation

pip install supy

Documentation

See the full documentation at: https://suews.readthedocs.io

Quick Start

For users who want to run SUEWS simulations:

1. Install from PyPI (simplest):

   pip install supy
   

2. Run a simulation:

   suews-run /path/to/config.yml
   

For developers, see the Developer Note section below.

Developer Note

Development Environment

Claude Code Integration

SUEWS includes Claude Code configuration in the .claude/ directory with development skills for environment setup, code linting, build verification, PR review, and release management.

Install Skills via Marketplace (recommended for new contributors):

# In Claude Code, add the SUEWS skills marketplace
/plugin marketplace add UMEP-dev/SUEWS

# Then install the skills
/plugin install suews-dev@UMEP-dev/SUEWS

This provides access to:

• /setup-dev - Set up development environment (macOS, Linux, Windows)
• /lint-code - Check code style against SUEWS conventions
• /verify-build - Verify build configuration consistency
• /audit-pr - Review pull requests comprehensively
• /examine-issue - Analyse GitHub issues
• /log-changes - Update CHANGELOG with recent commits
• /prep-release - Prepare releases with pre-flight checks
• /sync-docs - Check doc-code consistency

Local Configuration (for contributors with cloned repo):

• Setup Guide: See .claude/README.md for workspace structure
• Skills Reference: See .claude/skills/ for detailed workflows

CLAUDE.md Protection System

This repository includes automatic protection for the CLAUDE.md configuration file to prevent accidental content loss:

• Automatic Features (no setup required):

  • GitHub Actions validation on all PRs/pushes affecting CLAUDE.md
  • Content reduction detection (alerts if >20% content removed)
  • Automatic snapshots on validation failures

• Local Protection (one-time setup):

  # Run once after cloning or pulling this feature
  bash .claude/scripts/setup-claude-protection.sh
  

  This enables:

  • Git pre-commit validation
  • Local backup system
  • Manual validation: python3 .claude/scripts/validate-claude-md.py

Local Development

Follow these steps to set up local development:

Prerequisites

Essential Tools:

• Fortran Compiler: gfortran (≥ 9.3.0) or Intel ifort
  • macOS: brew install gcc
  • Ubuntu/Debian: sudo apt-get install gfortran
  • Windows: Use WSL or MinGW-w64
• Version Control: git
• Package Manager: mamba (faster than conda)

  # Install mambaforge (if not already installed)
  curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
  bash Miniforge3-$(uname)-$(uname -m).sh
  

Recommended Tools:

• VS Code with extensions:
  • Modern Fortran
  • Python
  • GitHub Copilot (free for academic use)
• WSL (Windows users)

Setup Steps

1. Clone the repository:

   git clone https://github.com/UMEP-dev/SUEWS.git
   cd SUEWS
   

2. Initialise submodules (required for SPARTACUS dependency):

   git submodule init
   git submodule update
   

   Note: If permission denied, configure SSH for GitHub

3. Create development environment:

   mamba env create -f env.yml
   

   This creates suews-dev environment with all required packages.

4. Activate environment:

   mamba activate suews-dev
   

5. Build SUEWS:

   make dev       # Install in editable mode
   make test      # Run tests (optional)
   

   Run make to see all available commands and quick start workflows.

6. Verify installation:

   pip show supy
   suews-run --help
   

Development Workflow

• Build commands:

  make dev          # Install in editable mode (self-healing, works after clean)
  make test         # Run test suite only
  make clean        # Clean build artifacts (smart - keeps .venv if active)
  make docs         # Build documentation
  make livehtml     # Live documentation preview
  make              # Show help summary (default target)
  

• Common workflows:

  make clean && make dev    # Fresh start (most common for troubleshooting)
  git pull && make dev      # Update code and rebuild
  make dev && make test     # Build and test changes
  

• Environment management:

  make help         # Show all available commands
  make deactivate   # Show deactivation command
  

• Common issues:

  • Build conflicts: Run make clean && make dev (most reliable)
  • Import errors: Ensure you're in the suews-dev environment
  • Permission errors on Windows: Right-click project folder → Properties → Security → Edit → Everyone → Allow

Project Structure

SUEWS/
├── src/
│   ├── suews/          # Fortran physics engine
│   ├── supy/           # Python interface
│   └── supy_driver/    # F2Py wrapper
├── test/               # Test suite
├── docs/               # Documentation source
├── env.yml             # Development environment
└── Makefile            # Build commands

Contributing

Code Style and Formatting

SUEWS maintains consistent code style through automated formatting:

• Coding Standards: See CODING_GUIDELINES.md for detailed standards
• Automated Formatting: The master branch is automatically formatted after merge
• Zero Friction: Contributors can focus on functionality; formatting is handled by machines
• Tools Used:
  • Python: ruff (configuration in .ruff.toml)
  • Fortran: fprettify (configuration in .fprettify.rc)

For Contributors: Just write working code! Formatting will be applied automatically after merge.

Testing Development Versions

For developers who need to test pre-release versions from test.pypi.org:

1. Install uv (one-time setup):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Create isolated environment with uv:

uv venv .venv-dev
source .venv-dev/bin/activate  # Linux/macOS
# or: .venv-dev\Scripts\activate  # Windows
# You'll see (.venv-dev) in your terminal prompt when activated

Note: uv venv is 80x faster than python -m venv and manages Python versions automatically.

3. Check latest version: Visit https://test.pypi.org/project/supy/ to find the latest development version (format: YYYY.M.D.dev0)

4. Install development version:

# Replace 2025.9.16.dev0 with the latest version from step 3
uv pip install --extra-index-url https://test.pypi.org/simple/ \
              --index-strategy unsafe-best-match \
              supy==2025.9.16.dev0

5. Verify installation:

python -c "import supy; print(f'SUEWS version: {supy.__version__}')"
# Should show: 2025.9.16.dev0 (or your installed version)

6. Test functionality:

python -c "import supy as sp; sp.load_sample_data(); print('✓ Installation successful')"

For future use: Always activate the environment before working:

source .venv-dev/bin/activate  # Linux/macOS
# or: .venv-dev\Scripts\activate  # Windows
# Use 'deactivate' to exit the environment

Why uv?

• Creates virtual environments 80x faster than python -m venv
• Handles test.pypi.org dependencies correctly with --index-strategy unsafe-best-match
• Single tool for both environment and package management
• No Python installation required (uv can download Python as needed)