FlexGrid

On this page we provide information about the FlexGrid, which was introduced in GEOS-Chem 12.4.0.

Overview

FlexGrid is a new functionality that will allow users to define the grid for their GEOS-Chem simulation at run time. The major features include:

1. Reading in meteorology fields via HEMCO
2. Defining meteorology field, horizontal grid, and vertical grid at run time
3. Saving out boundary conditions via the HISTORY component
4. Reading in boundary conditions via HEMCO

Developers

• Jiawei Zhuang (Harvard)
• Jintai Lin (PKU)
• Melissa Sulprizio (Harvard)

Implementation

The table below shows the implementation plan for FlexGrid in GEOS-Chem:

Update	Description	Status
Stage 1: Read met fields by HEMCO	Add entries to read netCDF meteorology files in HEMCO_Config.rc Unify code for GEOS-FP and MERRA-2 meteorology by creating a new flexgrid_read_mod.F90	This update was included in GEOS-Chem 12.1.0, which was released on 26 Nov 2018.
Stage 2: Add capability to define custom grids	Define meteorology field, grid resolution, and grid domain at run time in input.geos Add new State_Grid derived type object to pass grid parameters from top level routines down Save out boundary conditions in HISTORY.rc and read in via HEMCO	This update was included in GEOS-Chem 12.4.0, which was released on 05 Aug 2019.

Read in meteorology fields via HEMCO

FlexGrid takes advantage of HEMCO's I/O interface and regridding & cropping capability. By reading the meteorology fields through HEMCO, the fields are automatically processed for the correct grid resolution and domain at run time. These fields are then passed to State_Met in the various subroutines in flexgrid_read_mod.F90. Reading meteorology fields in HEMCO also allows users to explicitly control each meteorological variable in run-time configuration files to perform meteorology sensitivity tests (an interface resembling GCHP).

The following lines in green were added to HEMCO_Config.rc:

###############################################################################
### BEGIN SECTION SETTINGS
###############################################################################

ROOT:                        /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/HEMCO 
METDIR:                      /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData/GEOS_4x5/GEOS_FP
...

###############################################################################
### NON-EMISSIONS DATA (subsection of BASE EMISSIONS SECTION)
###
### Non-emissions data. The following fields are read through HEMCO but do 
### not contain emissions data. The extension number is set to wildcard 
### character denoting that these fields will not be considered for emission 
### calculation. A given entry is only read if the assigned species name is 
### an HEMCO species.
###############################################################################

#==============================================================================
# --- Meteorology fields for FlexGrid ---
#==============================================================================

# --- CN fields ---
* FRLAKE    $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FRLAKE   */1/1/0               C xy  1  * -  1 1
* FRLAND    $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FRLAND   */1/1/0               C xy  1  * -  1 1
* FRLANDIC  $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FRLANDIC */1/1/0               C xy  1  * -  1 1
* FROCEAN   $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FROCEAN  */1/1/0               C xy  1  * -  1 1
* PHIS      $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        PHIS     */1/1/0               C xy  1  * -  1 1

# --- A1 fields ---
* ALBEDO    $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A1.$RES.$NC     ALBEDO   1980-2018/1-12/1-31/0-23/+30minute CY xy  1  * -  1 1
* CLDTOT    $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A1.$RES.$NC     CLDTOT   1980-2018/1-12/1-31/0-23/+30minute CY xy  1  * -  1 1
* EFLUX     $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A1.$RES.$NC     EFLUX    1980-2018/1-12/1-31/0-23/+30minute CY xy  1  * -  1 1
* EVAP      $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A1.$RES.$NC     EVAP     1980-2018/1-12/1-31/0-23/+30minute CY xy  1  * -  1 1
...

Define meteorology field and grid parameters in input.geos

Prior to FlexGrid, users would define the meteorology field and grid resolution at compile time by passing the MET= and GRID= options at compile time. Changing meteorology field or grid resolution would require recompiling the source code. In addition, many of the grid parameters were hardcoded in CMN_SIZE_mod.F or stored in module-level arrays (e.g. XMID, YMID, AREA_M2 in gc_grid_mod.F90). To implement a new meteorology field or nested grid, users would have to process meteorology files offline and update several areas of the GEOS-Chem source code to recognize the new grid.

FlexGrid introduces the capability to define the meteorology field in the Simulation Menu of input.geos and the grid resolution and domain in the Grid Menu of input.geos. The new derived type object State_Grid holds the user-defined grid parameters as well as those computed by GEOS-Chem at run time. This new capability greatly simplifies the process of running GEOS-Chem with other meteorology fields and on other grids. It also allows for the use of the same geos executable for different meteorology and grid settings.

The following lines in green were added to input.geos:

%%% SIMULATION MENU %%% :
Start YYYYMMDD, hhmmss  : 20160701 000000
End   YYYYMMDD, hhmmss  : 20160703 000000
Run directory           : ./
Root data directory     : /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData
Met field               : GEOS-FP
------------------------+------------------------------------------------------
%%% GRID MENU %%%       :
Grid resolution         : 4.0x5.0
Longitude min/max       : -180.0 180.0
Latitude  min/max       : -90.0   90.0
 Half-sized polar boxes?: T
Number of levels        : 47
Nested grid simulation? : F
 Buffer zone (N S E W ) :  3  3  3  3

The meteorology fields currently supported are GEOS-FP and MERRA-2. As of implementation, an error check in GeosCore/input_mod.F will stop the simulation if the meteorology type is not recognized, but other met fields may be added in the future to improve flexibility.

Users can now define the grid resolution and domain for their simulation at run time in the Grid Menu.

Grid Resolution
The grid resolutions currently supported are 4.0x5.0, 2.0x2.5, 0.5x0.625, and 0.25x0.3125 (real numbers, not integers, must be used). As of implementation, an error check in GeosCore/input_mod.F will stop the simulation if the meteorology type is not recognized, but this error check may be removed or other grid resolutions may be added in the future to improve flexibility. Theoretically, any grid resolution should work, but this has not been validated.

Grid Domain
Users can choose to use either global grids or nested/regional grids. To use a global grid, simply specify longitude and latitude bounds of -180.0, 180.0 and -90.0, 90.0. All global grids currently supported use half-sized polar boxes, but a switch is included in the Grid Menu for flexibility with other grids.

Vertical Grid
Users can also specify the vertical grid in number of levels. The vertical resolutions currently supported are 47 and 72 levels, formerly known as the reduced vertical grid and native-resolution vertical grid. As of implementation, an error check in GeosCore/input_mod.F will stop the simulation if the vertical resolution is not recognized, but this error check may be removed or other grid resolutions may be added in the future to improve flexibility.

Nested Grid
If using a grid other than a global grid, users must set the Nested grid simulation option to True and specify the number of grid cells along each border that define the buffer region (default is 3 3 3 3. The buffer region is the region where boundary conditions from a coarse-resolution simulation are applied.

From the settings specified in the Grid Menu, the number of grid boxes in the X, Y, and Z directions will be computed and stored in State_Grid%NX, State_Grid%NY, and State_Grid%NZ, which will replace the old IIPAR, JJPAR, and LLPAR parameters from CMN_SIZE_mod.F. Several additional fields will be computed at run time in GeosUtil/gc_grid_mod.F90. These fields include arrays of longitude centers (State_Grid%XMid, longitude edges (XEdge), latitude centers (State_Grid%YMid), latitude edges (State_Grid%YEdge), grid box areas (State_Grid%Area_M2), etc.

With this update, the following C-preprocessor switches have been removed from the code and are replaced with IF statements to check the relevant field in either State_Met or State_Grid.

• GEOS_FP, MERRA2
• GRID_4x5, GRID_2x25, GRID_05x0625, GRID025x03125
• NESTED_AS, NESTED_CH, NESTED_EU, NESTED_NA
• GRIDREDUCED

Save out boundary conditions in HISTORY.rc

A new BoundaryConditions collection allows users to save out instantaneous species concentration fields (v/v) at specified intervals (default is 3-hourly boundary conditions saved to daily files). For the initial implementation, global boundary condition fields will be saved out, and users can utilize these fields as boundary conditions for any custom nested-grid simulation. Eventually, the goal is to add the capability to define a specific region for saving out boundary conditions to save disk space.

The following lines in green were added to HISTORY.rc:

COLLECTIONS: 'Restart',
             'BoundaryConditions',
             ...

#==============================================================================
# %%%%% THE BoundaryConditions COLLECTION %%%%%
#
# GEOS-Chem boundary conditions for use in nested grid simulations
#
# Available for all simulations
#==============================================================================
  BoundaryConditions.template:   '%y4%m2%d2_%h2%n2z.nc4',
  BoundaryConditions.format:     'CFIO',
  BoundaryConditions.frequency:  00000000 030000
  BoundaryConditions.duration:   00000001 000000
  BoundaryConditions.mode:       'instantaneous'
  BoundaryConditions.LON_RANGE:  -130.0 -60.0,
  BoundaryConditions.LAT_RANGE:  10.0 60.0,
  BoundaryConditions.fields:     'SpeciesBC_?ADV?             ', 'GIGCchem',
::

NOTE: The .LON_RANGE and .LAT_RANGE options were added in GEOS-Chem 12.6.0. For subsetting with versions 12.4.0 and 12.5.0 used BoundaryConditions.subset : -130.0 -60.0 10.0 60.0.

Read in boundary conditions via HEMCO

The I/O routines in HEMCO will automatically regrid and crop the boundary conditions to the grid defined in input.geos. The boundary conditions will be applied to the buffer zone, also defined in input.geos. These fields are obtained from HEMCO and applied to the species concentrations (State_Chm%Species) in GeosCore/hcoi_gc_main_mod.F90.

The following lines in green were added to HEMCO_Config.rc:

# ExtNr ExtName                on/off  Species 
0       Base                   : on    *
    --> GC_RESTART             :       true     
    --> GC_BCs                 :       true
    ...

#==============================================================================
# --- GEOS-Chem boundary condition file --- 
#==============================================================================
(((GC_BCs
* BC_           ./GEOSChem.BoundaryConditions.$YYYY$MM$DD_$HH$MNz.nc4 SpeciesBC_?ADV?  1980-2019/1-12/1-31/0-23 RY xyz 1 * - 1 1
)))GC_BCs

IMPORTANT: As of implementation, the boundary condition files must have 8 time slices (e.g. hours 0, 3, 6, 9, 12, 15, 18, 21). When generating boundary conditions make sure you start your coarse-resolution simulation at least one day before the start of your nested grid simulation to ensure the boundary condition file for the first day includes hour 0. When hour 0 is missing, HEMCO sees 7 time slices and identifies the dataset as weekly data -- this warrants further investigation.

FlexGrid for different types of users

According to the availability of meteorological data, users can get different benefits from FlexGrid:

User type	Benefits
Only have standard met fields (e.g. global 4x5, 0.25x0.3125 nested NA)	Be able to explicitly control each met variable in HEMCO_Config.rc (like Extdata.rc for GCHP). You can freeze certain variables, apply scaling factors, or read user-generated met data. Be able to set up nested simulations over any sub-domains of the met field you have. For example, you can set up an east-US simulation in no time if you have the nested North American met field data. If a new nested domain is needed, you can skip the source code modification and just prepare the met field input.
Have global native met fields (For example, GCHP users might store them for global high-resolution runs. We can reuse them for nested simulations.)	Be able to run nested simulations over any domains in the world.

FlexGrid examples

HEMCO_Config.rc is the place to explicitly control all meteorological input variables (similar to Extdata.rc in GCHP). Each variable is listed in one line, just like other emission data entries in that file:

# --- CN fields ---
* FRLAKE    $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FRLAKE   */1/1/0               C xy  1  * -  1 1
* FRLAND    $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FRLAND   */1/1/0               C xy  1  * -  1  1
* FRLANDIC  $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FRLANDIC */1/1/0               C xy  1  * -  1 1 
* FROCEAN   $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        FROCEAN  */1/1/0               C xy  1  * -  1 1
* PHIS      $METDIR/$CNYR/01/$MET.$CNYR0101.CN.$RES.$NC        PHIS     */1/1/0               C xy  1  * -  1 1
...
# --- A3dyn fields ---
* DTRAIN    $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  DTRAIN   1980-2018/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1
* OMEGA     $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  OMEGA    1980-2018/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1
* RH        $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  RH       1980-2018/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1
* U         $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  U        1980-2018/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1
* V         $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  V        1980-2018/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1
...

Most of the tricks that you apply to the emission data can also be applied here, such as

• Adding scaling factors
• Applying masks
• Using different met field files
• Holding met fields constant

Change the met field path

Say you've modified the default temperature data to test the sensitivity to the temperature, you can just tell HEMCO to read your new file instead of the default file, while keep all other variables untouched:

* TMPU1     path_to_new_file    T        1980-2018/1-12/1-31/0-23          CY xyz  1  * -  1 1
* TMPU2     path_to_new_file    T        1980-2018/1-12/1-31/0-23/+3hour   CY xyz  1  * -  1 1

Freeze certain variables

You can force the model to keep reusing the wind in 2011 by restricting the time range (e.g. to see how does the trend of certain meteorological variables affects the simulation):

* U         $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  U        2011/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1
* V         $METDIR/$YYYY/$MM/$MET.$YYYY$MM$DD.A3dyn.$RES.$NC  V        2011/1-12/1-31/0-23/+90minute CY xyz 1  * -  1 1

Supported horizontal grid definitions

Examples of grid definitions in input.geos are provided below for users looking to recreate the global and nested grids used in GEOS-Chem prior to the FlexGrid implementation. All examples below may be used with GEOS-FP met fields. MERRA-2 met fields may be used with all examples below except for the 0.25° x 0.3125° grids.

4° x 5° global grid

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 4.0x5.0
Longitude min/max       : -180.0 180.0
Latitude  min/max       : -90.0   90.0
 Half-sized polar boxes?: T
Number of levels        : 47
Nested grid simulation? : F
 Buffer zone (N S E W ) :  3  3  3  3

2° x 2.5° global grid

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 2.0x2.5
Longitude min/max       : -180.0 180.0
Latitude  min/max       : -90.0   90.0
 Half-sized polar boxes?: T
Number of levels        : 47
Nested grid simulation? : F
 Buffer zone (N S E W ) :  3  3  3  3

0.5° x 0.625° nested Asia

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 0.5x0.625
Longitude min/max       :  60.0 150.0
Latitude  min/max       : -11.0  55.0
 Half-sized polar boxes?: F
Number of levels        : 47
Nested grid simulation? : T
 Buffer zone (N S E W ) :  3  3  3  3

0.5° x 0.625° nested Europe

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 0.5x0.625
Longitude min/max       : -30.0 50.0
Latitude  min/max       :  30.0 70.0
 Half-sized polar boxes?: F
Number of levels        : 47
Nested grid simulation? : T
 Buffer zone (N S E W ) :  3  3  3  3

0.5° x 0.625° nested North America

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 0.5x0.625
Longitude min/max       : -140.0 -40.0
Latitude  min/max       :   10.0  70.0
 Half-sized polar boxes?: F
Number of levels        : 47
Nested grid simulation? : T
 Buffer zone (N S E W ) :  3  3  3  3

0.25° x 0.3125° nested China

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 0.25x0.3125
Longitude min/max       : 70.0 140.0
Latitude  min/max       : 15.0  55.0
 Half-sized polar boxes?: F
Number of levels        : 47
Nested grid simulation? : T
 Buffer zone (N S E W ) :  3  3  3  3

0.25° x 0.3125° nested Europe

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 0.25x0.3125
Longitude min/max       : -15.0 40.0
Latitude  min/max       : 32.75 61.25
 Half-sized polar boxes?: F
Number of levels        : 47
Nested grid simulation? : T
 Buffer zone (N S E W ) :  3  3  3  3

0.25° x 0.3125° nested North America

See this link for grid details.

%%% GRID MENU %%%       :
Grid resolution         : 0.25x0.3125
Longitude min/max       : -130.0 -60.0
Latitude  min/max       :   9.75  60.0
 Half-sized polar boxes?: F
Number of levels        : 47
Nested grid simulation? : T
 Buffer zone (N S E W ) :  3  3  3  3

References

Xu, J.-W., Lin, J.-T., Luo, G., Adeniran, J., and Kong, H.: Foreign emissions exacerbate PM2.5 pollution in China through nitrate chemistry, Atmospheric Chemistry and Physics, 23, 4149–4163, doi:10.5194/acp-23-4149-2023, 2023 (As an example of the use of FlexGrid)