Getting Started with GCHP

GCHP Main Page

Overview

GEOS-Chem High Performance (GCHP) represents the next generation of GEOS-Chem. Capabilities that distinguish GCHP from standard GEOS-Chem (GEOS-Chem "Classic") include:

• Flexible-resolution simulations, from ~4° x 5° (C24) to ~0.25° x 0.3125° (C360) without the need for code edits or recompilation
• Use of the cubed-sphere (CS) grid, which eliminates the need for polar filtering and brings GEOS-Chem into line with the NASA GEOS AGCM
• MPI distributed-memory parallelization which enables running a single job across multiple machines

This page will guide you through the wiki pages to get started with the latest release of GCHP.

GCHP Quick Start Guide

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

Frequently Asked Questions

I do not have a high performance compute cluster. Can I run GCHP?

Yes, you can run GCHP on as little as a single node as long as there are at least 6 cores available. We are working to make serial runs on a single core possible in the future.

Is GCHP only for high resolution runs?

No! You can run GCHP at the cubed-sphere grid equivalent of 4x5 (c24) and 2x2.5 (c48). The GCHP standard simulation run directory is set up for c48 by default starting in GCHP v11-02e but can easily be changed to whatever resolution you would like to run at by updating the runConfig.sh bash script in the run directory. Unlike GEOS-Chem classic, a single GCHP run directory can be used for any run resolution.

What are the different cubed-sphere resolutions and how do they compare to lat/lon grids?

Below we summarize the standard resolution specifications and the recommended timesteps (based on the timesteps used in GEOS-Chem "classic").

Standard resolution specification	Approximate CS equivalent(s)	Suggested timestep (s)
4° x 5°	C24	1200
2° x 2.5°	C48, C45	900
1° x 1.25°	C96, C90	600
0.5° x 0.625°1	C192, C180	300
0.25° x 0.3125°2	C384, C360	300
0.125° x 0.15625°	C7203	180

¹ Native resolution of MERRA-2 product from GMAO
² Native resolution of GEOS-FP product from GMAO
³ Native cubed-sphere resolution of GEOS-5

I changed my model resolution and my run completed successfully. Are there any scientific considerations I should be aware of before drawing conclusions from my results?

Yes, there are several resolution-dependent settings or inputs that will result in degraded output quality if the model resolution increases from the default c24. These include lightning scale factors, dust parameterization, regridded cloud variables, and use of the Voronoi timezones. The GCHP Development Team is working to resolve these dependencies. Until then, please contact the GEOS-Chem Support Team for more information.

I don't have met fields at the lat/lon equivalent of the cubed-sphere resolution I want to run at. What should I use?

As a general rule of thumb you may run GCHP at cubed-sphere resolutions up to a factor of two larger than your input met resolution equivalent. For example, you could use 2x2.5 input met for both c24 and c48 runs. GCHP will generally run successfully with even higher ratios, such as 2x2.5 input met for c180. However, in these cases you should use caution in your interpretation of results. In general it is always best to use the finest met resolution available and 0.25x0.3125 is the default input met resolution starting in v11-02d. See the [Shared Data Directories wiki page] for instructions on how to access fine resolution meteorology files.

Should I change my simulation timestep if I run at very high resolution?

You may increase your timestep to improve speed but this is not required. A 30 minute dynamics timestep and 60 minute chemistry timestep may be adequate for your purposes. We recommend that you never reduce your timestep from the default of 10 minutes for dynamics and 20 minutes for chemistry/emissions.

How can I get a restart file for a different cubed-sphere resolution?

All GCHP run directories come with symbolic links to five resolutions of restart files stored in ExtData/SPC_RESTARTS: c24, c48, c96, c180, and c360. You can generate restart files for other resolutions by regridding an existing restart file using the Fortran tool csregridtool for created by Sebastian Eastham.

git clone https://bitbucket.org/sdeastham/csregridtool

Python regridding tools are also available and will be included in the gcpy package currently in development. Contact GCST member Lizzie Lundgren for more information.

I can now compile and run GCHP. Do you have tips that might help me optimize my use of GCHP?

Below are several time-saving tips to keep in mind when you start regularly using GCHP. This by no means an exhaustive list. Please submit your own to GCST if you think something should be included!

1. Only recompile code you changed. Use make help to see your options for compiling.
2. Changing simulations does not require recompilation. You can copy the geos executable to different run directories for the same code version.
3. runConfig.sh overwrites settings in other config files. Beware!
4. Do not simply run the executable; use or adapt run scripts provided. Using gchp.local.run to run from the command line with 6 cores for quick tests.
5. Run-time MAPL/ESMF errors are nearly always from bad config. Check your run directory *.rc files and runConfig.sh.
6. Errors in CAP usually inidicate bad simulation dates; check runConfig.sh.
7. ExtData errors indicate a problem in input. Set MAPL_DEBUG_LEVEL to 20 in runConfig.sh to maximize ExtData debug prints to the log file.
8. MAPL History error is problem with diagnostics; check HISTORY.rc.
9. Search for “making install” in file compile.log to find MAPL build errors.
10. Create a GCHP GitHub issue if you think you need to edit MAPL or ESMF.

---

GCHP Main Page

--Lizzie Lundgren (talk) 16:51, 10 May 2019 (UTC)