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

From Geos-chem
Jump to: navigation, search
(The RUNS section)
 
(157 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 fresh copies of run directories for your GEOS-Chem simulations.
+
__FORCETOC__
 +
'''''[[Downloading_data_from_Amazon_Web_Services_cloud_storage|Previous]] | [[Creating run directories for GEOS-Chem 13.0.0 and later|Next]] | [[Getting Started with GEOS-Chem]]'''''
 +
#[[Minimum system requirements for GEOS-Chem|Minimum system requirements]]
 +
#[[Installing required software]]
 +
#[[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>
 +
#*[[Creating run directories for GEOS-Chem 13.0.0 and later|... for GEOS-Chem 13.0.0 and later versions]]
 +
#*[[Creating run directories for GEOS-Chem 12.9.3 and prior|... for GEOS-Chem 12.9.3 and prior versions]]
 +
#[[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.)
+
== Overview ==
  
Next, clone the GEOS-Chem unit tester package with the command:
+
The method that you will use to download run directories changed in [[GEOS-Chem 13.0.0]].  Detailed instructions for downloading GEOS-Chem source code may be found in the links below:
 
+
git clone -b v10-01-public git://git.as.harvard.edu/bmy/GEOS-Chem-UnitTest UT
+
 
+
This will create a copy of the GEOS-Chem Unit Tester package in a directory named <tt>UT</tt> for short. 
+
 
+
The option
+
 
+
-b v10-01-public
+
 
+
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]].
+
 
+
--[[User:Bmy|Bob Y.]] 13:36, 19 March 2015 (EDT)
+
 
+
== 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:
+
 
+
  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. 
+
 
+
Your <tt>CopyRunDirs.input</tt> 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: 
+
#  Customize the run directory for your system by specifying these values:
+
#  -------------------------------------------------------------------
+
#  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
+
#  COPY_PATH  : Local path where run directory will be copied to
+
#  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:
+
#  18 Mar 2015 - R. Yantosca - Initial version
+
#  19 Mar 2015 - E. Lundgren - Simplify content for only copying run dirs
+
#EOP
+
#------------------------------------------------------------------------------
+
#
+
# !INPUTS:
+
#
+
    VERSION    : v10-01h
+
    DESCRIPTION : Create run directory from UnitTest
+
    COPY_PATH  : /home/{USER}/GC/rundirs
+
    DATA_ROOT  : /as/data/geos/ExtData
+
    HEMCO_ROOT  : {DATAROOT}/HEMCO
+
    RUN_ROOT    : /home/{USER}/UT/runs
+
    RUN_DIR    : {RUNROOT}/{RUNDIR}
+
    PERL_DIR    : /home/{USER}/UT/perl
+
    COPY_CMD    : cp -rfL
+
#
+
# !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  2x25        -      Hg          2013070100  2013070101  -
+
  geos5    2x25        -      Hg          2005070100  2005070101  -
+
  geosfp  4x5        -      fullchem    2013070100  2013070101  -
+
  geos4    4x5        -      Hg          2005070100  2005070101  -
+
  geos4    4x5        -      CH4          2005070100  2005070101  -
+
  geosfp  4x5        -      Hg          2013070100  2013070101  -
+
  geosfp  4x5        -      POPs        2013070100  2013070101  -
+
!END OF RUNS:
+
#EOP
+
#------------------------------------------------------------------------------
+
 
+
''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 INPUTS section ===
+
 
+
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.
+
  
 
{| border=1 cellspacing=0 cellpadding=5  
 
{| border=1 cellspacing=0 cellpadding=5  
|-bgcolor="#CCCCCC"
+
|- bgcolor="#CCCCCC"
!width="100px"|Option
+
!width="300px"|If you are using
!width="825px"|Description
+
!width="500px"|Then please read this chapter
  
 
|-valign="top"
 
|-valign="top"
|<tt>VERSION</tt>
+
|[[GEOS-Chem 13.0.0]] or later
|An ID tag that will be added to all log files and output files.
+
|''[[Creating run directories for GEOS-Chem 13.0.0 and later]]''
  
 
|-valign="top"
 
|-valign="top"
|<tt>DESCRIPTION</tt>
+
|[[GEOS-Chem 12#12.9.3|GEOS-Chem 12.9.3]] or earlier
|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.
+
|''[[Creating run directories for GEOS-Chem 12.9.3 and prior]]''
 
+
|-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"
+
|<tt>DATA_ROOT</tt>
+
|Specifies the path for your root-level data directory.
+
 
+
|-valign="top"http://wiki.seas.harvard.edu/geos-chem/skins//common/images/button_nowiki.png
+
|<tt>HEMCO_ROOT</tt>
+
|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. 
+
<b>Leave this as-is.</b>
+
 
+
|-valign="top"
+
|<tt>RUN_ROOT</tt>
+
|Specifies the top-level unit test run directories. 
+
<b>Leave this as-is.</b>
+
 
+
|-valign="top"
+
|<tt>PERL_DIR</tt>
+
|Specifies the directory where the unit test Perl scripts are found.
+
<b>Leave this as-is.</b>
+
 
+
|-valign="top"
+
|<tt>COPY_CMD</tt>
+
|Specifies the command used to copy run directories from the GEOS-Chem Unit Tester to <tt>COPY_PATH</tt>.
+
*The default setting is <tt>cp -rfL</tt>. This will create a new copy of the directory, even if the prior copy exists.
+
*The <tt>-L</tt> option to the <tt>cp</tt> 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.
+
  
 
|}
 
|}
  
--[[User:Bmy|Bob Y.]] 14:20, 19 March 2015 (EDT)
 
 
=== The RUNS section ===
 
 
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>.
 
 
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  2x25        -      Hg          2013070100  2013070101  -
 
 
will tell the <tt>gcCopyRunDirs</tt> script to create a run directory for a GEOS-Chem simulation using:
 
 
*[[GEOS-FP]] met fields
 
*On the [http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_2x25 2&deg; x 2.5&deg; GEOS-Chem horizontal grid]
 
*For the [[Mercury|GEOS-Chem Hg specialty simulation]]
 
*Starting at 00:00 GMT on 2013/07/01
 
*Ending at 01:00 GMT on 2013/07/01
 
 
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 [http://wiki.seas.harvard.edu/geos-chem/index.php/Overview_of_GMAO_met_data_products; GMAO met data products wiki page].
 
 
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>).
 
 
== Generating copies of run directories ==
 
 
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
 
 
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 wish, you can create many customized copies of <tt>CopyRunDirs.input</tt>.  For example, suppose you edit CopyRunDirs.input to generate a mercury run directory. You can then save it as a separate file and use it explicitly with gcCopyRunDirs.
 
 
cp CopyRunDirs.input CopyRunDirs.Hg  # Input file set up to only copy the Hg run directories
 
 
 
gcCopyRunDirs CopyRunDirs.Hg               
 
 
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(s).  Run directories will be created as subdirectories of <tt>!COPY_PATH</tt>.
 
 
Let's examine the contents of of a sample <tt>geosfp_2x25_Hg</tt> run directory.  Issue the following commands:
 
 
cd ~/GC/rundirs/geosfp_2x25_Hg  # Change to geosfp_2x25_Hg run dir
 
 
 
make fileclean                  # Remove any files left over from previous unit test runs
 
 
ls -l                          # Get detailed directory listing
 
 
And you will see this directory listing:
 
 
-rw-r--r-- 1 bmy bmy  17137 2015-03-18 16:18 HEMCO_Config.rc
 
-rw-r--r-- 1 bmy bmy  17116 2015-03-18 16:18 HEMCO_Config.template
 
-rw-r--r-- 1 bmy bmy    4568 2015-03-18 16:18 Makefile
 
-rwxr-xr-x 1 bmy bmy    1458 2015-03-18 16:18 getEnd.pl*
 
-rwxr-xr-x 1 bmy bmy    1374 2015-03-18 16:18 getStart.pl*
 
-rw-r--r-- 1 bmy bmy 7391476 2015-03-18 16:18 initial_trac_rst.geosfp_2x25_Hg
 
-rw-r--r-- 1 bmy bmy  12082 2015-03-18 16:20 input.geos
 
-rw-r--r-- 1 bmy bmy  12060 2015-03-18 16:18 input.geos.template
 
-rw-r--r-- 1 bmy bmy  210712 2015-03-18 16:18 ocean_rst.geosfp_2x25_Hg.201307010000
 
 
''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>.  The template files are otherwise not used.
 
 
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)
 
 
== 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.  (We invite you to consult 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>geos5_2x25_Hg</tt> simulation, from the previous sections.)
 
 
make -j4 CODE_DIR=~/GC/Code.v10-01 VERSION=v10-01 MET=geosfp GRID=2x25 TRACEBACK=y mp
 
 
This will create the following output files:
 
 
{| border=1 cellspacing=0 cellpadding=5
 
|-bgcolor="#CCCCCC"
 
!width="350px"|File
 
!width="750px"|Description
 
|-valign="top"
 
|<tt>HEMCO.log.mp</tt>
 
|This is the HEMCO log file.  Detailed information about the emissions that are being read from disk into HEMCO will be sent here.  You can look at this file in order to determine there was an error in HEMCO caused by invalid input in the <tt>HEMCO_Config.rc</tt> file.
 
|-valign="top"
 
|<tt>HEMCO_restart.YYYYMMDDhh.nc</tt>
 
|This is the HEMCO restart file.  Several quantities that are tracked by HEMCO are saved here, so that they can be used to initialize another GEOS-Chem simulation.
 
|-valign="top"
 
|<tt>v10-01.geosfp_2x25_Hg.mp</tt>
 
|This is the log file from the GEOS-Chem simulation.
 
|-valign="top"
 
|<tt>trac_avg.geosfp_2x25_Hg.YYYYMMDDhh.mp</tt>
 
|This is the diagnostic output file (aka the "binary punch file") that contains time-averaged output.
 
|-valign="top"
 
|<tt>trac_rst.geosfp_2x25_Hg.YYYYMMDDhhmm.mp</tt>
 
|This is the GEOS-Chem tracer restart file.  Tracer concentrations are saved here so that they can be used to initialize another GEOS-Chem simulation.
 
|-valign="top"
 
|<tt>ocean_rst.YYYYMMDDhhmm.nc</tt>
 
|This is the ocean mercury restart file.  This file is only produced by the [[Mercury|GEOS-Chem mercury specialty simulation]].  Several quantities pertaining to the ocean mercury module are saved here so that they can be used to initialize another GEOS-Chem mercury simulation 
 
|-valign="top"
 
|<tt>diaginfo.dat</tt>
 
|Contains diagnostic quantities for GAMAP.  This file is created by GEOS-Chem.
 
|-valign="top"
 
|<tt>tracerinfo.dat</tt>
 
|Contains tracer name metadata for GAMAP.  This file is created by GEOS-Chem.
 
 
|}
 
 
NOTE: If you wish, you can omit the <tt>VERSION</tt> option.  In this case, the version ID string will automatically be set to <tt>GC</tt> and the GEOS-Chem log file name will be <tt>GC.geosfp_2x25_Hg.mp</tt>, etc.
 
 
If you wish, you can also start a GEOS-Chem simulation without OpenMP parallelization by typing:
 
 
make -j4 CODE_DIR=~/GC/Code.v10-01 VERSION=v10-01 MET=geosfp GRID=2x25 TRACEBACK=y sp
 
 
In this case the output files in the table above will have the <tt>.sp</tt> suffix instead of <tt>.mp</tt>.
 
  
--[[User:Bmy|Bob Y.]] 15:58, 19 March 2015 (EDT)
+
----
 +
'''''[[Downloading_data_from_Amazon_Web_Services_cloud_storage|Previous]] | [[Creating run directories for GEOS-Chem 13.0.0 and later|Next]] | [[Getting Started with GEOS-Chem]]'''''

Latest revision as of 21:30, 8 December 2020

Previous | Next | Getting Started with GEOS-Chem

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


Contents

Overview

The method that you will use to download run directories changed in GEOS-Chem 13.0.0. Detailed instructions for downloading GEOS-Chem source code may be found in the links below:

If you are using Then please read this chapter
GEOS-Chem 13.0.0 or later Creating run directories for GEOS-Chem 13.0.0 and later
GEOS-Chem 12.9.3 or earlier Creating run directories for GEOS-Chem 12.9.3 and prior



Previous | Next | Getting Started with GEOS-Chem