Difference between revisions of "Performing Difference Tests with GEOS-Chem"

From Geos-chem
Jump to: navigation, search
(Created page with "On this page we show you how to use the GEOS-Chem Unit Tester to generate and use difference tests to evaluate modifications to GEOS-Chem. == Downloading the GEOS-Chem Un...")
 
Line 109: Line 109:
  
 
The <tt>DiffTest.input</tt> file has a layout that is very similar to the [[Creating_GEOS-Chem_run_directories#Editing_the_CopyRunDirs.input_file|<tt>CopyRunDirs.input</tt> file]] located in the same directory. The only difference is the addition of <tt>CODE_REF</tt> and <tt>CODE_DEV</tt> lines in the [[Creating_GEOS-Chem_run_directories#Section_1:_INPUTS|<tt>INPUTS</tt> section]]. Those lines can be used to specify the paths of the reference (Ref) and development (Dev) codes that you would like to compare.
 
The <tt>DiffTest.input</tt> file has a layout that is very similar to the [[Creating_GEOS-Chem_run_directories#Editing_the_CopyRunDirs.input_file|<tt>CopyRunDirs.input</tt> file]] located in the same directory. The only difference is the addition of <tt>CODE_REF</tt> and <tt>CODE_DEV</tt> lines in the [[Creating_GEOS-Chem_run_directories#Section_1:_INPUTS|<tt>INPUTS</tt> section]]. Those lines can be used to specify the paths of the reference (Ref) and development (Dev) codes that you would like to compare.
 +
 +
== Generating a GEOS-Chem DiffTest Directory ==
 +
 +
Once you have edited the <tt>DiffTest.input</tt> script to your liking, you can use that to generate fresh copies of GEOS-Chem DiffTest directories.  Make sure you are in the <tt>perl</tt> directory, and then type:
 +
 +
./gcCreateDiffTest
 +
 +
If you do not pass a file name to <tt>gcCreateDiffTest</tt>, then the <tt>gcCreateDiffTest</tt> script will use the <tt>DiffTest.input</tt> file that you just modified. 
 +
 +
Executing <tt>gcCreateDiffTest</tt> will create a new GEOS-Chem DiffTest directory corresponding to each entry that you specified in the input file <tt>RUNS</tt> section.  Each run directory will be created as a subdirectory of <tt>COPY_PATH</tt> that you specified in the input file <tt>INPUTS</tt> section.
 +
 +
Let's examine the contents of a sample <tt>DiffTest_geosfp_4x5_standard</tt> run directory.  Issue the following commands:
 +
 +
cd ~/GC/rundirs/geosfp_4x5_fullchem  # Change to geosfp_4x5_fullchem run dir
 +
 
 +
make fileclean                      # Remove any files left over from previous unit test runs
 +
 +
ls -1                                # Get directory listing
 +
 +
And you will see this directory listing:
 +
 +
ctm_summarizediff.pro
 +
Dev/
 +
locateDiagDiffs.sh
 +
logs/
 +
Makefile
 +
plots/
 +
README
 +
Ref/
 +
summarizeDiagDiffs.sh

Revision as of 16:14, 12 January 2017

On this page we show you how to use the GEOS-Chem Unit Tester to generate and use difference tests to evaluate modifications to GEOS-Chem.

Downloading the GEOS-Chem Unit Tester

First, make sure that your system has these software packages installed. (Most of these come standard with your Unix-based operating system.)

Next, clone the GEOS-Chem Unit Tester package with the command:

git clone https://bitbucket.org/gcst/geos-chem-unittest UT

This will create a copy of the GEOS-Chem Unit Tester package in a directory named UT for short.

NOTE: The Git clone process may take a few minutes to complete depending on your connection speed.

Editing the DiffTest.input file

Once you have downloaded the GEOS-Chem Unit Tester to your disk space, switch to the perl/ directory:

cd UT/perl

In this directory there is a Perl script named gcCreateDiffTest that you will use to generate fresh copies of GEOS-Chem difference test run directories. This script uses an input file named DiffTest.input, which is also located in the perl directory.

Your DiffTest.input file will look something like this:

#------------------------------------------------------------------------------
#                  GEOS-Chem Global Chemical Transport Model                  !
#------------------------------------------------------------------------------
#BOP
#
# !DESCRIPTION: Input file that specifies configuration for creating a
#  DiffTest directory from the UnitTester. 
#\\
#\\
# !REMARKS:
#  For a complete description of how to customize the settings in the
#  INPUTS and RUNS sections, see the following wiki posts:
#
#   wiki.geos-chem.org/Creating_GEOS-Chem_run_directories#Section_1:_INPUTS
#   wiki.geos-chem.org/Creating_GEOS-Chem_run_directories#Section_2:_RUNS
#
# !REVISION HISTORY: 
#  01 Oct 2015 - E. Lundgren - Initial version, based on CopyRunDirs.input
#EOP
#------------------------------------------------------------------------------
#
# !INPUTS:
#
# %%% ID tags %%%
#
   VERSION        : v11-01
   DESCRIPTION    : Create run directory from UnitTest
#
# %%% Data path and HEMCO settings %%%
#
   DATA_ROOT      : /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData
   HEMCO_ROOT     : {DATAROOT}/HEMCO
   VERBOSE        : 0
   WARNINGS       : 1
#
# %%% Unit tester path names %%%
#
   UNIT_TEST_ROOT : {HOME}/UT
   RUN_ROOT       : {UTROOT}/runs
   RUN_DIR        : {RUNROOT}/{RUNDIR}
   PERL_DIR       : {UTROOT}/perl
#
# %%% Reference (Ref) and Development (Dev) codes %%%
#
   CODE_REF       : {HOME}/GC/Code.Ref
   CODE_DEV       : {HOME}/GC/Code.Dev
#
# %%% Target directory and copy command %%%
#
   COPY_PATH      : {HOME}/GC/DiffTest/v11-01
   COPY_CMD       : cp -rfL
#
# !RUNS:
#  Specify the runs directories that you want to make DiffTests out of.
#  Here we provide a few examples, but you may copy additional entries from
#  UnitTest.input and modify the dates as needed. You can deactivate
#  certain directories by commenting them out with "#".
#
#--------|-----------|------|------------|------------|------------|---------|
# MET    | GRID      | NEST | SIMULATION | START DATE | END DATE   | EXTRA?  |
#--------|-----------|------|------------|------------|------------|---------|
   geosfp   4x5         -      standard     2013070100   2013070101   -
#  geosfp   4x5         -      tropchem     2013070100   2013070101   -
#  geosfp   4x5         -      soa          2013070100   2013070101   -
#  geosfp   4x5         -      soa_svpoa    2013070100   2013070101   -
#  geosfp   4x5         -      aciduptake   2013070100   2013070101   -
#  geosfp   4x5         -      UCX          2013070100   2013070101   -
#  geosfp   4x5         -      RRTMG        2013070100   2013070101   -
#  geosfp   4x5         -      RnPbBe       2013070100   2013070101   -
#  geosfp   4x5         -      Hg           2013010100   2013010101   -
#  geosfp   4x5         -      POPs         2013070100   2013070101   -
#  geosfp   4x5         -      TOMAS40      2013070100   2013070101   -
#  geosfp   4x5         -      CH4          2013070100   2013070101   -
#  geosfp   4x5         -      tagO3        2013070100   2013070101   -
#  geosfp   4x5         -      tagCO        2013070100   2013070101   -
#  geosfp   2x25        -      CO2          2013070100   2013070101   -
#  geosfp   4x5         -      aerosol      2013070100   2013070101   - 
#  geosfp   025x03125   ch     tropchem     2013070100   201307010010 -
#  geosfp   025x03125   na     tropchem     2013070100   201307010010 -
!END OF RUNS:
#EOP
#------------------------------------------------------------------------------

NOTE: Lines starting with a # character will be treated as comments.

The DiffTest.input file has a layout that is very similar to the CopyRunDirs.input file located in the same directory. The only difference is the addition of CODE_REF and CODE_DEV lines in the INPUTS section. Those lines can be used to specify the paths of the reference (Ref) and development (Dev) codes that you would like to compare.

Generating a GEOS-Chem DiffTest Directory

Once you have edited the DiffTest.input script to your liking, you can use that to generate fresh copies of GEOS-Chem DiffTest directories. Make sure you are in the perl directory, and then type:

./gcCreateDiffTest

If you do not pass a file name to gcCreateDiffTest, then the gcCreateDiffTest script will use the DiffTest.input file that you just modified.

Executing gcCreateDiffTest will create a new GEOS-Chem DiffTest directory corresponding to each entry that you specified in the input file RUNS section. Each run directory will be created as a subdirectory of COPY_PATH that you specified in the input file INPUTS section.

Let's examine the contents of a sample DiffTest_geosfp_4x5_standard run directory. Issue the following commands:

cd ~/GC/rundirs/geosfp_4x5_fullchem  # Change to geosfp_4x5_fullchem run dir 
  
make fileclean                       # Remove any files left over from previous unit test runs

ls -1                                # Get directory listing

And you will see this directory listing:

ctm_summarizediff.pro
Dev/
locateDiagDiffs.sh
logs/
Makefile
plots/
README
Ref/
summarizeDiagDiffs.sh