Difference between revisions of "Creating GEOS-Chem run directories"

From Geos-chem
Jump to: navigation, search
(GEOS-Chem Output Files)
(For GEOS-Chem 12.9.3 and prior versions)
(121 intermediate revisions by 4 users not shown)
Line 1: Line 1:
On this page we show you how to use the [[GEOS-Chem Unit Tester]] to generate and use fresh copies of run directories for your GEOS-Chem simulations. 
+
__FORCETOC__
 +
'''''[[Downloading_data_from_Amazon_Web_Services_cloud_storage|Previous]] | [[GEOS-Chem configuration files|Next]] | [[Getting Started with GEOS-Chem]]'''''
 +
#[[Minimum system requirements for GEOS-Chem|Minimum system requirements (and software installation)]]
 +
#[[Configuring your computational environment]]
 +
#[[Downloading GEOS-Chem source code|Downloading source code]]
 +
#[[Downloading GEOS-Chem data directories|Downloading data directories]]
 +
#<span style="color:blue">'''Creating run directories'''</span>
 +
#[[GEOS-Chem configuration files|Configuring runs]]
 +
#[[Compiling GEOS-Chem|Compiling]]
 +
#[[Running GEOS-Chem|Running]]
 +
#[[GEOS-Chem output files|Output files]]
 +
#[[Python tools for use with GEOS-Chem]]
 +
#[[GEOS-Chem_coding_and_debugging|Coding and debugging]]
 +
#[[GEOS-Chem_overview#Further_reading|Further reading]]
  
== Downloading the GEOS-Chem Unit Tester ==
 
  
First, make sure that your system [[Debugging_with_the_GEOS-Chem_unit_tester#Requirements|has these software packages installed]].  (Most of these come standard with your Unix-based operating system.)
+
The method that you will use to download run directories changed in [[GEOS-Chem 13.0.0]].   
  
Next, clone the GEOS-Chem unit tester package with the command:
+
== For GEOS-Chem 13.0.0 and later versions ==
  
git clone -b v10-01-public git://git.as.harvard.edu/bmy/GEOS-Chem-UnitTest UT
+
This content has been migrated to the [https://geos-chem.readthedocs.io/en/latest/gcc-guide/02-build/create-rundir.html '''Create a run directory''' chapter of <tt>geos-chem.readthedocs.io</tt>.]
  
This will create a copy of the GEOS-Chem Unit Tester package in a directory named <tt>UT</tt> for short.
+
== For GEOS-Chem 12.9.3 and prior versions ==
  
The option
+
<span style="color:red"><big><strong>NOTE: The GEOS-Chem Unit Tester was retired for GEOS-Chem 13.0.0 and later versions.<br>
 +
This content is now outdated, but we will preserve it here for reference.</strong></big></span>
 +
----
  
  -b v10-01-public
+
First, make sure that your system [[Unit_Tester_for_GEOS-Chem_12#Requirements|has these software packages installed]]. (Most of these come standard with your Unix-based operating system.)
  
specifies which branch of the GEOS-Chem Unit Tester that you would like to download.  Branches in the GEOS-Chem unit tester correspond to each internal version of GEOS-Chem (i.e. the states of the code for which we run 1-month benchmark simulations), as well as the publicly-released versions.  Most likely, you will want to download the '''v10-01-public''' branch of the GEOS-Chem Unit Tester, which corresponds to the public release of [[GEOS-Chem v10-01]].
+
Next, clone the [[GEOS-Chem Unit Tester]] package with these commands:
  
--[[User:Bmy|Bob Y.]] 13:36, 19 March 2015 (EDT)
+
git clone <nowiki>https://github.com/geoschem/geos-chem-unittest</nowiki> UT
 +
cd UT
 +
git checkout master
 +
 
 +
This will download a fresh copy of the <tt>GEOS-Chem-UnitTest</tt> repository into a directory named <tt>UT</tt>, and place you in the '''master''' branch.  The '''master''' branch always corresponds to the last benchmarked GEOS-Chem version.
 +
 
 +
If you would like to check out the Unit Tester that corresponds to a specific numbered GEOS-Chem version you can type one of the following commands:
 +
 
 +
git checkout 12.0.0
 +
git checkout v11-02-rc
 +
git checkout v11-02e
 +
 
 +
etc.
 +
 
 +
''NOTE: The Git clone process may take a few minutes to complete depending on your connection speed.''
 +
 
 +
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 21:10, 21 June 2018 (UTC)
 +
 
 +
== Available run directories ==
 +
 
 +
=== Benchmark run directory ===
 +
 
 +
The [[GEOS-Chem Unit Tester]] includes a run directory called '''4x5_standard''' (GEOS-Chem v11-01 and later) or '''4x5_benchmark''' (GEOS-Chem v10-01). The standard [http://acmg.seas.harvard.edu/geos/geos_benchmark.html GEOS-Chem benchmark simulation] utilizes the [[GEOS-FP]] met fields ([[GEOS-Chem_horizontal_grids#GMAO_4_x_5_grid|4&deg; x 5 &deg;]], [[GEOS-Chem_vertical_grids#72-layer_vertical_grid|72 levels]]) with the [[#UCX chemistry mechanism|UCX tropospheric-stratospheric chemistry mechanism]] and [[Secondary organic aerosols|secondary organic aerosols]] included.
 +
 
 +
To reproduce our latest 1-month benchmark simulation, you can edit the <tt>CopyRunDirs.input</tt> file so that the following line is uncommented under <tt>RUNS</tt>:
 +
 
 +
  geosfp  4x5        -      benchmark    2016070100  2016080100  -
 +
 
 +
Make sure to check the start and end date so that your simulation will run for July 2016. You can then create the GEOS-Chem benchmark run directory by typing <tt>./gcCopyRunDirs</tt>. Navigate to your the newly created <tt>geosfp_4x5_benchmark</tt> run directory. To compile the GEOS-Chem source code, type:
 +
 
 +
make -j4 build
 +
 
 +
That will create a <tt>geos.mp</tt> executable file that you can use to submit your GEOS-Chem benchmark simulation to a queue system.
 +
 
 +
For older versions of GEOS-Chem, the compile command was formerly
 +
 
 +
make -j4 mpbuild
 +
 
 +
=== Other run directories ===
 +
 
 +
Run directories are provided for a combination of met field, grid, and simulation type and are named accordingly. For more details on the simulation types, please see our [[GEOS-Chem chemistry mechanisms|''GEOS-Chem chemistry mechanism'' wiki page]].
  
 
== Editing the CopyRunDirs.input file ==
 
== Editing the CopyRunDirs.input file ==
  
Once you have [[#Downloading the GEOS-Chem unit tester|downloaded the GEOS-Chem Unit Tester]] to your disk space, switch to the <tt>perl/</tt> directory:
+
Once you have downloaded the GEOS-Chem Unit Tester to your disk space, switch to the <tt>perl/</tt> directory:
  
 
  cd UT/perl
 
  cd UT/perl
  
 
In this directory there is a Perl script named <tt>gcCopyRunDirs</tt> that you will use to generate fresh copies of GEOS-Chem run directories.  This script uses an input file named <tt>CopyRunDirs.input</tt>, which is also located in the <tt>perl</tt> directory.   
 
In this directory there is a Perl script named <tt>gcCopyRunDirs</tt> that you will use to generate fresh copies of GEOS-Chem run directories.  This script uses an input file named <tt>CopyRunDirs.input</tt>, which is also located in the <tt>perl</tt> directory.   
 +
 +
<span style="color:red">'''IMPORTANT:''' The <tt>CopyRunDirs.input</tt> file that comes with the Unit Tester provides only a small sample of the possible run directories that you can create. You can add as many entries to the <tt>RUNS</tt> section as you wish. See the <tt>UnitTest.input</tt> file for a complete list of all possible run directories that you can add to <tt>CopyRunDirs.input</tt>.</span>
  
 
Your <tt>CopyRunDirs.input</tt> file will look something like this:
 
Your <tt>CopyRunDirs.input</tt> file will look something like this:
Line 38: Line 94:
 
  #\\
 
  #\\
 
  #\\
 
  #\\
  # !REMARKS:
+
  # !REMARKS:
  #  Customize the run directory for your system by specifying these values:
+
  #  For a complete description of how to customize the settings in the
  #  -------------------------------------------------------------------
+
  #  INPUTS and RUNS sections, see the following wiki posts:
#  VERSION    : A tag used to identify this Unit Test (e.g. v10-01h)
+
  #
  # DESCRIPTION : A short description of this file's run dir copy configuration
+
  #  wiki.geos-chem.org/Creating_GEOS-Chem_run_directories#Section_1:_INPUTS
  # COPY_PATH   : Local path where run directory will be copied to
+
  #   wiki.geos-chem.org/Creating_GEOS-Chem_run_directories#Section_2:_RUNS
#  DATA_ROOT  : Root GEOS-Chem data directory
+
# HEMCO_ROOT  : Root directory where HEMCO emissions data files are stored
+
  # RUN_ROOT    : Unit test run directories are subdirectories of RUN_ROOT
+
#  RUN_DIR    : Individual unit test run directory path
+
#  PERL_DIR    : Unit Test perl script directory (i.e. this directory)
+
# COPY_CMD    : Unix copy command with optional tags
+
 
  #
 
  #
  # !REVISION HISTORY:
+
  # !REVISION HISTORY:  
 
  #  18 Mar 2015 - R. Yantosca - Initial version
 
  #  18 Mar 2015 - R. Yantosca - Initial version
 
  #  19 Mar 2015 - E. Lundgren - Simplify content for only copying run dirs
 
  #  19 Mar 2015 - E. Lundgren - Simplify content for only copying run dirs
 +
#  19 May 2015 - R. Yantosca - Now can specify VERBOSE and WARNINGS options
 
  #EOP
 
  #EOP
 
  #------------------------------------------------------------------------------
 
  #------------------------------------------------------------------------------
Line 59: Line 110:
 
  # !INPUTS:
 
  # !INPUTS:
 
  #
 
  #
     VERSION     : v10-01
+
# %%% ID tags %%%
     DESCRIPTION : Create run directory from UnitTest
+
#
     COPY_PATH  : /home/{USER}/GC/rundirs
+
     VERSION       : v11-01
    DATA_ROOT  : /as/data/geos/ExtData
+
     DESCRIPTION   : Create run directory from UnitTest
     HEMCO_ROOT : {DATAROOT}/HEMCO
+
#
     RUN_ROOT    : /home/{USER}/UT/runs
+
# %%% Data path and HEMCO settings %%%
     RUN_DIR     : {RUNROOT}/{RUNDIR}
+
#
     PERL_DIR   : /home/{USER}/UT/perl
+
     DATA_ROOT      : /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData
     COPY_CMD   : cp -rfL
+
     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
 +
#
 +
# %%% Target directory and copy command %%%
 +
#
 +
    COPY_PATH      : {HOME}/GC/rundirs
 +
     COPY_CMD       : cp -rfL
 
  #
 
  #
 
  # !RUNS:
 
  # !RUNS:
  #  Specify the debugging runs that you want to perform below.
+
  #  Specify the runs directories that you want to copy below.
 
  #  Here we provide a few examples, but you may copy additional entries from
 
  #  Here we provide a few examples, but you may copy additional entries from
 
  #  UnitTest.input and modify the dates as needed. You can deactivate copying
 
  #  UnitTest.input and modify the dates as needed. You can deactivate copying
Line 78: Line 143:
 
  # MET    | GRID      | NEST | SIMULATION | START DATE | END DATE  | EXTRA?  |
 
  # MET    | GRID      | NEST | SIMULATION | START DATE | END DATE  | EXTRA?  |
 
  #--------|-----------|------|------------|------------|------------|---------|
 
  #--------|-----------|------|------------|------------|------------|---------|
   geosfp  4x5        -      fullchem     2013070100  2013070101   -
+
   geosfp  4x5        -      standard     2013070100  2013080100   -
   geosfp  4x5        -      soa          2013070100  2013070101  -
+
# geosfp  4x5        -      gc_timing   2013070100  2013070800  -
  geosfp  4x5        -      soa_svpoa    2013070100  2013070101  -
+
# geosfp  4x5        -      tropchem    2013070100  2013070101  -
  geosfp  4x5        -      UCX          2013070100  2013070101  UCX=y
+
# geosfp  4x5        -      soa          2013070100  2013070101  -
  geosfp  4x5        -      RRTMG        2013070100  2013070101  RRTMG=y
+
# geosfp  4x5        -      soa_svpoa    2013070100  2013070101  -
  geosfp  4x5        -      RnPbBe      2013070100  2013070101  -
+
# geosfp  4x5        -      aciduptake  2013070100  2013070101  -
  geosfp  4x5        -      Hg          2013070100   2013070101   -
+
# geosfp  4x5        -      UCX          2013070100  2013070101  -
  geosfp  4x5        -      POPs        2013070100  2013070101  -
+
# geosfp  4x5        -      RRTMG        2013070100  2013070101  -
  geosfp  4x5        -      CH4          2013070100  2013070101  -
+
# geosfp  4x5        -      RnPbBe      2013070100  2013070101  -
  geosfp  4x5        -      tagO3        2013070100  2013070101  -
+
# geosfp  4x5        -      Hg          2013010100   2013010101   -
  geosfp  4x5        -      tagCO        2013070100  2013070101  -
+
# geosfp  4x5        -      POPs        2013070100  2013070101  -
  geosfp  2x25        -      CO2          2013070100  201307010030 -
+
# geosfp  4x5        -      TOMAS40      2013070100  2013070101  -
  geosfp  4x5        -      aerosol      2013070100  2013070101  -  
+
# geosfp  4x5        -      CH4          2013070100  2013070101  -
  geosfp  025x03125  ch    fullchem     2013070100  201307010010 -
+
# geosfp  4x5        -      tagO3        2013070100  2013070101  -
  geosfp  025x03125  na    fullchem     2013070100  201307010010 -
+
# geosfp  4x5        -      tagCO        2013070100  2013070101  -
 +
# geosfp  2x25        -      CO2          2013070100  201307010030 -
 +
# geosfp  4x5        -      aerosol      2013070100  2013070101  -  
 +
# geosfp  025x03125  ch    tropchem     2013070100  201307010010 -
 +
# geosfp  025x03125  na    tropchem     2013070100  201307010010 -
 +
# gchp    4x5        -      tropchem    2013070100  2013070101  -
 
  !END OF RUNS:
 
  !END OF RUNS:
 
  #EOP
 
  #EOP
Line 99: Line 169:
 
''NOTE: Lines starting with a <tt>#</tt> character will be treated as comments.''
 
''NOTE: Lines starting with a <tt>#</tt> character will be treated as comments.''
  
The <tt>CopyRunDirs.input</tt> file has a layout that is very similar to the [[Debugging_with_the_GEOS-Chem_unit_tester#Specifying_unit_test_options_with_an_input_file|GEOS-Chem Unit Tester input files]]. (These are the files named <tt>UnitTest.input</tt>, etc.Like the GEOS-Chem Unit Tester input files, <tt>CopyRunDirs.input</tt> is composed of an [[#The_INPUTS_section|<tt>!INPUTS</tt>]] section and a [[#The_RUNS_section|<tt>!RUNS</tt>]] section, which are described below.
+
The <tt>CopyRunDirs.input</tt> file has a layout that is very similar to the [[Debugging_with_the_GEOS-Chem_unit_tester#Specifying_unit_test_options_with_an_input_file|GEOS-Chem Unit Tester input files]] (<tt>UnitTest.input</tt> located within this directory). Like the GEOS-Chem Unit Tester input files, <tt>CopyRunDirs.input</tt> is composed of an <tt>INPUTS</tt> section and a <tt>RUNS</tt> section, which are described below.
  
 
=== Section 1: INPUTS ===
 
=== Section 1: INPUTS ===
  
Under the <tt>!INPUTS:</tt> section, you can customize the directory paths and other options for your system. [[#Specifying options in the input file|As seen above]], most of these inputs are self-explanatory.
+
Under the <tt>INPUTS</tt> section, you can customize the directory paths and other options for your system. Each configurable input is described in the table below.
  
 
{| border=1 cellspacing=0 cellpadding=5  
 
{| border=1 cellspacing=0 cellpadding=5  
Line 117: Line 187:
 
|<tt>DESCRIPTION</tt>
 
|<tt>DESCRIPTION</tt>
 
|A short (1-sentence) description of the purpose of this specific file (optional). This may be used to differentiate different input files, such as if you pre-configure several for future re-use.
 
|A short (1-sentence) description of the purpose of this specific file (optional). This may be used to differentiate different input files, such as if you pre-configure several for future re-use.
 
|-valign="top"
 
|<tt>COPY_PATH</tt>
 
|Specifies the root directory on your disk server where copies of the GEOS-Chem run directories will be created.
 
  
 
|-valign="top"
 
|-valign="top"
Line 126: Line 192:
 
|Specifies the path for your root-level data directory.   
 
|Specifies the path for your root-level data directory.   
  
|-valign="top"http://wiki.seas.harvard.edu/geos-chem/skins//common/images/button_nowiki.png
+
|-valign="top"
 
|<tt>HEMCO_ROOT</tt>
 
|<tt>HEMCO_ROOT</tt>
 
|Specifies the top-level path for the [[HEMCO data directories|HEMCO data directory tree]].
 
|Specifies the top-level path for the [[HEMCO data directories|HEMCO data directory tree]].
 
*The <tt>{DATAROOT}</tt> token in <tt>HEMCO_ROOT</tt> will be replaced with the value you specify for <tt>RUN_ROOT</tt> option.   
 
*The <tt>{DATAROOT}</tt> token in <tt>HEMCO_ROOT</tt> will be replaced with the value you specify for <tt>RUN_ROOT</tt> option.   
 
<b>Leave this as-is.</b>
 
<b>Leave this as-is.</b>
 +
 +
|-valign="top"
 +
|<tt>VERBOSE</tt>
 +
|Specifies the level of debug output that will be sent to the HEMCO log file. (0=no debug output; 3=max debug output)
 +
*Recommended setting: <tt>0</tt>
 +
 +
|-valign="top"
 +
|<tt>WARNINGS</tt>
 +
|Specifies the level of warning messages that will be sent to the HEMCO log file. (0=no warnings; 3=max warnings)
 +
*Recommended setting: <tt>1</tt>
 +
 +
|-valign="top"
 +
|<tt>UNIT_TEST_ROOT</tt>
 +
|Specifies the path to the GEOS-Chem Unit Tester.
  
 
|-valign="top"
 
|-valign="top"
 
|<tt>RUN_ROOT</tt>
 
|<tt>RUN_ROOT</tt>
 
|Specifies the top-level unit test run directories.   
 
|Specifies the top-level unit test run directories.   
 +
<b>Leave this as-is.</b>
 +
 +
|-valign="top"
 +
|<tt>RUN_DIR</tt>
 +
|Specifies the run directory subdirectory.
 
<b>Leave this as-is.</b>
 
<b>Leave this as-is.</b>
  
Line 141: Line 226:
 
|Specifies the directory where the unit test Perl scripts are found.
 
|Specifies the directory where the unit test Perl scripts are found.
 
<b>Leave this as-is.</b>
 
<b>Leave this as-is.</b>
 +
 +
|-valign="top"
 +
|<tt>COPY_PATH</tt>
 +
|Specifies the directory on your disk server where copies of the GEOS-Chem run directories will be created.
  
 
|-valign="top"
 
|-valign="top"
Line 149: Line 238:
  
 
|}
 
|}
 
--[[User:Bmy|Bob Y.]] 14:20, 19 March 2015 (EDT)
 
  
 
=== Section 2: RUNS ===
 
=== Section 2: RUNS ===
  
The layout of the <tt>!RUNS</tt> section is identical to [[#Debugging_with_the_GEOS-Chem_unit_tester|The <tt>!RUNS</tt> section in the GEOS-Chem Unit Tester input files]]. This allows you to copy and paste text from one or more GEOS-Chem Unit Tester input files into <tt>CopyRunDirs.input</tt>.
+
The layout of the <tt>RUNS</tt> section is identical to the <tt>RUNS</tt> section in the GEOS-Chem Unit Tester input file. This enables copying and pasting simulation settings text from <tt>UnitTest.input</tt> into <tt>CopyRunDirs.input</tt>.
  
 
For example, the following line:
 
For example, the following line:
Line 166: Line 253:
 
  # MET    | GRID      | NEST | SIMULATION | START DATE | END DATE  | EXTRA?  |
 
  # MET    | GRID      | NEST | SIMULATION | START DATE | END DATE  | EXTRA?  |
 
  #--------|-----------|------|------------|------------|------------|---------|
 
  #--------|-----------|------|------------|------------|------------|---------|
   geosfp  4x5        -      fullchem     2013070100  2013070101   -
+
   geosfp  4x5        -      standard     2013070100  2013080100   -
  
will tell the <tt>gcCopyRunDirs</tt> script to create a run directory for a GEOS-Chem simulation using:
+
will tell the <tt>gcCopyRunDirs</tt> script to create a run directory for a GEOS-Chem simulation with the following settings:
  
*[[GEOS-FP]] met fields
+
*Using [[GEOS-FP]] met fields
*On the [http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5&deg; GEOS-Chem horizontal grid]
+
*On the [[GEOS-Chem_horizontal_grids#GMAO_4_x_5_grid|4&deg; x 5&deg; GEOS-Chem horizontal grid]]
 
*For the [[NOx-Ox-HC-aerosol|GEOS-Chem standard full-chemistry simulation]]
 
*For the [[NOx-Ox-HC-aerosol|GEOS-Chem standard full-chemistry simulation]]
 
*Starting at 00:00 GMT on 2013/07/01
 
*Starting at 00:00 GMT on 2013/07/01
*Ending at 01:00 GMT on 2013/07/01
+
*Ending at 00:00 GMT on 2013/08/01
  
The date range will be used to initialize the <tt>input.geos</tt> file that is read during a GEOS-Chem simulation. Once the run directory is created, you may edit these dates within the <tt>input.geos</tt> file. Note, however, that time ranges must remain within the time range covered by the <tt>MET</tt> field you are using. You can check the <tt>MET</tt> field temporal coverage on the [http://wiki.seas.harvard.edu/geos-chem/index.php/Overview_of_GMAO_met_data_products; GMAO met data products wiki page]. Also note that the restart files automatically generated for the run directory correspond only to the original date specified in the <tt>CopyRunDirs.input</tt> file.  Restart files for a later dates must be generated by running a simulation that ends on that date.
+
The date range will be used to initialize the <tt>input.geos</tt> file that is read during a GEOS-Chem simulation. Once the run directory is created, you may edit these dates within the <tt>input.geos</tt> file. Note, however, that time ranges must remain within the time range covered by the <tt>MET</tt> field you are using. You can check the <tt>MET</tt> field temporal coverage on the [[Overview_of_GMAO_met_data_products|GMAO met data products wiki page]]. '''Also note that we recommend using the restart files to spin up GEOS-Chem for at least one year prior to your simulation start date. You may use the resulting output restart files as initial values for your simulation.'''
  
You can add as many entries to the <tt>!RUNS</tt> section as you wish. Simply cut and paste from one of the existing GEOS-Chem Unit Test input files (e.g. <tt>UnitTest.input</tt> within UT/perl).
+
You can add as many entries to the RUNS section as you wish. See the <tt>UnitTest.input</tt> file for a complete list of all possible run directories entries that you can add to <tt>CopyRunDirs.input</tt>.
  
== Generating a Run Directory ==
+
== Generating a GEOS-Chem Run Directory ==
  
 
Once you have edited the <tt>CopyRunDirs.input</tt> script to your liking, you can use that to generate fresh copies of GEOS-Chem run directories.  Make sure you are in the <tt>perl</tt> directory, and then type:
 
Once you have edited the <tt>CopyRunDirs.input</tt> script to your liking, you can use that to generate fresh copies of GEOS-Chem run directories.  Make sure you are in the <tt>perl</tt> directory, and then type:
  
  gcCopyRunDirs
+
  ./gcCopyRunDirs
  
If you do not pass a file name to <tt>gcCopyRunDirs</tt>, then the <tt>gcCopyRunDirs</tt> script will use the <tt>CopyRunDirs.input</tt> file that you just created.   
+
If you do not pass a file name to <tt>gcCopyRunDirs</tt>, then the <tt>gcCopyRunDirs</tt> script will use the <tt>CopyRunDirs.input</tt> file that you just modified.   
  
 
If you wish, you can create many customized copies of <tt>CopyRunDirs.input</tt>.  For example, suppose you edit <tt>CopyRunDirs.input</tt> to generate a full-chemistry run directory. You can then save it as a separate file and use it explicitly with <tt>gcCopyRunDirs</tt>.
 
If you wish, you can create many customized copies of <tt>CopyRunDirs.input</tt>.  For example, suppose you edit <tt>CopyRunDirs.input</tt> to generate a full-chemistry run directory. You can then save it as a separate file and use it explicitly with <tt>gcCopyRunDirs</tt>.
Line 192: Line 279:
 
  cp CopyRunDirs.input CopyRunDirs.fullchem  # Input file set up to only copy the full-chemistry run directories
 
  cp CopyRunDirs.input CopyRunDirs.fullchem  # Input file set up to only copy the full-chemistry run directories
 
    
 
    
  gcCopyRunDirs CopyRunDirs.Hg               
+
  ./gcCopyRunDirs CopyRunDirs.fullchem           
  
Executing <tt>gcCopyRunDirs</tt> will create a new GEOS-Chem run directory corresponding to each entry that you specified in the <tt>CopyRunDirs.*</tt> file.  Each run directory will be created as a subdirectory of <tt>!COPY_PATH</tt>.
+
Executing <tt>gcCopyRunDirs</tt> will create a new GEOS-Chem run 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>geosfp_4x5_fullchem</tt> run directory.  Issue the following commands:
+
Let's examine the contents of a sample <tt>geosfp_4x5_standard</tt> run directory.  Navigate to your newly created run directory and tssue 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
 
  make fileclean                      # Remove any files left over from previous unit test runs
 
   
 
   
  ls -l                               # Get detailed directory listing
+
  ls -1                               # Get directory listing
  
 
And you will see this directory listing:
 
And you will see this directory listing:
  
  -rw-r--r-- 1 mpayer mpayer    7862 2015-04-03 15:19 FJX_j2j.dat
+
  benchmark.run
  -rw-r--r-- 1 mpayer mpayer    44808 2015-04-03 15:19 FJX_spec.dat
+
  GEOSChem.Restart.20160701_0000z.nc4
-rw-r--r-- 1 mpayer mpayer  186359 2015-04-03 15:19 HEMCO_Config.rc
+
  getRunInfo
-rw-r--r-- 1 mpayer mpayer    4872 2015-04-03 15:19 Makefile
+
  HEMCO_Config.rc
-rw-r--r-- 1 mpayer mpayer      783 2015-04-03 15:19 README
+
  HEMCO_Diagn.rc
-rw-r--r-- 1 mpayer mpayer      610 2015-04-03 15:19 chemga.dat
+
  HISTORY.rc
  -rw-r--r-- 1 mpayer mpayer    42186 2015-04-03 15:19 dust.dat
+
  input.geos
  -rwxr-xr-x 1 mpayer mpayer    1458 2015-04-03 15:19 getEnd.pl*
+
  Makefile
  -rwxr-xr-x 1 mpayer mpayer    1374 2015-04-03 15:19 getStart.pl*
+
  output/
  -rw-r--r-- 1 mpayer mpayer  199632 2015-04-03 15:19 globchem.dat
+
  README
  -rw-r--r-- 1 mpayer mpayer  401972 2015-04-03 15:19 initial_hemco_rst.geosfp_4x5_fullchem.nc
+
  validate
-rw-r--r-- 1 mpayer mpayer 41110480 2015-04-03 15:19 initial_trac_rst.geosfp_4x5_fullchem
+
-rw-r--r-- 1 mpayer mpayer    15913 2015-04-03 15:19 input.geos
+
  -rw-r--r-- 1 mpayer mpayer    26194 2015-04-03 15:19 jv_spec_mie.dat
+
  -rw-r--r-- 1 mpayer mpayer      905 2015-04-03 15:19 mglob.dat
+
  -rw-r--r-- 1 mpayer mpayer    42185 2015-04-03 15:19 org.dat
+
-rw-r--r-- 1 mpayer mpayer    42185 2015-04-03 15:19 so4.dat
+
-rw-r--r-- 1 mpayer mpayer    42186 2015-04-03 15:19 soot.dat
+
-rw-r--r-- 1 mpayer mpayer    42185 2015-04-03 15:19 ssa.dat
+
-rw-r--r-- 1 mpayer mpayer    42185 2015-04-03 15:19 ssc.dat
+
  -rwxr-xr-x 1 mpayer mpayer    7303 2015-04-03 15:19 validate*
+
  
 
''NOTE: Run directories for other simulations may contain other files not pictured here.''
 
''NOTE: Run directories for other simulations may contain other files not pictured here.''
  
The <tt>input.geos</tt> and <tt>HEMCO_Config.rc</tt> files have been customized for this particular simulation.  They were created from the corresponding template files <tt>input.geos.template</tt> and <tt>HEMCO_Config.template</tt> in the Unit Tester.
+
The <tt>input.geos</tt> and <tt>HEMCO_Config.rc</tt> files have been customized for this particular simulation.  They were created from the corresponding template files <tt>input.geos.template</tt> and <tt>HEMCO_Config.template</tt> in the Unit Tester. The Perl script <tt>getRunInfo</tt> is used by the Makefile to extract information about the simulation from <tt>input.geos</tt>. HEMCO and tracer restart files are also included in every run directory but care must be taken when using them. See the section below for more information about restart files.
 
+
The Perl scripts <tt>getStart.pl</tt> and <tt>getEnd.pl</tt> pass the starting and ending dates of the simulation, as specified in the <tt>input.geos</tt> file, to the <tt>Makefile</tt>.
+
 
+
--[[User:Bmy|Bob Y.]] 14:24, 19 March 2015 (EDT)<br>
+
--[[User:Melissa Payer|Melissa Sulprizio]] 15:26, 3 April 2015 (EDT)
+
 
+
== Compiling and Running GEOS-Chem ==
+
 
+
Once you have created one or more GEOS-Chem run directories, you can use them for your GEOS-Chem simulations.  First, doublecheck that the settings in the <tt>input.geos</tt> and <tt>HEMCO_Config.rc</tt> files are correct for the simulation that you are trying to run. See the [http://manual.geos-chem.org/ GEOS-Chem Manual] for more information about setting simulation options.
+
 
+
To start a GEOS-Chem simulation, type the following commands.  (We'll use the example of the <tt>geosfp_4x5_fullchem</tt> simulation, from the previous sections.)
+
 
+
make -j4 CODE_DIR=~/GC/Code.v10-01 VERSION=v10-01 MET=geosfp GRID=4x5 TRACEBACK=y mp
+
 
+
The above command specifies: (1) the location of the code to compile (<tt>CODE_DIR</tt>), (2) a version tag to use as a prefix in our data output file (<tt>VERSION</tt>), (3) the met field to use (<tt>MET</tt>), (4) the grid resolution to use (<tt>GRID</tt>), and (5) whether to show traceback for debugging (<tt>TRACEBACK</tt>). The <tt>MET</tt> and <tt>GRID</tt> values must match those for your run directory. If you wish, you can omit the <tt>VERSION</tt> option.  If you do not include <tt>VERSION</tt>, it will automatically be set to <tt>GC</tt>..
+
 
+
The final command <tt>mp</tt> is a makefile target defined in the file <tt>Makefile</tt> within the run directory. In our example, <tt>mp</tt> indicates that our code will be compiled and then run with [[Parallelizing_GEOS-Chem|OpenMP parallelization]]. You can also specify <tt>sp</tt> to compile and run code using a single processor. This will result in output files having the <tt>.sp</tt> rather than <tt>.mp</tt> suffix. See the <tt>Makefile</tt> for other make options and [http://acmg.seas.harvard.edu/geos/doc/man/chapter_3.html#RunDir Section 3.6.2 of the GEOS-Chem Manual] for more information about makefiles.
+
 
+
== GEOS-Chem Output Files ==
+
 
+
Once the GEOS-Chem simulation is complete, you will see several new files in the run directory. Some of these are generated for all simulations while others may be simulation-dependent. For the case of our full-chemistry simulation example, the following files are output:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="350px"|File
+
!width="750px"|Description
+
 
+
|-valign="top"
+
|<tt>trac_avg.geosfp_4x5_fullchem.YYYYMMDDhh.mp</tt> or<br><tt>trac_avg.geosfp_4x5_fullchem.YYYYMMDDhh.sp</tt>
+
|Diagnostic output file that contains time-averaged output for diagnostics enabled in <tt>input.geos</tt>.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap GAMAP].</b>
+
 
+
|-valign="top"
+
|<tt>trac_rst.geosfp_4x5_fullchem.YYYYMMDDhhmm.mp</tt> or<br><tt>trac_rst.geosfp_4x5_fullchem.YYYYMMDDhhmm.sp</tt>
+
|Tracer restart file that contains instantaneous tracer concentrations at simulation end time. This file saves instantaneous concentrations of all transported tracers (listed in the Tracer Menu of <tt>input.geos</tt>) and may be used to initialize another GEOS-Chem simulation.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP].</b>
+
 
+
|-valign="top"
+
|<tt>HEMCO_restart.YYYYMMDDhh.nc.mp</tt> or<br><tt>HEMCO_restart.YYYYMMDDhh.nc.sp</tt>
+
|HEMCO restart file containing several quantities tracked by HEMCO for use in initializing another GEOS-Chem simulation. This file includes data used to calculate [[Hudman_et_al_2012_soil_NOx_emissions_algorithm|soil NOx emissions]], [[Ship_emissions#PARANOX_ship_plume_model|PARANOX ship plume chemistry]], and [[MEGAN_v2.1_plus_Guenther_2012_biogenic_emissions|MEGAN biogenic emissions]].
+
<b>Data in this file are in [http://www.unidata.ucar.edu/software/netcdf/docs/faq.html#whatisit netcdf format].</b>
+
 
+
|-valign="top"
+
|<tt>v10-01.geosfp_4x5_fullchem.mp</tt> or<br><tt>v10-01.geosfp_4x5_fullchem.sp</tt>
+
|GEOS-Chem simulation log file.
+
<b>Open this file in a text editor to diagnose compile and run errors.</b>
+
 
+
|-valign="top"
+
|<tt>HEMCO.log.mp</tt> or<br><tt>HEMCO.log.sp</tt>
+
|HEMCO log file containing detailed information about the emissions read from disk into HEMCO.
+
<b>Open this file in a text editor to diagnose HEMCO errors.</b>
+
 
+
|-valign="top"
+
|<tt>smv2.log</tt>
+
|SMVGEAR II log file containing information about reactions and species used by the ND65 prod-loss diagnostic. This file is only produced when SMVGEAR, and thus it will not be created for the [[GEOS-Chem_chemistry_mechanisms#Specialty_simulations|specialty simulations]].
+
<b>Open this file in a text editor to see if SMVGEAR read the <tt>globchem.dat file properly</tt>. </b>
+
 
+
|-valign="top"
+
|<tt>diaginfo.dat</tt>
+
|File generated by GEOS-Chem that contains diagnostic quantities for use with [http://acmg.seas.harvard.edu/gamap/ GAMAP].
+
 
+
|-valign="top"
+
|<tt>tracerinfo.dat</tt>
+
|File generated by GEOS-Chem that contains tracer name metadata for use with [http://acmg.seas.harvard.edu/gamap/ GAMAP].
+
|}
+
 
+
 
+
Additional files may be created by GEOS-Chem, depending on your simulation type and the options specified in the <tt>input.geos</tt> file. Other optional GEOS-Chem output files include:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="350px"|File
+
!width="750px"|Description
+
 
+
|-valign="top"
+
|<tt>spec_rst.geosfp_4x5_fullchem.YYYYMMDDhh</tt>
+
|Species restart file that contains instantaneous species concentrations at simulation end time. This file saves instantaneous concentrations of all chemical species (listed in <tt>globchem.dat</tt>) on all levels for continuation and may be used to initialize another GEOS-Chem simulation.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP].</b>
+
 
+
|-valign="top"
+
|<tt>stations.YYYYMMDDhh</tt>
+
|Diagnostic output file that contains ND48 station timeseries output as specified in <tt>input.geos</tt>.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP]. For more information on working with ND48 timeseries output, see our [http://acmg.seas.harvard.edu/gamap/doc/timeseries_brief_tutorial.pdf timeseries tutorial].</b>
+
 
+
|-valign="top"
+
|<tt>tsYYYYMMDDhh.bpch</tt>
+
|Diagnostic output file that contains ND49 instantaneous timeseries output as specified in <tt>input.geos</tt>.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP]. For more information on working with ND49 timeseries output, see our [http://acmg.seas.harvard.edu/gamap/doc/timeseries_brief_tutorial.pdf timeseries tutorial].</b>
+
 
+
|-valign="top"
+
|<tt>ts_24hr_avg.YYYYMMDDhh.bpch</tt>
+
|Diagnostic output file that contains ND50 24-hour average timeseries output as specified in <tt>input.geos</tt>.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP].</b>
+
 
+
|-valign="top"
+
|<tt>ts_satellite.YYYYMMDDhh.bpch</tt>
+
|Diagnostic output file that contains ND51 local-time-average (satellite) timeseries output as specified in <tt>input.geos</tt>.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP].</b>
+
 
+
|-valign="top"
+
|<tt>paranox_ts.YYYYMMDDhh.bpch</tt>
+
|Diagnostic output file that contains ND63 ship timeseries output as specified in <tt>input.geos</tt>.
+
<b>Data in this file are in [http://acmg.seas.harvard.edu/gamap/doc/Chapter_6.html#6.2 "binary punch" format] and may be viewed and manipulated using [http://acmg.seas.harvard.edu/gamap/ GAMAP].</b>
+
 
+
|-valign="top"
+
|<tt>ocean_rst.YYYYMMDDhhmm.nc</tt>
+
|Ocean mercury restart file containing several quantities pertaining to the ocean mercury module saved at the end of the GEOS-Chem simulation. Like the tracer restart file, this file may be used to initialize another GEOS-Chem [[Mercury|mercury simulation]].
+
<b>Data in this file are in the in [http://www.unidata.ucar.edu/software/netcdf/docs/faq.html#whatisit netcdf format].</b>
+
 
+
|-valign="top"
+
|<tt>plane.log.YYYYMMDD</tt?>
+
|Diagnostic output file containing planeflight information scheduled via the [http://acmg.seas.harvard.edu/geos/doc/man/chapter_5.html#Planeflight <tt>Planeflight.dat</tt>] file. This diagnostic is turned on in the Planeflight Menu of <tt>input.geos</tt>.
+
<b>The data in this text file can be read and plotted using GAMAP routines [http://acmg.seas.harvard.edu/gamap/doc/by_alphabet/gamap_c.html#CTM_READ_PLANEFLIGHT <tt>CTM_READ_PLANEFLIGHT</tt>] and [http://acmg.seas.harvard.edu/gamap/doc/by_alphabet/gamap_p.html#PLANE_PLOT <tt>PLANE_PLOT</tt>].
+
 
+
|}
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] 15:42, 3 April 2015 (EDT)
+
 
+
== Available run directories ==
+
 
+
Here we summarize the run directories that are available in the [[GEOS-Chem Unit Tester]]. Please choose the run directory or run directories that are most relevant for your research.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="100px"|Met field
+
!width="175px"|Resolution
+
!width="100px"|[[NOx-Ox-HC-aerosol|Full-<br>chem]]
+
!width="100px"|[[UCX_chemistry_mechanism|UCX]]
+
!width="100px"|[[Coupling_GEOS-Chem_with_RRTMG|RRTMG]]
+
!width="100px"|[[Secondary_organic_aerosols|SOA]]
+
!width="100px"|[[Secondary_organic_aerosols#SOA_simulation_with_semi-volatile_POA|SOA w/<br>SVPOA]]
+
!width="100px"|[[Rn-Pb-Be_simulation|Rn-<br>Pb-Be]]
+
!width="100px"|[[Mercury|Hg]]
+
!width="100px"|[[POPs_simulation|POPs]]
+
!width="100px"|[[Tagged_CO_simulation|Tag CO]]
+
!width="100px"|[[Tagged_O3_simulation|Tag O3]]
+
!width="100px"|[[CH4_simulation|CH4]]
+
!width="100px"|[[CO2_simulation|CO2]]
+
!width="100px"|[[Aerosol-only_simulation|Aer-<br>osols]]
+
!width="100px"|[[TOMAS_aerosol_microphysics|TOMAS]]
+
 
+
|-valign="top"
+
|[[GEOS-FP]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5&deg;]
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
 
+
|-valign="top"
+
|[[GEOS-FP]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_2x25 2&deg; x 2.5&deg;]
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-FP]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_025_CH 0.25&deg; x 0.3125&deg;<br>nested CH]
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-FP]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_025_NA 0.25&deg; x 0.3125&deg;<br>nested NA]
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-bgcolor="#CCCCCC" height="10px"
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-5]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5&deg;]
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
 
+
|-valign="top"
+
|[[GEOS-5]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_2x25 2&deg; x 2.5&deg;]
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-5]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_05_CH 0.5&deg; x 0.666&deg;<br>nested CH]
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-5]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_05_NA 0.5&deg; x 0.666&deg;<br>nested NA]
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-bgcolor="#CCCCCC"
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[MERRA]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5&deg;]
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|
+
 
+
|-valign="top"
+
|[[MERRA]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_2x25 2&deg; x 2.5&deg;]
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-bgcolor="#CCCCCC" height="10px"
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-4]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5&deg;]
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|
+
 
+
|-bgcolor="#CCCCCC" height="10px"
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GCAP]]
+
|[http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GCAP_4x5 4&deg; x 5&deg;]
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|}
+
 
+
'''LEGEND'''
+
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top"
+
|width="75px" bgcolor="#00FF00"|
+
|width="250px"|Run directory is available
+
 
+
|-valign="top"
+
|bgcolor="#FFFF00"|
+
|Run directory is in need of updating
+
 
+
|-valign="top"
+
|bgcolor="#FF0000"|
+
|Run directory is obsolete 
+
 
+
|-valign="top"
+
|
+
|Run directory is not available
+
 
+
|}
+
--[[User:Melissa Payer|Melissa Sulprizio]] 17:52, 1 April 2015 (EDT)
+
  
=== Run directory tips and tricks ===
 
*In each run directory, we provide a GEOS-Chem restart file that you can use to initialize your simulation. However, it is highly recommended that you not use these restart files for any of your production runs. Rather, you will probably want to generate your own restart file by spinning up the model for at least a year.
 
* You can create a run directory for the [[GEOS-Chem_nested_grid_simulations|nested grid simulations]] from a 4&deg; x 5&deg; or 2&deg; x 2.5&deg; run directory by following these steps:
 
:# Modify the <tt>input.geos</tt> file for the nested grid simulation. Complete instructions can be found on [[Setting_up_GEOS-Chem_nested_grid_simulations|this wiki page]].
 
:# Regrid the restart file(s) using the [http://acmg.seas.harvard.edu/gamap/doc/by_category/Regridding.html GAMAP regridding routines]. For example, [http://acmg.seas.harvard.edu/gamap/doc/by_category/Regridding.html#REGRIDH_RESTART REGRIDH_RESTART] can be used to regrid the tracer restart file from one horizontal resolution to another. You can then use [http://acmg.seas.harvard.edu/gamap/doc/by_alphabet/gamap_c.html#CREATE_NESTED CREATE_NESTED] to crop the restart file to your nested domain (CH, EU, or NA).
 
* You can create a [[MERRA]] run directory from a [[GEOS-5]] or [[GEOS-FP]] run directory, since all three met fields have the same horizontal and vertical resolution.
 
* If you would like to run a simulation and the run directory is not available in the Unit Tester, you can follow these steps:
 
:# Modify the <tt>input.geos</tt> file for your simulation type following the relevant checklist in [http://acmg.seas.harvard.edu/geos/doc/man/contents.html# Chapter 6 of the GEOS-Chem Manual].
 
:# Create a "fake" restart file using GAMAP routine [http://acmg.seas.harvard.edu/gamap/doc/by_alphabet/gamap_m.html#MAKE_RESTART MAKE_RESTART].
 
:# Alternatively, you can send an email to the relevant [http://acmg.seas.harvard.edu/geos/geos_working_groups.html Working Group] to see if another member can provide you with a run directory or restart file.
 
*The [[GEOS-Chem Unit Tester]] can be used to create run directories for [[GEOS-Chem v10-01]] and later versions. If you wish to download a run directory for an older version of GEOS-Chem, you can follow [http://acmg.seas.harvard.edu/geos/doc/archive/man.v9-02/chapter_2.html#DownRun these instructions].
 
  
--[[User:Melissa Payer|Melissa Sulprizio]] 18:23, 1 April 2015 (EDT)
+
----
 +
'''''[[Downloading_data_from_Amazon_Web_Services_cloud_storage|Previous]] | [[GEOS-Chem configuration files|Next]] | [[Getting Started with GEOS-Chem]]'''''

Revision as of 18:36, 10 August 2022

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements (and software installation)
  2. Configuring your computational environment
  3. Downloading source code
  4. Downloading data directories
  5. Creating run directories
  6. Configuring runs
  7. Compiling
  8. Running
  9. Output files
  10. Python tools for use with GEOS-Chem
  11. Coding and debugging
  12. Further reading


The method that you will use to download run directories changed in GEOS-Chem 13.0.0.

For GEOS-Chem 13.0.0 and later versions

This content has been migrated to the Create a run directory chapter of geos-chem.readthedocs.io.

For GEOS-Chem 12.9.3 and prior versions

NOTE: The GEOS-Chem Unit Tester was retired for GEOS-Chem 13.0.0 and later versions.
This content is now outdated, but we will preserve it here for reference.


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 these commands:

git clone https://github.com/geoschem/geos-chem-unittest UT
cd UT
git checkout master

This will download a fresh copy of the GEOS-Chem-UnitTest repository into a directory named UT, and place you in the master branch. The master branch always corresponds to the last benchmarked GEOS-Chem version.

If you would like to check out the Unit Tester that corresponds to a specific numbered GEOS-Chem version you can type one of the following commands:

git checkout 12.0.0
git checkout v11-02-rc
git checkout v11-02e

etc.

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

--Bob Yantosca (talk) 21:10, 21 June 2018 (UTC)

Available run directories

Benchmark run directory

The GEOS-Chem Unit Tester includes a run directory called 4x5_standard (GEOS-Chem v11-01 and later) or 4x5_benchmark (GEOS-Chem v10-01). The standard GEOS-Chem benchmark simulation utilizes the GEOS-FP met fields (4° x 5 °, 72 levels) with the UCX tropospheric-stratospheric chemistry mechanism and secondary organic aerosols included.

To reproduce our latest 1-month benchmark simulation, you can edit the CopyRunDirs.input file so that the following line is uncommented under RUNS:

 geosfp   4x5         -      benchmark     2016070100   2016080100   -

Make sure to check the start and end date so that your simulation will run for July 2016. You can then create the GEOS-Chem benchmark run directory by typing ./gcCopyRunDirs. Navigate to your the newly created geosfp_4x5_benchmark run directory. To compile the GEOS-Chem source code, type:

make -j4 build

That will create a geos.mp executable file that you can use to submit your GEOS-Chem benchmark simulation to a queue system.

For older versions of GEOS-Chem, the compile command was formerly

make -j4 mpbuild

Other run directories

Run directories are provided for a combination of met field, grid, and simulation type and are named accordingly. For more details on the simulation types, please see our GEOS-Chem chemistry mechanism wiki page.

Editing the CopyRunDirs.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 gcCopyRunDirs that you will use to generate fresh copies of GEOS-Chem run directories. This script uses an input file named CopyRunDirs.input, which is also located in the perl directory.

IMPORTANT: The CopyRunDirs.input file that comes with the Unit Tester provides only a small sample of the possible run directories that you can create. You can add as many entries to the RUNS section as you wish. See the UnitTest.input file for a complete list of all possible run directories that you can add to CopyRunDirs.input.

Your CopyRunDirs.input file will look something like this:

#------------------------------------------------------------------------------
#                  GEOS-Chem Global Chemical Transport Model                  !
#------------------------------------------------------------------------------
#BOP
#
# !DESCRIPTION: Input file that specifies configuration for creating and
#  copying a run 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: 
#  18 Mar 2015 - R. Yantosca - Initial version
#  19 Mar 2015 - E. Lundgren - Simplify content for only copying run dirs
#  19 May 2015 - R. Yantosca - Now can specify VERBOSE and WARNINGS options
#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
#
# %%% Target directory and copy command %%%
# 
   COPY_PATH      : {HOME}/GC/rundirs
   COPY_CMD       : cp -rfL
#
# !RUNS:
#  Specify the runs directories that you want to copy below.
#  Here we provide a few examples, but you may copy additional entries from
#  UnitTest.input and modify the dates as needed. You can deactivate copying
#  run certain directories by commenting them out with "#".
#
#--------|-----------|------|------------|------------|------------|---------|
# MET    | GRID      | NEST | SIMULATION | START DATE | END DATE   | EXTRA?  |
#--------|-----------|------|------------|------------|------------|---------|
  geosfp   4x5         -      standard     2013070100   2013080100   -
# geosfp   4x5         -      gc_timing    2013070100   2013070800   -
# 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   201307010030 -
# geosfp   4x5         -      aerosol      2013070100   2013070101   - 
# geosfp   025x03125   ch     tropchem     2013070100   201307010010 -
# geosfp   025x03125   na     tropchem     2013070100   201307010010 -
# gchp     4x5         -      tropchem     2013070100   2013070101   -
!END OF RUNS:
#EOP
#------------------------------------------------------------------------------

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

The CopyRunDirs.input file has a layout that is very similar to the GEOS-Chem Unit Tester input files (UnitTest.input located within this directory). Like the GEOS-Chem Unit Tester input files, CopyRunDirs.input is composed of an INPUTS section and a RUNS section, which are described below.

Section 1: INPUTS

Under the INPUTS section, you can customize the directory paths and other options for your system. Each configurable input is described in the table below.

Option Description
VERSION An ID tag that will be added to all log files and output files.
DESCRIPTION A short (1-sentence) description of the purpose of this specific file (optional). This may be used to differentiate different input files, such as if you pre-configure several for future re-use.
DATA_ROOT Specifies the path for your root-level data directory.
HEMCO_ROOT Specifies the top-level path for the HEMCO data directory tree.
  • The {DATAROOT} token in HEMCO_ROOT will be replaced with the value you specify for RUN_ROOT option.

Leave this as-is.

VERBOSE Specifies the level of debug output that will be sent to the HEMCO log file. (0=no debug output; 3=max debug output)
  • Recommended setting: 0
WARNINGS Specifies the level of warning messages that will be sent to the HEMCO log file. (0=no warnings; 3=max warnings)
  • Recommended setting: 1
UNIT_TEST_ROOT Specifies the path to the GEOS-Chem Unit Tester.
RUN_ROOT Specifies the top-level unit test run directories.

Leave this as-is.

RUN_DIR Specifies the run directory subdirectory.

Leave this as-is.

PERL_DIR Specifies the directory where the unit test Perl scripts are found.

Leave this as-is.

COPY_PATH Specifies the directory on your disk server where copies of the GEOS-Chem run directories will be created.
COPY_CMD Specifies the command used to copy run directories from the GEOS-Chem Unit Tester to COPY_PATH.
  • The default setting is cp -rfL. This will create a new copy of the directory, even if the prior copy exists.
  • The -L option to the cp will create "hard" copies of files that are symbolic links. This command may differ slightly depending on the flavor of your Unix-based Operating system.

Section 2: RUNS

The layout of the RUNS section is identical to the RUNS section in the GEOS-Chem Unit Tester input file. This enables copying and pasting simulation settings text from UnitTest.input into CopyRunDirs.input.

For example, the following line:

#
# !RUNS:
#  Specify the debugging runs that you want to perform below.
#  You can deactivate runs by commenting them out with "#".
#
#--------|-----------|------|------------|------------|------------|---------|
# MET    | GRID      | NEST | SIMULATION | START DATE | END DATE   | EXTRA?  |
#--------|-----------|------|------------|------------|------------|---------|
  geosfp   4x5         -      standard     2013070100   2013080100   -

will tell the gcCopyRunDirs script to create a run directory for a GEOS-Chem simulation with the following settings:

The date range will be used to initialize the input.geos file that is read during a GEOS-Chem simulation. Once the run directory is created, you may edit these dates within the input.geos file. Note, however, that time ranges must remain within the time range covered by the MET field you are using. You can check the MET field temporal coverage on the GMAO met data products wiki page. Also note that we recommend using the restart files to spin up GEOS-Chem for at least one year prior to your simulation start date. You may use the resulting output restart files as initial values for your simulation.

You can add as many entries to the RUNS section as you wish. See the UnitTest.input file for a complete list of all possible run directories entries that you can add to CopyRunDirs.input.

Generating a GEOS-Chem Run Directory

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

./gcCopyRunDirs

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

If you wish, you can create many customized copies of CopyRunDirs.input. For example, suppose you edit CopyRunDirs.input to generate a full-chemistry run directory. You can then save it as a separate file and use it explicitly with gcCopyRunDirs.

cp CopyRunDirs.input CopyRunDirs.fullchem   # Input file set up to only copy the full-chemistry run directories
 
./gcCopyRunDirs CopyRunDirs.fullchem            

Executing gcCopyRunDirs will create a new GEOS-Chem run 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 geosfp_4x5_standard run directory. Navigate to your newly created run directory and tssue the following commands:

make fileclean                       # Remove any files left over from previous unit test runs

ls -1                                # Get directory listing

And you will see this directory listing:

benchmark.run
GEOSChem.Restart.20160701_0000z.nc4
getRunInfo
HEMCO_Config.rc
HEMCO_Diagn.rc
HISTORY.rc
input.geos
Makefile
output/
README
validate

NOTE: Run directories for other simulations may contain other files not pictured here.

The input.geos and HEMCO_Config.rc files have been customized for this particular simulation. They were created from the corresponding template files input.geos.template and HEMCO_Config.template in the Unit Tester. The Perl script getRunInfo is used by the Makefile to extract information about the simulation from input.geos. HEMCO and tracer restart files are also included in every run directory but care must be taken when using them. See the section below for more information about restart files.



Previous | Next | Getting Started with GEOS-Chem