SUEWS

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

---

Documentation

• Documentation site: https://suews.readthedocs.io/

• Documentation source: docs folder in this repo

Compilation

Note: the following steps have been tested on macOS 14.1 and above, and WSL on Windows 10.

Prerequisites

Essential

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

Recommended

• VS Code - for code editing
• VS Code Co-pilot - for AI-assisted code writing (free for academic use)
• WSL - for Linux-like environment on Windows (Windows users only)

Compilation Steps

1. Since SUEWS includes a dependency package SPARTACUS, initialise this submodule by:

git submodule init
git submodule update

Then source code of SPARTACUS will be loaded into 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.

2. Configure mamba environment:

mamba env create -f env.yml

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

3. Activate the environment:

mamba activate suews-dev

4. Compile SUEWS:

4.1. For development with all tests:

make

4.2. For development without tests:

make dev

This will install Python packages supy-driver and supy into the current environment (suews-dev). Several command-line tools will be installed under bin folder for SUEWS simulations:

• suews-run: the main SUEWS binary
• suews-convert: a tool to convert SUEWS input files between formats

The usage of both tools can be checked with the --help option (e.g., suews-run --help).

5. Verify installation:

pip show supy

Developer Note

Note

the following is deprecated and will be updated

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

2. fully clean and recompile SUEWS:

make clean; make

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