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:
- Reading in meteorology fields via HEMCO
- Defining meteorology field, horizontal grid, and vertical grid at run time
- Saving out boundary conditions via the HISTORY component
- 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 |
|
|
| Stage 2: Add capability to define custom grids |
|
|
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) |
|
| Have global native met fields
(For example, GCHP users might store them for global high-resolution runs. We can reuse them for nested simulations.) |
|
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
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)