THIS PROJECT IS ARCHIVED AND NOW MAINTAINED BY @UMEP-dev.
This is a public repo for SUEWS source code and documentation.
-
Documentation site: https://suews-docs.readthedocs.io/
-
Documentation source:
docsfolder in this repo
These branches are regularly curated by admin members with specific purposes and set with triggers for automatic deployment (via MS Azure Pipeline) in the releases page named Latest Release Test:
master:- the main branch that keeps milestone and stable features.
pushis restricted to admin members.
develop:- used for core developments.
pushis restricted to admin members.
- Please keep the development changes documented in the Documentation repo.
- The SUEWS docs are mainly written in RST but Markdown is also acceptable.
- Your changes to docs will be reviewed and merged into public release if appropriate.
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.
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.
The test workflow is as follows (details refer to the Makefile test recipe and related python code):
- clean existing build and rebuild the code;
- create a temporary directory as working directory to perform checks;
- copy the rebuilt
SUEWS_{version}binary to the temporary folder; - copy the version specific input files under
Release/InputTables/{version}to the temporary folder (see below for its preparation); - run python code to perform the above checks and write out test results to the console:
- if all tests are successful, the code is generally good to go;
- if any test failed, we NEED to look into the reasons for the failure and resolve them before any further feature-added operations.
-
Prepare a base run:
- under
Test/BaseRun, create a folder named with version/feature info (e.g.,2019a); - perform a simulation to produce example output files, which will later be used as standard run to verify the correct code functionalities.
Note: all the above input files will be automatically copied under
Release/InputTableswith explicit version/feature (e.g.,Release/InputTables/2019a) and later archived in public releases for users; so carefully construct test data to include in the input files. - under
-
Configure test namelist file
Test/code/BTS_config.nml:name_exe: the SUEWS binary name that will be used for testing.dir_exe: the directory to copyname_exe.dir_input: the directory to copy input files; suggested to beRelease/InputTables/{version}.dir_baserun: the base run against which to test identity in results.
GDB is a generic debugging tool used along with gfortran. Here are some tips to debug SUEWS code:
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 option, to avoid hacking your macOS, is to use Linux docker images with gfortran&gdb installations: e.g., alpine-gfortran.
Once the docker image is installed, simply run this from the SUEWS root folder for debugging:
docker run --rm -it -v $(pwd):/source cmplopes/alpine-gfortran /bin/bash
which will mount the current SUEWS directory to docker's path /source and enter the interactive mode for debugging.
- enable the debugging related flags in
MakefileunderSUEWS-SourceCodeby 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
SUEWSbinary 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.
- Please raise issues for questions in the development so our progress can be well managed.
![azure-pipelines[bot] avatar](https://avatars.githubusercontent.com/in/9426?v=4 "azure-pipelines[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent