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 climate-model wrf science-research urban-climate urban-planning sensors reporter particles

Last synced: about 15 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

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: about 2 months ago

Total Commits: 5,571
Total Committers: 30
Avg Commits per committer: 185.7
Development Distribution Score (DDS): 0.161

Commits in past year: 784
Committers in past year: 4
Avg Commits per committer in past year: 196.0
Development Distribution Score (DDS) in past year: 0.457

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

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 246
Total pull requests: 162
Average time to close issues: about 1 year
Average time to close pull requests: 1 day
Total issue authors: 35
Total pull request authors: 7
Average comments per issue: 2.23
Average comments per pull request: 0.64
Merged pull request: 135
Bot issues: 0
Bot pull requests: 0

Past year issues: 95
Past year pull requests: 110
Past year average time to close issues: about 2 months
Past year average time to close pull requests: about 15 hours
Past year issue authors: 13
Past year pull request authors: 4
Past year average comments per issue: 2.22
Past year average comments per pull request: 0.72
Past year merged pull request: 85
Past year bot issues: 0
Past year bot pull requests: 0

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

Top Issue Authors

  • sunt05 (75)
  • ghost (43)
  • MatthewPaskin (43)
  • biglimp (9)
  • dayantur (6)
  • utterances-bot (5)
  • Empanag (5)
  • ljarvi (5)
  • LllC-mmd (5)
  • megstretton (4)
  • suegrimmond (4)
  • Kangarooboxer (4)
  • CsillaVG (3)
  • RussellGl (3)
  • vitorlavor (3)

Top Pull Request Authors

  • sunt05 (96)
  • MatthewPaskin (37)
  • ljarvi (16)
  • LllC-mmd (4)
  • dayantur (4)
  • vitorlavor (3)
  • yiqing1021 (2)

Top Issue Labels

  • enhancement (41)
  • WIP (35)
  • documentation (29)
  • STEBBS (20)
  • P1 (19)
  • P0 (19)
  • SPARTACUS (19)
  • pydantic (14)
  • P2 (10)
  • SuPy (9)
  • needs-test (8)
  • bug (7)
  • snow (7)
  • P4 (6)
  • RSL (6)
  • P3 (6)
  • pre-processing (5)
  • help wanted (5)
  • CO2 (5)
  • post-processing (4)
  • ESTM (4)
  • OHM (4)
  • Anthropogenic Emissions (4)
  • dev (4)
  • benchmark (3)
  • no-issue-activity (3)
  • BEERS (3)
  • EHC (3)
  • user question (3)
  • DailyState (3)

Top Pull Request Labels

  • bug (2)

Dependencies

.github/workflows/f-prettify.yml actions
  • actions/checkout v1 composite
  • actions/setup-python v2 composite
  • elstudio/actions-js-build/commit v2 composite
.github/workflows/archive/build-SUEWS.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/archive/clean-artifact.yml actions
  • glassechidna/artifact-cleaner v2 composite
.github/workflows/archive/move.yml actions
.github/workflows/archive/stale.yml actions
  • actions/stale v5 composite
.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
src/supy/pyproject.toml pypi
src/supy/requirements.txt pypi
  • auditwheel *
  • build *
  • pytest *
  • twine *
src/supy/setup.py pypi
  • DRIVER_REQ ,
  • atmosp *
  • cdsapi *
  • chardet *
  • click *
  • dask *
  • f90nml *
  • f90wrap ==0.2.12
  • importlib_resources *
  • lmfit *
  • matplotlib *
  • multiprocess *
  • numdifftools *
  • pandas <
  • pandas *
  • platypus-opt ==1.0.4
  • pvlib *
  • scipy *
  • seaborn *
  • xarray *

Score: 7.975908360165539