Quickstart Guide
This quickstart guide is for quick reference on how to download, build, and run GEOS-Chem Classic, which is the single-node instance of GEOS-Chem.
Tip
Please also see our GCHP Quickstart Guide if you would like to run GEOS-Chem across using more than one computational node.
This guide assumes that your environment satisfies GEOS-Chem Classic hardware and software requirements. This means you should load a compute environment such that programs like cmake are available before continuing. If you do not have some of the required software dependencies, you can find instructions for installing external dependencies in our Spack instructions.
For simplicity we will also refer to GEOS-Chem Classic as simply GEOS-Chem on this page. More detailed instructions on downloading, compiling, and running GEOS-Chem can be found in the User Guide elsewhere on this site.
1. Clone GEOS-Chem Classic
Download the source code:
$ git clone --recurse-submodules https://github.com/geoschem/GCClassic.git GCClassic
$ cd GCClassic
Tip
If you wish, you may choose a different name for the source code folder, e.g.
$ git clone --recurse-submodules https://github.com/geoschem/GCClassic.git my_code_dir
$ cd my_code_dir
Upon download you will have the most recently released version. You can check what this is by printing the last commit in the git log and scanning the output for tag.
$ git log -n 1
Tip
To use an older GEOS-Chem Classic version (e.g. 14.0.0), follow these additional steps:
$ git checkout tags/14.0.0 # Points HEAD to the tag "14.0.0"
$ git branch version_14.0.0 # Creates a new branch at tag "14.0.0"
$ git checkout version_14.0.0 # Checks out the version_14.0.0 branch
$ git submodule update --init --recursive # Reverts submodules to the "14.0.0" tag
You can do this for any tag in the version history. For a list of all tags, type:
$ git tag
If you have any unsaved changes, make sure you commit those to a branch prior to updating versions.
2. Create a run directory
Navigate to the run/
subdirectory. To create a run
directory, run the script ./createRunDir.sh
:
$ cd run/
$ ./createRunDir.sh
Creating a run directory is interactive, meaning you will
be asked multiple questions to set up the simulation. For example,
running createRunDir.sh
will prompt questions about
configurable settings such as simulation type, grid resolution,
meteorology source, and number of vertical levels. It will also ask
you where you want to store your run directory and what you wish to
name it, including whether you want to use the default name,
e.g. gc_4x5_merra2_fullchem
. We recommend storing run
directories in a place that has a large storage capacity. It does
not need to be in the same location as your source code. When
creating a run directory you can quit and start from scratch at any
time.
For demonstration purposes, we will use a full chemistry simulation
run directory with the default name (gc_merra2_4x5_fullchem
).
The steps to setup and run other types of GEOS-Chem Classic
simulations follow the same pattern as the examples shown below.
Attention
The first time you create a run directory, you will be asked to provide registration information. Please answer all of the questions, as it will help us to keep track of GEOS-Chem usage worldwide. We will also add your information to the GEOS-Chem Users web page.
Important
The convection scheme used for GEOS-FP met generation changed from RAS to Grell-Freitas with impact on GEOS-FP meteorology files starting June 1, 2020, specifically enhanced vertical transport. In addition, there is a bug in convective precipitation flux following the switch where all values are zero. While this bug is automatically fixed by computing fluxes online for runs starting on or after June 1 2020, the fix assumes meteorology year corresponds to simulation year. Due to these issues we recommend splitting up GEOS-FP runs in time such that a single simulation does not run across June 1, 2020. Instead. set one run to stop on June 1 2020 and then restart a new run from there. If you wish to use a GEOS-FP meteorology year different from your simulation year please create a GEOS-Chem GitHub issue for assistance.
3. Load your environment
Always make sure that all libraries and environment variables are loaded prior to building GEOS-Chem Classic. An easy way to do this is to write an environment file and load that file every time you work with GEOS-Chem. To make this extra easy you can create a symbolic link to your environment file within your run directory or for reference. For example, do the following in your new run directory to have a handy link to the environment you plan on using.
$ cd /path/to/gc_4x5_merra2_fullchem # Skip if you are already here
$ ln -s ~/envs/gcc.gfortran10.env gcc.env
Then every time you start up a session to work with GEOS-Chem in your run directory you can easily load your environment.
$ source gcc.env
4. Configure your build
You may build GEOS-Chem Classic from within the run directory or from
anywhere else on your system. But we recommend that you always build
GEOS-Chem Classic from within the run directory. This is convenient
because it keeps all build files in close proximity to where you will
run the model. For this purpose the GEOS-Chem run directory includes a
build directory called build/
.
First, navigate to the build/
folder of your run directory:
$ cd /path/to/gc_4x5_merra2_fullchem # Skip if you are already here
$ cd build
The next step is to configure your build. These
are persistent settings that are saved to your build directory. A
useful configuration option is -DRUNDIR
. This option lets you
specify one or more run directories that GEOS-Chem is “installed” to;
that is, where where the executable is copied, when you do
make install.
Configure your build so it installs GEOS-Chem to the run directory you
created in Step 2. The run directory is one directory level higher
than the build
directory. Also located one level higher than
the build directory is the CodeDir
symbolic link to the
top-level GEOS-Chem source code directory. Use the following command to
configure your build:
$ cmake ../CodeDir -DRUNDIR=..
GEOS-Chem has a number of additional configuration options you can add here. For example, to compile with RRTMG after running the above command:
Note
The .
in the cmake command above is
important. It tells CMake that your current working directory
(i.e., .
) is your build directory.
$ cmake . -DRRTMG=y
A useful configuration option is to build in debug mode. Doing this is a good idea if you encountered an error (such as a segmentation fault) in a previous run and need more information about where the error happened and why.
$ cmake . -DCMAKE_BUILD_TYPE=Debug
Click here for more information on configuration options.
5. Compile and install
Compiling GEOS-Chem Classic should take about a
minute, but it can vary depending on your system, your compiler, and
your configuration options. To maximize build speed you should compile
GEOS-Chem in parallel using as many cores as are available. Do this
with the -j
flag from the build/
directory:
$ cd /path/to/gc_4x5_merra2_fullchem/build # Skip if you are already here
$ make -j
Upon successful compilation, install the compiled executable to your run directory:
$ make install
This copies executable build/bin/gcclassic
and supplemental
files to your run directory.
Note
You can update build settings at any time:
Navigate to your build directory.
Update your build settings with cmake (only if they differ since your last execution of cmake)
Recompile with make -j. Note that the build system automatically figures out what (if any) files need to be recompiled.
Install the rebuilt executable with make install.
If you do not install the executable to your run directory you can always get the executable from the directory build/bin.
6. Configure your run directory
Now, navigate to your run directory:
$ cd /path/to/gcc_4x5_merra2_fullchem
You should review these files before starting a simulation:
- geoschem_config.yml
Controls several frequently-updated simulation settings (e.g. start and end time, which operations to turn on/off, etc.)
- HISTORY.rc
Controls GEOS-Chem diagnostic settings.
- HEMCO_Diagn.rc
Controls emissions diagnostic settings via HEMCO.
- HEMCO_Config.rc
Controls which emissions inventories and other non-emissions data will be read from disk (via HEMCO).
Attention
If you wish to spin up a GEOS-Chem simulation with a restart file
that has (1) missing species or (2) a timestamp that does not
match the start date in geoschem_config.yml,
simply change the time cycle flag for the SPC_
entry in
HEMCO_Config.rc from
* SPC_ ... $YYYY/$MM/$DD/$HH EFYO xyz 1 * - 1 1
to
* SPC_ ... $YYYY/$MM/$DD/$HH CYS xyz 1 * - 1 1
This will direct HEMCO to read the closest date
available (C
), to use the simulation year
(Y
), and to skip any species (S
) not found
in the restart file.
Skipped species will be assigned the initial concentration
(units: \(mol\ mol^{-1}\) w/r/t dry air) specified by its
BackgroundVV
entry in species_database.yml. If the species does not have a
BackgroundVV
value specified, then its initial
concentration will be set to \(1.0{\times}10^{-20}\)
instead.
Please see our Customize simulations with research options Supplemental Guide to learn how you can customize your simulation by activating alternate science options in your simulations.
7. Download input data
Before you can run your GEOS-Chem Classic simulation, you must first download the required input data. These data include:
Meteorological fields (e.g. GEOS-FP, MERRA-2, GEOS-IT, or GCAP2)
Tip
If your institution has several GEOS-Chem users, then someone may have already downloaded these data for you. If this is the case, you may start running your your GEOS-Chem Classic simulation right away.
The easiest way to download data is to perform a dry-run simulation. This is a GEOS-Chem Classic simulation that steps through time, but does not perform computations or read data files from disk. Instead, the dry-run simulation prints a list of all data files that the simulation would have read.
To start a dry-run simulation, type this command:
$ ./gcclassic --dryrun | tee log.dryrun
This will generate the log.dryrun
log file, which contains the
list of data files to be downloaded.
Once the dry-run simulation has finished, use the
download_data.py
file (included in your run directory) to
download the required data.
Note
Depending on your system, you might have to activate a Conda or
Mamba environment containing a version of Python before running the
download.data.py
script. Ask your sysadmin.
To start the data download, type:
$ ./download_data.py log.dryrun geoschem+http
This will download data from the GEOS-Chem Input Data portal using the HTTP data transfer protocol.
Tip
If you have AWS CLI (command line interface) installed on your system, you can use this command instead:
$ ./download_data.py log.dryrun geoschem+aws
This will use the AWS CLI data download protocol instead, which should be faster than regular HTTP connections. This is the command you should use if you are running GEOS-Chem Classic in an AWS EC2 instance.
We also maintain separate data portals for special nested-grid domains as well as the GCAP 2.0 meteorology.
For more information about dry-run simulations, please see our Download data with a dry-run simulation chapter.
8. Run your simulation
If you used an environment file to load software libraries prior to building GEOS-Chem then you should load that file prior to running. To run GEOS-Chem Classic, type at the command line:
$ ./gcclassic
If you wish to send output to a log file, use:
$ ./gcclassic > GC.log 2>&1
We recommend running GEOS-Chem Classic as a batch job, although you can also do short runs interactively. Running GEOS-Chem as a batch job means that you write a script (usually bash) and then you submit that script to your local job scheduler (SLURM, LSF, etc.). If you write a batch script you can include sourcing your environment file within the script to ensure you always use the intended environment. Submitting GEOS-Chem as a batch job is slightly different depending on your scheduler. If you aren’t familiar with scheduling jobs on your system, ask your system administrator for guidance.
Those are the basics of using GEOS-Chem Classic! See this user guide, step-by-step guides, and reference pages for more detailed instructions.