Difference between revisions of "Creating run directories for GEOS-Chem 13.0.0 and later"

From Geos-chem
Jump to: navigation, search
 
(7 intermediate revisions by 2 users not shown)
Line 13: Line 13:
 
#[[Running GEOS-Chem|Running]]
 
#[[Running GEOS-Chem|Running]]
 
#[[GEOS-Chem output files|Output files]]
 
#[[GEOS-Chem output files|Output files]]
#[[Guide_to_visualization_and_analysis_tools_for_GEOS-Chem|Visualizing and processing output]]
+
#[[Python tools for use with GEOS-Chem]]
 
#[[GEOS-Chem_coding_and_debugging|Coding and debugging]]
 
#[[GEOS-Chem_coding_and_debugging|Coding and debugging]]
 
#[[GEOS-Chem_overview#Further_reading|Further reading]]
 
#[[GEOS-Chem_overview#Further_reading|Further reading]]
  
  
== Overview ==
+
This content has been migrated to the [https://geos-chem.readthedocs.io/en/latest/gcc-guide/02-build/create-rundir.html '''Create a run directory''' chapter of <tt>geos-chem.readthedocs.io</tt>].
 
+
We have greatly simplified run directory creation in [[GEOS-Chem 13.0.0]] and later versions.  You no longer need to download the separate [[GEOS-Chem Unit Tester]] repository any longer, but can create run directories from a script in the GEOS-Chem source code itself.
+
 
+
== Example 1: Creating a run directory for a full-chemistry simulation ==
+
 
+
Let us walk through the process of creating a run directory for a global GEOS-Chem full-chemistry simulation.
+
 
+
'''1.''' Navigate to the <tt>GCClassic</tt> superproject folder and get a directory listing:
+
 
+
      cd /path/to/your/GCClassic
+
      ls -CF
+
 
+
:You should see this output:
+
 
+
  CMakeLists.txt  LICENSE  run@  src/
+
 
+
:As mentioned previously, <tt>run@</tt> is a symbolic link.  It actually points to the to the <tt>src/GEOS-Chem/run/GCClassic</tt> folder.  This folder contains several scripts and template files for run directory creation. 
+
 
+
'''2.'''  Navigate to the <tt>run</tt> folder and get a directory listing:
+
 
+
      cd run
+
      ls -CF
+
 
+
:and you should see this output:
+
 
+
      archiveRun.sh*    gitignore                  HISTORY.rc.templates/  runScriptSamples/
+
      createRunDir.sh*  HEMCO_Config.rc.templates/  input.geos.templates/
+
      getRunInfo*      HEMCO_Diagn.rc.templates/  README
+
 
+
:You can see several folders (highlighted in the directory display with <tt>/</tt>) and a few executable scripts (highlighted with <tt>*</tt>).  The script we are interested in is <tt>createRunDir.sh</tt>.
+
 
+
'''3.''' Run the <tt>createRunDir.sh</tt> script.  Type:
+
 
+
  ./createRunDir.sh
+
 
+
'''4.''' You will then be prompted to supply information about the run directory that you wish to create:
+
 
+
      ===========================================================
+
      GEOS-CHEM RUN DIRECTORY CREATION
+
      ===========================================================
+
 
+
      -----------------------------------------------------------
+
      Choose simulation type:
+
      -----------------------------------------------------------
+
        1. Full chemistry
+
        2. Aerosols only
+
        3. CH4
+
        4. CO2
+
        5. Hg
+
        6. POPs
+
        7. Tagged CH4
+
        8. Tagged CO
+
        9. Tagged O3
+
        10. TransportTracers
+
 
+
:To create a run directory for the full-chemistry simulation, type <tt>1</tt> followed by the <tt>ENTER</tt> key. 
+
 
+
'''5.''' You will then be prompted to specify whether you want to perform chemistry in the stratosphere or not:
+
 
+
      -----------------------------------------------------------
+
      Choose chemistry domain:
+
      -----------------------------------------------------------
+
        1. Troposphere + stratosphere (Recommended)
+
        2. Troposphere only
+
 
+
:Select the recommended option: Type <tt>1</tt> and then <tt>ENTER</tt>. 
+
 
+
'''6.''' You will then be asked to specify any additional options for the full-chemistry simulation (such as adding the RRTMG radiative transfer model, APM or TOMAS microphysics, etc.)
+
 
+
      -----------------------------------------------------------
+
      Choose additional simulation option:
+
      -----------------------------------------------------------
+
        1. Standard
+
        2. Benchmark
+
        3. Complex SOA
+
        4. Marine POA
+
        5. Acid uptake on dust
+
        6. TOMAS
+
        7. APM
+
        8. RRTMG
+
 
+
:'''6a''': For the standard full-chemistry simulation, type <tt>1</tt> followed by <tt>ENTER</tt>.
+
 
+
:'''6b''': To add an option to the full-chemistry simulation, type a number between <tt>2</tt> to <tt>8</tt> and press <tt>ENTER</tt>.
+
 
+
'''7.''' You will then be asked to specify the meteorology type for the simulation (GEOS-FP or MERRA-2):
+
 
+
      -----------------------------------------------------------
+
      Choose meteorology source:
+
      -----------------------------------------------------------
+
        1. MERRA-2 (Recommended)
+
        2. GEOS-FP
+
 
+
:You should use the recommended option (MERRA-2) if possible.  Type <tt>1</tt> followed by <tt>ENTER</tt>.
+
 
+
'''8.''' The next menu will prompt you for the horizontal resolution that you wish to use:
+
 
+
      -----------------------------------------------------------
+
      Choose horizontal resolution:
+
      -----------------------------------------------------------
+
        1. 4.0  x 5.0
+
        2. 2.0  x 2.5
+
        3. 0.5  x 0.625
+
 
+
:'''8a.''' If you wish to set up a global simulation, type either <tt>1</tt> or <tt>2</tt> followed by <tt>ENTER</tt>. 
+
 
+
:'''8b.''' If you wish to set up a nested-grid simulation, type <tt>3</tt> and hit <tt>ENTER</tt>.  Then you will be followed by a nested-grid menu:
+
 
+
      -----------------------------------------------------------
+
      Choose horizontal grid domain:
+
      -----------------------------------------------------------
+
        1. Global
+
        2. Asia
+
        3. Europe
+
        4. North America
+
        5. Custom
+
 
+
:Select your preferred horizontal domain, followed by <tt>ENTER</tt>.
+
 
+
'''9.''' You will then be prompted for the vertical dimension of the grid.
+
 
+
      -----------------------------------------------------------
+
      Choose number of levels:
+
      -----------------------------------------------------------
+
        1. 72 (native)
+
        2. 47 (reduced)
+
 
+
:'''9a.''' For most simulations, you will want to use 72 levels.  Type <tt>1</tt> followed by <tt>ENTER</tt>.
+
 
+
:'''9b.''' For some memory-intensive simulations (such as nested-grid simulations), you can use 47 levels.  Type <tt>2</tt> followed by <tt>ENTER</tt>.
+
 
+
'''10.''' You will then be prompted for the folder in which you wish to create the run directory. 
+
 
+
      -----------------------------------------------------------
+
      Enter path where the run directory will be created:
+
      -----------------------------------------------------------
+
 
+
:'''10a.''' You can enter an absolute path (such as <tt>/n/home09/ryantosca/</tt> followed by <tt>ENTER</tt>).
+
 
+
:'''10b.''' Or you can enter a relative path (such as <tt>~/rundirs</tt> followed by <tt>ENTER</tt>).  In this case you will see that the <tt>./createRunDir.sh</tt> script will expand the path to:
+
 
+
      Expanding to: /n/home09/ryantosca/rundirs
+
 
+
'''11.''' The next menu will prompt you for the run directory name. 
+
 
+
      -----------------------------------------------------------
+
      Enter run directory name, or press return to use default:
+
 
+
      NOTE: This will be a subfolder of the path you entered above.
+
      -----------------------------------------------------------
+
 
+
:You should use the default run directory name whenever possible.  Type <tt>ENTER</tt> to select the default.
+
 
+
:The script will display the following output:
+
 
+
      -- Using default directory name gc_4x5_fullchem       
+
 
+
:or if you are creating a nested grid simulation:
+
 
+
      -- Using default directory name gc_05x0625_fullchem
+
 
+
:and then:
+
 
+
      -- This run directory has been set up for 20190701 - 20190801.
+
        You may modify these settings in input.geos.
+
 
+
      -- The default frequency and duration of diagnostics is set to monthly.
+
        You may modify these settings in HISTORY.rc and HEMCO_Config.rc.
+
 
+
'''12.''' The last menu will prompt you with:
+
 
+
      -----------------------------------------------------------
+
      Do you want to track run directory changes with git? (y/n)
+
      -----------------------------------------------------------
+
 
+
:Type <tt>y</tt> and then <tt>ENTER</tt>/  Then you will be able to track changes that you make to GEOS-Chem configuration files with Git.  This can be a lifesaver when debugging -- you can revert to an earlier state and then start fresh.
+
 
+
'''13.''' The script will display the full path to the run directory.  You can navigate there and then start editing the GEOS-Chem configuration files.
+
 
+
== Example 2: Creating a run directory for the methane simulation ==
+
 
+
The process of creating run directories for the GEOS-Chem specialty simulations is similar to that as listed in Example 1 above.  However, the number of menus that you need to select from will likely be fewer than for the full-chemistry simulation.  We'll use the methane simulation as an example.
+
 
+
'''1.''' Navigate to the <tt>GCClassic</tt> superproject folder and get a directory listing:
+
 
+
      cd /path/to/your/GCClassic
+
      ls -CF
+
 
+
:You should see this output:
+
 
+
      CMakeLists.txt  LICENSE  run@  src/
+
 
+
:As mentioned previously, <tt>run@</tt> is a symbolic link.  It actually points to the to the <tt>src/GEOS-Chem/run/GCClassic</tt> folder.  This folder contains several scripts and template files for run directory creation. 
+
 
+
'''2.'''  Navigate to the <tt>run</tt> folder and get a directory listing:
+
 
+
      cd run
+
      ls -CF
+
 
+
:and you should see this output:
+
 
+
      archiveRun.sh*    gitignore                  HISTORY.rc.templates/  runScriptSamples/
+
      createRunDir.sh*  HEMCO_Config.rc.templates/  input.geos.templates/
+
      getRunInfo*      HEMCO_Diagn.rc.templates/  README
+
 
+
:You can see several folders (highlighted in the directory display with <tt>/</tt>) and a few executable scripts (highlighted with <tt>*</tt>).  The script we are interested in is <tt>createRunDir.sh</tt>.
+
 
+
'''3.''' Run the <tt>createRunDir.sh</tt>.  Type:
+
 
+
  ./createRunDir.sh
+
 
+
'''4.''' You will then be prompted to supply information about the run directory that you wish to create:
+
 
+
      ===========================================================
+
      GEOS-CHEM RUN DIRECTORY CREATION
+
      ===========================================================
+
 
+
      -----------------------------------------------------------
+
      Choose simulation type:
+
      -----------------------------------------------------------
+
        1. Full chemistry
+
        2. Aerosols only
+
        3. CH4
+
        4. CO2
+
        5. Hg
+
        6. POPs
+
        7. Tagged CH4
+
        8. Tagged CO
+
        9. Tagged O3
+
        10. TransportTracers
+
 
+
:To select the GEOS-Chem methane specialty simulation, type <tt>3</tt> followed by <tt>ENTER</tt>.
+
 
+
'''5.''' You will then be asked to specify the meteorology type for the simulation (GEOS-FP or MERRA-2):
+
 
+
      -----------------------------------------------------------
+
      Choose meteorology source:
+
      -----------------------------------------------------------
+
        1. MERRA-2 (Recommended)
+
        2. GEOS-FP
+
 
+
:To accept the recommended meteorology (MERRA-2), type <tt>1</tt> followed by <tt>ENTER</tt>.
+
 
+
'''6.''' The next menu will prompt you for the horizontal resolution that you wish to use:
+
 
+
      -----------------------------------------------------------
+
      Choose horizontal resolution:
+
      -----------------------------------------------------------
+
        1. 4.0  x 5.0
+
        2. 2.0  x 2.5
+
        3. 0.5  x 0.625
+
 
+
:'''6a.''' If you wish to set up global simulation, type either <tt>1</tt> or <tt>2</tt> followed by <tt>ENTER</tt>. 
+
 
+
:'''6b.''' If you wish to set up a nested-grid simulation, type <tt>3</tt> and hit <tt>ENTER</tt>.  Then you will be followed by a nested-grid menu:
+
 
+
      -----------------------------------------------------------
+
      Choose horizontal grid domain:
+
      -----------------------------------------------------------
+
        1. Global
+
        2. Asia
+
        3. Europe
+
        4. North America
+
        5. Custom
+
 
+
:Type the number of your preferred option and then hit <tt>ENTER</tt>.
+
 
+
'''7.''' You will then be prompted for the vertical dimension of the grid.
+
 
+
      -----------------------------------------------------------
+
      Choose number of levels:
+
      -----------------------------------------------------------
+
        1. 72 (native)
+
        2. 47 (reduced)
+
 
+
:'''7a.''' For most simulations, you will want to use 72 levels.  Type <tt>1</tt> followed by <tt>ENTER</tt>
+
 
+
:'''7b.''' For some memory-intensive simulations (such as nested-grid simulations), you can use 47 levels.  Type <tt>2</tt> followed by <tt>ENTER</tt>.
+
 
+
'''8.''' You will then be prompted for the folder in which you wish to create the run directory. 
+
 
+
      -----------------------------------------------------------
+
      Enter path where the run directory will be created:
+
      -----------------------------------------------------------
+
 
+
:'''8a.''' You enter this an absolute path (such as <tt>/n/home09/ryantosca/</tt> followed by <tt>ENTER</tt>).
+
 
+
:'''8b.''' Or you can enter a relative path (such as <tt>~/rundirs</tt> followed by <tt>ENTER</tt>).  In this case you will see that the <tt>./createRunDir.sh</tt> script will expand the path to:
+
 
+
Expanding to: /n/home09/ryantosca/rundirs
+
 
+
'''9.''' The next menu will prompt you for the run directory name. 
+
 
+
      -----------------------------------------------------------
+
      Enter run directory name, or press return to use default:
+
 
+
      NOTE: This will be a subfolder of the path you entered above.
+
      -----------------------------------------------------------
+
 
+
:You should use the default run directory name whenever possible.  Type <tt>ENTER</tt>.  The script will display the following output:
+
 
+
      -- Using default directory name gc_4x5_CH4     
+
 
+
:or if you are creating a nested grid simulation:
+
 
+
      -- Using default directory name gc_05x0625_CH4
+
 
+
:and then:
+
 
+
      -- This run directory has been set up for 20190701 - 20190801.
+
        You may modify these settings in input.geos.
+
 
+
      -- The default frequency and duration of diagnostics is set to monthly.
+
        You may modify these settings in HISTORY.rc and HEMCO_Config.rc.
+
 
+
'''10.''' The last menu will prompt you with:
+
 
+
      -----------------------------------------------------------
+
      Do you want to track run directory changes with git? (y/n)
+
      -----------------------------------------------------------
+
 
+
:Type <tt>y</tt> and then <tt>ENTER</tt>/  Then you will be able to track changes that you make to GEOS-Chem configuration files with Git.  This can be a lifesaver when debugging -- you can revert to an earlier state and then start fresh.
+
 
+
'''11.''' The script will display the full path to the run directory.  You can navigate there and then start editing the GEOS-Chem configuration files.
+
 
+
== Configuring runs ==
+
 
+
You may now skip ahead to our ''[[GEOS-Chem configuration files|Configuring runs]]'' chapter.
+
  
  
 
----
 
----
 
'''''[[Creating GEOS-Chem run directories|Previous]] | [[Creating run directories for GEOS-Chem 12.9.3 and prior|Next]] | [[Getting Started with GEOS-Chem]]'''''
 
'''''[[Creating GEOS-Chem run directories|Previous]] | [[Creating run directories for GEOS-Chem 12.9.3 and prior|Next]] | [[Getting Started with GEOS-Chem]]'''''

Latest revision as of 20:59, 3 August 2022

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 GEOS-Chem 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


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



Previous | Next | Getting Started with GEOS-Chem