Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

SUEWS

Surface Urban Energy and Water Balance Scheme.
https://github.com/UMEP-dev/SUEWS

Category: Climate Change
Sub Category: Earth and Climate Modeling

Keywords

land-surface-model urban-analytics urban-climate-model

Keywords from Contributors

land-surface-modeling suews wrf urban-climate climate-model science-research qgis urban-planning

Last synced: about 16 hours ago
JSON representation

Repository metadata

Surface Urban Energy and Water Balance Scheme

README.md

SUEWS

DOI

This is a public repo for SUEWS source code and documentation.

Documentation

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

[!NOTE]
the following is deprecated and will be updated

Development Environment

Claude Code Integration

For enhanced development productivity, SUEWS includes integration with Claude Code in a containerised environment:

  • Setup Guide: See claude-dev/README.md for complete setup instructions
  • Quick Start:
    • Workspace Manager (recommended): ./claude-dev/claude.sh start myproject
    • Direct Setup: ./claude-dev/setup-claude-dev.sh from repository root
  • Features: Intelligent code assistance, automated testing, British academic standards, multi-workspace support
  • Benefits: Isolated environment, reproducible development, AI-powered debugging, parallel project development

Traditional Development

For local development without containerisation, follow these steps:

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:

    # Quick development build (recommended)
make dev

# Or full build with tests
make

  6. Verify installation:

    pip show supy
suews-run --help
Development Workflow

  • Build commands:

    make dev          # Fast development build
make              # Full build with tests
make test         # Run test suite only
make clean        # Clean build artifacts
make wheel        # Build distribution wheels
make docs         # Build documentation
make livehtml     # Live documentation preview

  • Environment management:

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

  • Common issues:

    • Build conflicts: Run make clean before rebuilding
    • 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.

For Local Development (optional):

make format  # Format code locally
make lint    # Check code style

Debugging with GDB

GDB is a generic debugging tool used along with gfortran.
Here are some tips to debug SUEWS code:

GDB on macOS

Recent macOS (since High Sierra) introduces extra security procedures for system level operations that makes installation GDB more tedious than before.
The best practice, in TS's opinion, to avoid hacking your macOS, is to use Linux docker images with gfortran & gdb installations: e.g., alpine-gfortran
(otherwise, this guide might be useful for installation of GDB on macOS; also run set startup-with-shell off inside GDB before run the debuggng process)

Once the docker image is installed, simply run this from the SUEWS root folder for debugging:

 docker run --rm -it -v $(pwd):/source sunt05/alpine-gfortran /bin/bash

which will mount the current SUEWS directory to docker's path /source and enter the interactive mode for debugging.

debugging with GDB

  1. enable the debugging related flags in Makefile under SUEWS-SourceCode by removing the # after the equal sign =:
FCNOOPT = -O0
FFLAGS = -O3 $(STATIC) $(FCDEBUG) -Wall -Wtabs -fbounds-check -cpp \
					-Wno-unused-dummy-argument -Wno-unused-variable
  1. fully clean and recompile SUEWS:
make clean; make
  1. copy the recompiled SUEWS binary into your SUEWS testing folder (e.g., Test/BaseRun/2019a) and load it into GDB:
gdb SUEWS

run

then you should have stack info printed out by GDB if any runtime error occurs.

More detailed GDB tutorial can be found here.

Questions

  • Please raise issues for questions in the development so our progress can be well managed.

Owner metadata

GitHub Events

Total
Last Year

Committers metadata

Last synced: 15 days ago

Total Commits: 7,868
Total Committers: 34
Avg Commits per committer: 231.412
Development Distribution Score (DDS): 0.22

Commits in past year: 1,027
Committers in past year: 8
Avg Commits per committer in past year: 128.375
Development Distribution Score (DDS) in past year: 0.328

Name Email Commits
Ting Sun s****5@g****m 6139
Silvia Rognone r****a@g****m 538
matthew m****n@p****k 368
github-actions[bot] g****] 220
Järvi, Leena J l****i@h****i 93
Lewis Blunn m****3@g****m 77
Hamidreza Omidvar o****a@g****m 76
lyy l****9@m****n 50
HelenWard h****d@r****k 42
natalieth n****s@g****m 42
Fredrik Lindberg f****l@g****e 35
Vitor Lavor v****r@h****m 31
yiqing1021 d****4@s****k 30
zhenkunl l****k@y****t 27
Sue Grimmond 2****d 15
unknown x****r@N****e 14
unknown h****a@W****k 13
claude[bot] 2****] 10
azure-pipelines[bot] a****] 10
unknown x****0@S****k 10
HarroJongen 5****n 4
黄文娟 h****n@h****l 3
Shiho Onomura s****a@g****e 3
Jonas Kittner j****r@r****e 3
Xiaoxiong Xie 3****e 2
Fredrik Lindberg x****r@h****e 2
pjay-PC\pjay p****3@1****m 2
dependabot-preview[bot] 2****] 2
IzzyWillow i****s@p****k 2
Csilla V Gal c****g@g****m 1
and 4 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 372
Total pull requests: 483
Average time to close issues: 7 months
Average time to close pull requests: 5 days
Total issue authors: 40
Total pull request authors: 9
Average comments per issue: 1.39
Average comments per pull request: 1.31
Merged pull request: 333
Bot issues: 10
Bot pull requests: 20

Past year issues: 104
Past year pull requests: 164
Past year average time to close issues: 18 days
Past year average time to close pull requests: 13 days
Past year issue authors: 11
Past year pull request authors: 7
Past year average comments per issue: 1.17
Past year average comments per pull request: 1.86
Past year merged pull request: 106
Past year bot issues: 1
Past year bot pull requests: 15

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/UMEP-dev/SUEWS

Top Issue Authors

  • sunt05 (150)
  • MatthewPaskin (61)
  • dayantur (33)
  • ghost (27)
  • github-actions[bot] (10)
  • biglimp (8)
  • megstretton (6)
  • vitorlavor (5)
  • LllC-mmd (5)
  • suegrimmond (5)
  • Kangarooboxer (4)
  • Empanag (4)
  • utterances-bot (4)
  • bartpannemans (4)
  • XiaoxiongXie (3)

Top Pull Request Authors

  • sunt05 (318)
  • MatthewPaskin (71)
  • dayantur (37)
  • github-actions[bot] (20)
  • ljarvi (15)
  • vitorlavor (9)
  • yiqing1021 (8)
  • LllC-mmd (4)
  • HarroJongen (1)

Top Issue Labels

  • 1-feature (52)
  • 3-P1 (47)
  • 4-ready (36)
  • 3-P2 (35)
  • 1-bug (34)
  • 2-infra:data-model (32)
  • enhancement (30)
  • WIP (28)
  • 2-infra:input (26)
  • 1-maintenance (23)
  • documentation (23)
  • 4-in-progress (23)
  • 2-infra:test (21)
  • 2-doc:user (19)
  • P0 (18)
  • 2-infra:ci (16)
  • bug (13)
  • P1 (11)
  • SuPy (10)
  • SPARTACUS (10)
  • 3-P0 (10)
  • design-sensitive (9)
  • build-failure (9)
  • P2 (7)
  • mechanical (7)
  • 4-needs-science (7)
  • 4-needs-deps (7)
  • 2-doc:dev (6)
  • 2-infra:output (6)
  • 2-infra:packaging (6)

Top Pull Request Labels

  • 0-ci:schema-audit-ok (9)
  • 0-physics:change (8)
  • 1-bug (4)
  • 1-maintenance (4)
  • 2-module:dailystate (4)
  • 2-infra:data-model (4)
  • schema-audit-ok (4)
  • 3-P1 (4)
  • 4-in-progress (3)
  • 3-P0 (2)
  • 2-module:ohm (2)
  • 4-needs-science (2)
  • 3-P2 (2)
  • 4-ready (2)
  • design-sensitive (2)
  • 2-infra:input (2)
  • STEBBS (1)
  • 4-needs-obs (1)
  • 2-module:spartacus (1)
  • 2-infra:utility (1)
  • module:rslprof (1)
  • 4-needs-discussion (1)
  • 2-doc:user (1)
  • 2-infra:ci (1)
  • 1-feature (1)
  • 2-module:anohm (1)
  • bug (1)
  • 2-infra:output (1)

Dependencies

.github/workflows/build-publish_to_pypi.yml actions
  • actions/checkout v3 composite
  • actions/download-artifact v3 composite
  • actions/upload-artifact v3 composite
  • pypa/cibuildwheel v2.9.0 composite
  • pypa/gh-action-pypi-publish release/v1.5 composite
.github/workflows/claude-code-review.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/github-script f28e40c7f34bde8b3046d885e986cb6290c5673b composite
  • anthropics/claude-code-action 28f83620103c48a57093dcc2837eec89e036bb9f composite
.github/workflows/data-interface-version-audit.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
.github/workflows/dependency-audit.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • astral-sh/setup-uv d0cc045d04ccac9d8b7881df0226f9e82c39688e composite
.github/workflows/workflow-security.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • astral-sh/setup-uv d0cc045d04ccac9d8b7881df0226f9e82c39688e composite
.github/workflows/benchmark-pytest-scheduler.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
.github/workflows/cibuildwheel-debug.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
  • mxschmitt/action-tmate c0afd6f790e3a5564914980036ebf83216678101 composite
.github/workflows/claude.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/github-script f28e40c7f34bde8b3046d885e986cb6290c5673b composite
  • anthropics/claude-code-action 28f83620103c48a57093dcc2837eec89e036bb9f composite
.github/workflows/interaction-limits.yml actions
.github/workflows/knowledge-pack-audit.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
.github/workflows/rust-clippy.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
.github/workflows/ci-metrics-overhead.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
.github/workflows/docs-sync.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/github-script f28e40c7f34bde8b3046d885e986cb6290c5673b composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • astral-sh/setup-uv 38f3f104447c67c051c4a08e39b64a148898af3a composite
src/suews_bridge/Cargo.lock cargo
  • 134 dependencies
.github/workflows/claude-dispatch.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • anthropics/claude-code-action 9278e593553fcd1b65eede335d8c7e7e80da92db composite
.github/workflows/pages-deploy.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/configure-pages 45bfe0192ca1faeb007ade9deae92b16b8254a0d composite
  • actions/deploy-pages cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 composite
  • actions/github-script f28e40c7f34bde8b3046d885e986cb6290c5673b composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-pages-artifact 7b1f4a764d45c48632c6b24a0339c27f5614fb0b composite
  • astral-sh/setup-uv 38f3f104447c67c051c4a08e39b64a148898af3a composite
.github/actions/build-suews/action.yml actions
  • actions/cache 668228422ae6a00e4ad889ee87cd7109ec5666a7 composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
  • pypa/cibuildwheel 9c00cb4f6b517705a3794b22395aedc36257242c composite
.github/workflows/release-docs-anchor.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • astral-sh/setup-uv 38f3f104447c67c051c4a08e39b64a148898af3a composite
.github/workflows/schema-version-audit.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
.github/workflows/sync-agent-plugin.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
src/suews_bridge/pyproject.toml pypi
.github/workflows/discourse-to-issue.yml actions
.github/workflows/test-api-cross-python-reusable.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
src/suews_bridge/Cargo.toml cargo
  • tempfile 3 development
  • arrow 54
  • clap 4.5
  • paste 1.0
  • pyo3 0.29
  • rayon 1.10
  • serde 1.0
  • serde_json 1.0
  • serde_yaml 0.9
  • thiserror 2.0
mcp/pyproject.toml pypi
  • anyio >=4
  • httpx <1.0
  • mcp >=1.2,<2
  • supy *
.github/workflows/benchmark-checkout-provenance.yml actions
  • ./.github/actions/build-suews * composite
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
.github/workflows/benchmark-regression.yml actions
  • ./.github/actions/build-suews * composite
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite
pyproject.toml pypi
  • atmosp *
  • cdsapi *
  • chardet *
  • click *
  • f90nml *
  • jsonschema *
  • lmfit *
  • matplotlib *
  • numpy >=1.22
  • packaging *
  • pandas <3; python_version < '3.13' and platform_system == 'Linux'
  • pandas python_version >= '3.13' or platform_system != 'Linux'
  • pyarrow >=22; python_version >= '3.14'
  • pyarrow >=20,<21; python_version < '3.14' and platform_system == 'Linux'
  • pyarrow >=20; python_version < '3.14' and platform_system != 'Linux'
  • pydantic >=2.12
  • pytz *
  • pyyaml *
  • rich *
  • scikit-learn *
  • scipy python_version >= '3.13' or platform_system != 'Linux'
  • scipy <1.15; python_version < '3.13' and platform_system == 'Linux'
  • seaborn *
  • tzfpy >=1.0.0
.github/workflows/build-wheels-reusable.yml actions
  • ./.github/actions/build-suews * composite
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
.github/workflows/encoding-audit.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
.github/workflows/rust-yaml-aliases-audit.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a26af69be951a213d495a4c3e4e4022e16d87065 composite
.github/workflows/test-detect-changes.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • dorny/paths-filter de90cc6fb38fc0963ad72b210f1f284cd68cea36 composite
.github/workflows/validate-claude-md.yml actions
  • actions/checkout de0fac2e4500dabe0009e67214ff5f5447ce83dd composite
  • actions/setup-python a309ff8b426b58ec0e2a45f0f869d46889d02405 composite
  • actions/upload-artifact bbbca2ddaa5d8feaa63e36b76fdaad77386f024f composite

Score: 8.111328003286733