Difference between revisions of "GEOS-Chem in CESM"
(→Building the model) |
|||
| Line 53: | Line 53: | ||
SIMA = System for Integrated Modeling of the Atmosphere | SIMA = System for Integrated Modeling of the Atmosphere | ||
| − | == | + | == One-time Setup == |
| − | === | + | === Download CESM === |
Relevant NCAR docs: [https://escomp.github.io/CESM/versions/master/html/downloading_cesm.html#downloading-the-code-and-scripts Downloading CESM] | Relevant NCAR docs: [https://escomp.github.io/CESM/versions/master/html/downloading_cesm.html#downloading-the-code-and-scripts Downloading CESM] | ||
| Line 61: | Line 61: | ||
To use GEOS-Chem you should checkout CESM tag cesm2_3_alpha17e or later. This version uses CAM tag cam6_3_160 which includes GEOS-Chem v14.1.2. The NCAR CESM documentation will guide you through downloading CESM and populating the externals. "Externals" mean source code repositories that are separate from the CESM source code repository that you download. This is similar to how the GC-Classic initial download is mostly an empty set of directories until you run 'git submodule update --init --recursive' which checks out git submodules. CESM uses a package called manage_externals rather than git submodules and stores information about the externals in local configuration file Externals.cfg (see [https://github.com/ESCOMP/CESM/blob/master/Externals.cfg here] for example file). All externals are checked out with command "./manage_externals/checkout_externals". The checkout is recursive, meaning any external that has its own custom externals config file will also have the externals in that file checked out. This is how GEOS-Chem and HEMCO are downloaded. The CAM external includes file Externals_CAM.cfg (example [https://github.com/ESCOMP/CAM/blob/cam_development/Externals_CAM.cfg here]) which specifies GEOS-Chem, as well as the HEMCO interface (HEMCO_CESM). HEMCO is specified in the HEMCO_CESM externals config file Externals_HCO.cfg (example [https://github.com/ESCOMP/HEMCO_CESM/blob/master/Externals_HCO.cfg here]). | To use GEOS-Chem you should checkout CESM tag cesm2_3_alpha17e or later. This version uses CAM tag cam6_3_160 which includes GEOS-Chem v14.1.2. The NCAR CESM documentation will guide you through downloading CESM and populating the externals. "Externals" mean source code repositories that are separate from the CESM source code repository that you download. This is similar to how the GC-Classic initial download is mostly an empty set of directories until you run 'git submodule update --init --recursive' which checks out git submodules. CESM uses a package called manage_externals rather than git submodules and stores information about the externals in local configuration file Externals.cfg (see [https://github.com/ESCOMP/CESM/blob/master/Externals.cfg here] for example file). All externals are checked out with command "./manage_externals/checkout_externals". The checkout is recursive, meaning any external that has its own custom externals config file will also have the externals in that file checked out. This is how GEOS-Chem and HEMCO are downloaded. The CAM external includes file Externals_CAM.cfg (example [https://github.com/ESCOMP/CAM/blob/cam_development/Externals_CAM.cfg here]) which specifies GEOS-Chem, as well as the HEMCO interface (HEMCO_CESM). HEMCO is specified in the HEMCO_CESM externals config file Externals_HCO.cfg (example [https://github.com/ESCOMP/HEMCO_CESM/blob/master/Externals_HCO.cfg here]). | ||
| − | === | + | === Download input data === |
Relevant NCAR docs: [https://escomp.github.io/CESM/versions/master/html/downloading_cesm.html#downloading-input-data Downloading input data] | Relevant NCAR docs: [https://escomp.github.io/CESM/versions/master/html/downloading_cesm.html#downloading-input-data Downloading input data] | ||
| Line 69: | Line 69: | ||
On external cluster: | On external cluster: | ||
| − | + | === Configure CIME === | |
| − | === | + | |
| − | + | ||
| − | + | ||
==== Scenario 1: NCAR Derecho HPC cluster ==== | ==== Scenario 1: NCAR Derecho HPC cluster ==== | ||
| Line 105: | Line 102: | ||
4. Create a file named name_of_your_cluster.cmake under cmake_macros to include any necessary cmake macros to point the compiler to the correct ESMF, netCDF, MPI library location. Refer to userdefined.cmake for some sample definitions. This .cmake file will automatically be used based on the machine name. | 4. Create a file named name_of_your_cluster.cmake under cmake_macros to include any necessary cmake macros to point the compiler to the correct ESMF, netCDF, MPI library location. Refer to userdefined.cmake for some sample definitions. This .cmake file will automatically be used based on the machine name. | ||
| − | === Building the model === | + | == Quickstart basics == |
| + | |||
| + | === Create and setup a case === | ||
| + | |||
| + | === Build the model === | ||
| + | |||
| + | Building CESM is done by python script case.build in the case directory. See the [https://esmci.github.io/cime/versions/master/html/users_guide/building-a-case.html CIME documentation on building a case] for instructions and detailed information, including how to rebuild. Always remember to setup your case prior to building. For reference, here are the basic commands to (1) build, and (2) clean your build. | ||
| + | |||
| + | ./case.build | ||
| + | ./case.build --clean | ||
| + | |||
| + | === Run the model === | ||
| + | |||
| + | === Output data and logs === | ||
| − | + | == Tips and tricks == | |
| − | === | + | === Case tools === |
| − | === | + | === Build-time settings === |
| − | == | + | === Run-time settings === |
| − | === | + | === When to create a new case === |
| − | === | + | === Configuring diagnostics === |
| − | === | + | === Developing the model === |
== Debugging and getting help == | == Debugging and getting help == | ||
Revision as of 16:29, 21 May 2024
Contents
Overview
This page serves as a resource for using GEOS-Chem in the Community Earth System Model (CESM). It is meant to supplement not replace existing CESM documentation and therefore includes a guide to navigating CESM resources maintained by NCAR. The rest of the page focuses on aspects of the model specific to GEOS-Chem and is written primarily to help offline GEOS-Chem users get started. CESM users interested in using GEOS-Chem chemistry may also find it useful but should additionally look at GEOS-Chem documentation listed on the main page of this wiki.
(Brief history of GEOS-Chem in CESM with citable references...here or in a new section)
CESM Resources
Model documentation
The best way to successfully use GEOS-Chem chemistry in CESM is to become familiar with CESM documentation and guides maintained by NCAR. The CESM2 Quickstart Guide contains an overview of the model and instructions for downloading, building, and running CESM2. CESM2 is built upon a framework called Common Infrastructure for Modeling the Earth (CIME, pronounced "SEAM") which handles configuring, compiling, testing, and running the model. Offline GEOS-Chem users can think of CIME as run directory management and testing, containing the equivalent of what is found in the 'run' and 'test' directories within GEOS-Chem. Read through the CIME documentation to become familiar with the concepts of CIME and to get detailed instructions for creating run directories, configuring a run, building the source code, and running the model. Community Atmosphere Model (CAM) is the atmospheric component of CESM and includes both GEOS-Chem and HEMCO as subcomponents. The CAM6.3 documentation builds upon information in the CESM Quickstart Guide and the CIME documentation. Read through it to learn about the atmospheric component's configuration options, data inputs, and model outputs.
Model websites
NCAR maintains several websites with up-to-date information about CESM. The CAM website and CESM with Chemistry Wiki page are of particular interest to GEOS-Chem users.
Data visualization and analysis
NCAR provides jupyter notebook examples of visualizing and analyzing CESM output data. Examples for atmospheric chemistry modeling with CAM-Chem are relevant for modeling with GEOS-Chem.
Getting help
CESM help requests are handled on a searchable forum maintained by NCAR. Consider registering for a free account if you plan to use CESM.
Glossary
CAM = Community Atmosphere Model
case = unique set of compset and grid
case directory = user-created directory for a case where you can configure, build, and run CESM using CIME tools
CESM = Community Earth System Model
CIME = Common Infrastructure for Modeling the Earth
component = building block of CESM; the model is comprised of seven geophysical components, one external system processing component, and one driver/coupler component
compset = named set of components with default component-specific configurations and namelist settings
SIMA = System for Integrated Modeling of the Atmosphere
One-time Setup
Download CESM
Relevant NCAR docs: Downloading CESM
To use GEOS-Chem you should checkout CESM tag cesm2_3_alpha17e or later. This version uses CAM tag cam6_3_160 which includes GEOS-Chem v14.1.2. The NCAR CESM documentation will guide you through downloading CESM and populating the externals. "Externals" mean source code repositories that are separate from the CESM source code repository that you download. This is similar to how the GC-Classic initial download is mostly an empty set of directories until you run 'git submodule update --init --recursive' which checks out git submodules. CESM uses a package called manage_externals rather than git submodules and stores information about the externals in local configuration file Externals.cfg (see here for example file). All externals are checked out with command "./manage_externals/checkout_externals". The checkout is recursive, meaning any external that has its own custom externals config file will also have the externals in that file checked out. This is how GEOS-Chem and HEMCO are downloaded. The CAM external includes file Externals_CAM.cfg (example here) which specifies GEOS-Chem, as well as the HEMCO interface (HEMCO_CESM). HEMCO is specified in the HEMCO_CESM externals config file Externals_HCO.cfg (example here).
Download input data
Relevant NCAR docs: Downloading input data
On Derecho:
On external cluster:
Configure CIME
Scenario 1: NCAR Derecho HPC cluster
Scenario 2: External HPC cluster
Prerequisites
The paths to these libraries (containing their bin, lib or lib64) is necessary to configure CIME to point to the right locations.
- Intel or GNU compiler
- netCDF, netCDF-Fortran
- MPI
- ESMF built with PIO support (built-in is OK) and netCDF IO support.
Configuring CIME
Relevant NCAR docs: Defining the machine - CIME documentation
Set up is much easier if previous users of your HPC cluster have configured a prior version of CESM.
CIME configuration for CESM2.3 has slightly changed. In previous versions of CESM, environmental configuration specific to your HPC cluster was in one config_machines.xml file. In CESM2.3 and above, the same information is now split into separate files. The following steps should be performed to add your HPC cluster configuration to CIME, while consulting a prior setup of CESM for relevant entries.
All of the below configuration is under ccs_config/machines.
1. Edit config_machines.xml to add a new line within <NODENAME_REGEX> with <value MACH="name_of_your_cluster">regex pattern here</value> to match the hostname pattern of your HPC system (consult the hostname command).
2. Create a folder with name_of_your_cluster. It may be easier to copy the existing ubuntu-latest folder.
3. Edit config_machines.xml to insert the machine configuration (<machine> tag) from a previous version of CESM. This usually includes MPI configuration and OS information as well as compiler configuration. The actual entries can be very long.
4. Create a file named name_of_your_cluster.cmake under cmake_macros to include any necessary cmake macros to point the compiler to the correct ESMF, netCDF, MPI library location. Refer to userdefined.cmake for some sample definitions. This .cmake file will automatically be used based on the machine name.
Quickstart basics
Create and setup a case
Build the model
Building CESM is done by python script case.build in the case directory. See the CIME documentation on building a case for instructions and detailed information, including how to rebuild. Always remember to setup your case prior to building. For reference, here are the basic commands to (1) build, and (2) clean your build.
./case.build ./case.build --clean
Run the model
Output data and logs
Tips and tricks
Case tools
Build-time settings
Run-time settings
When to create a new case
Configuring diagnostics
Developing the model
Debugging and getting help
For general CESM help please use the DiscussCESM forum linked to in the CESM Resources section of this page. For GEOS-Chem help please following support instructions provided on GEOS-Chem ReadTheDocs here. Depending on the issue you may be referred by the CESM Support Team to contact the GEOS-Chem Support Team, or vice versa.
