-
Couldn't load subscription status.
- Fork 2
GEOS_CTM_UserGuide
The Goddard Earth Observing System version 5 (GEOS-5) General Circulation Model (GCM) makes use of the
Earth System Modeling Framework (ESMF) to enable model configurations with many functions.
One of the options of the GEOS-5 GCM is the GEOS-5 Chemistry Transport Model (GEOS-5 CTM),
which is an offline simulation of chemistry
and constituent transport driven by a specified meteorology and other model output fields.
This document describes the basic components of the GEOS-5 CTM, and is a user's guide on to how to
obtain and run simulations on the NCCS Discover platform.
In addition, we provide information on how to change the model configuration input files to meet users' needs.
The GEOS-5 Chemistry Transport Model (CTM) integrates one configurable CTM with options for running any chemistry module
currently available within the GEOS-5 GCM code base.
It uses the GEOS-5 Earth System Modeling Framework (ESMF) infrastructure
(MAPL, the History component and the ExtData component) and the GEOS-5 advection component (AdvCore)
to drive the GEOS-5 Chemistry component (that includes options for
the Global Modeling Initiative (GMI) [Logan et al., 2003], the Global Ozone Chemistry Aerosol Radiation and Transport (GOCART)
[Chin et al., 2000], GEOS-Chem [Bey et al., 2001], etc.).
Detailed information about the GEOS-5 CTM is available in [Kouatchou et al., 2015][Kouatchou et al., 2017].
The main components of GEOS-5 CTM are:
-
AdvCore: the transport component which source code is part of the GEOS-5 directory
@FVdycoreCubed_GridComp/. -
Chemistry: the GEOS-5 Chemistry component which contains all the options for chemistry models available in GEOS-5 GCM, such as GOCART, GMI, GEOS-Chem, etc. The entire GEOS-5
@GEOSchem_GridComp/defines this component. - Diffusion: component where various diffusion methods are implemented.
- Convection: component where various convection methods are implemented.
- GEOS-5 CTM Cinderella: a component which primary role is to provide services to the other components. For instance, it will compute the courant numbers or derive variables needed for RAS calculations.
- CTM Hist: works along with the Cinderella component only to derive fields for HISTORY.
Before you start manipulating the CTM code, you need to issue the commands to load the modules:
module use -a /discover/Swede/gmao_SIteam/modulefiles-SLES12
module load GEOSenv
which make available the latest git, CMake, and mepo modules.
Assuming that you want to get the branch name vXX.YY.ZZ, issue the command:
git clone -b vXX.YY.ZZ [email protected]:GEOS-ESM/GEOSctm.git
You will get the directory GEOSctm that contains:
CMakeLists.txt CODE_OF_CONDUCT.md config/ COPYRIGHT LICENSE-NOSA README.md
CMakePresets.json components.yaml CONTRIBUTING.md LICENSE parallel_build.csh src/
If we zoom in src/, we will have the basic directory structure:
src/
src/Applications
src/Applications/GEOSctm_App/
src/Components/
src/Components/GEOSctm_GridComp/
src/Components/GEOSctm_GridComp/CTMconvection_GridComp/
src/Components/GEOSctm_GridComp/CTMdiffusion_GridComp/
src/Components/GEOSctm_GridComp/CTMpTracers_GridComp/
src/Shared/
At this stage, the Shared/ is empty and the GEOSctm_GridComp/ folder only has components specific to the CTM (Cinderella, Idealized Passive Tracer, Convection and Diffusion).
In the next section, we will also obtain the external components (Chemistry, Advection, etc.).
To be able to compile and run the CTM code, we need to checkout components that are not specific to the CTM.
From the terminal, type:
mepo clone
and the following components will be added (all of them starting with @):
@env/
@cmake/
src/Shared/@FMS/
src/Shared/@GMAO_Shared/
src/Shared/@MAPL/
src/Components/GEOSctm_GridComp/@FVdycoreCubed_GridComp/
src/Components/GEOSctm_GridComp/@GEOSchem_GridComp/
From the GEOSctm/ directory, issue the commands:
source @env/g5_modules
mkdir build
cd build
cmake .. -DBASEDIR=$BASEDIR/Linux -DCMAKE_Fortran_COMPILER=ifort -DCMAKE_INSTALL_PREFIX=../install
make -j4 install
If everything goes well, the executable GEOSctm.x will be in the directory GEOSctm/install/bin/.
In case you want to compile the code in debugging mode, the cmake command should be:
cmake .. -DBASEDIR=$BASEDIR/Linux -DCMAKE_Fortran_COMPILER=ifort -DCMAKE_INSTALL_PREFIX=../install -DCMAKE_BUILD_TYPE=Debug
For other compilation options, please visit GEOS-ESM/GEOSctm.
In order to run GEOS-5 CTM, a "setup" script is available with a suite of default configurations. Go to the directory GEOSctm/install/bin/ and run the script:
./ctm_setup
You will answer a series of questions to determine the model configuration (horizontal resolution, type of Chemistry, driving dataset, etc.) you are interested in. The table below shows the possible configuration options.
| Name | Available Options |
|---|---|
| Horizontal Resolution (deg) | 8, 4, 2, 1, 1/2, 1/4, 1/8, 1/16 |
| Chemistry | Passive Tracer, GOCART, GMI, Idealized Passive Tracer |
| Driving Dataset | MERRA2, FP |
The script will automatically generate configuration files and run scripts. In your experiment directory, it will create:
CAP.rc: file containing information on start date & time,
end date & time of job segment, duration of job
segment, stop date & time of entire experiment.
HISTORY.rc: file for selecting the type of diagnostics to be produced
ctm_run.j: SLURM script for submitting the job
RC/ contains all the resource files needed to drive the model
CTM_GridComp.rc: file for turning on/off Convection, Diffusion
and for selecting the type of meteorological
driving (MERRA2 or FP)
GEOSCTM.rc: file for setting model parameters
MAPL_ExtData.rc: file needed by ExtData to read external data files
Before submitting the job script, create the file:
cap_restart: ASCII file containing (single line) starting the
date (YYYYMMDD) and time (HHMMSS) of the job segment
in the format: YYYYMMDD HHMMSS
and then issue the command:
qsub ctm_run.j
Remark: When you run the ctm_setup script, the template files MERRA2_ExtData.rc.tmpl
FP_ExtData.rc.tmpl are generated.
At run time, the SLURM script ctm_run.j manipulates one of them (based on the initial settings)
to create a file similar to MAPL_ExtData.rc.
The CTM_GridComp.rc file is used to set options for Convection, Diffusion and the type meteorological data.
We need to set the variable metType that has two options:
- MERRA2 (default): data files available from 1979 to present.
- FP: data files available from February 2014 to present.
If you need to use the FP forcing data file...
By default, Convection is activated all configurations but not the Idealized Passive Trace configuration (where Convection is not needed). For the GMI Chemistry, we have the setting:
do_ctmConvection: T
convecType: 2
For the other configurations, we have:
do_ctmConvection: T
convecType: 1 # convective transport only
By default, Duffusion is activated all configurations but Idealized Passive Tracer. In case we want to exercise Diffusion, we need to set:
do_ctmDiffusion: T
In earlier versions of the code, the atmospheric 3D pressure (PLE) was read in (by default) from external data files. The code was modified to allow the reading of the surface pressure (PS) instead and PLE is calculated using PS and the AKs and BKs. If users still want to read PLE, they need ro set:
read_PLE: T
By default, Advection is always turned on regardless of the configuration used. If you do not want to exercise the Advection component, use the setting:
do_ctmAdvection: F
By default, the courant numbers (CX & CY) and the mass fluxes (MFX & MFY) are calculated by the CTM Cinderella component using the wind fields and the 3D pressure. There is also an option to read in CX, CY, MFX & MFY from forcing data files. You following setting is needed:
read_advCoreFields: T
By default, it is assumed that the CX, CY, MFX & MFY are in the lat-lon grid. If they are instead in the cubed-sphere grid, the surface pressure (PS) and the specific humidity (Q) also need to be read in the cubed-sphere grid.
In the process of generating the configuration scripts, the following files were created:
-
CAP.rc: contains begin/end date and time of entire job, stop date, duration (in days) of each job segment. -
ctm_run.j: SLURM script -
cap_restart: contains two numbers pointing to the starting date YYYYMMDD and starting hour HHMMSS of the job.
Assume that we want to carry out a 12-month experiment with January 1, 2005 as starting date. We want to run one month at the time. The file cap_restart will have
20050101 000000
and the file CAP.rc will have the settings:
BEG_DATE: 20000101 000000
END_DATE: 20060101 000000
JOB_SGMT: 00000031 000000
Note that the stop date END_DATE is January 1, 2006. We will need to submit the PBS script:
qsub ctm_run.j
When the first job segment is completed (for January 2005), the script will resubmit itself. The file cap_restart will automatically be updated to contain:
20050201 000000
GEOS-5 contains the Gridded Component ExtData that has the ability to read from external files variables needed by the model. ExtData
- Relies on a resource file that lists the variables to be read in. Each variable is represented with the following information: short name, dimension, unit, path to netCDF/hdf file containing the variable, variable name in the file, reading frequency, etc.
- Can perform unit conversion. It has basic scaling and offset calculations.
- Does time interpolation.
- Does vertical interpolation.
- Does on the fly regridding.
- Is called at every time step before all the other run methods (Physics, Dynamics).
- Is the last ESMF gridded component the entire code will rely on to look for the availability of a given variable (requested by another ESMF gridded component). If the variable cannot be provided, the code will abort.
PrimaryExports%%
# ---------|-------------|-------|--------|----------------------|--------|--------|-------------|----------|
# Import | | | Regrid | Refresh | OffSet | Scale | Variable On | File |
# Name | Units | Clim | Method | Time Template | Factor | Factor | File | Template |
# ---------|-------------|-------|--------|----------------------|--------|--------|-------------|----------|
SLP 'Pa' N N 0 0.0 1.0 SLP /discover/nobackup/projects/gmao/merra2/data/products/d5124_m2_@sMonth/Y%y4/M%m2/@MERRA2type.tavg1_2d_slv_Nx.%y4%m2%d2.nc4
T 'K' N N 0 0.0 1.0 T /discover/nobackup/projects/gmao/merra2/data/products/d5124_m2_@sMonth/Y%y4/M%m2/@MERRA2type.inst3_3d_asm_Nv.%y4%m2%d2.nc4
PS 'Pa' N N 0 0.0 1.0 PS /discover/nobackup/projects/gmao/merra2/data/products/d5124_m2_@sMonth/Y%y4/M%m2/@MERRA2type.tavg1_2d_slv_Nx.%y4%m2%d2.nc4
UC0;VC0 'm s-1' N N 0 0.0 1.0 U;V /discover/nobackup/projects/gmao/merra2/data/products/d5124_m2_@sMonth/Y%y4/M%m2/@MERRA2type.inst3_3d_asm_Nv.%y4%m2%d2.nc4
UC1;VC1 'm s-1' N N 0;730 0.0 1.0 U;V /discover/nobackup/projects/gmao/merra2/data/products/d5124_m2_@sMonth/Y%y4/M%m2/@MERRA2type.inst3_3d_asm_Nv.%y4%m2%d2.nc4
This option applies to FP data files
PrimaryExports%%
# ---------|-------------|-------|--------|----------------------|--------|--------|-------------|----------|
# Import | | | Regrid | Refresh | OffSet | Scale | Variable On | File |
# Name | Units | Clim | Method | Time Template | Factor | Factor | File | Template |
# ---------|-------------|-------|--------|----------------------|--------|--------|-------------|----------|
SLP 'Pa' N N 0 0.0 1.0 SLP /gpfsm/dnb04/projects/p14/pub/fp/das/Y%y4/M%m2/D%d2/GEOS.fp.asm.tavg1_2d_slv_Nx.%y4%m2%d2_%h2%n2.V01.nc4 2015-01-01T00:30:00P01:00
T 'K' N N 0 0.0 1.0 T /gpfsm/dnb04/projects/p14/pub/fp/das/Y%y4/M%m2/D%d2/GEOS.fp.asm.inst3_3d_asm_Nv.%y4%m2%d2_%h2%n2.V01.nc4 2015-01-01T00:00:00P03:00
PS 'Pa' N N 0 0.0 1.0 PS /gpfsm/dnb04/projects/p14/pub/fp/das/Y%y4/M%m2/D%d2/GEOS.fp.asm.inst3_3d_asm_Nv.%y4%m2%d2_%h2%n2.V01.nc4 2015-01-01T00:00:00P03:00
UC0;VC0 'm s-1' N N 0 0.0 1.0 U;V /gpfsm/dnb04/projects/p14/pub/fp/das/Y%y4/M%m2/D%d2/GEOS.fp.asm.inst3_3d_asm_Nv.%y4%m2%d2_%h2%n2.V01.nc4 2015-01-01T00:00:00P03:00
UC1;VC1 'm s-1' N N 0;730 0.0 1.0 U;V /gpfsm/dnb04/projects/p14/pub/fp/das/Y%y4/M%m2/D%d2/GEOS.fp.asm.inst3_3d_asm_Nv.%y4%m2%d2_%h2%n2.V01.nc4 2015-01-01T00:00:00P03:00
To produce a field by the HISTORY component, it is important to know the acronym of the component which owns it. The table below lists the main component names and their acronyms.
| Component Name | Name in HISTORY.rc |
|---|---|
| GEOS-5 CTM Cinderella | CTMenv |
| CTM History | CTMhist |
| GEOSchem Cinderella | CHEMENV |
| Passive Tracer | TR |
| Idealized Passive Tracer | pTracers |
| GOCART Chemistry | GOCART |
| GMI Chemistry | GMICHEM |
| Convection | CONVECTION |
| Diffusion | DIFFUSION |
The Overpass diagnostics (at 10 am and 2 pm) are created in the GEOSchem Cinderella component. The available fields are:
| Short Names | Long Names |
|---|---|
| OVP10_AIRDENS | moist_air_density_10am_local (kg m-3) |
| OVP14_AIRDENS | moist_air_density_2pm_local (kg m-3) |
| OVP10_T | air_temperature_10am_local (K) |
| OVP14_T | air_temperature_2pm_local (K) |
| OVP10_PL | mid_level_pressure_10am_local (Pa) |
| OVP14_PL | mid_level_pressure_2pm_local (Pa) |
| OVP10_PLE | edge_pressure_10am_local (Pa) |
| OVP14_PLE | edge_pressure_2pm_local (Pa) |
| OVP10_QV_VMR | water_vapor_10am_local (mol mol-1) |
| OVP14_QV_VMR | water_vapor_2pm_local (mol mol-1) |
| OVP10_QLTOT | mass_fraction_of_cloud_liquid_water_10am_local (kg kg-1) |
| OVP14_QLTOT | mass_fraction_of_cloud_liquid_water_2pm_local (kg kg-1) |
| OVP10_PS | surface_pressure_10am_local (Pa) |
| OVP14_PS | surface_pressure_2pm_local (Pa) |
| OVP10_PPBL | pbltop_pressure_10am_local (Pa) |
| OVP14_PPBL | pbltop_pressure_2pm_local (Pa) |
| OVP10_TROPP | tropopause_pressure_10am_local (Pa) |
| OVP14_TROPP | tropopause_pressure_2pm_local (Pa) |
| OVP10_U10M | eastward_10m_wind_speed_10am_local (m s-1) |
| OVP14_U10M | eastward_10m_wind_speed_2pm_local (m s-1) |
| OVP10_V10M | northward_10m_wind_speed_10am_local (m s-1) |
| OVP14_V10M | northward_10m_wind_speed_2pm_local (m s-1) |
A sample setting in the HISTORY.rc file is:
ovpC.template: '%y4%m2%d2_%h2%n2z.nc4',
ovpC.archive: '%c/Y%y4',
ovpC.format: 'CFIO',
ovpC.mode: 'instantaneous',
ovpC.frequency: 240000,
ovpC.duration: 240000,
ovpC.ref_time: 000000,
ovpC.resolution: 180 91,
ovpC.fields: 'OVP10_PS' , 'CHEMENV' ,
'OVP10_T' , 'CHEMENV' ,
'OVP10_PL' , 'CHEMENV' ,
'OVP10_U10M' , 'CHEMENV' ,
'OVP10_V10M' , 'CHEMENV' ,
'OVP10_TROPP' , 'CHEMENV' ,
'OVP10_QLTOT' , 'CHEMENV' ,
'OVP10_PPBL' , 'CHEMENV' ,
'OVP10_QV_VMR' , 'CHEMENV' ,
::
The CTM code can produce tendencies for Advection (TRADVI), Diffusion (TRI) and Convection (MTRI).
You can output the tendencies of the fields friendly to those components.
conv_tendency.template: '%y4%m2%d2_%h2%n2z.nc4',
conv_tendency.archive: '%c/Y%y4',
conv_tendency.format: 'CFIO',
conv_tendency.mode: 'instantaneous',
conv_tendency.frequency: 010000,
conv_tendency.duration: 240000,
conv_tendency.ref_time: 000000,
conv_tendency.resolution: 180 91,
conv_tendency.fields: 'MTRI%GOCART::CO2IM' , 'GEOSctm' , 'CO2_MOISTTEND',
'MTRI%GOCART::COIM' , 'GEOSctm' , 'CO_MOISTTEND',
::
diff_tendency.template: '%y4%m2%d2_%h2%n2z.nc4',
diff_tendency.archive: '%c/Y%y4',
diff_tendency.format: 'CFIO',
diff_tendency.mode: 'instantaneous',
diff_tendency.frequency: 010000,
diff_tendency.duration: 240000,
diff_tendency.ref_time: 000000,
diff_tendency.resolution: 180 91,
diff_tendency.fields: 'TRI%GOCART::CO2IT' , 'GEOSctm' , 'CO2_TURBTEND',
'TRI%GOCART::COIT' , 'GEOSctm' , 'CO_TURBTEND',
::
adv_tendency.template: '%y4%m2%d2_%h2%n2z.nc4',
adv_tendency.archive: '%c/Y%y4',
adv_tendency.format: 'CFIO',
adv_tendency.mode: 'instantaneous',
adv_tendency.frequency: 010000,
adv_tendency.duration: 240000,
adv_tendency.ref_time: 000000,
adv_tendency.resolution: 180 91,
adv_tendency.fields: 'TRADVI%GOCART::CO2ID' , 'GEOSctm' , 'CO2_ADVTEND',
'TRADVI%GOCART::COID' , 'GEOSctm' , 'CO_ADVTEND',
::
When the setting:
enable_rasCalculations: T
is available in the CTM_GridComp.rc file, the CTM Cinderella component will compute (suing the RAS module) the convective mass fluxes and pass them to the Convective components.
As we stated earlier, by default the code expects all the data files to be in the lat-lon grid. However, we have made experiments (using the FP data files) where CX, CY, MFX & MFY were in the cubed-sphere grid. In such experiments, the surface pressure (PS) and the specific humidity (Q) were also on the cubed-sphere grid whereas all the other fields remained in the lat-lon grid.
It is required to have the following setting in the CTM_GridComp.rc file:
read_advCoreFields: T
If you need to make changes to the code, we recommend that you first create a feature branch, immediately after checking out the code:
git checkout -b feature_branch_name
after making your changes and committing them to your local feature branch repository, you can push them to the remote feature branch repository:
git push --set-upstream origin feature_branch_name
[Bey et al., 2001] Bey, I., Jacob, D. J., M.Yantosca, R., Logan, J. A., Filed, B. D., Fiore, A. M., Li, Q., Liu, H. Y., Mickley, L. J., and Schiltz, M. G. (2001). Global modeling of tropospheric chemistry with assimilated meteorology: Model description and evaluation,. J. Geophys. Res., 106:23073–23095.
[Chin et al., 2000] Chin, M., Rood, R. B., Lin, S.-J., Muller, J., and Thompson, A. (2000). Atmospheric sulfur cycle simulated in the global model GOCART: model description and global properties. J. Geophys. Res., 105:24671–24687.
[Kouatchou et al., 2015] Kouatchou, J., A. Molod, J. E. Nielsen, B. Auer, W. Putman and T. Clune, GEOS-5 Chemistry Transport Model User’s Guide. GMAO Office Note No. 8 (Version 1.0), 26 pp, available from http://gmao.gsfc.nasa.gov/pubs/office_notes.
[Kouatchou et al., 2017] Kouatchou, J., T. Clune, B. Auer, J. E. Nielsen and A. Molod (2017) Parallel performance analysis of two infrastructure frameworks for GMI chemistry, American Meteorological Society’s Third Symposium on High Performance Computing for Weather, Water, and Climate.
[Logan et al., 2003] Logan, J. A., Bergmann, D., Rodriguez, J., Chatfield, R., Considine, D., Wang, Y., Jacob, D., Prather, M., Rotman, D., and Cameron-Smith, P. (2003). Evaluation of tropo- spheric chemistry simulations for the Global Modeling Initiative (GMI). Geophysical Research Abstracts, 5.