top_left_banner  SimCon logo


WRF - Experiments in INTENT, OPTIONAL Arguments and Precision

The Experiments

This page describes a series of experiments which you may run on WRF. The experiments are controlled by scripts which call fpt to re-engineer the WRF code, build and run the re-engineered code and compare the output with the output generated by a standard UCAR WRF build. The scripts may be downloaded from this site as described below.

The experiments are:

1. vanilla A build of WRF re-engineered by fpt but with no engineering changes.
2. remove_intent All non-mandatory INTENT declarations (about 35,000 in WRFV3.4.1) are removed.
3. enforce_intent_in All violations of INTENT (IN), where the INTENT (IN) argument is written to in the code, are corrected by copying the argument concerned to a temporary variable. In both WRFV3.4.1 and WRFV3.6.1 there are 138 arguments which are affected.
4. check_optional Access violations are counted for all optional arguments which are not guarded by IF (PRESENT(...)) constructs. The violations occur when the sub-program accesses the argument but it is not present at the call-site.
5. correct_precision Literal numbers which are associated by assignment or by arithmetic operators to objects of higher precision are corrected to the precision of those objects.
6. monitor_precision This experiment carries out the correction of precision described in 5 above. In all cases where there is a change in the value of the number concerned, a function or subroutine invocation is inserted to record that the changed value has been used. This experiment was made because the test runs on WRFV3.4.1 with em_b_wave showed no changes in results.

More experiments will be added as they become available.

Pre-requisites for the Experiments

You will need:

The WRF Version

The scripts available here are set up for WRFV3.4.1 and WRFV3.6.1. Please note that the different versions of WRF contain different files, and the fpt scripts in the directory fpt/ in the test environment will need to be updated if other versions are used.

Downloading and Installing the Test Environment

Download and install the WRF test environment as follows:

  1. Download the file wrf_analyses.tar.gz here. The description on this page is for version 2.0 of this file. The version is indicated in the setup script.
  2. Create a working directory for the test environment. We will call this wrf_fpt in this document but it can have any name.
  3. Copy the WRFV3 distribution, currently either WRFV3.4.1.TAR.gz or WRFV3.6.1.TAR.gz, to this directory. If you choose to analyse the current version, WRFV3.6.1, you will also have downloaded a corrected version of the source file mediation_feedback_domain.F.fix-3.6.1. Please copy this file to the working directory as well. Unpack wrf_analyses.tar.gz to this directory and ensure that the C shell scripts in the tools/ directory are executable. i.e.
     
    $ tar -xvf wrf_analyses.tar.gz
    $ chmod a+x tools/*.csh

Please examine the script tools/setup_WRFV3_fpt_test_environment.csh. It runs as follows:

  1. It creates the directory UCAR_not_built_WRFV3.6.1/WRFV3 or UCAR_not_built_WRFV3.4.1/WRFV3, and unpacks the appropriate WRF distribution into it.
  2. It copies UCAR_not_built_<version>/... to UCAR_clean_build_<version>/... , configures WRF in this directory and builds it with the standard UCAR build procedure.
  3. It creates the directory run_tests_<version>/WRFV3/ and copies the run/ and test/ directories from UCAR_clean_build_<version>/WRFV3/... to it. It then sets the file protections on the UCAR_not_built_<version>/... and UCAR_clean_build_<version>/... directories to prevent accidental overwriting.
  4. It creates the directory run_tests_<version>/WRFV3/main/ and copies wrf.exe and ideal.exe from UCAR_clean_build_<version>/WRFV3/main to it. The executable wrf.exe is renamed wrf_UCAR.exe to distinguish it from the executables created in re-engineered builds.
  5. In the run_tests_<version>/WRFV3/... directories it sets up the links for em_b_wave and runs the standard UCAR builds of ideal.exe and wrf_UCAR.exe to create the WRF output file wrfout_d01_0001-01-01_00:00:00. This file is renamed wrfout_<version>_UCAR, e.g. wrfout_WRFV3.6.1_UCAR, and is available for comparison with the output from re-engineered builds.

If you would like to suggest improvements to this, or any other of the scripts in the tools/ directory please e-mail SimCon.

Execute the script tools/setup_WRFV3_fpt_test_environment.csh. The script has two arguments. The first is the WRF version, currently either WRFV3.4.1 or WRFV3.6.1. The second is the optional letter 's' which instructs the script to run as silemtly as possible, with minimal prompting. This script will prompt you to configure WRF. In the first instance it is probably better to set up a single processor run with no nesting. We are only going to run the ideal case em_b_wave in the first tests. Note that this setup builds and runs WRF, and will therefore take about an hour to run. For example:

$ tools/setup_WRFV3_fpt_test_environment.csh WRFV3.6.1 s

At the end of this script the test environment working directory contains:

fpt/ Scripts for fpt to re-engineer the WRF code
 
fpt_build_environment/
   WRFV3/ ... Directories where the re-engineered code will be built
fpt_output/
   WRFV3/ ... Directories where fpt will re-write the re-engineered code
modified_build_files_WRFV3.4.1/
   WRFV3/ ... Small changes to the UCAR Makefiles for the fpt build
modified_build_files_WRFV3.6.1/
   WRFV3/ ... Small changes to the UCAR Makefiles for the fpt build
modified_source_minimal_WRFV3.4.1/
   WRFV3/ ... A small group of Fortran files modified by hand
modified_source_minimal_WRFV3.6.1/
   WRFV3/ ... A small group of Fortran files modified by hand
run_tests_<version>/
   WRFV3/ ... The main/, run/ and test/ directories for running WRF
 
tools/ The csh scripts which run the experiments
 
UCAR_clean_build_<version>/
   WRFV3/ ... A standard build of WRF (With ideal set up for em_b_wave)
UCAR_not_built_<version>/
   WRFV3/The UCAR WRF distribution with no changes
 
wrf_analyses.tar.gz The file downloaded to set up the environment
 
WRFV3.4.1.TAR.gz The WRF version 3.4.1 distribution
      or
WRFV3.6.1.TAR.gz The WRF version 3.6.1 distribution and
mediation_feedback_domain.F.fix_3.6.1

The Experiments

The experiments on WRF are each run by a single, one line command made in the main test environment directory, wrf_fpt . The commands are:

$ tools/WRFV3_fpt_experiment.csh WRFV3.6.1 vanilla
 
$ tools/WRFV3_fpt_experiment.csh WRFV3.6.1 remove_intent
 
$ tools/WRFV3_fpt_experiment.csh WRFV3.6.1 enforce_intent_in
 
$ tools/WRFV3_fpt_experiment.csh WRFV3.6.1 check_optional
 
$ tools/WRFV3_fpt_experiment.csh WRFV3.6.1 correct_precision
 
$ tools/WRFV3_fpt_experiment.csh WRFV3.6.1 monitor_precision

Where WRFV3.6.1 may be replaced by WRFV3.4.1 for experiments on that version.

Please examine the script WRFV3_fpt_experiment. Again, if you would like to suggest improvements, please e-mail SimCon.

The script runs as follows:

  1. The fpt_output directory structure is cleaned of all Fortran files. fpt will write the re-engineered code into these directories.
  2. fpt is run with the fpt script for the named WRF version and experiment. These scripts are in the fpt/ directory. The scripts are named WRFV3.4.1_vanilla.fsp , WRFV3.4.1_remove_intent etc. The re-engineered files are written to the fpt_output directory.
  3. The fpt_output directory structure is copied to a directory structure named for the experiment, for example, fpt_output_WRFV3.4.1_vanilla and fpt_output_WRFV3.6.1_remove_intent. These files are then available for comparison with the files in the UCAR distribution (In, e.g. UCAR_not_built_WRFV3.6.1/ and UCAR_clean_build_WRFV3.6.1).
  4. The script then sets up the fpt build environment. This is made up of the files from the original UCAR_clean_build_<version> directories, overwritten by the Fortran files generated by fpt in the fpt_output directories and by a small number of modified make files, copied from the modified_build_files_<version> directories. The original UCAR versions of the C files and *.h files are retained. Some *.h files are included by the Fortran code, but some of these are also included by the C code, and the Fortran comments added by fpt and delimited by ! characters cause problems.
  5. WRF is then compiled in the fpt_build_environment directories for the ideal case em_b_wave. Note that here is no need to run the UCAR configure script because this was done when the environment was set up. The executable file wrf.exe is renamed for the experiment, e.g. to wrf_vanilla.exe and is moved to the run_tests_<version>/WRFV3/main/ directory.
  6. A run of the re-engineered executable is then made in the run_tests_<version>/WRFV3/run/ directory. For example, for the vanilla case, the script runs ideal.exe and then wrf_vanilla.exe.
  7. The new WRF output file, wrfout_d01_0001-01-01_00:00:00 is renamed for the experiment, e.g. to wrfout_WRFV3.6.1_vanilla and is compared with the output file generated by the standard UCAR build.

Experiment 1 - vanilla

When fpt processes WRF it re-writes and re-formats every single line of the Fortran code. The code is re-written to files with the same names as the original files, and the organisation of the cpp pre-processor commands in the code is preserved. The vanilla experiment is run for two reasons:

  1. It is important to confirm that fpt does not damage the code in any way. In this experiment, we compare the output generated by the ideal case em_b_wave with that generated by a standard UCAR build. With the compilers which we have tested, gfortran and ifort, there are no changes. We therefore believe that fpt does not damage the code.
  2. The remaining experiments make engineering changes to the code. A systematic comparison with the UCAR_not_built files is difficult because fpt re-formats the code as well as changing it. The formatting rules are the same for the vanilla files and for the other experiments. A comparison with the vanilla files will therefore expose the engineering changes which fpt will make.

Experiments 2 and 3 - remove_intent and enforce_intent_in

WRF contains a large number of errors where sub-program arguments declared INTENT (IN) are written to. These experiments show that:

  1. The compilers which we have tested, gfortran and ifort, do not appear to use the INTENT declarations in code generation. No changes in behaviour were observed, even when about 35,000 INTENT declarations were removed from WRF.
  2. No change in behaviour was observed when arguments declared to be INTENT (IN) were protected from modification by copying them to temporary variables. WRF does not appear to use the changes made to the INTENT (IN) arguments.

However, the situation is unsatisfactory. The issue is discussed in detail in the WRF - Errors in INTENT Declarations page.

Experiment 4 - check_optional

If an optional sub-program argument is not present in a call to its sub-program and is accessed within the sub-program code, an access violation occurs. This is prevented by enclosing accesses to optional arguments in sections of code guarded by (IF (PRESENT(...)) constructs.

In WRF there are a large number of optional arguments which are not guarded in this way. For further discussion, please see WRF Optional Arguments.

In this experiment, code is inserted to count the accesses to missing optional arguments at run-time. In the ideal case em_b_wave no accesses to missing optional arguments are detected.

Experiments 5 and 6 - correct_precision and monitor_precision

WRF contains a large number of cases where single precision numbers are used in expressions with double precision variables. For example, in WRFV3/dyn_em/module_advect_em.F :

f0 = 1./3.*qim2-7./6.*qim1+11./6.*qi
f1 = -1./6.*qim1+5./6.*qi+1./3.*qip1
f2 = 1./3.*qi+5./6.*qip1-1./6.*qip2

the variables f0, f1 and f2 are DOUBLE PRECISION but the numbers 1., 6. and 3. are single precision. fpt may be used to change the precision of real numbers to the highest precision of the objects to which they are connected by assignment or by arithmetic or relational operators. The experiment correct_precision makes this change.

Surprisingly, this does not change the output generated by em_b_wave. The issue is discussed in detail in the WRF Precision of Numbers page. The monitor_precision experiment shows that the simple test case, em_b_wave, does not visit any of the changed numbers.

Copyright ©1995 to 2017 Software Validation Ltd. All rights reserved.