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 particle reporting sensor

Last synced: about 4 hours ago
JSON representation

Repository metadata

Surface Urban Energy and Water Balance Scheme

Host: GitHub
URL: https://github.com/UMEP-dev/SUEWS
Owner: UMEP-dev
License: mpl-2.0
Fork: true (Urban-Meteorology-Reading/SUEWS)
Created: 2020-12-22T22:44:06.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2025-06-07T21:06:14.000Z (about 18 hours ago)
Last Synced: 2025-06-07T22:26:44.004Z (about 16 hours ago)
Topics: land-surface-model, urban-analytics, urban-climate-model
Language: Fortran
Homepage: https://suews.readthedocs.io/
Size: 789 MB
Stars: 14
Watchers: 9
Forks: 8
Open Issues: 78
Releases: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

SUEWS

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

SUEWS

Documentation

Documentation site: https://suews.readthedocs.io/
Documentation source: docs folder in this repo

Compilation

Prerequisites

Essential

gfortran (>= 9.3.0)
git - for version control
mamba - avoid using conda as it is too slow

Compilation

Since SUEWS includes a dependency package SPARTACUS, one needs to initialise this submodule by:

git submodule init
git submodule update

Then source code of SPARTACUS will be loaded into SUEWS-SourceCode/ext_lib/spartacus-surface

Note: if a permission denied error occurs, one usually needs to fix the SSH connection to GitHub by following the official guide here.

Configure mamba environment by:

mamba env create -f env.yml

This will create a new environment named suews-dev with all the required packages installed.

Activate the environment by:

make activate suews-dev

Compile SUEWS

4.1 compile the code and perform all tests

make

4.2 only compile the code

make dev

This will install a python package supy-driver and supy into the current environment (i.e., suews-dev).
Also, several command-line tools will be installed under bin folder, which can be used to perform SUEWS simulations:

suews-run: the main SUEWS binary
suews-convert: a tool to convert SUEWS input files from old format to new format
the usage of both of which can be checked by --help option (e.g., suews-run --help).

Check if supy is installed by:

pip show supy

Developer Note

When doing pip install -e supy-driver using WSL in VS Code on Windows 10 I got the error "[Errno 13] Permission denied: 'build/bdist.linux-x86_64/wheel/supy_driver-2021a2.dist-info'". The solution was in the Windows file explorer to right-click the project directory (SUEWS) -> properties -> security -> edit -> everyone -> tick allow -> apply.

Branch

`master` branch

master is the main branch that keeps milestone and stable features.

push is restricted to admin members.

If one needs to fix a bug or implement a new feature, please open an issue with details and then submit a pull request with respect to that issue.

Documentation

Please keep the development changes in CHANGELOG.md.

Test

Whenever changes are made, please run make test in the repo root to check if your changes are working or not.
If any error, please resolve it or justify that the test is giving false alarm.

Tests and purposes

make test will perform the following checks:

if single-grid-multi-year run could be successful: to check if multi-year run is functional;
if multi-grid-multi-year run could be successful: to check if multi-grid run is functional;
if test run results could match those from the standard run (runs under BaseRun): to check if any non-functional changes would break the current code;
if all physics schemes are working: to check possible invalid physics schemes.

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

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

fully clean and recompile SUEWS:

make clean; make

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

Name: UMEP-dev
Login: UMEP-dev
Email:
Kind: organization
Description:
Website:
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/62675320?v=4
Repositories: 5
Last ynced at: 2023-03-06T16:59:29.327Z
Profile URL: https://github.com/UMEP-dev

GitHub Events

Total

Create event: 69
Commit comment event: 6
Issues event: 85
Watch event: 2
Delete event: 11
Issue comment event: 103
Push event: 543
Pull request review comment event: 13
Pull request review event: 31
Pull request event: 84
Fork event: 1

Last Year

Create event: 69
Commit comment event: 6
Issues event: 85
Watch event: 2
Delete event: 11
Issue comment event: 103
Push event: 543
Pull request review comment event: 13
Pull request review event: 31
Pull request event: 84
Fork event: 1

Committers metadata

Last synced: 29 days 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
Jä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: 223
Total pull requests: 118
Average time to close issues: 10 months
Average time to close pull requests: 2 days
Total issue authors: 35
Total pull request authors: 6
Average comments per issue: 2.01
Average comments per pull request: 0.31
Merged pull request: 103
Bot issues: 0
Bot pull requests: 0

Past year issues: 82
Past year pull requests: 68
Past year average time to close issues: 22 days
Past year average time to close pull requests: about 18 hours
Past year issue authors: 13
Past year pull request authors: 3
Past year average comments per issue: 1.57
Past year average comments per pull request: 0.16
Past year merged pull request: 55
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 (72)
ghost (39)
MatthewPaskin (39)
Empanag (5)
ljarvi (5)
LllC-mmd (5)
megstretton (4)
dayantur (4)
Kangarooboxer (4)
CsillaVG (3)
utterances-bot (3)
RussellGl (3)
vitorlavor (3)
biglimp (3)
becqui00 (3)

Top Pull Request Authors

sunt05 (67)
MatthewPaskin (26)
ljarvi (16)
LllC-mmd (4)
vitorlavor (3)
yiqing1021 (2)

Top Issue Labels

enhancement (38)
WIP (30)
documentation (27)
STEBBS (19)
P0 (19)
SPARTACUS (18)
P1 (17)
pydantic (10)
P2 (9)
SuPy (9)
needs-test (8)
snow (7)
bug (6)
P4 (6)
P3 (6)
help wanted (5)
CO2 (5)
RSL (5)
dev (4)
Anthropogenic Emissions (4)
water balance (3)
DTS (3)
OHM (3)
DailyState (3)
EHC (3)
post-processing (3)
no-issue-activity (3)
LAI (2)
user question (2)
WRF-SUEWS (2)

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.922985958711196

SUEWS

Keywords

Keywords from Contributors

Repository metadata

README.md

SUEWS

Documentation

Compilation

Prerequisites

Essential

Recommended

Compilation

Developer Note

Branch

master branch

Documentation

Test

Tests and purposes

Debugging with GDB

GDB on macOS

debugging with GDB

Questions

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Dependencies

`master` branch