Port Validation for CAM


Below we outline an inexpensive procedure based on a perturbation growth test that can establish port validity with reasonable confidence. While it is highly likely that a successful perturbation growth test indicates a valid port, the ultimate assurance that ported code is running correctly comes from running a full climate simulation and comparing it to a control simulation produced by the trusted model. For that purpose we provide the climatology files from CAM control runs, and diagnostic tools to use for comparing your model run with the CAM controls.

Although the results of the perturbation growth test do not provide definitive port validity, we find the test to be extremely useful because it fails reliably, indicating that there is a problem with the port that needs to be fixed before incurring the expense of a full climate simulation.

Perturbation simulation controls

Each model configuration listed below is linked to a tar file that contains:

CAM-3.0, Eulerian dycore, T31-L26, IBM.    [details]
NOTE: The CAM-3.0 control can also be used to validate CAM-3.0.p1.

CAM-3.1, Eulerian dycore, T31-L26, IBM.    [details]
NOTE: The changes applied to CAM's default physics between v3.0 and v3.1 were structural changes that affect answers at the roundoff level. However, a bug fix was applied to the aqua-planet mode between v3.0 and v3.1 which changed the aqua-planet climate. Since the perturbation growth tests are run using aqua-planet mode, the updated perturbation control run for CAM-3.1 must be used to validate the port of CAM-3.1. It can also be used to validate the port of CAM-3.1.p1.

Example: Validate port of CAM-3.0 to a Linux cluster

The example below assumes that the validation will be done for the Eulerian dycore at T31-L26 resolution, and that the control simulation from the NCAR run has been downloaded.

  1. Configure CAM - To build CAM for perturbation growth testing the configure command must be invoked with the -pergro option. Since T31 is not the default Eulerian resolution it must be explicitly specified (-res 48x96). Also, suppose the Linux cluster being evaluated has the Lahey Fortran compiler installed. Since PGI compilers are the default assumed in the CAM Makefile the compiler must also be explicitly declared (-fc lf95). And finally, the default parallelization on Linux platforms is none (i.e., serial). We wish to use MPI and this must also be explicitly specified (-spmd).
    % configure -pergro -res 48x96 -fc lf95 -spmd

    NOTE: This configure command assumes that the netCDF and MPI include/library directories are specified in your environment. If not then add the appropriate locations to the configure command-line, or set the locations using the environment variables.

  2. Run CAM - The namelist for a two day run with no perturbation applied to the initial temperature field is set up as follows:
    % build-namelist -case p0 \
        -namelist "&camexp nsrest=0 nelapse=-2 mss_irt=0 nrefrq=0 \
           nhtfrq=1 ndens=1 mfilt=145 hfilename_spec='h%t.nc' \
           empty_htapes=.true. fincl1='T:I','PS:I' aqua_planet=.true.  /"

    This specifies a two-day initial run, in "aqua-planet" mode, with real*8 precision output of just the T and PS fields at every timestep. Additional variables set for convenience specify no archiving to remote storage, no writing a restart file, and renaming the history file to 'h0.nc'. Note that output of the PS field is required for computing the difference statistic which is a mass weighted RMS value.

  3. Compute RMS temperature differences - The temperature difference of interest is between the run just completed (in file h0.nc), and the downloaded control run (in file e48ph_ibm_p0.nc). Using the perl script cprncdf this difference will be calculated for each timesample in the file with the command:
    % cprncdf e48ph_ibm_p0.nc h0.nc > RMST_e48_cmp_ibm

    Note that when cprncdf is invoked this way it will run cprnc on the history files before striping out the RMS T values. So the cprnc utility must already be built and in your path. cprnc comes with the CAM distribution (in the models/atm/cam/tools/cprnc directory).

  4. Plot RMS temperature differences - Finally we need to plot the difference growth curve produced in the previous step (in file RMST_e48_cmp_ibm) against the perturbation growth curve for the control run (downloaded with the control history file, in file RMST_e48ph_ibm_aqpgro). This can be done with the perl script cprncplt via the following command:
    % cprncplt -b -t -pltitle "cam3.0, EUL-T31, port validation" \
      -l "perturbation: cam3.0(ibm)","difference: cam3.0(ibm) - cam3.0(pc/lf95)" \
      RMST_e48ph_ibm_aqpgro RMST_e48_cmp_ibm

    The script cprncplt assumes that the yorick utility is installed and in your path. The arguments tell the script to run in batch mode (-b), plot time in days rather than timestep number (-t, this option assumes there is two days worth of data in the file), add a title (-pltitle "string"), and add line legends (-l "line1","line2"). In batch mode the plot output is written to the postscript file pertGrowth.ps. Here is the plot from a linux cluster at NCAR:

    This validation plot provides a good example of a "fuzzy" pass. The jump in the difference curve is only to a value of order 10e-7, while large differences in the solutions will result in RMS values typically greater than 10e-3. There is indication in the last few timesteps of the perturbation curve that it is also heading rapidly towards larger RMS values, and perhaps will settle at values of order 10e-7 for the same reasons that the difference curve has jumped to those values. At this point in the validation process these curves are sufficiently alike to warrent moving to the next step which is doing a full climate simulation to compare with the controls.