This is the SUEWS urban climate model repository.

pip install supy

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

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.

SUEWS includes Claude Code configuration in the .claude/ directory:

• Setup Guide: See .claude/README.md for workspace structure
• Quick Start: See .claude/reference/quick-start.md for environment setup
• Custom Commands: /log-changes for automatic CHANGELOG updates

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

Follow these steps to set up local development:

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)

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

• 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

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

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.

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)