Information for WRF Code Contributors

WRF welcomes community code contributions, and this document outlines the process.




Requirements for WRF Code Contribution

Contributions to the WRF repository can be submitted to the relevant branch at any point. Code contributors are responsible for the following:




WRF Coding Standards

WRF Code submissions must adhere to the following WRF coding standards:

  • Modify a single Fortran file - ideally a single module - per submission; but multiple modules are allowed.

  • Use standard Fortran free format.

    • ! : for comments

    • & : at the end for continuation lines


  • Indent code.

  • 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, list and provide a brief description of each variable, including units.

  • Where possible, include publication references for scientific formulae and process formulations attributed to others.

  • Place comments around all non-trivial code blocks.

  • Use “IMPLICIT NONE.”

  • Declare all variables.

  • Use “INTENT IN/OUT/INOUT.” Although some compilers may not heed these statements, they provide valuable information for researchers.

  • Do not include PRINT statements or diagnostic WRITE statements: instead, use “call wrf_message”. Debugging statements contained within special IF tests are acceptable.

  • Do not include READ statements after model initialization. However, it is acceptable to input look-up table values on a single processor that are then broadcast. 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.”

  • EQUIVALENCE statements are not accepted for new code.

  • Do not use COMMON blocks that are outside a self-contained module (they should appear above the CONTAINS statement). It is recommended that no COMMON blocks be used within a module.

  • No MPI calls or communication should be within the physics layer, except the WRF version of MPI broadcast calls to send information, such as look-up table data, to 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).

  • Physics routines should not include horizontal differencing. Physics module computations are in the vertical direction only. If horizontal differencing is required in a routine, please seek assistance from the DC.

  • When adding a new physics package or 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 start-of-simulation initializations, include an initialization routine. Call this routine from the physics initialization at the model start - do not call it from the solver, nor during a ‘first time step check.’ The latter approach can introduce OpenMP race conditions.

  • Call the initialization routine from the relevant physics_init routine (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 pre-defined in the model, if possible. Use share/module_model_constants.F to obtain existing constants or to define new ones.

  • Use correct indexing inside of the physics routines:

    • loops should only run through the tile index bounds

    • 2-D/3-D arrays defined as state variables in the Registry should only be memory-dimensioned

    • 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 must not break existing builds.

  • OPTIONAL data should always test with PRESENT before use.





Code Testing

Proposing developers are responsible for:

  • Performing required testing

    • Both positive and negative testing - demonstrate that the code does as intended and confirm that the code does not do anything unintended

    • Existing code developers/owners whose code may be impacted by the changes may require additional testing


  • Ensuring proposed changes are correct

  • Providing adequate details in the PR regarding code modification impacts on other parts of the model



Code proposed for WRF must pass regression tests before being approved (see details). The following three testing areas are required:

  1. Software testing

  2. Case testing

  3. Feature testing


Developers are required to run their code through WRF regression testing either via Pull Request automated tests or an equivalent framework. These tests are short with minimal memory and 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

  • All test results and corresponding namelist.input files must be provided for review. Non-identical datasets will report bias and RMS differences on a per-field basis.

  • If a new option is introduced, when not activated, there should be no change in code behavior.

  • When a new run-time option is not activated, there should be no memory increase. Contributors must provide the cost of new or modified schemes, relative to several other similar schemes.

  • Case simulations must be run to assess the new code’s robustness and reasonableness. It is not necessary that these simulations are run for long forecasts or use large domains, but they should employ parallel processing. New test cases must be provided to demonstrate this for new schemes.





Seeking Permission from Original Code Developers/Owners

To contribute to existing code not originally authored or overseen by the contributor, permission from the primary author or oversight group is required before submitting a pull request. The original author or oversight group retains veto power. Developers are responsible for communicating modifications and obtaining this permission.





WRF Physics Review Panel

A review process conducted by the WRF Physics Review Panel (WPRP) is required for all new physics package contributions. Note that the WPRP only reviews new physics packages. Bugfixes, non-fundamental modifications to existing physics schemes, and development in WRF’s dynamics, numerics, or software framework do not require a WPRP review.





Submitting a GitHub Pull Request

Code proposed for WRF must be offered through a properly-formatted GitHub pull request (PR). All communication must be conducted through the GitHub PR process, including test results, comment responses, and pull request documentation.





Documentation

The level of documentation varies, dependant on: 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.


Contributors must include the following in the pull request (PR):

  • type of modification

  • modification keywords

  • source code

  • changes made

  • list of files modified

  • tests conducted

  • release notes


See Making a Good Pull Request Message for details.


Following code acceptance, contributors are required to provide documentation and/or literature referencing their code or feature contributions. Documentation may be in the form a web page, README file, or inline documentation.