Fortran Analysis, Engineering & Migration

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:

More experiments will be added as they become available.

Pre-requisites for the Experiments

You will need:

• A Linux Installation (The scripts have been tested under Ubuntu 10.04, 12.04 and 14.04). You may be able to run these experiments under OSX and some Unix installations. If you do so, please would you tell us.
• C shell - If this is not installed, the Ubuntu installation is made by $ sudo apt-get install csh
• C and Fortran compilers. The scripts have been tested with gfortran and ifort.
• The Unix/Linux macro pre-processor m4. The Ubuntu installation is made by $ sudo apt-get install m4
• An installation of NetCDF. This is not trivial. After several failed builds with later versions, we found the sources of NetCDF-3.6.3 at http://www.unidata.ucar.edu/software/netcdf/binaries.html (We did not find any binaries). The NetCDF-3.6.3 sources built (With some errors) and successfully created the required binary files. All of the WRF builds we used were made with NetCDF-3. The NetDCF libraries must be built with the same C and Fortran compilers which you will use to build WRF.
• The WRF distribution. The scripts here are set up for WRFV3.4.1 and for WRFV3.6.1, which may be downloaded from http://www2.mmm.ucar.edu/wrf/users/download/get_sources.html. You do not need to install WRF. This is done automatically by the scripts which run the experiments.
• If you choose to analyse WRFV3.6.1, you will need a corrected version of the file share/mediation_feedback_domain.F. This file is downloaded from http://www2.mmm.ucar.edu/wrf/users/wrfv3.6/known-prob-3.6.1.html at the heading "Building WRF Serially". Download the file mediation_feedback_domain.F.fix-3.6.1 but do not rename it. It is copied into place by the setup scripts.
• An fpt installation. The scripts require fpt version 3.8-i or later. This may be downloaded at the download tab at the top of this page. If you are a new fpt user and need a licence key, please indicate that you are working on WRF and we will send a temporary key to you. The automatically generated keys on the website only last for a few days, but you can use them to get started.

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:

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 2024 Software Validation Ltd. All rights reserved.