Ctrl+K

Development Guide

Tip

  1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page.

1.3. Development Guide#

Note

If you are interested in contributing to the code please open a new discussion in the UMEP Community to illustrate your proposal: we are happy to collaborate in an open development mode.

1.3.1. Essential pre-requisites#

compliation

git

testing

1.3.2. Code guidelines#

If you are interested in contributing to the code please contact Sue Grimmond.

1.3.3. Coding#

  1. Core physics and calculation schemes of SUEWS are written in Fortran 90

  2. Code is hosted in GitHub as private repository

  3. Variables

    • Names should be defined at least in one place in the code – ideally when defined

    • Implicit None should be used in all subroutines

    • Variable name should include units. e.g. Temp_C, Temp_K

    • Output variable attributes should be provided in the TYPE structure defined in the ctrl_output module as follows:

      : TYPE varAttr
: CHARACTER(len = 15) :: header ! short name in headers
: CHARACTER(len = 12) :: unit   ! unit
: CHARACTER(len = 14) :: fmt    ! output format
: CHARACTER(len = 50) :: longNm ! long name for detailed description
: CHARACTER(len = 1)  :: aggreg ! aggregation method
: CHARACTER(len = 10) :: group  ! group: datetime, default, ESTM, Snow, etc.
: INTEGER             :: level  ! output priority level: 0 for highest (defualt output)
: END TYPE varAttr

  4. Code should be written generally

  5. Data set for testing should be provided

  6. Demonstration that the model performance has improved when new code has been added or that any deterioration is warranted.

  7. Additional requirements for modelling need to be indicated in the manual

  8. All code should be commented in the program (with initials of who made the changes – name specified somewhere and institution)

  9. The references used in the code and in the equations will be collected to a webpage

  10. Current developments that are being actively worked on

1.3.4. Testing#

  1. The testing of SUEWS is done using Python 3

  2. The following tests are done for each release of SUEWS:

  1. Working status of all physics schemes

  2. Year-grid looping logic

  3. Identity of output results with internal test dataset

Please use pre-defined make test option to check if your code can pass all tests or not. If not, the correctness of added code should be justified with caution.

1.3.5. Preparation of SUEWS Manual#

  1. The SUEWS manual is written in reStructuredText (aka rst) with a Sphinx flavour

  2. The SUEWS manual is hosted by readthedocs.org

  3. CSV tables used in following pages are automatically generated from the Description field in Input Options by each build, so DON’T manually edit them as your edits will be swiped automatically:

1.3.6. F2PY tips#

This includes several DON’T’s that have never been mentioned by F2PY docs:

  1. DON’T mix comments as lines into argument list of Fortran subroutines/functions:

DONT:

subroutine(&
! DONT DO this
args&
)

OK:

subroutine(&
args& ! OK this way
)

2. DON’T end a subroutine as ENDSUBROUTINE. Instead, leave a space in between to form END SUBROUTINE. Otherwise, the subroutines won’t be correctly parsed and picked up by F2PY.

Contents