Introduction

The cpld_gengrid program and associated script related functions create the files required for Fix and IC files for the coupled model.

This document is part of the UFS_UTILS documentation.

The cpld_gengrid program is part of the UFS_UTILS project.

Creating Fix and IC files required for the Coupled Model

For the UFS coupled model application S2S or S2SW, the following fix files are required:

The CICE6 grid and mask file
The mesh file for the desired OCN/ICE resolution, which is identical for MOM6 and CICE6.
The mapped ocean mask on the FV3 tiles
The ESMF regridding weights required to create the CICE6 IC from CPC (SIS2) reanalysis.
The ESMF regridding weights required to remap the CICE6 or MOM6 output from tripole grid to a rectilinear grid (optional).

Since MOM6 creates the model grid at runtime (including adjusting the land mask, if required), the required files for CICE and UFSAtm must be created in a pre-processing step using only the MOM6 supergrid, topography and land mask files as input. This allows the mapped ocean mask (used for creating of the ATM ICs) and the CICE6 grid and mask files to be consistent with the run-time configuration of MOM6.

Background:

MOM6 grids

The MOM6 supergrid contains a MOM6 grid at twice the desired resolution. The indexing of the supergrid vs the reduced grid is:

        Super Grid               Reduced Grid


    I-1,J+1     I+1,J+1
       X─────X─────X            I-1,J   i,j
       │     │     │               X─────X
       │     │     │               │     │
       │    i│j    │               │  T  │
       X─────X─────X               │     │
       │     │     │               X─────X
       │     │     │          I-1,J-1    I,J-1
       │     │     │
       X─────X─────X
    I-1,J-1     I+1,J-1

MOM6 uses an Arakawa C grid. Within cpld_gridgen, these are referred to as "stagger" locations, and named as follows:

             Bu────Cv─────Bu
             │            │
             │            │
             Cu    Ct     Cu
             │            │
             │            │
             Bu────Cv─────Bu

Rotation angles

For the tripole grid, a rotation angle is defined to translate vectors to/from the grid (i-j) orientation from/to true E-W. The rotation angle is calculated at run-time in MOM6 (src/initialization/MOM_shared_initialization.F90). However, CICE6 requires a rotation at the corner (Bu) grid points, which for points along the tripole seam requires values on the other side of the tripole fold. In cpld_gridgen, these values are found by "flipping over" the values on the last row of the MOM6 super-grid. If ipL and ipR are the i-indices of the poles along the last j-row:

            ipL-1     ipL    ipL+1            ipR-1     ipR    ipR+1
               x-------x-------x     |||        x-------x-------x

then after folding along the tripole seam, ipL and ipR must align:

                           ipR+1     ipR    ipR-1
                              x-------x-------x
                           ipL-1     ipL    ipL+1
                              x-------x-------x

Using the folded seam, the values required for calculating the rotation angle on the Bu grid points are available and can be calculated in the same way as MOM6 calculates rotation angles for the Ct grid points.

SCRIP format files

For calculating interpolation weights using ESMF, a SCRIP file needs to be provided. A SCIP file contains the both the grid locations of any stagger grid location (e.g. Ct) and the associated grid vertices for that point. As seen from the above diagram, for the Ct points, those grid vertices are given by the Bu grid locations.

SCRIP requires that the vertices be ordered counter-clockwise so that the center grid point is always to the left of the vertex. In cpld_gridgen, vertices are defined counter-clockwise from upper right. Ct vertices are located on the Bu grid (as shown above), Cu vertices on the Cv grid, Cv vertices on the Cu grid and Bu vertices on the Ct grid. For example, for the Ct grid, the vertices are:

         Vertex #2             Vertex #1
         Bu(i-1,j)             Bu(i,j)
                     Ct(i,j)
       Bu(i-1,j-1)             Bu(i,j-1)
         Vertex #3             Vertex #4

so that the vertices for the Ct grid are found as off-sets of the i,j index of the Bu grid

 iVertCt(4) = (/0, -1, -1,  0/)
 jVertCt(4) = (/0,  0, -1, -1/)

Careful examination of the remaining stagger locations lead to similar definitions for the i,j offsets required to extract the vertices, all of which can be defined in terms of the iVertCt and jVertCt values.

Special treatment is require at the bottom of the grid, where the vertices of the Ct and Cu grid must be set manually (note, these points are on land.) The top of the grid also requires special treatment because the required vertices are located across the tripole seam. This is accomplished by creating 1-d arrays which hold the Ct and Cu grid point locations across the matched seam.

Generating the grid files

The cpld_gridgen program and associated script related functions perform the following tasks:

read the MOM6 supergrid and ocean mask file and optionally creates the required topo_edits file if the land mask for MOM6 is to be changed at runtime.
create a master grid file containing all stagger locations of the grid fully defined
create the CICE6 grid variables and writes the required CICE6 grid file
create a SCRIP file for the center stagger (Ct) grid points and a second SCRIP file also containing the land mask
create the ESMF conservative regridding weights to map the ocean mask to the FV3 tiles and write the mapped mask to 6 tile files
create the ESMF regridding weights to map the 1/4 CICE6 restart file to a lower resolution tripole grid
optionally call a routine to generate ESMF regridding weights to map the tripole grid to a set of rectilinear grids
use the command line command ESMF_Scrip2Unstruct to generate the ocean mesh from the SCRIP file containing the land mask (item 4)
use an NCO command line command to generate the CICE6 land mask file from the CICE6 grid file

The generated files

The exact list of files produced by the cpld_gridgen.sh script will vary depending on several factors. For example, if the DO_POSTWGHTS flag is true, then a SCRIP format file will be produced for each rectilinear destination grid desired and a file containing the regridding weights to map from the center Ct stagger point to the rectilinear grid will also be written. Because both MOM6 and CICE6 velocity variables are located at Cu,Cv or Bu locations, additional files will also be created to regrid from the velocity stagger locations to the center Ct location. If an OCN/ICE grid resolution less than 1/4 degree is chosen, then a file containing regridding weights from the 1/4 degree grid to a lower resolution grid will also be written. Note also that multiple intermediate SCRIP format files may be produced depending on the options chosen.

Executing the script for the 1/4 deg OCN/ICE resolution will result in the following files being produced in the output location:

Output files for 1/4 deg
File name	Description	Function
tripole.mx025.nc	master grid file	Creating all subsequent grid or mapping files
grid_cice_NEMS_mx025.nc	the CICE grid file	used at runtime by CICE6
kmtu_cice_NEMS_mx025.nc	the CICE mask file	used at runtime by CICE6
mesh.mx025.nc	the ocean and ice mesh file	used at runtime by CICE6, MOM6, and CMEPS
C384.mx025.tile[1-6].nc	the mapped ocean mask on the ATM tiles	used to create ATM ICs consistent with the fractional grid

If the optional post-weights are generated, the following files will be produced in the output location:

Optional post-weights files for 1/4deg
File name	Function
tripole.mx025.[Cu][Cv][Bu].to.Ct.bilinear.nc	the ESMF weights for mapping OCN or ICE output fields from the various stagger locations on the tripole grid to the center (Ct) stagger location on the same tripole grid using bilinear mapping
tripole.mx025.Ct.to.rect.[destination resolution].[bilinear][conserve].nc	the ESMF weights for mapping variables on the center (Ct) stagger location on the tripole grid to a rectilinear grid with [destination resolution] using either bilinear or conservative mapping

If a resolution other than 1/4 degree is used in cpld_gridgen.sh, the following file will be produced in the output location:

Output files for CICE6 IC creation at tripole destination resolution
File name	Function
tripole.mx025.Ct.to.mx[destination resolution].Ct.neareststod.nc	the ESMF weights for mapping the 1/4 CICE ICs to a tripole [destination resolution] using nearest source-to-destination mapping

If run-time land mask changes for MOM6 are requested, the following file will be produced in the output location:

Output files for run-time modification of MOM6 land mask
File name	Function
ufs.[Default filename].nc	Topo-edits required for UFS application. These are appended to the existing default topo edits file and implemented at run time with the parameter flag `ALLOW_LANDMASK_CHANGES=true`. All files produced by the cpld_gridgen.sh will be consistent with this run-time land mask.