Global Model Test Bed
CCPP Coding Standards
The purpose of proposing basic coding standards is not to dictate stylistic preference, but to inform developers about the needs for various compiler releases, and various assumptions regarding the Fortran source code. The standards listed here complement those of NCEP Coding Standards v2016a directives and the standards put forth by the NGGPS Overarching Systems (OAS) team that existed until 2016.
Host application cap interfacing with IPDe
The host application cap directly calls the source code contained within the IPD CCPP system.
These calls are to initialize the list of pointers, and then to populate the data and metadata in the list that will be sent to the IPDe.
This initialization happens once per model domain. During each time step, the host application cap loops over the calls to the physical parameterizations, ccpp_run(), via the information that was ingested from the external SDF.
Since the data bundle cdata is an argument, the host application cap must know about this Fortran TYPE via MODULE association.
Physics caps interfacing with IPDe
This code for a cap for each physics scheme is automatically manufactured for most physical parameterizations. Should there be interest in modifying the cap, the constructed file can be modified, though some intervention will be required to stop the cap from being overwritten during the build step.
The cap retrieves a pointer to what is assumed to be a stride-one (for the fastest incrementing index) contiguous array. Masking is available by passing in sufficient information through the argument lists. For example, passing in the array size, and also passing in the indexes over which to perform computations. An array mask, for example filled with 0s and 1s, would also be possible.
With the initial release of the IPD CCPP code, only a single element of metadata is passed ccpp_field_get() to uniquely determine which pointer to return.
The utility functions that generate a cap, given a compliant physics scheme, should be used exclusively with the same version of the CCPP code that contains all of the source code.
That the utility routines will manufacture conformable calls can only be guaranteed within the confines of a consistent IPD CCPP code base.
Within the physical parameterizations
This section deals with recommended practices to make parameterizations CCPP-compliant. Care needs to be taken when including licensing information in the physics schemes, and the intellectual property coordinator at the contributor's institution should be involved. The intended CCPP license on release is available here.
Beyond the listed requirements, the coding standards within the physical parameterizations themselves must remain fairly lax. For the IPD CCPP system to be able to interface the host application and a physical parameterization, the scheme must adhere to compliance regulations. The physical parameterizations need to use Fortran MODULE constructs, so modern Fortran is required.
Whether users choose to write in fixed or free format only becomes problematic when other schemes choose a different format.
Some Fortran compilers try to determine the format based on a file suffix convention.
For someone trying to introduce new schemes into an existing host application, locating the correct place in configuration and Makefiles to place compiler dependent format flags for a single file may prove difficult.
The recommendation would be to write in free format.
If the fixed format is a user's preferred style, then column six of the continued line can be the ampersand character &
, and column 73 or after should contain an ampersand for the line that will continue.
For a given scheme type, adding in special coding that must be replicated within each scheme of that scheme type should be avoided (for example, computing radar reflectivity within each microphysics scheme).
General purpose computations should be separated from the surrounding physical parameterizations, and made available as a separate, albeit small, scheme
(which is referred to as an interstitial scheme
).
Argument lists for the entry point routines should generally contain single variables. For example, if a scheme needs to have the mixing ratios for vapor, cloud, and rain, and will use them all individually within a scheme, then those fields should be separated. An example of when a multi-variable field would be appropriate in an argument list would be for vertical diffusion. Regardless of the number of arrays inside the array of fields, each of the individual fields is treated similarly during the vertical diffusion processing. Another counter example would be when complicated data structures, such as with radiation look-up tables, are passed as arguments to various routines.
When possible, overall program functionality structures should not be utilized within physics schemes. Examples of these tend to be associated with the needs for external libraries, such as for I/O and communications. Other examples of problematic program flow relates to detecting an error and stopping within a scheme. Not all distributed memory jobs will successfully shut down without a proper sequencing of commands.
Compilers have many useful flags. Physical parameterizations should be able to run successfully with the full range of bounds checking, floating traps, and uninitialized values under multiple compilers.
The physical parameterizations should be able to provide bit-wise reproducible results on differing numbers of processors, and the results should be identical for serial, shared memory, and distributed memory builds.
When an error occurs, the parameterization should return with a non-zero exit code and a string describing the error. All error messages should be unique, allowing an error message to be traced back to a single issuing location. Error messages should be output by the host application as the schemes are not allowed to write to standard output or standard error files themselves.
For entry point routines, variables should come from the argument list, including physical constants. Physical parameterizations should not call routines from a different scheme. If a function or subroutine is to be shared, the function subprogram should be placed in a separate module that houses only utility routines. Any information that does come from another MODULE via USE association should have the ONLY clause added. Examples of acceptable symbols to share include physical functions (convert relative humidity to specific humidity) and Fortran TYPE definitions.
All variables in the entry point routines should be declared as one of three possible INTENT states: IN, OUT, INOUT.
For the purposes of automation, three entry point routines must exist for each scheme: _run, _init, _finalize.
No OpenMP threading should be used within the code, as this parallel functionality has been reserved for the physics cap layer.
No explicit distributed memory MPI calls should be inside the physical parameterizations, unless guarded by CPP directives (see requirement H4).
Short numerical routines that have no Fortran intrinsic are appropriate to include in source code. Timing tests should verify that the algorithm is not dominating the cost of the physics scheme. If the code was part of an online library, provide sufficient references to find the code again. Note that with Fortran 2008, Bessel functions, error functions, gamma functions, and L2 norms are standard.
Build mechanism
The build system for the IPDe utilizes the Cmake software to construct system-specific makefiles. The build system for any physics parameterizations, as well as for the atmospheric driver components, is unique to those systems.
The CCPP utilizes dynamically loaded libraries containing the physical parameterizations (since the physics suite is defined at runtime), which must be built as dynamic libraries (.so) with position-independent code (-fPIC). The constructed library must be available at runtime through the specification of the LD_LIBRARY_PATH, or by specifying the library in the suite definition XML file. Examples therefore will be included in the CCPP releases.
Events
No Upcoming Events
