Difference between revisions of "Obtaining a GCHP Run Directory"

From Geos-chem
Jump to: navigation, search
(ExtData directory path)
 
(20 intermediate revisions by one other user 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]] | [[GCHP Main Page]]'''''
+
'''''[[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>
  
==Step 1: Create Run Directory==
+
==Create Run Directory==
  
Navigate to the <code>run/</code> subdirectory of the source code and create a run directory using shell script <code>createRunDir.sh</code>.
+
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
 
  $ cd ~/GCHPctm/run
Line 22: Line 28:
 
During the course of script execution you will be asked a series of questions:
 
During the course of script execution you will be asked a series of questions:
  
=== ExtData directory path ===
+
==== 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 <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.
+
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.
  
===Simulation type===
+
-----------------------------------------------------------
 +
Enter path for ExtData:
 +
-----------------------------------------------------------
  
You will next be prompted for what simulation you wish to create a run directory for.
+
====Choose simulation type====
  
 +
Enter the integer number that is next to the simulation type you want to use.
 +
 +
-----------------------------------------------------------
 
  Choose simulation type:
 
  Choose simulation type:
  1. TransportTracers
+
-----------------------------------------------------------
  2. Standard
+
  1. Full chemistry
  3. Benchmark
+
  2. TransportTracers
  
Enter the integer number next to the simulation type you want to use that is displayed on the screen.
+
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.
  
===Meteorology source===
+
-----------------------------------------------------------
 +
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
  
Next, choose which meteorology source you would like to use.
+
====Choose meteorology source====
  
 +
Enter the integer number that is next to the input meteorology source you would like to use.
 +
 +
-----------------------------------------------------------
 
  Choose meteorology source:
 
  Choose meteorology source:
   1. MERRA2 (recommended)
+
-----------------------------------------------------------
 +
   1. MERRA2 (Recommended)
 
   2. GEOS-FP
 
   2. GEOS-FP
  
Currently GCHP supports GEOS-FP and MERRA2 data only. Input data resolution is 0.25x0.325 for GEOS-FP and 0.5x0.625 for MERRA2 by default. Unlike GEOS-Chem Classic, GCHP input meteorology data does not need to be the same grid type or grid resolution as the grid and resolution you run at.
+
====Enter run directory path====
  
===Storage location===
+
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.
 
+
Next, enter the target path where you want your run directory to be stored.
+
  
 +
-----------------------------------------------------------
 
  Enter path where the run directory will be created:
 
  Enter path where the run directory will be created:
 +
-----------------------------------------------------------
  
Do not include symbolic links in the path. Choose your path wisely to keep your runs organized.
+
====Enter run directory name====
  
===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.
 
+
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 <code>gchp_{simulation_type}</code>. Here is an example of what you will see if using the default name for the standard full chemistry simulation:
+
  
 +
-----------------------------------------------------------
 
  Enter run directory name, or press return to use default:
 
  Enter run directory name, or press return to use default:
   
+
  -----------------------------------------------------------
+
Using default directory name gchp_standard
+
 
+
===Run directory version control===
+
  
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 or turning components on or off. With version control you can keep track of exactly what you changed relative to the original settings.
+
====Put run directory under version control (optional)====
  
This is what you will see if you use to put your run directory under version control with git:
+
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)
 
  Do you want to track run directory changes with git? (y/n)
  y
+
  -----------------------------------------------------------
Initialized empty Git repository in /n/home/user003/gchp_standard/.git/
+
  
We strongly recommend using this feature 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>, and then commit those changes with your source code updates. If you forked the repository you can then push to your fork and do a pull request to send us your updates.
+
== Set Environment ==
  
== Step 2: Set Environment ==
+
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>.
 
+
Set the <code>gchp.env</code> symbolic link to your GCHP environment file using shell script <code>setEnvironment</code>.
+
  
 
  cd /home/gchp_fullchem
 
  cd /home/gchp_fullchem
Line 85: Line 103:
 
'''Tips:'''
 
'''Tips:'''
 
*You can keep your environment file anywhere on your system for reuse across multiple run directories.
 
*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.
+
*Always source <code>gchp.env</code> prior to building and running GCHP. It is included by default in all example run scripts.
*Include <code>source gchp.env</code> at the top of your run scripts.
+
*Check CMake file <tt>CMakeCache.txt</tt> when in doubt about what environment was used to build the executable.
 
+
== Additional information ==
+
 
+
A new run directory should be created for each different version of GEOS-Chem you use. Version information per run directory is located in file <code>rundir.version</code>.
+
  
 
--------------------------------------
 
--------------------------------------
'''''[[Downloading_GCHP|Previous]] | [[Setting_Up_the_GCHP_Environment|Next]] | [[Getting Started with GCHP]] | [[GCHP Main Page]]'''''
+
'''''[[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