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

From Geos-chem
Jump to: navigation, search
(GEOS-Chem Output Files)
Line 9: Line 9:
 
  git clone -b v10-01-Release git://git.as.harvard.edu/bmy/GEOS-Chem-UnitTest UT
 
  git clone -b v10-01-Release 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.   
+
This will create a copy of the GEOS-Chem Unit Tester package in a directory named <code>UT</code> for short.   
  
 
The option
 
The option
Line 27: Line 27:
 
The [[GEOS-Chem Unit Tester]] includes a run directory called '''geosfp_4x5_benchmark.''' As of May 2015, the standard [http://acmg.seas.harvard.edu/geos/geos_benchmark.html GEOS-Chem benchmark simulation] utilizes the [[GEOS-FP]] met fields ([http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5 &deg;], [http://acmg.seas.harvard.edu/geos/doc/man/appendix_3.html#GEOS-5_native 72 levels]) with the [[#UCX chemistry mechanism|UCX tropospheric-stratospheric chemistry mechanism]] and [[Secondary organic aerosols|secondary organic aerosols]] included.  
 
The [[GEOS-Chem Unit Tester]] includes a run directory called '''geosfp_4x5_benchmark.''' As of May 2015, the standard [http://acmg.seas.harvard.edu/geos/geos_benchmark.html GEOS-Chem benchmark simulation] utilizes the [[GEOS-FP]] met fields ([http://acmg.seas.harvard.edu/geos/doc/man/appendix_2.html#GMAO_4x5 4&deg; x 5 &deg;], [http://acmg.seas.harvard.edu/geos/doc/man/appendix_3.html#GEOS-5_native 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_v10-01_benchmark_history#1-month_benchmark_v10-01-public-release_with_SOA_on|1-month benchmark simulation for v10-01]], you can edit the <tt>CopyRunDirs.input</tt> file so that the following line is uncommented under <tt>RUNS</tt>:
+
To reproduce our latest [[GEOS-Chem_v10-01_benchmark_history#1-month_benchmark_v10-01-public-release_with_SOA_on|1-month benchmark simulation for v10-01]], you can edit the <code>CopyRunDirs.input</code> file so that the following line is uncommented under <code>RUNS</code>:
  
 
   geosfp  4x5        -      benchmark    2013070100  2013080100  UCX=y
 
   geosfp  4x5        -      benchmark    2013070100  2013080100  UCX=y
  
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 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 <code>gcCopyRunDirs</code>. Navigate to your the newly created <code>geosfp_4x5_benchmark</code> run directory. To compile and run your benchmark simulation, type:
  
 
  make -j4 mp
 
  make -j4 mp
Line 39: Line 39:
 
  make -j4 mpbuild
 
  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.
+
That will create a <code>geos.mp</code> executable file that you can use to submit your GEOS-Chem benchmark simulation to a queue system.
  
'''''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.'''''
+
'''''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 <code>UCX=y</code> option in your <code>make</code> command.'''''
  
 
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:38, 23 June 2015 (UTC)
 
--[[User:Melissa Payer|Melissa Sulprizio]] ([[User talk:Melissa Payer|talk]]) 19:38, 23 June 2015 (UTC)
Line 384: Line 384:
 
== Editing the CopyRunDirs.input file ==
 
== 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:
+
Once you have downloaded the GEOS-Chem Unit Tester to your disk space, switch to the <code>perl/</code> 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 <code>gcCopyRunDirs</code> that you will use to generate fresh copies of GEOS-Chem run directories.  This script uses an input file named <code>CopyRunDirs.input</code>, which is also located in the <code>perl</code> directory.   
  
Your <tt>CopyRunDirs.input</tt> file will look something like this:
+
Your <code>CopyRunDirs.input</code> file will look something like this:
  
 
  #------------------------------------------------------------------------------
 
  #------------------------------------------------------------------------------
Line 464: Line 464:
 
  #------------------------------------------------------------------------------
 
  #------------------------------------------------------------------------------
  
''NOTE: Lines starting with a <tt>#</tt> character will be treated as comments.''
+
''NOTE: Lines starting with a <code>#</code> 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.
+
The <code>CopyRunDirs.input</code> 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]] (<code>UnitTest.input</code> located within this directory). Like the GEOS-Chem Unit Tester input files, <code>CopyRunDirs.input</code> is composed of an <code>INPUTS</code> section and a <code>RUNS</code> 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. Each configurable input is described in the table below.
+
Under the <code>INPUTS</code> 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 478: Line 478:
  
 
|-valign="top"
 
|-valign="top"
|<tt>VERSION</tt>
+
|<code>VERSION</code>
 
|An ID tag that will be added to all log files and output files.
 
|An ID tag that will be added to all log files and output files.
  
 
|-valign="top"
 
|-valign="top"
|<tt>DESCRIPTION</tt>
+
|<code>DESCRIPTION</code>
 
|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"
 
|-valign="top"
|<tt>COPY_PATH</tt>
+
|<code>COPY_PATH</code>
 
|Specifies the root directory on your disk server where copies of the GEOS-Chem run directories will be created.
 
|Specifies the root directory on your disk server where copies of the GEOS-Chem run directories will be created.
  
 
|-valign="top"
 
|-valign="top"
|<tt>DATA_ROOT</tt>
+
|<code>DATA_ROOT</code>
 
|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"http://wiki.seas.harvard.edu/geos-chem/skins//common/images/button_nowiki.png
|<tt>HEMCO_ROOT</tt>
+
|<code>HEMCO_ROOT</code>
 
|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 <code>{DATAROOT}</code> token in <code>HEMCO_ROOT</code> will be replaced with the value you specify for <code>RUN_ROOT</code> option.   
 
<b>Leave this as-is.</b>
 
<b>Leave this as-is.</b>
  
 
|-valign="top"
 
|-valign="top"
|<tt>RUN_ROOT</tt>
+
|<code>RUN_ROOT</code>
 
|Specifies the top-level unit test run directories.   
 
|Specifies the top-level unit test run directories.   
 
<b>Leave this as-is.</b>
 
<b>Leave this as-is.</b>
  
 
|-valign="top"
 
|-valign="top"
|<tt>PERL_DIR</tt>
+
|<code>PERL_DIR</code>
 
|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"
 
|-valign="top"
|<tt>COPY_CMD</tt>
+
|<code>COPY_CMD</code>
|Specifies the command used to copy run directories from the GEOS-Chem Unit Tester to <tt>COPY_PATH</tt>.
+
|Specifies the command used to copy run directories from the GEOS-Chem Unit Tester to <code>COPY_PATH</code>.
*The default setting is <tt>cp -rfL</tt>.  This will create a new copy of the directory, even if the prior copy exists.  
+
*The default setting is <code>cp -rfL</code>.  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.
+
*The <code>-L</code> option to the <code>cp</code> 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.
  
 
|-valign="top"
 
|-valign="top"
|<tt>VERBOSE</tt>
+
|<code>VERBOSE</code>
 
|Specifies the level of debug output that will be sent to the HEMCO log file. (0=no debug output; 3=max debug output)
 
|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>
+
*Recommended setting: <code>0</code>
  
 
|-valign="top"
 
|-valign="top"
|<tt>WARNINGS</tt>
+
|<code>WARNINGS</code>
 
|Specifies the level of warning messages that will be sent to the HEMCO log file. (0=no warnings; 3=max warnings)
 
|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>
+
*Recommended setting: <code>1</code>
  
 
|}
 
|}
Line 531: Line 531:
 
=== Section 2: RUNS ===
 
=== 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>.
+
The layout of the <code>RUNS</code> section is identical to the <code>RUNS</code> section in the GEOS-Chem Unit Tester input file. This enables copying and pasting simulation settings text from <code>UnitTest.input</code> into <code>CopyRunDirs.input</code>.
  
 
For example, the following line:
 
For example, the following line:
Line 545: Line 545:
 
   geosfp  4x5        -      fullchem    2013070100  2013070101  -
 
   geosfp  4x5        -      fullchem    2013070100  2013070101  -
  
will tell the <tt>gcCopyRunDirs</tt> script to create a run directory for a GEOS-Chem simulation using:
+
will tell the <code>gcCopyRunDirs</code> script to create a run directory for a GEOS-Chem simulation using:
  
 
*[[GEOS-FP]] met fields
 
*[[GEOS-FP]] met fields
Line 553: Line 553:
 
*Ending at 01:00 GMT on 2013/07/01
 
*Ending at 01:00 GMT on 2013/07/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 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.   
+
The date range will be used to initialize the <code>input.geos</code> file that is read during a GEOS-Chem simulation. Once the run directory is created, you may edit these dates within the <code>input.geos</code> file. Note, however, that time ranges must remain within the time range covered by the <code>MET</code> field you are using. You can check the <code>MET</code> 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 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.
+
You can add as many entries to the <code>RUNS</code> 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 ==
 
== 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 <code>CopyRunDirs.input</code> script to your liking, you can use that to generate fresh copies of GEOS-Chem run directories.  Make sure you are in the <code>perl</code> 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 <code>gcCopyRunDirs</code>, then the <code>gcCopyRunDirs</code> script will use the <code>CopyRunDirs.input</code> file that you just created.   
  
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 <code>CopyRunDirs.input</code>.  For example, suppose you edit <code>CopyRunDirs.input</code> to generate a full-chemistry run directory. You can then save it as a separate file and use it explicitly with <code>gcCopyRunDirs</code>.
  
 
  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
Line 571: Line 571:
 
  gcCopyRunDirs CopyRunDirs.Hg                 
 
  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>.  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.
+
Executing <code>gcCopyRunDirs</code> will create a new GEOS-Chem run directory corresponding to each entry that you specified in the input file <code>RUNS</code>.  Each run directory will be created as a subdirectory of <code>COPY_PATH</code> that you specified in the input file <code>INPUTS</code> 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 <code>geosfp_4x5_fullchem</code> run directory.  Issue the following commands:
  
 
  cd ~/GC/rundirs/geosfp_4x5_fullchem  # Change to geosfp_4x5_fullchem run dir  
 
  cd ~/GC/rundirs/geosfp_4x5_fullchem  # Change to geosfp_4x5_fullchem run dir  
Line 607: Line 607:
 
''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 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 <code>input.geos</code> and <code>HEMCO_Config.rc</code> files have been customized for this particular simulation.  They were created from the corresponding template files <code>input.geos.template</code> and <code>HEMCO_Config.template</code> in the Unit Tester. The Perl script <code>getRunInfo</code> is used by the Makefile to extract information about the simulation from <code>input.geos</code>. 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 ==  
 
== Important Notes About Restart Files ==  
Line 615: Line 615:
 
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 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.
+
The start date of your spin-up must correspond to the month of the tracer restart file (<code>initial_trac_rst.{RUNDIR_NAME}</code>), 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.  
+
If the start date of your spin-up does not exactly match that of the HEMCO restart file that comes with the run directory,(<code>HEMCO_restart.{DATE}.nc</code>), 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 <code>HEMCO_Config.rc</code>. 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)
 
--[[User:Lizzie Lundgren|Lizzie Lundgren]] ([[User talk:Lizzie Lundgren|talk]]) 16:24, 22 December 2015 (UTC)
Line 626: Line 626:
  
 
* 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:
 
* 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]].
+
*# Modify the <code>input.geos</code> 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).
 
*# 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).
+
* 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 <code>geosfp_4x5_UCX</code> run directory as an example).
*#[[#Generating_a_GEOS-Chem_Run_Directory|Create a run directory]] for GEOS-FP using <tt>gcCopyRunDirs</tt>
+
*#[[#Generating_a_GEOS-Chem_Run_Directory|Create a run directory]] for GEOS-FP using <code>gcCopyRunDirs</code>
*#Type <tt>cp -R geosfp_4x5_UCX merra_4x5_UCX</tt>
+
*#Type <code>cp -R geosfp_4x5_UCX merra_4x5_UCX</code>
*#Type <tt>cd merra_4x5_UCX</tt>
+
*#Type <code>cd merra_4x5_UCX</code>
*#Type <tt>rename geosfp merra *</tt>
+
*#Type <code>rename geosfp merra *</code>
*#Open <tt>input.geos</tt> in a text editor and change all the occurrences of "geosfp" to "merra"
+
*#Open <code>input.geos</code> in a text editor and change all the occurrences of "geosfp" to "merra"
*#Type <tt>make superclean</tt>
+
*#Type <code>make superclean</code>
*#Type <tt>make distclean</tt> in the Code dir
+
*#Type <code>make distclean</code> in the Code dir
 
*#[[#Compiling_and_Running_GEOS-Chem|Compile and run]]
 
*#[[#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:
 
* 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].
+
*# Modify the <code>input.geos</code> 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].
 
*# 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.
 
*# 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.
Line 650: Line 650:
 
== Compiling and Running GEOS-Chem ==
 
== 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.
+
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 <code>input.geos</code> and <code>HEMCO_Config.rc</code> 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.  
 
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.)
+
To start a GEOS-Chem simulation, type the following commands. (We'll use the example of the <code>geosfp_4x5_fullchem</code> simulation, from the previous sections.)
  
 
  make -j4 TRACEBACK=y mp
 
  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.  
+
The above command turns on traceback for debugging and invokes the <code>mp</code> 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 <code>.mp</code> 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>).  
+
There are many other targets you may use with make. For example, you can use target <code>sp</code> 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 <code>.sp</code> rather than <code>.mp</code> suffix to distinguish them from the OpenMP parallelized run output. Alternatively, you can build GEOS-Chem source code without running a simulation (<code>mpbuild</code> or <code>spbuild</code>) or run a simulation without rebuilding (<code>mprun</code> or <code>sprun</code>). There are also several housekeeping targets that clean the run directory (e.g. <code>mpdataclean</code>, <code>mpexeclean</code>, <code>mplogclean</code>, and <code>mpclean</code>) and the source code (e.g. <code>realclean</code>).  
  
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.
+
See the <code>Makefile</code> 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)
 
--[[User:Lizzie Lundgren|Lizzie Lundgren]] 13:12, 15 April 2015 (EDT)

Revision as of 17:20, 5 December 2016

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.

Downloading the GEOS-Chem Unit Tester

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

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

git clone -b v10-01-Release 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 UT for short.

The option

-b v10-01-Release

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.

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

--Bob Y. 12:25, 1 May 2015 (EDT)

Available run directories

Benchmark run directory

The GEOS-Chem Unit Tester includes a run directory called geosfp_4x5_benchmark. As of May 2015, 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 for v10-01, you can edit the CopyRunDirs.input file so that the following line is uncommented under RUNS:

 geosfp   4x5         -      benchmark    2013070100   2013080100   UCX=y

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 gcCopyRunDirs. Navigate to your the newly created geosfp_4x5_benchmark run directory. To compile and run your benchmark simulation, type:

make -j4 mp

To compile only, type:

make -j4 mpbuild

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

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 UCX=y option in your make command.

--Melissa Sulprizio (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 (e.g. geosfp_4x5_UCX). For more details on the simulation types, please see our 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 directory or run directories that are most relevant for your research.

Met field Grid NOx-Ox-
HC-aerosol
UCX RRTMG soa soa_svpoa RnPbBe Hg POPs tagCO tagO3 CH4 CO2 aerosol TOMAS40
geosfp 4x5
geosfp 2x25
geosfp 025x03125
CH
geosfp 025x03125
NA
geos5 4x5
geos5 2x25
geos5 05x0666
CH
geos5 05x0666
NA
merra 4x5
merra 2x25
geos4 4x5
gcap 4x5

LEGEND

Run directory is available
Run directory is in need of updating
Run directory is obsolete
Run directory is not available

--Melissa Sulprizio (talk) 17:36, 26 May 2015 (UTC)

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.

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:  
#  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
#  VERBOSE     : HEMCO verbose level  (0=no output, 3=max output)
#  WARNINGS    : HEMCO warnings level (0=no warnings, 3=max warnings)
#
# !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-01
   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
   VERBOSE     : 0
   WARNINGS    : 1
#
# !RUNS:
#  Specify the debugging runs that you want to perform 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         -      fullchem     2013070100   2013070101   -
  geosfp   4x5         -      soa          2013070100   2013070101   -
  geosfp   4x5         -      soa_svpoa    2013070100   2013070101   -
  geosfp   4x5         -      UCX          2013070100   2013070101   UCX=y
  geosfp   4x5         -      RRTMG        2013070100   2013070101   RRTMG=y
  geosfp   4x5         -      RnPbBe       2013070100   2013070101   -
  geosfp   4x5         -      Hg           2013070100   2013070101   -
  geosfp   4x5         -      POPs         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     fullchem     2013070100   201307010010 -
  geosfp   025x03125   na     fullchem     2013070100   201307010010 -
!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.
COPY_PATH Specifies the root directory on your disk server where copies of the GEOS-Chem run directories will be created.
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.

RUN_ROOT Specifies the top-level unit test run directories.

Leave this as-is.

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

Leave this as-is.

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.
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

--Bob Y. (talk) 22:38, 19 May 2015 (UTC)

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         -      fullchem     2013070100   2013070101   -

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

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. 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 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 created.

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.Hg                 

Executing gcCopyRunDirs will create a new GEOS-Chem run directory corresponding to each entry that you specified in the input file RUNS. 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_fullchem run directory. Issue the following commands:

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

ls -l                                # Get detailed directory listing

And you will see this directory listing:

-rw-r--r-- 1 mpayer mpayer     7862 2015-04-03 15:19 FJX_j2j.dat
-rw-r--r-- 1 mpayer mpayer    44808 2015-04-03 15:19 FJX_spec.dat
-rw-r--r-- 1 mpayer mpayer   186359 2015-04-03 15:19 HEMCO_Config.rc
-rw-r--r-- 1 mpayer mpayer     4872 2015-04-03 15:19 Makefile
-rw-r--r-- 1 mpayer mpayer      783 2015-04-03 15:19 README
-rw-r--r-- 1 mpayer mpayer      610 2015-04-03 15:19 chemga.dat
-rw-r--r-- 1 mpayer mpayer    42186 2015-04-03 15:19 dust.dat
-rwxr-xr-x 1 mpayer mpayer     1458 2015-04-03 15:19 getEnd.pl*
-rwxr-xr-x 1 mpayer mpayer     1374 2015-04-03 15:19 getStart.pl*
-rw-r--r-- 1 mpayer mpayer   199632 2015-04-03 15:19 globchem.dat
-rw-r--r-- 1 mpayer mpayer   401972 2015-04-03 15:19 HEMCO_restart.200607010000.nc
-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.

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.

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 (initial_trac_rst.{RUNDIR_NAME}), 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,(HEMCO_restart.{DATE}.nc), 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 HEMCO_Config.rc. 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.

--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 Important Notes About Restart Files section above for more information.
  • You can create a run directory for the nested grid simulations from a 4° x 5° or 2° x 2.5° run directory by following these steps:
    1. Modify the input.geos file for the nested grid simulation. Complete instructions can be found on this wiki page.
    2. Regrid the restart file(s) using the GAMAP regridding routines. For example, REGRIDH_RESTART can be used to regrid the tracer restart file from one horizontal resolution to another. You can then use 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 geosfp_4x5_UCX run directory as an example).
    1. Create a run directory for GEOS-FP using gcCopyRunDirs
    2. Type cp -R geosfp_4x5_UCX merra_4x5_UCX
    3. Type cd merra_4x5_UCX
    4. Type rename geosfp merra *
    5. Open input.geos in a text editor and change all the occurrences of "geosfp" to "merra"
    6. Type make superclean
    7. Type make distclean in the Code dir
    8. 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:
    1. Modify the input.geos file for your simulation type following the relevant checklist in Chapter 6 of the GEOS-Chem Manual.
    2. Create a "fake" restart file using GAMAP routine MAKE_RESTART.
    3. Alternatively, you can send an email to the relevant Working Group to see if another member can provide you with a run directory or restart file.

--Melissa Sulprizio (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 input.geos and HEMCO_Config.rc files are correct for the simulation that you are trying to run. See the GEOS-Chem Manual for more information about setting simulation options. Also see the 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 geosfp_4x5_fullchem simulation, from the previous sections.)

make -j4 TRACEBACK=y mp

The above command turns on traceback for debugging and invokes the mp target in the Makefile. This compiles the source code at path CODE_DIR with OpenMP parallelization and then runs the resultant GEOS-Chem executable using the simulation settings in the configuration files. The suffix .mp 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 sp 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 .sp rather than .mp suffix to distinguish them from the OpenMP parallelized run output. Alternatively, you can build GEOS-Chem source code without running a simulation (mpbuild or spbuild) or run a simulation without rebuilding (mprun or sprun). There are also several housekeeping targets that clean the run directory (e.g. mpdataclean, mpexeclean, mplogclean, and mpclean) and the source code (e.g. realclean).

See the Makefile for all make options and the GEOS-Chem Makefile Structure wiki page wiki page for more information about compiling GEOS-Chem and using the run directory Makefile.

--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 wiki page.

--Melissa Sulprizio (talk) 22:25, 5 February 2016 (UTC)