Information for WRF Code Contributors

Information for WRF Code Contributors

 

 

WRF Code Contribution— Background

 

The WRF Model reflects a tradition of code contributions from the community.  This document catalogs the procedures and requirements for contributing code to WRF.  Prospective contributors should familiarize themselves with this information. 

 

The WRF Developers’ Committee (DC) (described in “WRF Code Repository and Release Administration” document) oversees the management and maintenance of the WRF code repository.  The DC has responsibility for the process of reviewing new code, and it evaluates and processes requests to commit code to the repository. 

 

The WRF Model software is maintained using Git and is housed on a public GitHub repository: https://github.com/wrf-model/WRF.  Requests to add code to the WRF GitHub repository are known as “pull requests” or “PRs”, and they are reviewed by DC members or others with the necessary experience in the code areas.

 

For preparing and integrating their code, prospective contributors can, as necessary, be assigned a DC liaison.  For those new to the contribution process, please read the WRF GitHub page "Workflow for WRF Code Modification": https://github.com/wrf-model/WRF/wiki/Workflow-for-WRF-Code-Modification.   

 

 

WRF Code Contribution— Requirements

 

Contributor Responsibilities

Code may be offered to the appropriate branch of the WRF repository at any time.  The basic responsibilities for code contributors are as follows:

 

(1)  Meeting WRF coding standards;

(2)  Performing code testing;

(3)  Warning the DC of limiting assumptions or possible code conflicts;

(4)  Providing commit information; and

(5)  Documentation.

 

Contribution Steps and Standards

The steps and standards are laid out here and additional details are provided in the following section.

(i) Code proposed for WRF must adhere to WRF coding standards.

 

(ii) Code proposed for WRF must be thoroughly tested prior to submission.

 

It is a proposing developer’s responsibility to perform all required testing.  The developer must ensure that the proposed change is correct and that its impacts on other parts of the model are described in adequate detail in the PR.  The developer must consider both positive and negative tests: demonstrate that the code does as intended and confirm that the code does not do anything unintended.  Other developers or code owners who are potentially impacted by the proposed change may require that additional tests be performed.

 

(ii) Code proposed for WRF must be offered through a properly-formatted GitHub

pull request (PR).

 

– PR elements are described in: https://github.com/wrf-model/WRF/wiki/Making-a-good-pull-request-message .

 

The developer must conduct all communications through the GitHub PR process, including test results, responses to comments, and pull request documentation. 

 

(iii) Code accepted for WRF must be accompanied by adequate supporting documentation.

 

The level of documentation will vary depending on a number of factors: whether the code is a bugfix or a new scheme, whether the modification is relatively contained, whether the change impacts a large segment of the community, whether the code makes assumptions about availability of non-local data, etc.

 

(iv) Code changes that modify scientific results must be verified by the developer and be

available for review. 

 

(v) Developers who wish to contribute modifications to existing schemes or

parameterizations that are not theirs, or which they do not officially oversee, should first get permission from the code’s primary author or the group overseeing the code.  Pull requests will not be considered without the agreement of the original developer or primary maintainer.

 

The original author or the group responsible for the code has veto power over proposed changes.  It is the responsibility of the developer to communicate his or her modifications to the author or oversight group and to obtain permission.

 

(vi) New physics packages require review by the WRF Physics Review Panel.

 

The contribution of new physics packages requires a review by the WRF Physics Review Panel (WPRP).  Note that the WPRP is not engaged for submissions other than new physics packages, such as (i) bugfixes or non-fundamental modifications to existing physics schemes or (ii) developments in WRF’s dynamics, numerics, or software framework.

 

 

WRF Code Contribution— Coding Standards

 

Code submitted for consideration for WRF must adhere to the following rules and practices:

• Use a single Fortran file, preferably as a single module; multiple modules, however, are acceptable.
• Use standard Fortran free format (“!” for comments, “&” at the end for continuation lines).
• Indent code, and do not exceed line lengths of 132 characters.
• If modifying an existing module, follow its code style.
• In the top-level physics routine of a new module: (i) list each variable and (ii) provide a brief description of the variable, with its units shown.
• Where possible, include publication references for scientific formulae and process formulations taken from others.
• Place comments around all non-trivial blocks of code.
• Use IMPLICIT NONE and declare all variables.
• Use INTENT IN/OUT/INOUT, at least at the top level.  While these statements are not always heeded by compilers, they provide valuable information for other researchers.
• Do not include any PRINT statements or diagnostic WRITE statements: instead, use “call wrf_message”.  Debugging statements that are contained within special IF tests are acceptable, however.
• Do not include READ statements after model initialization.  However, the inputting of look-up table values on a single processor that are then broadcast is acceptable. Initializations such as these should not be handled when the scheme is called from WRF’s solve subroutine.
• Do not use STOP or PAUSE statements: instead, use “call wrf_error_fatal”.
• It is preferred that no EQUIVALENCE statements be used, although there are large existing packages which use them extensively.  There are issues with optimization and parallelism that the user has to consider when using EQUIVALENCE statements.
• Do not use COMMON blocks that are outside of a self-contained module: that is, no COMMON blocks should appear above the CONTAINS statement.  It is recommended that no COMMON blocks be used within a module.
• Do not use MPI calls or do communication within the physics layer.  In initialization, however, it is acceptable to include the WRF version of MPI broadcast calls to send out such information as look-up table data to all of the other processes in the communicator.
• Do not introduce OpenMP directives in physics schemes.
• Use the top of a module for module-wide parameters (e.g., for look-up table values and flags set at initialization).
• Do not include computations that involve horizontal differencing in physics routines, as the assumption for all physics modules is that the computations are in the vertical direction only.  If horizontal differencing is required in a routine, please contact wrfhelp for assistance.
• When adding a new physics package or adding new state variables to an existing package, use the “package” option in the Registry files.
• Any known restrictions to a physics package (e.g., grid distance assumptions, mandatory microphysics variables, model top limit) should be explicitly coded into the namelist tests (i.e., share/module_check_a_mundo.F).
• Write code modularly where possible.  Repeated loops over different variables (e.g., u, v, T, q) should be abstracted into a subroutine with repeated calls.
• For the interface layer between the physics drivers and the physics schemes, pass variable arrays, flags, and physical constants through argument lists, not through USE association.
• For doing start-of-simulation initializations, include an initialization routine.  This routine should be called from the physics initialization during the model start, not from the solver and not based on a check of the time step being the first.  The latter type of logic introduces OpenMP race conditions.
• The initialization routine is to be called from the relevant routine of physics_init (CASE SELECT).
• The main run-time routine must be called from the relevant driver (CASE SELECT).
• Use physical constants (e.g., gravity, etc.) that are already defined in the model, if possible. The module share/module_model_constants.F is where to obtain existing constants or to define new ones.
• Use the correct indexing inside of the physics routines: (i) loops should always, and only, run through the tile index bounds; (ii) 2-D/3-D arrays defined as state variables in the Registry should always, and only, be memory-dimensioned; and (iii) local arrays should be tile-dimensioned.
• Distinguish indices explicitly when passing values into the top-level physics scheme.
  • Tile dimension— its, ite, etc: for loop limits and local array dimensions
  • Memory dimension— ims, ime, etc: for dimensions of WRF (registry) arrays
  • Domain dimension— ids, ide, etc: only for domain-boundary tests
• New modifications cannot break existing builds.
• OPTIONAL data should always test with PRESENT before use.

 

WRF Code Contribution— Code Testing

 

Code proposed for WRF must pass regression tests before being approved.  The testing is detailed at https://github.com/wrf-model/wrf-coop/blob/master/README_user.md. Three areas of testing are required:

 

(a) Software testing;

(b) Case testing; and

(c) Feature testing. 

 

Before code is approved, developers must do software testing by running it through the WRF regression testing via Pull Request automated tests or another framework that supports the equivalent suite of tests.  These tests are short and do not have large memory or time requirements.

 

• New schemes must provide identical results for unoptimized code run in serial, shared-memory, and distributed-memory tests.  These bit-wise identical results may be verified using the diffwrf utility, located in the WRF/external/io_netcdf directory.

 

Usage: external/io_netcdf/diffwrf wrf_file_1 wrf_file_2

 

• The results of all of the tests and the namelist.input files must be provided to WRF support personnel for their review.  Datasets that are not identical will report bias and rms differences on a per-field basis.

 

• If an option is introduced in the code, there should be no changes to the behavior of WRF when the option is not activated.

 

• There should be no increase in memory from new code when the run-time option is not selected.  For comparative purposes, the developer/contributor must supply information to WRF support personnel on the cost of the new or modified scheme, relative to several other similar schemes.

 

• Code testing also requires that case simulations be made to assess the new code’s robustness and reasonableness. While these simulations do not need to have long forecasts or use large domains, they should employ parallel processing. New test cases necessary to demonstrate this for new schemes should be provided to WRF support personnel.

 

 

WRF Code Contribution— Documentation

 

Contributors must provide information on their proposed code in the pull request (PR).  This must include the type of modification, modification keywords, source code, changes made, list of files modified, tests conducted, and release notes.  Required information for a PR may be found in:

https://github.com/wrf-model/WRF/wiki/Making-a-good-pull-request-message .

 

After code has been accepted, contributors must provide documentation or, if available, reference papers for their code or feature contributions.  The documentation may be in the form of a web page, README, or inline documentation.

 

 

5/25