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

From Geos-chem
Jump to: navigation, search
(Generating a GEOS-Chem Run Directory)
(48 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]] | [[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 <nowiki>https://bitbucket.org/gcst/geos-chem-unittest</nowiki> UT
+
 
+
This will create a copy of the GEOS-Chem Unit Tester package in a directory named <tt>UT</tt> for short. 
+
 
+
''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]]) 15:12, 20 December 2016 (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 '''geosfp_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 [[GEOS-Chem_v11-01_benchmark_history#v11-01k|1-month benchmark simulation for v11-01]], you can edit the <tt>CopyRunDirs.input</tt> file so that the following line is uncommented under <tt>RUNS</tt>:
+
 
+
  geosfp  4x5        -      standard    2013070100  2013080100  -
+
 
+
Make sure to check the start and end date so that your simulation will run for July 2013. 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 and run your benchmark simulation, type:
+
 
+
make -j4 mp
+
 
+
To compile only, type:
+
 
+
make -j4 mpbuild
+
 
+
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.
+
 
+
<span style="color:darkorange">'''''NOTE: If you are compiling GEOS-Chem within the code directory, and not within a run directory created from the GEOS-Chem Unit Tester, you will need to pass the <tt>UCX=y</tt> option in your <tt>make</tt> command.'''''</span>
+
 
+
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:38, 23 June 2015 (UTC)
+
 
+
=== 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]].
+
 
+
The following table summarizes the run directories that are available in the [[GEOS-Chem Unit Tester]]. Please choose the run directories that are most relevant for your research.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-bgcolor="#CCCCCC"
+
!width="100px"|Met field(s)
+
!width="200px"|Grid
+
!width="100px"|[[GEOS-Chem_chemistry_mechanisms#Mechanisms_in_GEOS-Chem_v10-01_and_later_versions|Standard]]
+
!width="100px"|[[NOx-Ox-HC-aerosol|Tropchem]]
+
!width="100px"|[[UCX chemistry mechanism|UCX]]
+
!width="100px"|[[Secondary organic aerosols|SOA]]
+
!width="100px"|[[Secondary organic aerosols#SOA simulation with semi-volatile POA|SOA-SVPOA]]
+
!width="100px"|[[Mineral_dust_aerosols#Surface_chemistry_on_dust|AcidUptake]]
+
!width="100px"|[[Aerosol_emissions#Online_emission_of_marine_primary_organic_aerosol_.28POA.29|MarinePOA]]
+
!width="100px"|[[Coupling GEOS-Chem with RRTMG|RRTMG]]
+
!width="100px"|[[Rn-Pb-Be simulation|RnPbBe]]
+
!width="100px"|[[Mercury|Hg]]
+
!width="100px"|[[Mercury|tagHg]]
+
!width="100px"|[[POPs simulation|POPs]]
+
!width="100px"|[[Tagged CO simulation|tagCO]]
+
!width="100px"|[[Tagged O3 simulation|tagO3]]
+
!width="100px"|[[CH4 simulation|CH4]]
+
!width="100px"|[[CO2 simulation|CO2]]
+
!width="100px"|[[Aerosol-only simulation|aerosol]]
+
!width="100px"|[[TOMAS aerosol microphysics|TOMAS15]]
+
!width="100px"|[[TOMAS aerosol microphysics|TOMAS40]]
+
 
+
|-valign="top"
+
|[[GEOS-FP]]<br>[[GEOS-5]]<br>[[MERRA]]<br>[[MERRA-2]]
+
|[[GEOS-Chem_horizontal_grids#GMAO_4_x_5_grid|4x5]]
+
|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"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
 
+
|-valign="top"
+
|[[GEOS-FP]]<br>[[GEOS-5]]<br>[[MERRA]]<br>[[MERRA-2]]
+
|[[GEOS-Chem_horizontal_grids#GMAO_2_x_2.5_grid|2x2.5]]
+
|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"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|
+
 
+
|-bgcolor="#cccccc"
+
!colspan="21"|Nested grid simulations:
+
 
+
|-valign="top"
+
|[[GEOS-FP]]
+
|[[GEOS-Chem_horizontal_grids#0.25_x_0.3125_CH_nested_grid|025x03125<br>CH]]
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-FP]]
+
|[[GEOS-Chem_horizontal_grids#0.25_x_0.3125_NA_nested_grid|025x03125<br>NA]]
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-5]]
+
|[[GEOS-Chem_horizontal_grids#0.5_x_0.666_CH_nested_grid|05x0666<br>CH]]
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GEOS-5]]
+
|[[GEOS-Chem_horizontal_grids#0.5_x_0.666_NA_nested_grid|05x0666<br>NA]]
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
 
+
|-bgcolor="#cccccc"
+
!colspan="21"|Other:
+
 
+
|-valign="top"
+
|[[GMAO_GEOS-4|GEOS-4]]
+
|[[GEOS-Chem_horizontal_grids#GMAO_4_x_5_grid|4x5]]
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
|
+
|
+
|
+
|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|bgcolor="#00FF00"|
+
|
+
|bgcolor="#00FF00"|
+
|
+
|
+
 
+
|-valign="top"
+
|[[GCAP]]
+
|[[GEOS-Chem_horizontal_grids#GMAO_4_x_5_grid|4x5]]
+
|
+
|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]] ([[User talk:Melissa Payer|talk]]) 20:10, 8 December 2016 (UTC)
+
 
+
== Editing the CopyRunDirs.input file ==
+
 
+
Once you have 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:
+
#  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 <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]] (<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 ===
+
 
+
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  
|-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>DATA_ROOT</tt>
+
|Specifies the path for your root-level data directory. 
+
 
+
|-valign="top"
+
|<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>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"
+
|<tt>RUN_ROOT</tt>
+
|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>
+
 
+
|-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_PATH</tt>
+
|Specifies the directory on your disk server where copies of the GEOS-Chem run directories will be created.
+
 
+
|-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.
+
  
 
|}
 
|}
  
=== Section 2: RUNS ===
 
 
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:
 
 
#
 
# !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 <tt>gcCopyRunDirs</tt> script to create a run directory for a GEOS-Chem simulation with the following settings:
 
 
*Using [[GEOS-FP]] met fields
 
*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]]
 
*Starting at 00: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 [[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 comment out the lines containing runs you may wish to copy in the future.
 
 
== 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:
 
 
./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 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>.
 
 
cp CopyRunDirs.input CopyRunDirs.fullchem  # Input file set up to only copy the full-chemistry 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 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_standard</tt> 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:
 
 
brc.dat
 
dust.dat
 
FJX_j2j.dat
 
FJX_spec.dat
 
getRunInfo
 
h2so4.dat
 
HEMCO_Config.rc
 
HEMCO_restart.201307010000.nc
 
input.geos
 
jv_spec_mie.dat
 
Makefile
 
org.dat
 
output/
 
README
 
so4.dat
 
soot.dat
 
ssa.dat
 
ssc.dat
 
v11-01.run
 
validate
 
 
''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 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.
 
 
== Important Notes About Restart Files ==
 
 
Restart files are included in every run directory. The dates corresponding to the restart files are not necessarily the same as your intended simulation start date, or the start date you specified when creating the run directory from the Unit Tester. The actual date for the restart files is shown in the filename of the HEMCO restart file (e.g. HEMCO_restart.200607010000.nc). When creating a run directory for a GEOS-Chem simulation, take note of what this date is and use the information in this section to determine how to properly use the restart files that come with the run directory.
 
 
The restart files included in the run directory are for use with spinning up the model to the start date of your production run. We recommend running GEOS-Chem for at least one year to generate new restart files prior to performing your intended simulations. For the case of tagged ozone, we recommend spinning up the model for 10 years.
 
 
The start date of your spin-up must correspond to the month of the tracer restart file (<tt>initial_trac_rst.{RUNDIR_NAME}</tt>), but not necessarily the year, so that seasonality is correctly incorporated. The end date of your spin-up should match the start date of your intended production run so that you end up with restart files for that day.
 
 
If the start date of your spin-up does not exactly match that of the HEMCO restart file that comes with the run directory,(<tt>HEMCO_restart.{DATE}.nc</tt>), then you should not use the HEMCO restart file. You should instead use default emissions values by setting 'HEMCO_RESTART' from 'true' to 'false' in <tt>HEMCO_Config.rc</tt>. Be sure to remember to re-enable the HEMCO restart file after your spin-up run to use the newly generated HEMCO restart file corresponding to your production run start date.
 
 
--[[User:Lizzie Lundgren|Lizzie Lundgren]] ([[User talk:Lizzie Lundgren|talk]]) 16:24, 22 December 2015 (UTC)
 
 
== Tips and tricks for creating run directories ==
 
 
*In each run directory, we provide GEOS-Chem restart files that you can use to initialize your simulation. However, it is highly recommended that you do not use these restart files for any of your production runs. Rather, you should generate your own restart files by spinning up the model for at least a year. See the [[Creating_GEOS-Chem_run_directories#Important_Notes_About_Restart_Files|Important Notes About Restart Files]] section above for more information.
 
 
* 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. Gabriele Curci found found that the following procedure can be used to create a MERRA run directory from a GEOS-FP run directory (using a <tt>geosfp_4x5_UCX</tt> run directory as an example).
 
*#[[#Generating_a_GEOS-Chem_Run_Directory|Create a run directory]] for GEOS-FP using <tt>gcCopyRunDirs</tt>
 
*#Type <tt>cp -R geosfp_4x5_UCX merra_4x5_UCX</tt>
 
*#Type <tt>cd merra_4x5_UCX</tt>
 
*#Type <tt>rename geosfp merra *</tt>
 
*#Open <tt>input.geos</tt> in a text editor and change all the occurrences of "geosfp" to "merra"
 
*#Type <tt>make superclean</tt>
 
*#Type <tt>make distclean</tt> in the Code dir
 
*#[[#Compiling_and_Running_GEOS-Chem|Compile and run]]
 
 
* 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]] ([[User talk:Melissa Payer|talk]]) 18:42, 26 August 2015 (UTC)
 
 
== Compiling and Running GEOS-Chem ==
 
 
Once you have created one or more GEOS-Chem run directories, you may use them for your GEOS-Chem simulations.  First, double-check 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. Also see the [[Creating_GEOS-Chem_run_directories#Important_Notes_About_Restart_Files|Important notes about restart files]] section above for important information about the appropriate use of restart files and the necessity of spinning up the model.
 
 
Next, open the Makefile in a text editor and define the variables CODE_DIR, LOG_DIR, and VERSION specific to your simulation. CODE_DIR is the path to the GEOS-Chem source code you wish to use. LOG_DIR is the path to which you wish to send your log files. VERSION is text you wish to include as a prefix in your output log filename. You can also pass any of these three variables manually to the make command, overwriting the definitions stored in the Makefile.
 
 
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 TRACEBACK=y mp
 
 
The above command turns on traceback for debugging and invokes the <tt>mp</tt> target in the Makefile. This compiles the source code at path CODE_DIR with [[Parallelizing_GEOS-Chem|OpenMP parallelization]] and then runs the resultant GEOS-Chem executable using the simulation settings in the configuration files. The suffix <tt>.mp</tt> is included in each output filename to indicate that you enabled OpenMP parallelization for your GEOS-Chem run.
 
 
There are many other targets you may use with make. For example, you can use target <tt>sp</tt> to compile and run code using a single processor rather than multiple processors. This is useful for generating a baseline from which you can diagnose and debug parallelization errors. Output files will have a <tt>.sp</tt> rather than <tt>.mp</tt> suffix to distinguish them from the OpenMP parallelized run output. Alternatively, you can build GEOS-Chem source code without running a simulation (<tt>mpbuild</tt> or <tt>spbuild</tt>) or run a simulation without rebuilding (<tt>mprun</tt> or <tt>sprun</tt>). There are also several housekeeping targets that clean the run directory (e.g. <tt>mpdataclean</tt>, <tt>mpexeclean</tt>, <tt>mplogclean</tt>, and <tt>mpclean</tt>) and the source code (e.g. <tt>realclean</tt>).
 
 
See the <tt>Makefile</tt> for all make options and the [[GEOS-Chem_Makefile_Structure|GEOS-Chem Makefile Structure wiki page]] wiki page for more information about compiling GEOS-Chem and using the run directory Makefile.
 
 
--[[User:Lizzie Lundgren|Lizzie Lundgren]] 13:12, 15 April 2015 (EDT)
 
 
== 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 more information, see our [[GEOS-Chem Output Files|''GEOS-Chem Output Files'' wiki page]].
 
  
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 22:25, 5 February 2016 (UTC)
+
----
 +
'''''[[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]]'''''

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