HEMCORelease 13.0.0-alpha.10

GEOS-Chem Support Team

Dec 08, 2020

GETTING STARTED

1 Quick start 1

2 Requirements 3

3 Downloading GCHP 5

4 Compiling GCHP 7

5 Creating a run directory 9

6 Configuring a run directory 11

7 Running GCHP 13

8 Plotting GCHP output 15

9 Stretched-grid simulations 17

10 Editing this user guide 19

Index 21

i

ii

CHAPTER

ONE

QUICK START

todo

1

HEMCO, Release 13.0.0-alpha.10

2 Chapter 1. Quick start

CHAPTER

TWO

REQUIREMENTS

2.1 Software requirements

The following are GCHP’s required dependencies:

• Git

• Fortran compiler (gfortran 8.3 or greater, ifort 18 or greater)

• CMake (version 3.13 or greater)

• NetCDF-C, NetCDF-CXX, NetCDF-Fortran

• MPI (C, C++, and Fortran)

• ESMF (version 8.0.0 or greater)

You must load your environment file prior to building and running GCHP.

$ source /home/envs/gchpctm_ifort18.0.5_openmpi4.0.1.env

If you don’t already have ESMF 8.0.0+, you will need to download and build it. You only need to build ESMF onceper compiler and MPI configuration (this includes for ALL users on a cluster!). It is therefore worth downloadingand building somewhere stable and permanent, as almost no users of GCHP would be expected to need to modifyor rebuild ESMF except when adding a new compiler or MPI. Instructions for downloading and building ESMF areavailable at the GCHP wiki.

It is good practice to store your environment setup in a text file for reuse. Below are a couple examples that loadlibraries and export the necessary environment variables for building and running GCHP. Note that library versioninformation is included in the filename for easy reference. Be sure to use the same libraries that were used to createthe ESMF build install directory stored in environment variable ESMF_ROOT.

Environment file example 1

# file: gchpctm_ifort18.0.5_openmpi4.0.1.env

# Start freshmodule --force purge

# Load modules (some include loading other libraries such as netcdf-C and hdf5)module load intel/18.0.5module load openmpi/4.0.1module load netcdf-fortran/4.5.2module load cmake/3.16.1

# Set environment variables

(continues on next page)

3

HEMCO, Release 13.0.0-alpha.10

(continued from previous page)

export CC=gccexport CXX=g++export FC=ifort

# Set location of ESMFexport ESMF_ROOT=/n/lab_shared/libraries/ESMF/ESMF_8_0_1/INSTALL_ifort18_openmpi4

Environment file example 2

# file: gchpctm_gcc7.4_openmpi.rc

# Start freshmodule --force purge

# Load modulesmodule load gcc-7.4.0spack load cmakespack load openmpi%gcc@7.4.0spack load hdf5%gcc@7.4.0spack load netcdf%gcc@7.4.0spack load netcdf-fortran%gcc@7.4.0

# Set environment variablesexport CC=gccexport CXX=g++export FC=gfortran

# Set location of ESMFexport ESMF_ROOT=/n/home/ESMFv8/DEFAULTINSTALLDIR

4 Chapter 2. Requirements

CHAPTER

THREE

DOWNLOADING GCHP

When cloning GCHP you will get the main branch by default.

$ git clone https://github.com/geoschem/gchpctm.git Code.GCHP$ cd Code.GCHP$ git submodule update --init --recursive

If you would like a different version of GCHP you can checkout the branch or tag from the top-level directory. Bewarethat you must always then update the submodules again to checkout the compatible submodule versions. If you haveany unsaved changes in a submdodule, such as local GEOS-Chem development, make sure you commit those to abranch prior to updating versions.

$ cd Code.GCHP$ git checkout tags/13.0.0-alpha.6$ git submodule update --init --recursive

5

HEMCO, Release 13.0.0-alpha.10

6 Chapter 3. Downloading GCHP

CHAPTER

FOUR

COMPILING GCHP

Building with CMake is different than with GNU Make (the way to build GEOS-Chem versions prior to 13.0).With CMake, there are two steps: (1) a cmake command, and (2) a make command. The cmake commandis used to set major options, and is often run just once per build directory. Running this command with-DCMAKE_BUILD_TYPE=Debug will result in a GCHP build with bounds checking and other debug options. Ad-ditional compile options, such as LUO_WETDEP, can be appended with -D, e.g. -DLUO_WETDEP=y.

4.1 Create your build directory

The build directory will contain all files related to building GCHP with a specific environment and set of compilerflags. All source code directories outside of the build directory remain unchanged during compilation, unlike in earlierversions of GCHP in which *.o files (for example) were scattered throughout the source code tree. You can put yourbuild directory in the root directory of Code.GCHP or you can put it anywhere else.

For your very first built we recommend that you build from the source code for simplicity.

$ cd Code.GCHP$ mkdir build

As you get more advanced, you may wish to create your build directory in your run directory or in a directory specificto GCHP version.

4.2 Configure CMake

The first argument passed to the cmake command must be the relative path to the root GCHP directory. For the caseof the build directory within source code directory, the root GCHP directory is one level up.

$ cd build$ cmake ..

If you store your build directory in your run directory instead then the relative path would be ../CodeDir, makinguse of the symbolic link to the source code that is automatically generated when creating a run directory.

If the last few lines of output from cmake look similar to the following snippet then your build was configuredsuccessfully.

...-- Configuring done-- Generating done-- Build files have been written to: /data10/bindle/Code.GCHP/build

7

HEMCO, Release 13.0.0-alpha.10

4.3 Compile

The full build does not occur until you run the make command.

$ make -j

4.4 Recompiling

Once the above steps have been performed only the make step should be necessary each time you need to rebuild thecode. The exceptions to this are if you change your environment or your compile options. In all cases it should never benecessary to run make clean. The make command already checks all components of the build for changes. If youwant to rebuild from scratch because you changed environments, simply delete all files from the build/ directoryand recompile. You can also create a new build directory (with a different name) and compile from there to preserveyour previous build.

8 Chapter 4. Compiling GCHP

CHAPTER

FIVE

CREATING A RUN DIRECTORY

First, make a high-level directory to contain all the run directories associated with this version of GCHP. This shouldbe somewhere with plenty of space, as all run output will be in subdirectories of this directory. You can optionallycreate one or more build directories here for storage and easy access to GCHP builds specific to a certain version (seeprevious section on building GCHP).

$ mkdir /scratch/testruns/GCHP/13.0.0

Next, enter the run/ subdirectory in Code.GCHP. Do not edit this directory - this is the template for all other rundirectories! Instead, use the script there to create a new run directory, following the instructions printed to the screen.

$ cd Code.GCHP$ cd run$ ./createRunDir.sh

For example, to create a standard (full-chemistry) run directory, choose (actual responses in brackets):

• Standard simulation (2)

• MERRA2 meteorology (2)

• The directory you just created in step 1 (/scratch/rundirs/GCHP/13.0.0)

• A distinctive run directory name (fullchem_first_test)

• Use git to track run directory changes (y)

This will create and set up a full-chemistry, MERRA-2, GCHP run directory in /scratch/testruns/GCHP/13.0.0/fullchem_first_test. Note that these options only affect the run directory contents, and NOT the buildprocess - the same GCHP executable is usable for almost all simulation types and supported met data options.

Navigate to your new run directory, and set it up for the first run:

$ cd /scratch/testruns/GCHP/13.0.0/fullchem_first_test$ ./setEnvironment /home/envs/gchpctm_ifort18.0.5_openmpi4.0.1.env # This sets up the→˓gchp.env symlink$ source gchp.env # Set up build environment, if not already done$ cp runScriptSamples/gchp.run . # Set up run script - your system is likely to be→˓different! See also gchp.local.run.$ cp CodeDir/build/bin/geos . # Get the compiled executable

9

HEMCO, Release 13.0.0-alpha.10

10 Chapter 5. Creating a run directory

CHAPTER

SIX

CONFIGURING A RUN DIRECTORY

todo

11

HEMCO, Release 13.0.0-alpha.10

12 Chapter 6. Configuring a run directory

CHAPTER

SEVEN

RUNNING GCHP

$ sbatch gchp.run

For more information about GCHP, see the following resources: GCHP wiki. GCHP issues on GitHub

13

HEMCO, Release 13.0.0-alpha.10

14 Chapter 7. Running GCHP

CHAPTER

EIGHT

PLOTTING GCHP OUTPUT

todo

15

HEMCO, Release 13.0.0-alpha.10

16 Chapter 8. Plotting GCHP output

CHAPTER

NINE

STRETCHED-GRID SIMULATIONS

todo

17

HEMCO, Release 13.0.0-alpha.10

18 Chapter 9. Stretched-grid simulations

CHAPTER

TEN

EDITING THIS USER GUIDE

This user guide is generated with Sphinx.

10.1 Quick start

To build this user guide on your local machine, you need to install Sphinx. Sphinx is a Python 3 package and it is avail-able via pip. This user guide uses the Read The Docs theme, so you will also need to install sphinx-rtd-theme.

$ pip install sphinx sphinx-rtd-theme

To build this user guide locally, navigate to the docs/ directory and make the html target.

gcuser:~$ cd gcpy/docsgcuser:~/gcpy/docs$ make html

This will build the user guide in docs/build/html, and you can open index.html in your web-browser. Thesource files for the user guide are found in docs/source.

Note: You can clean the documentation with make clean.

10.2 Learning reST

Writing reST can be tricky at first. Whitespace matters, and some directives can be easily miswritten. Two importantthings you should know right away are:

• Indents are 3-spaces

• “Things” are separated by 1 blank line. For example, a list or code-block following a paragraph should beseparated from the paragraph by 1 blank line.

You should keep these in mind when you’re first getting started. Dedicating an hour to learning reST will save youtime in the long-run. Below are some good resources for learning reST.

• reStructuredText primer: (single best resource; however, it’s better read than skimmed)

• Official reStructuredText reference (there is a lot of information here)

• Presentation by Eric Holscher (co-founder of Read The Docs) at DjangoCon US 2015 (the entire presentationis good, but reST is described from 9:03 to 21:04)

• YouTube tutorial by Audrey Tavares’s

19

HEMCO, Release 13.0.0-alpha.10

A good starting point would be Eric Holscher’s presentations followed by the reStructuredText primer.

10.3 Style guidelines

Important: This user guide is written in semantic markup. This is important so that the user guide remains maintain-able. Before contributing to this documentation, please review our style guidelines (below). When editing the source,please refrain from using elements with the wrong semantic meaning for aesthetic reasons. Aesthetic issues can beaddressed by changes to the theme.

For titles and headers:

• Section headers should be underlined by # characters

• Subsection headers should be underlined by - characters

• Subsubsection headers should be underlined by ^ characters

• Subsubsubsection headers should be avoided, but if necessary, they should be underlined by " characters

File paths (including directories) occuring in the text should use the :file: role.

Program names (e.g. cmake) occuring in the text should use the :program: role.

OS-level commands (e.g. rm) occuring in the text should use the :command: role.

Environment variables occuring in the text should use the :envvar: role.

Inline code or code variables occuring in the text should use the :code: role.

Code snippets should use .. code-block:: <language> directive like so

.. code-block:: python

import gcpyprint("hello world")

The language can be “none” to omit syntax highlighting.

For command line instructions, the “console” language should be used. The $ should be used to denote the console’sprompt. If the current working directory is relevant to the instructions, a prompt like gcuser:~/path1/path2$should be used.

Inline literals (e.g. the $ above) should use the :literal: role.

20 Chapter 10. Editing this user guide

INDEX

Eenvironment variable

ESMF_ROOT, 3ESMF_ROOT, 3

21