Difference between revisions of "Obtaining a GCHP Run Directory"

From Geos-chem
Jump to: navigation, search
 
(53 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
----
 +
<span style="color:crimson;font-size:120%">'''The GCHP documentation has moved to https://gchp.readthedocs.io/.''' The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!</span>
 +
----
 +
 
__FORCETOC__
 
__FORCETOC__
−
'''''[[Downloading_GCHP|Previous]] | [[Setting_Up_the_GCHP_Environment|Next]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GEOS-Chem_HP|GCHP Home]]'''''
+
'''''[[Compiling_GCHP|Previous]] | [[Running_GCHP:_Basics|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''
 
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
 
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
 +
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 
#[[Downloading_GCHP|Downloading Source Code and Data Directories]]
 
#[[Downloading_GCHP|Downloading Source Code and Data Directories]]
 +
#[[Compiling_GCHP|Compiling]]
 
#<span style="color:blue">'''Obtaining a Run Directory'''</span>
 
#<span style="color:blue">'''Obtaining a Run Directory'''</span>
−
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 
−
#[[Compiling_GCHP|Compiling]]
 
 
#[[Running_GCHP:_Basics|Running GCHP: Basics]]
 
#[[Running_GCHP:_Basics|Running GCHP: Basics]]
 
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
 
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
Line 13: Line 17:
 
<br>
 
<br>
  
−
== Overview ==
+
==Create Run Directory==
  
−
The method for creating a run directory changed between 12.1.0 and prior versions. Prior to 12.1.0, acquiring a GCHP run directory requires downloading the GEOS-Chem Unit Tester, configuring a text file, and running a perl script. This is the same method as creating GEOS-Chem Classic run directories. For version 12.1.0 and later, we no longer use the Unit Tester to create run directories. Instead, create run directories directly from the GCHP source code repository.
+
GCHP run directories are created from within the source code. A new run directory should be created for each different version of GEOS-Chem you use. Git version information is logged to file <code>rundir.version</code> within the run directory upon creation.
  
−
This page separately details both methods of run directory creation. Make sure you follow instructions for the GEOS-Chem version that you are using. If you are uncertain about what version you have, please contact the GEOS-Chem Support Team.
+
To create a run directory, navigate to the <code>run/</code> subdirectory of the source code and execute shell script <code>createRunDir.sh</code>.
  
−
== 12.1.0 and Later ==
+
$ cd ~/GCHPctm/run
 +
$ ./createRunDir.sh
  
−
===Step 1: Create Run Directory===
+
During the course of script execution you will be asked a series of questions:
  
−
Run directories are created directly from the GCHP source code repository starting in version 12.1.0. Navigate to GCHP subdirectory <tt>Run/</tt> and run shell script <tt>createRunDir.sh</tt>.
+
==== Enter ExtData directory path ====
  
−
./createRunDir.sh
+
The first time you create a GCHP run directory on your system you will be prompted for a path to GEOS-Chem shared data directories. The path should include the name of your <code>ExtData</code> directory and should not contain symbolic links. The path you enter will be stored in file <code>.geoschem/config</code> in your home directory as environment variable <code>GC_DATA_ROOT</code>. If that file does not already exist it will be created for you. When creating additional run directories you will only be prompted again if the file is missing or if the path within it is not valid.
  
−
You can pass a run directory name as an optional argument if you wish.
+
  -----------------------------------------------------------
−
 
+
Enter path for ExtData:
−
  ./createRunDir.sh gchp_12.1.0_RnPbBe
+
-----------------------------------------------------------
−
 
+
−
During the course of script execution you will be asked a series of questions:
+
  
−
#The very first time you create a run directory you will be prompted for your ExtData path where you store GEOS-Chem shared data directories. The ExtData path should include the name of your ExtData directory. For example, it may be something like this: <tt>/n/lfs/gcgrid/gcdata/ExtData</tt>. It is a good idea to have this ready prior to creating your first run directory. Make sure you do not include any symbolic links in the path. Once entered, it will be stored in file <tt>.geoschem/config</tt> in your home directory as environment variable <tt>GC_DATA_ROOT</tt>. If that file does not already exist it will be created for you.
+
====Choose simulation type====
−
#Subsequent runs of <tt>createRunDir.sh</tt> will always source that file to get your location for shared data directories and you will not be prompted again. If your ExtData path changes in the future you must provide the new path in <tt>.geoschem/config</tt>. The run directory creation script will prompt you to do so only if the file is missing or if the path within it is not valid.
+
−
#You will next be prompted for what simulation you wish to create a run directory for. Enter the integer number next to the simulation type you want to use that is displayed on the screen.
+
−
#Following simulation type, enter the meteorology you want to use in the same way. Options for GEOS-FP and MERRA2 will be displayed.
+
−
#Next, enter the target path where you want your run directory to be stored. Do not include symbolic links in the path.
+
−
#You will then be prompted to enter a run directory name if you did not pass one as an optional argument when calling the script. You are given the option to simply press return and use the default run directory name of format <tt>gchp_{simulation_type}</tt>. If you are not storing your run directory at a path that indicates GEOS-Chem version, we recommend storing the version number directly in the run directory name to avoid later confusion. However, please note that you can always look up the run directory version within the run directory itself in file <tt>rundir.version</tt>.
+
−
#Finally, you will be asked if you want to track run directory changes with git version control. This feature is useful if you plan on making feature updates to GEOS-Chem that involve changes to the run directory, such as adding emissions. With version control you can keep track of exactly what you changed relative to the original settings. This is also useful if you plan on submitting an update for inclusion in the standard model since you can copy changes directly from your version history to <tt>GCHP/Run</tt>, including those changes in the same repository as your source code updates.
+
  
−
=== Step 2: Set Environment File Symbolic Link ===
+
Enter the integer number that is next to the simulation type you want to use.
  
−
Once you have created a run directory you need to set the <tt>gchp.env</tt> symbolic link to your GCHP environment file. This file will be sourced automatically every time you compile using the Makefile and every time you run using one of the provided run scripts. If you write your own run script, be sure to include <tt>source gchp.env</tt> to use the same environment that you compiled with.
+
-----------------------------------------------------------
 +
Choose simulation type:
 +
-----------------------------------------------------------
 +
  1. Full chemistry
 +
  2. TransportTracers
  
−
To set the <tt>gchp.env</tt> symbolic link execute shell script <tt>setEnvironment</tt> and pass the path to your environment file. You can keep your environment file anywhere on your system; it does not need to be stored in the run directory.  
+
If creating a full chemistry run directory you will be given additional options. Enter the integer number that is next to the simulation option you want to run.
  
−
./setEnvironment /home/gchp/envs/gchp_ifort17_openmpi.env
+
-----------------------------------------------------------
 +
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
  
−
Several examples of GCHP environment files are provided in subdirectory <tt>environmentFileSamples</tt>. For more information on developing a working environment file for GCHP see the next chapter in this online manual.
+
====Choose meteorology source====
  
−
=== Step 3: Copy Run Script to Run Directory (Optional) ===
+
Enter the integer number that is next to the input meteorology source you would like to use.
  
−
Run scripts are what you submit to your compute cluster to execute your GCHP run. It is not required since you sometimes can run interactively using the same resources used for your command line tasks. However, we recommend submitting GCHP runs as jobs. Several examples of GCHP run scripts, mostly for SLURM, are provided in subdirectory <tt>runScriptSamples</tt>. All example run scripts include <tt>source gchp.env</tt>. If you customize your own run script make sure you include this before use.
+
  -----------------------------------------------------------
 +
Choose meteorology source:
 +
-----------------------------------------------------------
 +
  1. MERRA2 (Recommended)
 +
  2. GEOS-FP
  
−
== Prior to 12.1.0 ==
+
====Enter run directory path====
  
−
===Step 1: Create Run Directory===
+
Enter the target path where the run directory will be stored. You will be prompted to enter a new path if the one you enter does not exist.
  
−
Prior to version 12.1.0 you can create a GCHP run directory using the [[GEOS-Chem Unit Tester]]. The instructions for this are nearly the same as instructions for creating a GEOS-Chem Classic run directory. See the [[Creating_GEOS-Chem_run_directories|GEOS-Chem Classic wiki page for creating a GEOS-Chem run directory]] for additional information beyond what is provided below.
+
-----------------------------------------------------------
 +
Enter path where the run directory will be created:
 +
-----------------------------------------------------------
  
−
From your primary GCHP directory (e.g. <tt>/mypath/GCHP</tt>), download a clean copy the development version of the GEOS-Chem Unit Tester on Github:
+
====Enter run directory name====
  
−
git clone git@github.com:geoschem/geos-chem-unittest.git UT
+
Enter the run directory name, or accept the default. You will be prompted for a new name if a run directory of the same name already exists at the target path.
  
−
There are three run directories available for GCHP: the radon-lead-beryllium simulation, the standard full chemistry simulation, and the benchmarking simulation which incorporates both simple and complex SOA for validation. The default settings for all run directories are a 72-level simulation using 0.25x0.3125 GEOS-FP meteorology and internal c24 cubed sphere grid resolution (roughly equivalent to 4x5). Please note that unlike GEOS-Chem Classic there are not separate run directories for different grid resolutions.
+
-----------------------------------------------------------
 +
Enter run directory name, or press return to use default:
 +
-----------------------------------------------------------
  
−
Example steps for creating a standard full-chemistry run directory called <tt>gchp_standard</tt>:
+
====Put run directory under version control (optional)====
−
+
−
#Change directories into <tt>/mypath/GCHP/UT/perl</tt>
+
−
#Open <tt>CopyRunDirs.input</tt> in a text editor and make the following changes:
+
−
##Update <tt>GCGRID_ROOT</tt> and <tt>DATA_ROOT</tt> to point to the GEOS-Chem shared data directories on your system.
+
−
##Update variable <tt>UNIT_TEST_ROOT</tt> to match the directory to which you cloned the unit tester (e.g. <tt>/mypath/UT</tt>)
+
−
##Update variable <tt>COPY_PATH</tt> to be the target directory where you want to store your run directories (e.g. <tt>/mypath/GCHP/rundirs</tt>)
+
−
##Uncomment the lines for the GCHP run directories you would like to download (search for gchp_standard)
+
−
##Set the start and end dates for the simulations you are creating.
+
−
##Make sure all other run directory options are commented out
+
−
#Run the following perl script to create the run directory <tt>/mypath/GCHP/rundirs/gchp_standard</tt>:
+
−
    ./gcCopyRunDirs CopyRunDirs.input
+
  
−
See the [[Creating_GEOS-Chem_run_directories|''Creating GEOS-Chem run directories'' wiki page]] for more information.
+
Enter whether you would like your run directory tracked with git version control. With version control you can keep track of exactly what you changed relative to the original settings. This is useful for trouble-shooting as well as tracking run directory feature changes you wish to migrate back to the standard model.
  
−
=== Step 2: Set Up the Run Directory ===
+
-----------------------------------------------------------
 +
Do you want to track run directory changes with git? (y/n)
 +
-----------------------------------------------------------
  
−
Symbolic links to restart files, input data, and tile files for mapping between lat-lon and cubed sphere grids are automatically included in the run directory and do not require additional setup. However, you should check that the links were properly set by ensuring none are broken symbolic links.
+
== Set Environment ==
  
−
Then manually set a symbolic link to your source code directory. A utility bash script included in the run directory called <tt>setCodeDir</tt> will do this for you. Execute it as follows:
+
Set the <code>gchp.env</code> symbolic link to the same GCHP environment file you used for building the executable. This generically named symbolic link exists for convenience for inclusion in reusable scripts to automate build and run. To set it, use shell script <code>setEnvironment</code>.
  
−
  ./setCodeDir /path/to/code
+
cd /home/gchp_fullchem
 +
  ./setEnvironment /home/envs/gchp_ifort19_openmpi4.env
  
−
Note that there should not be any symbolic links within the path that you pass to setCodeDir as this will cause a compile error within ESMF.
+
'''Tips:'''
 +
*You can keep your environment file anywhere on your system for reuse across multiple run directories.
 +
*Always source <code>gchp.env</code> prior to building and running GCHP. It is included by default in all example run scripts.
 +
*Check CMake file <tt>CMakeCache.txt</tt> when in doubt about what environment was used to build the executable.
  
 
--------------------------------------
 
--------------------------------------
−
'''''[[Downloading_GCHP|Previous]] | [[Setting_Up_the_GCHP_Environment|Next]] | [[Getting_Started_With_GCHP|User Manual Home]] | [[GEOS-Chem_HP|GCHP Home]]'''''
+
'''''[[Compiling_GCHP|Previous]] | [[Running_GCHP:_Basics|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''

Latest revision as of 15:40, 8 December 2020

The GCHP documentation has moved to https://gchp.readthedocs.io/. The GCHP documentation on http://wiki.seas.harvard.edu/ will stay online for several months, but it is outdated and no longer active!


Previous | Next | Getting Started with GCHP | GCHP Main Page

  1. Hardware and Software Requirements
  2. Setting Up the GCHP Environment
  3. Downloading Source Code and Data Directories
  4. Compiling
  5. Obtaining a Run Directory
  6. Running GCHP: Basics
  7. Running GCHP: Configuration
  8. Output Data
  9. Developing GCHP
  10. Run Configuration Files


Create Run Directory

GCHP run directories are created from within the source code. A new run directory should be created for each different version of GEOS-Chem you use. Git version information is logged to file rundir.version within the run directory upon creation.

To create a run directory, navigate to the run/ subdirectory of the source code and execute shell script createRunDir.sh. 

$ cd ~/GCHPctm/run
$ ./createRunDir.sh

During the course of script execution you will be asked a series of questions:

Enter ExtData directory path

The first time you create a GCHP run directory on your system you will be prompted for a path to GEOS-Chem shared data directories. The path should include the name of your ExtData directory and should not contain symbolic links. The path you enter will be stored in file .geoschem/config in your home directory as environment variable GC_DATA_ROOT. If that file does not already exist it will be created for you. When creating additional run directories you will only be prompted again if the file is missing or if the path within it is not valid. 

-----------------------------------------------------------
Enter path for ExtData:
-----------------------------------------------------------

Choose simulation type

Enter the integer number that is next to the simulation type you want to use. 

-----------------------------------------------------------
Choose simulation type:
-----------------------------------------------------------
  1. Full chemistry
  2. TransportTracers

If creating a full chemistry run directory you will be given additional options. Enter the integer number that is next to the simulation option you want to run. 

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

Choose meteorology source

Enter the integer number that is next to the input meteorology source you would like to use. 

-----------------------------------------------------------
Choose meteorology source:
-----------------------------------------------------------
 1. MERRA2 (Recommended)
 2. GEOS-FP

Enter run directory path

Enter the target path where the run directory will be stored. You will be prompted to enter a new path if the one you enter does not exist. 

-----------------------------------------------------------
Enter path where the run directory will be created:
-----------------------------------------------------------

Enter run directory name

Enter the run directory name, or accept the default. You will be prompted for a new name if a run directory of the same name already exists at the target path. 

-----------------------------------------------------------
Enter run directory name, or press return to use default:
-----------------------------------------------------------

Put run directory under version control (optional)

Enter whether you would like your run directory tracked with git version control. With version control you can keep track of exactly what you changed relative to the original settings. This is useful for trouble-shooting as well as tracking run directory feature changes you wish to migrate back to the standard model. 

-----------------------------------------------------------
Do you want to track run directory changes with git? (y/n)
-----------------------------------------------------------

Set Environment

Set the gchp.env symbolic link to the same GCHP environment file you used for building the executable. This generically named symbolic link exists for convenience for inclusion in reusable scripts to automate build and run. To set it, use shell script setEnvironment. 

cd /home/gchp_fullchem
./setEnvironment /home/envs/gchp_ifort19_openmpi4.env

Tips:

  • You can keep your environment file anywhere on your system for reuse across multiple run directories.
  • Always source gchp.env prior to building and running GCHP. It is included by default in all example run scripts.
  • Check CMake file CMakeCache.txt when in doubt about what environment was used to build the executable.

Previous | Next | Getting Started with GCHP | GCHP Main Page

Retrieved from "https://wiki.seas.harvard.edu/geos-chem/index.php?title=Obtaining_a_GCHP_Run_Directory&oldid=48672"