Difference between revisions of "Obtaining a GCHP Run Directory"

From Geos-chem
Jump to: navigation, search
(Step 1: Create Run Directory)
 
(78 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|Getting Started with GCHP]]'''''
+
'''''[[Compiling_GCHP|Previous]] | [[Running_GCHP:_Basics|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''
#[[Downloading_GCHP|Downloading Source Code]]
+
#[[GCHP_Hardware_and_Software_Requirements|Hardware and Software Requirements]]
#<span style="color:blue">'''Obtaining a Run Directory'''</span>
+
 
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 
#[[Setting_Up_the_GCHP_Environment|Setting Up the GCHP Environment]]
 +
#[[Downloading_GCHP|Downloading Source Code and Data Directories]]
 
#[[Compiling_GCHP|Compiling]]
 
#[[Compiling_GCHP|Compiling]]
#[[GCHP_Basic_Example_Run|Basic Example Run]]
+
#<span style="color:blue">'''Obtaining a Run Directory'''</span>
#[[GCHP_Run_Configuration_Files|Run Configuration Files]]
+
#[[Running_GCHP:_Basics|Running GCHP: Basics]]
#[[Running_GCHP|Advanced Run Examples]]
+
#[[Running_GCHP:_Configuration|Running GCHP: Configuration]]
#[[GEOS-Chem_HP_Output_Data|Output Data]]
+
#[[GCHP_Output_Data|Output Data]]
 
#[[Developing_GCHP|Developing GCHP]]
 
#[[Developing_GCHP|Developing GCHP]]
 +
#[[GCHP_Run_Configuration_Files|Run Configuration Files]]
 
<br>
 
<br>
  
== Overview ==
+
==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 <code>rundir.version</code> within the run directory upon creation.
 +
 
 +
To create a run directory, navigate to the <code>run/</code> subdirectory of the source code and execute shell script <code>createRunDir.sh</code>.
 +
 
 +
$ cd ~/GCHPctm/run
 +
$ ./createRunDir.sh
  
The procedure for acquiring a GCHP run directory is the same as acquiring a GCC run directory. However, you will need to take the added step of setting up your run directory by running a bash script included in the directory files.
+
During the course of script execution you will be asked a series of questions:
  
==Step 1: Create Run Directory==
+
==== Enter ExtData directory path ====
  
You can create a GCHP run directory using the [[GEOS-Chem Unit Tester]]. 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:
+
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.
  
  git clone git@github.com:GCST/geos-chem-unittest.git UT
+
  -----------------------------------------------------------
 +
Enter path for ExtData:
 +
-----------------------------------------------------------
  
There are three run directories available for GCHP starting in GEOS-Chem v11-02c. They are for the radon-lead-beryllium simulation, the standard full chemistry simulation, and the benchmarking simulation which now incorporates both simple and complex SOA. The default settings for all run directories are for a 72-level simulation using input 0.25x0.3125 meteorology, and internal c24 cubed sphere grid resolution (roughly equivalent to 4x5). Please note that internal resolution is now configurable within the run directory and the run directory name therefore does not include resolution (unlike GEOS-Chem "classic").
+
====Choose simulation type====
  
Example steps for creating a standard full-chemistry run directory called <tt>gchp_standard</tt>:
+
Enter the integer number that is next to the simulation type you want to use.
+
#Change directories into <tt>/mypath/GCHP/UTBE/perl</tt>
+
#Open <tt>CopyRunDirs.input</tt> in a text editor and make the following changes:
+
##Update <tt>DATA_ROOT</tt> to point to the [[GEOS-Chem_basics#The_GEOS-Chem_shared_data_directories|GEOS-Chem shared data directories]] on your system. The default settings are compatible with the Harvard Odyssey compute cluster.
+
##Change variable <tt>UNIT_TEST_ROOT</tt> to match the directory to which you cloned the unit tester (e.g. <tt>/mypath/UTBE</tt>)
+
##Change 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>)
+
##Comment out the line for the GEOS-FP standard simulation  (<tt>MET=geosfp</tt>, <tt>GRID=4x5</tt>, <tt>SIMULATION=standard</tt>)
+
##Uncomment the line for the GCHP standard run directory (<tt>MET=gchp</tt>, <tt>SIMULATION=standard</tt>)
+
#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.
+
-----------------------------------------------------------
 +
Choose simulation type:
 +
-----------------------------------------------------------
 +
  1. Full chemistry
 +
  2. TransportTracers
  
==Step 2: Set Up 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.
  
=== v11-02c ===
+
-----------------------------------------------------------
 +
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
  
Symbolic links to restart files, input data, and time files for mapping between lat-lon and cubed sphere grids are included in the run directory. Prior to compiling GCHP, however, you must 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:
+
====Choose meteorology source====
  
./setCodeDir /path/to/code
+
Enter the integer number that is next to the input meteorology source you would like to use.
  
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.
+
-----------------------------------------------------------
 +
Choose meteorology source:
 +
-----------------------------------------------------------
 +
  1. MERRA2 (Recommended)
 +
  2. GEOS-FP
  
--[[User:Lizzie Lundgren|Lizzie Lundgren]] ([[User talk:Lizzie Lundgren|talk]]) 16:18, 25 September 2017 (UTC)
+
====Enter run directory path====
  
=== v11-02b ===
+
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 v11-02c, additional steps are required after downloading the GCHP run directory to set it up for compilation and runs. These include setting symbolic links to your restart file and data directories containing source code, input data, and tile files (mapping between lat/lon and cubed sphere grids), and are done using the <tt>initialSetup.sh</tt> bash script included in the run directory. If you are using Harvard's [https://www.rc.fas.harvard.edu/odyssey/ Odyssey compute cluster] then most symbolic links will be set for you automatically. If you are on a system other than Odyssey then you will need to enter paths manually. Make sure that you have the full paths to all required directories before you start.
+
-----------------------------------------------------------
 +
Enter path where the run directory will be created:
 +
-----------------------------------------------------------
  
Prior to proceeding, you will need to download several directories and files for GCHP beyond what is used for GEOS-Chem classic v11-01 if they are not already present on your network. If someone at your school or institution has already set up GCHP on your network then these files likely already exist and you may skip this step. The necessary files and directories are as follows:
+
====Enter run directory name====
* <tt>ExtData/GCHP/Tilefiles</tt>
+
* <tt>ExtData/SPC_RESTARTS/initial_GEOSChem_rst.c24_standard.nc</tt>
+
* <tt>gcdata/GEOS_NATIVE/MODIS_LAI_201204/For_Olson_2001/XLAI_for_GCHP/</tt>
+
* <tt>gcdata/GEOS_NATIVE/Olson_Land_Map_201203/Olson_2001_Land_Map.025x025.generic.GCHP.nc</tt>
+
  
Steps to download these directories are the same as for GEOS-Chem classic as described on the [http://wiki.seas.harvard.edu/geos-chem/index.php/Downloading_GEOS-Chem_source_code_and_data#Downloading_the_shared_data_directories_via_anonymous_FTP Downloading Shared Data Directories] wiki page.  
+
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.
  
Once you are certain you have all necessary inputs, run the <tt>initialSetup.sh</tt> bash script included in the run directory by typing:
+
-----------------------------------------------------------
 +
Enter run directory name, or press return to use default:
 +
-----------------------------------------------------------
  
cd /mypath/GCHP/rundirs/gchp_c24_standard
+
====Put run directory under version control (optional)====
./initialSetup.sh
+
  
Based on the system you are using, you may expect to go through the following steps for set up:
+
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.
  
'''Odyssey Users'''
+
-----------------------------------------------------------
 +
Do you want to track run directory changes with git? (y/n)
 +
-----------------------------------------------------------
  
#Enter the path to the source code you downloaded (specify full path without symbolic links).
+
== Set Environment ==
#Enter <tt>y</tt> when asked if you are on Odyssey.
+
  
'''Non-Odyssey Users'''
+
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>.
  
#Enter the path to the source code you downloaded (specify full path without symbolic links).
+
cd /home/gchp_fullchem
#Enter <tt>n</tt> when asked if you are on Odyssey.
+
./setEnvironment /home/envs/gchp_ifort19_openmpi4.env
#You will go through a series of prompts asking you to set up the paths to your data directories. You should have the primary path for your group's shared data directories handy for this step (i.e. the path to [[Setting_up_the_ExtData_directory|<tt>ExtData</tt>]]). Within <tt>ExtData</tt> there should be subdirectories called <tt>HEMCO</tt>, <tt>CHEM_INPUTS</tt>, <tt>GCHP/TileFiles</tt>, and <tt>SPC_RESTARTS</tt>, as well as several met data subdirectories of format <tt>GEOS_{RESOLUTION}</tt>. If you are missing any of these subdirectories, exit out of initialSetup.sh (using Ctrl+C) and find out where they are located prior to continuing.
+
##For path containing met data, specify the location of the folder containing GEOS-FP formatted meteorological data at input grid resolution you wish to use. The default input meteorology in the run directory is 2x2.5 so enter <tt>/{LOCAL_PATH}/ExtData/GEOS_2x2.5/GEOS_FP</tt> for this tutorial. Instructions on how to update configuration files for other input resolutions are given later in the guide.
+
##For the path to HEMCO data directory, enter <tt>/{LOCAL_PATH}/ExtData/HEMCO</tt>.
+
##For the path to GEOS-Chem restart files, enter <tt>/{LOCAL_PATH}/ExtData/SPC_RESTARTS</tt>.
+
##For the path to CHEM_INPUTS directory, enter <tt>/{LOCAL_PATH}/ExtData/CHEM_INPUTS</tt>.
+
##For the path to tile files, enter <tt>/{LOCAL_PATH}/ExtData/GCHP/TileFiles</tt>.
+
  
 +
'''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]] | [[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