Versions Compared

Old Version 210

changes.mady.by.user Xylar Asay-Davis

Saved on

compared with

New Version Current

changes.mady.by.user Walter Hannah

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The purpose of this page is to document the procedure for adding support for new atmosphere grids. The process should be the same for new uniform resolutions as well as for new regionally-refined meshes, although some settings will need to be changed for new regionally-refined mesh configurations. This page is a work in progress, and will be updated as this process is refined and (eventually) made more automated. This documentation is an update of a document written by Mark Taylor and Colin Zarzycki, available as a Google Doc here.

Table of Contents

Table of Contents

Child Pages

Child pages (Children Display)

Useful Example Pages:

...

/wiki/spaces/NGDNA/pages/3086549115

...

 NE512 and NE1024 configurations

...

File

...

Tool

...

Type

...

Note

...

ncks, ncremap

...

NCO

...

mapping files and mesh template files

...

TempestRemap

...

C++

...

GenerateCSMesh:  make cubed sphere  Exodus (.g) files (spectral element "np" grid)
GenerateVolumetricMesh  create a FV "pg" from a spectral element "np" grid
ConvertExodusToSCRIP convert a FV "pg" Exodus file into a SCRIP file
GenerateOverlapMesh:  used in making mapping files
GenerateOfflineMap:  generate mapping files.  Only tool which can make mapping files directly from SE Exodus files.  

...

RRM Exodus (.g)  mesh files

...

SquadGen

...

C++

...

topo files

...

homme_tool

...

Fortran

...

Included with E3SM.  Should build and run on any system which can run the HOMME_P24.f19_g16_rx1.A test

Generate (obsolete) SCRIP files for the spectral element "np" dual grid

Used for topo smoothing for both FV "pg" and SE "np" grids. 

Can also do parallel interpolation from SE np4 grid to any SCRIP grid

...

topo files

...

cube_to_target

...

Fortran

...

NCAR utility for generating unsmoothed topography from high-res USGF data, and generating surface roughness fields from smoothed topography

...

mapping files

...

ESMF_Regridweightgen

...

Make FV->FV mapping files from SCRIP grid template files

Only tool which supports the montone 2nd order "bilin" map

...

gen_domain_files 

...

CIME and ELM tools

...

land surface dataset 

...

mksurfdata.pl, mksurfdata_map,

...

Perl and Fortran

...

ELM initial condition

...

interpinic

...

Fortran

4 options:

  1. cold start: (no IC file).  only suitable for testing functionality in other components.

  2. Run long spinup with prescribed atmosphere 

  3. Interpolate from a spunup IC file from a different simulation, via "interpinc" utility

  4. Inline interpolation for land initial condition is available in E3SM code, but this capability might get broken with the new land subgrid structure

Archives of already-created atmosphere grid and mapping files can be accessed at https://web.lcrc.anl.gov/public/e3sm/mapping/grids/ and https://web.lcrc.anl.gov/public/e3sm/mapping/maps/ . This page focuses on creating new versions of these files.

For the purpose of this step-by-step guide, we will walk through each step using an example of regenerating the ne4 grid that is already currently supported. For a new grid (i.e., ne512), just replace ne4 with the desired grid identifier. This is determined in Step 1 Generate a new "grid" file below, and the rest should follow.

For this example, I will assume a few environment variables, which we should set now. First, determine where to put the generated output files. For big grids, this can take up quite a bit of space, so choose a location with sufficient space. I have a symlink to my CSCRATCH directory on NESRC in my home directory, so I will put grid files there for this example:

Code Block
output_root=${HOME}/cscratch/e3sm/grids/ne4
mkdir -p ${output_root}

Types of Atmosphere grid metadata files

See SE Atmosphere Grid Overview (EAM & CAM) for description of the spectral elements, GLL nodes, subcell grid and dual grid.   

  • Exodus file: "ne4.g".   This is a netcdf file following Exodus conventions.  It gives the corners of all elements on the sphere and their connectivity.  It is independent of the polynomial order used inside the element ("np").  

    • This file is used by TempestRemap (TR) to generate mapping files.  The polynomial order is a command line option and the GLL nodes are internally generated by TR.  

  • SCRIP file:  "ne4pg2.scrip.nc".   This file contains a description of the atmosphere physics grid n the format used by the original incremental remap tool SCRIP. It is used for most output and also used to generate mapping files between components and for post-processing of most output.

  • Less common “GLL” metadata files needed for specialized purposes:

    • SCRIP file:  "ne4np4_scrip.nc".   This file contains a description (SCRIP format) of the GLL dual grid. It includes the locations of the GLL nodes and artificial bounding polygons around those nodes.   Ideally the spherical area of each polygon will match the GLL weight ("exact GLL areas"), but not all tools can achieve exact areas.  Inexact areas does not impact the accuracy of the resulting mapping algorithm, it just means that mass will not be exactly conserved by the mapping algorithm.  

    • latlon file:  "ne4np4_latlon.nc".   This file contains a list of all the GLL nodes in the mesh (in latitude/longitude coordinates).   The list of GLL nodes must be in the the internal HOMME global id ordering, matching the ordering used in CAM and EAM native grid output.   It also contains the connectivity of the GLL subcell grid.   

      • This file is used by CAM's interpic_new utility, and graphics programs Paraview and Visit when plotting native grid GLL output.

Step-by-step guide

1. Generate a new atmosphere "grid" file

Requirements: TempestRemap

In order to generate mapping files to do interpolation between a new atmosphere grid and the other component grids, we need to create a file that describes the atmosphere grid representation. The TempestRemap tool (https://github.com/ClimateGlobalChange/tempestremap) can be used to recreate the internal representation of the spectral element grids used in HOMME. The grid mesh file will be saved in an "exodus" type file (with a .g extension). 

TempestRemap can now be pulled in with NCO via conda, or can be built from source from the Github repository. To build from source, make sure a netCDF module is loaded. This can be accomplished by sourcing an env_mach_specific.sh from a working case on the target machine before building. Then, 

Code Block
git clone https://github.com/ClimateGlobalChange/tempestremap.git
cd tempestremap
make -f Makefile.gmake
cd ..

This will build TempestRemap into tempestremap/bin. For the rest of the tutorial, assume that the environment variable ${tempest_root} points to this directory (or where a conda-build of TempestRemap exists):

Code Block
tempest_root=${PWD}/tempestremap

We can generate an ne4 mesh easily now:

Code Block
${tempest_root}/bin/GenerateCSMesh --alt --res 4 --file ${output_root}/ne4.g

For RRM grids, SQuadGen should be used (available in a separate repository on Github here). See Generate the Grid Mesh (Exodus) File for a new Regionally-Refined Grid for details and examples. The example above follows the convention ne<res>.g. RRM meshes should follow the convention <area refined>_<base resolution>x<refinement level>.g. For example, for a RRM with 4x refinement from ne30 to ne120 over CONUS, we should use the convention conus_ne30x4.g (note that existing meshes use the naming convention <area of refinement>x<refinement level>v<version>.g, but future meshes should use the new naming convention; we also plan to eventually change the extension to _exodus.nc, but I believe this will break nco functionality to automatically detect when to use TempestRemap for mapping when detecting exodus files).

The Exodus file contains only information about the position of the spectral element on the sphere. For SE aware utilities such as TempestRemap, they can use the polynomial order and the reference element map to fill in necessary data such as the locations of the nodal GLL points. For non-SE aware utilities, we need additional meta data, described in the next section.   

2A. Generate control volume mesh files for E3SM v2 "pg2" grids 

Requirements:

  • exodus mesh file

  • TempestRemap

In E3SM v2, we switched to running physics on a FV pg2 grid and mapping files between the atmosphere and other components will be FV to FV type maps using the pg2 grids.  These can be generated by TempestRemap directly from the exodus mesh file:

Code Block
${tempest_root}/bin/GenerateVolumetricMesh --in ne4.g --out ne4pg2.g --np 2 --uniform                                  
${tempest_root}/bin/ConvertExodusToSCRIP --in ne4pg2.g --out ne4pg2.scrip.nc

2B. Generate "dual grid" mesh files (SCRIP and lat/lon format) for E3SM v1 "np4" GLL grids

Requirements:

  • exodus mesh file

  • homme_tool

Note: in E3SM v2, we switched to running physics on a FV pg2 grid and mapping files between the atmosphere and other components will be FV to FV type maps using the pg2 grids.   The spectral element "np4" grid is still used internally by the dynamics and for initial conditions, so the metadata described in this section is still needed for some analysis and preparation of initial conditions.   

Mapping files used by the coupler for mapping fluxes between SE "np4" and FV grids should be generated with TempestRemap and only need the exodus grid description (which provides the locations of the corners of the quadrilaterals that form the elements of the cube-sphere mesh) generated in Step 1 above. However, a handful of pre- and post-processing tools require a finite-volume equivalent of the spectral element grid (these tools include the surface roughness calculation in the land tool cube_to_target, ESMF mapping files used for interpolating land surface data to target grid, and post-processing regional and subgrid remapping tools). We refer to this finite-volume description of the SE grid as the "dual grid" to the SE grid (see page describing atmosphere grids in more detail here).     

Generate SCRIP “dual grid” with homme_tool:

  1. Be sure your environment matches the software environment loaded by E3SM by executing the output of this command:   e3sm/cime/scripts/Tools/get_case_env

  2. Use cmake to configure and compile standalone HOMME.  On a supported platform with the CIME environement, this should work out-of-the-box.  See e3sm/components/homme/README.cmake

  3. compile the HOMME tool utility: 

    1. cd /path/to/workingdir 

    2. make -j4 homme_tool

    3. executable:   /path/to/workingdir/src/tool/homme_tool

  4. Edit e3sm/components/homme/test/tool/namelist/template.nl and specify the grid resolution or RRM file

    1. For ne512, this would be ne = 512. For RRM grids, leave ne = 0, but will need to edit where the exodus grid file comes from

    2. for non-RRM grids using the older E3SM v1 dycore, add cubed_sphere_map=0 to template.nl

  5. See e3sm/components/homme/test/tool/test.job for examples of how to run the script and then use an NCL utilities to process the tool output into SCRIP and latlon formats.  

Specific details for running at NERSC on Cori(knl):

  1. Create a batch script hange "account" in the sbatch directives at the top of the script. For example, set #SBATCH --account=e3sm

  2. cmake -C /path/to/e3sm/components/homme/cmake/machineFiles/cori-knl.cmake  -DPREQX_NP=4 /path/to/workingdir

  3. Make sure a working NCL is in your PATH. On Cori, add the following to the script: module load ncl.

2C. Atmospheric mesh quality

Atmospheric RRM mesh quality can be measured with the “Max Dinv-based element distortion” metric. This will be printed in the log file for standalone HOMME or EAM simulations (and can be obtained from the log files during the topo generation step). It measures how distorted the elements become in the mesh transition region. It is the ratio of the two singular values of the 2x2 derivative matrix of the element map to the unit square, representing the ration of the largest length scale to the smallest length scale. A grid of perfect quadrilaterals will have a value of 1.0. The equal-angle cubed-sphere grid has a value of 1.7.   A high quality regionally refined grid will have a value less than 4. With a high quality grid, usually one can run with the timesteps used in a uniform grid with matching fine resolution. RRM grids with a value > 4 may require smaller timesteps for stability. Very large values indicate a problem with the grid and it should be redesigned.

3. Generate mapping files

Requirements:

  • TempestRemap

  • ESMF_RegridWeightGen

  • ncremap

  • grid descriptor files for each component that exists on a different grid
    (atmosphere, ocean, possibly land if on a different grid than the atmosphere)

In order to pass data between different components at runtime, a set of mapping files between each component is generated offline. These mapping files will also be used in Step 4 below (generating domain files).

See Transition to TempestRemap for Atmosphere grids for a discussion of different remap algorithms and when to use each.

TempestRemap and ESMF are the backends that generate the mapping weights, but this is all nicely encapsulated using ncremap. Tempest is the preferred method for creating mapping files.     The ncremap function, calling TempestRemap or ESMF, will decide which of these two tools to use based on the atmospheric input file.  If the *.scrip file was used, then ESMF will be called.  If the *.g file was used, then TempestRemap will be called.   The ESMF tools are adequate for making atmosphere-only-type component sets for E3SM, but this tool is less conservative than TempestRemap.   If you are making grids for a coupled run, then TempestRemap should be used.  

The easiest way to make sure ncremap is up to date and will work for this workflow, we can source the ESMF-Unified conda environment. Instructions for supported machines can be found here. For Edison and Cori, it is as simple as:

Code Block
source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_cori-haswell.sh

For unsupported machines you may need to install the conda environment via:

Code Block
conda install -c conda-forge -c e3sm e3sm-unified

TempestRemap was built in Step #1 above.     We need to tell ncremap where to find our TempestRemap binaries, so we need to append to our PATH:

Code Block
PATH=${tempest_path}/bin:${PATH}

And now we can use ncremap to generate ALL the needed mapping files between two grids, in this example the ne4 atmosphere and the oQU240 ocean grid (for the moment, we will put the land on the same grid as the atmosphere):

Code Block
atm_grid_file=ne4.g
ocn_grid_file=/global/cfs/cdirs/e3sm/inputdata/cpl/gridmaps/oQU240/ocean.QU.240km.scrip.151209.nc
cd ${output_root} && ncremap -P mwf -s $ocn_grid_file -g $atm_grid_file --nm_src=oQU240 --nm_dst=ne4np4 --dt_sng=20181114

In the above code, the "-P mwf" option triggers a specific procedure that invokes multiple ncremap commands which each invoke multiple Tempest commands.It produces 3 mapping files each for a2o and o2a. This multitude of mapping files for each component→component case are needed because fluxes need conservative mapping and states need non-conservative mapping. Because "-P mwf" results in a great deal of output being flushed to screen, it is mostly suppressed by default. To see all the output or to figure out how to run all the nco and tempest remap commands one-by-one, add "--dbg_lvl=2" to the ncremap command. This will print the commands but not execute them. The user can then use one of the printed commands, again with "--dbg_lvl=2" to see the actual commands being sent to Tempest.

If this command is successful, it should produce many mapping files in ${output_root}, that look something like

...

The purpose of this page is to document the procedure for adding support for new atmosphere grids. The process should be the same for new uniform resolutions as well as for new regionally-refined meshes, although some settings will need to be changed for new regionally-refined mesh configurations. This page is a work in progress, and will be updated as this process is refined and (eventually) made more automated. This documentation is an update of a document written by Mark Taylor and Colin Zarzycki, available as a Google Doc here.

Table of Contents

Table of Contents

Child Pages

Child pages (Children Display)

Useful Example Pages:

File

Tool

Type

Note


ncks, ncremap

NCO


mapping files and mesh template files

TempestRemap

C++

GenerateCSMesh:  make cubed sphere  Exodus (.g) files (spectral element "np" grid)
GenerateVolumetricMesh  create a FV "pg" from a spectral element "np" grid
ConvertMeshToSCRIP convert a FV "pg" Exodus file into a SCRIP file
GenerateOverlapMesh:  used in making mapping files
GenerateOfflineMap:  generate mapping files.  Only tool which can make mapping files directly from SE Exodus files.  

RRM Exodus (.g)  mesh files

SquadGen

C++


topo files

homme_tool

Fortran

Included with E3SM.  Should build and run on any system which can run the HOMME_P24.f19_g16_rx1.A test

Generate (obsolete) SCRIP files for the spectral element "np" dual grid

Used for topo smoothing for both FV "pg" and SE "np" grids. 

Can also do parallel interpolation from SE np4 grid to any SCRIP grid

topo files

cube_to_target

Fortran

NCAR utility for generating unsmoothed topography from high-res USGF data, and generating surface roughness fields from smoothed topography

mapping files

ESMF_Regridweightgen


Make FV->FV mapping files from SCRIP grid template files

Only tool which supports the montone 2nd order "bilin" map


gen_domain_files 

CIME and ELM tools


land surface dataset 

mksurfdata.pl, mksurfdata_map,

Perl and Fortran


ELM initial condition

interpinic

Fortran

4 options:

  1. cold start: (no IC file).  only suitable for testing functionality in other components.

  2. Run long spinup with prescribed atmosphere 

  3. Interpolate from a spunup IC file from a different simulation, via "interpinc" utility

  4. Inline interpolation for land initial condition is available in E3SM code, but this capability might get broken with the new land subgrid structure



Archives of already-created atmosphere grid and mapping files can be accessed at https://web.lcrc.anl.gov/public/e3sm/mapping/grids/ and https://web.lcrc.anl.gov/public/e3sm/mapping/maps/ . This page focuses on creating new versions of these files.

For the purpose of this step-by-step guide, we will walk through each step using an example of regenerating the ne4 grid that is already currently supported. For a new grid (i.e., ne512), just replace ne4 with the desired grid identifier. This is determined in Step 1 Generate a new "grid" file below, and the rest should follow.

For this example, I will assume a few environment variables, which we should set now. First, determine where to put the generated output files. For big grids, this can take up quite a bit of space, so choose a location with sufficient space. I have a symlink to my CSCRATCH directory on NESRC in my home directory, so I will put grid files there for this example:

Code Block
output_root=${HOME}/cscratch/e3sm/grids/ne4
mkdir -p ${output_root}

Types of Atmosphere grid metadata files

See SE Atmosphere Grid Overview (EAM & CAM) for description of the spectral elements, GLL nodes, subcell grid and dual grid.   

  • Exodus file: "ne4.g".   This is a netcdf file following Exodus conventions.  It gives the corners of all elements on the sphere and their connectivity.  It is independent of the polynomial order used inside the element ("np").  

    • This file is used by TempestRemap (TR) to generate mapping files.  The polynomial order is a command line option and the GLL nodes are internally generated by TR.  

  • SCRIP file:  "ne4pg2.scrip.nc".   This file contains a description of the atmosphere physics grid n the format used by the original incremental remap tool SCRIP. It is used for most output and also used to generate mapping files between components and for post-processing of most output.

  • Less common “GLL” metadata files needed for specialized purposes:

    • SCRIP file:  "ne4np4_scrip.nc".   This file contains a description (SCRIP format) of the GLL dual grid. It includes the locations of the GLL nodes and artificial bounding polygons around those nodes.   Ideally the spherical area of each polygon will match the GLL weight ("exact GLL areas"), but not all tools can achieve exact areas.  Inexact areas does not impact the accuracy of the resulting mapping algorithm, it just means that mass will not be exactly conserved by the mapping algorithm.  

    • latlon file:  "ne4np4_latlon.nc".   This file contains a list of all the GLL nodes in the mesh (in latitude/longitude coordinates).   The list of GLL nodes must be in the the internal HOMME global id ordering, matching the ordering used in CAM and EAM native grid output.   It also contains the connectivity of the GLL subcell grid.   

      • This file is used by CAM's interpic_new utility, and graphics programs Paraview and Visit when plotting native grid GLL output.


...

Step-by-step guide

1. Generate a new atmosphere "grid" file

Requirements: TempestRemap

In order to generate mapping files to do interpolation between a new atmosphere grid and the other component grids, we need to create a file that describes the atmosphere grid representation. The TempestRemap tool (https://github.com/ClimateGlobalChange/tempestremap) can be used to recreate the internal representation of the spectral element grids used in HOMME. The grid mesh file will be saved in an "exodus" type file (with a .g extension). 

TempestRemap can now be pulled in with NCO via conda, or can be built from source from the Github repository. To build from source, make sure a netCDF module is loaded. This can be accomplished by sourcing an env_mach_specific.sh from a working case on the target machine before building. Then, 

Code Block
git clone https://github.com/ClimateGlobalChange/tempestremap.git
cd tempestremap
make -f Makefile.gmake
cd ..

This will build TempestRemap into tempestremap/bin. For the rest of the tutorial, assume that the environment variable ${tempest_root} points to this directory (or where a conda-build of TempestRemap exists):

Code Block
tempest_root=${PWD}/tempestremap

We can generate an ne4 mesh easily now:

Code Block
${tempest_root}/bin/GenerateCSMesh --alt --res 4 --file ${output_root}/ne4.g

For RRM grids, SQuadGen should be used (available in a separate repository on Github here). See Generate the Grid Mesh (Exodus) File for a new Regionally-Refined Grid for details and examples. The example above follows the convention ne<res>.g. RRM meshes should follow the convention <area refined>_<base resolution>x<refinement level>.g. For example, for a RRM with 4x refinement from ne30 to ne120 over CONUS, we should use the convention conus_ne30x4.g (note that existing meshes use the naming convention <area of refinement>x<refinement level>v<version>.g, but future meshes should use the new naming convention; we also plan to eventually change the extension to _exodus.nc, but I believe this will break nco functionality to automatically detect when to use TempestRemap for mapping when detecting exodus files).

The Exodus file contains only information about the position of the spectral element on the sphere. For SE aware utilities such as TempestRemap, they can use the polynomial order and the reference element map to fill in necessary data such as the locations of the nodal GLL points. For non-SE aware utilities, we need additional meta data, described in the next section.   

2A. Generate control volume mesh files for E3SM v2 "pg2" grids 

Requirements:

  • exodus mesh file

  • TempestRemap

In E3SM v2, we switched to running physics on a FV pg2 grid and mapping files between the atmosphere and other components will be FV to FV type maps using the pg2 grids.  These can be generated by TempestRemap directly from the exodus mesh file:

Code Block
${tempest_root}/bin/GenerateVolumetricMesh --in ne4.g --out ne4pg2.g --np 2 --uniform                                  
${tempest_root}/bin/ConvertMeshToSCRIP --in ne4pg2.g --out ne4pg2.scrip.nc


2B. Generate "dual grid" mesh files (SCRIP and lat/lon format) for E3SM v1 "np4" GLL grids

Requirements:

  • exodus mesh file

  • homme_tool

Note: in E3SM v2, we switched to running physics on a FV pg2 grid and mapping files between the atmosphere and other components will be FV to FV type maps using the pg2 grids.   The spectral element "np4" grid is still used internally by the dynamics and for initial conditions, so the metadata described in this section is still needed for some analysis and preparation of initial conditions.   

Mapping files used by the coupler for mapping fluxes between SE "np4" and FV grids should be generated with TempestRemap and only need the exodus grid description (which provides the locations of the corners of the quadrilaterals that form the elements of the cube-sphere mesh) generated in Step 1 above. However, a handful of pre- and post-processing tools require a finite-volume equivalent of the spectral element grid (these tools include the surface roughness calculation in the land tool cube_to_target, ESMF mapping files used for interpolating land surface data to target grid, and post-processing regional and subgrid remapping tools). We refer to this finite-volume description of the SE grid as the "dual grid" to the SE grid (see page describing atmosphere grids in more detail here).     

Generate SCRIP “dual grid” with homme_tool:

  1. Be sure your environment matches the software environment loaded by E3SM by executing the output of this command:   e3sm/cime/scripts/Tools/get_case_env

  2. Use cmake to configure and compile standalone HOMME.  On a supported platform with the CIME environement, this should work out-of-the-box.  See e3sm/components/homme/README.cmake

  3. compile the HOMME tool utility: 

    1. cd /path/to/workingdir 

    2. make -j4 homme_tool

    3. executable:   /path/to/workingdir/src/tool/homme_tool

  4. Edit e3sm/components/homme/test/tool/namelist/template.nl and specify the grid resolution or RRM file

    1. For ne512, this would be ne = 512. For RRM grids, leave ne = 0, but will need to edit where the exodus grid file comes from

    2. for non-RRM grids using the older E3SM v1 dycore, add cubed_sphere_map=0 to template.nl

  5. See e3sm/components/homme/test/tool/test.job for examples of how to run the script and then use an NCL utilities to process the tool output into SCRIP and latlon formats.  

Specific details for running at NERSC on Cori(knl):

  1. Create a batch script hange "account" in the sbatch directives at the top of the script. For example, set #SBATCH --account=e3sm

  2. cmake -C /path/to/e3sm/components/homme/cmake/machineFiles/cori-knl.cmake  -DPREQX_NP=4 /path/to/workingdir

  3. Make sure a working NCL is in your PATH. On Cori, add the following to the script: module load ncl.

2C. Atmospheric mesh quality

Atmospheric RRM mesh quality can be measured with the “Max Dinv-based element distortion” metric. This will be printed in the log file for standalone HOMME or EAM simulations (and can be obtained from the log files during the topo generation step). It measures how distorted the elements become in the mesh transition region. It is the ratio of the two singular values of the 2x2 derivative matrix of the element map to the unit square, representing the ration of the largest length scale to the smallest length scale. A grid of perfect quadrilaterals will have a value of 1.0. The equal-angle cubed-sphere grid has a value of 1.7.   A high quality regionally refined grid will have a value less than 4. With a high quality grid, usually one can run with the timesteps used in a uniform grid with matching fine resolution. RRM grids with a value > 4 may require smaller timesteps for stability. Very large values indicate a problem with the grid and it should be redesigned.

3. Generate mapping files

Requirements:

  • TempestRemap

  • ESMF_RegridWeightGen

  • ncremap

  • grid descriptor files for each component that exists on a different grid
    (atmosphere, ocean, possibly land if on a different grid than the atmosphere)

In order to pass data between different components at runtime, a set of mapping files between each component is generated offline. These mapping files will also be used in Step 4 below (generating domain files).

See Transition to TempestRemap for Atmosphere grids for a discussion of different remap algorithms and when to use each.

TempestRemap and ESMF are the backends that generate the mapping weights, but this is all nicely encapsulated using ncremap. Tempest is the preferred method for creating mapping files.     The ncremap function, calling TempestRemap or ESMF, will decide which of these two tools to use based on the atmospheric input file.  If the *.scrip file was used, then ESMF will be called.  If the *.g file was used, then TempestRemap will be called.   The ESMF tools are adequate for making atmosphere-only-type component sets for E3SM, but this tool is less conservative than TempestRemap.   If you are making grids for a coupled run, then TempestRemap should be used.  

The easiest way to make sure ncremap is up to date and will work for this workflow, we can source the ESMF-Unified conda environment. Instructions for supported machines can be found here. For Edison and Cori, it is as simple as:

Code Block
source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_cori-haswell.sh

For unsupported machines you may need to install the conda environment via:

Code Block
conda install -c conda-forge -c e3sm e3sm-unified

TempestRemap was built in Step #1 above.     We need to tell ncremap where to find our TempestRemap binaries, so we need to append to our PATH:

Code Block
PATH=${tempest_path}/bin:${PATH}

And now we can use ncremap to generate ALL the needed mapping files between two grids, in this example the ne4 atmosphere and the oQU240 ocean grid (for the moment, we will put the land on the same grid as the atmosphere):

Code Block
atm_grid_file=ne4.g
ocn_grid_file=/global/cfs/cdirs/e3sm/inputdata/cpl/gridmaps/oQU240/ocean.QU.240km.scrip.151209.nc
cd ${output_root} && ncremap -P mwf -s $ocn_grid_file -g $atm_grid_file --nm_src=oQU240 --nm_dst=ne4np4 --dt_sng=20181114

In the above code, the "-P mwf" option triggers a specific procedure that invokes multiple ncremap commands which each invoke multiple Tempest commands.It produces 3 mapping files each for a2o and o2a. This multitude of mapping files for each component→component case are needed because fluxes need conservative mapping and states need non-conservative mapping. Because "-P mwf" results in a great deal of output being flushed to screen, it is mostly suppressed by default. To see all the output or to figure out how to run all the nco and tempest remap commands one-by-one, add "--dbg_lvl=2" to the ncremap command. This will print the commands but not execute them. The user can then use one of the printed commands, again with "--dbg_lvl=2" to see the actual commands being sent to Tempest.

If this command is successful, it should produce many mapping files in ${output_root}, that look something like

Code Block
map_${atm_grid}_to_${ocn_grid}_${method}.${datestring}.nc

...


map_${ocn_grid}

...

_to_${atm_grid}_${method}.${datestring}.nc
map_${atm_grid}

...

_to_${lnd_grid

...

For pg2 grids, the ncremap invocations are as follows, using ne30pg2 atmosphere, oEC60to30v3 ocean, and half-degree land grids as examples.

Code Block
atm_grid_file=ne30pg2.g
atm_scrip_grid_file=ne30pg2_scrip.nc
ocn_grid_file=ocean.oEC60to30v3.scrip.181106.nc
lnd_grid_file=SCRIPgrid_0.5x0.5_nomask_c110308.nc

atm_name=ne30pg2
ocn_name=oEC60to30v3
lnd_name=r05

## Conservative, monotone maps.

}_${method}.${datestring}.nc
map_${lnd_grid}_to_${atm_grid}_${method}.${datestring}.nc
map_${lnd_grid}_to_${ocn_grid}_${method}.${datestring}.nc
map_${ocn_grid}_to_${lnd_grid}_${method}.${datestring}.nc

where ${ocn_grid}, ${atm_grid}, and ${lnd_grid} are the names of the ocean and atmos grid provided above in the --nm_src and --nm_dst arguments, and ${datestring} is the date string provided above in the --dt_sng argument to ncremap.   The ${method} can be monotr, highorder, mono, intbilin, aave, blin, ndtos, nstod, and patc.  (TODO:  What do all these mean?)   If using the tri-grid option, the land grid files will be created from the ${lnd_grd}.  

For pg2 grids, the ncremap invocations are as follows, using ne30pg2 atmosphere, oEC60to30v3 ocean, and half-degree land grids as examples.

Code Block
atm_grid_file=ne30pg2.g
atm_scrip_grid_file=ne30pg2_scrip.nc
ocn_grid_file=ocean.oEC60to30v3.scrip.181106.nc
lnd_grid_file=SCRIPgrid_0.5x0.5_nomask_c110308.nc

atm_name=ne30pg2
ocn_name=oEC60to30v3
lnd_name=r05

## Conservative, monotone maps.

alg_name=mono

date=200110

function run {
    echo "src $src dst $dst map $map"
    ncremap -a tempest --src_grd=$src --dst_grd=$dst -m $map \
        -W '--in_type fv --in_np 1 --out_type fv --out_np 1 --out_format Classic --correct_areas' \
        $extra
}

extra=""

src=$ocn_grid_file
dst=$atm_grid_file
map="map_${ocn_name}_to_${atm_name}_${alg_name}.${date}.nc"
run

src=$atm_grid_file
dst=$ocn_grid_file
map="map_${atm_name}_to_${ocn_name}_${alg_name}.${date}.nc"
extra=--a2o
run
extra=""

src=$lnd_grid_file
dst=$atm_grid_file
map="map_${lnd_name}_to_${atm_name}_${alg_name}.${date}.nc"
run

src=$atm_grid_file
dst=$lnd_grid_file
map="map_${atm_name}_to_${lnd_name}_${alg_name}.${date}.nc"
run

## Nonconservative, monotone maps.

alg_name=bilin

src=$atm_scrip_grid_file
dst=$lnd_grid_file
map="map_${atm_name}_to_${lnd_name}_${alg_name}.${date}.nc"
ncremap -a bilinear -s $src -g $dst -m $map -W '--extrap_method  nearestidavg'

src=$atm_scrip_grid_file
dst=$ocn_grid_file
map="map_${atm_name}_to_${ocn_name}_${alg_name}.${date}.nc"
ncremap -a bilinear -s $src -g $dst -m $map -W '--extrap_method  nearestidavg'

...

Generating the topography and related surface roughness data sets is a detailed process that has been moved to it’s own page, with detailed instructions depending on the model version (V1, V2, V3)

Atmospheric Topography Generation

6. Generate and spin-up a new atmosphere initial condition

...

Code Block
#!/bin/bash

# Get machine-specific modules
env_mach_specific=env_mach_specific.sh
source ${env_mach_specific}

e3sm_root=/home/bhillma/codes/e3sm/branches/master

interp_root=${e3sm_root}/components/cameam/tools/interpic_new
template_file=${interp_root}/template.nc

input_atm_ic_file=/projects/ccsm/inputdata/atm/cam/inic/fv/cami-mam3_0000-01-01_0.9x1.25_L30_c100618.nc
nlevels=72
atm_latlon_file=/gscratch/bhillma/e3sm/grids/conusx8v1/conusx8v1np4b_latlon_170526.nc

# specify a file to pull information about vertical levels from
if [ ${nlevels} -eq 72 ]; then
    vertical_file=/projects/ccsm/inputdata/atm/cam/inic/homme/cami_mam3_Linoz_0000-01-ne120np4_L72_c160318.nc
elif [ ${nlevels} -eq 30 ]; then
    vertical_file=/projects/ccsm/inputdata/atm/cam/inic/homme/cami-mam3_0000-01-ne120np4_L30_c110928.nc
else
    echo "No input specified for nlevels=${nlevels}."
    exit 1
fi

datestring=`date +'%y%m%d'`
grid_name="conusx8v1"
output_root="/gscratch/bhillma/e3sm/grids/${grid_name}"
output_atm_ic_file=${output_root}/cami-mam3_0000-01-${grid_name}_L${nlevels}_c${datestring}.nc

# copy horizontal coordinates to template file
/projects/ccsm/nco/bin/ncks -O -v lat,lon ${atm_latlon_file} ${template_file}

# copy vertical coordinates from existing initial condition to template file
/projects/ccsm/nco/bin/ncks -A -v hyai,hybi,hyam,hybm ${vertical_file} ${template_file}

# build tool
cd ${interp_root}
make clean
gmake

# run the interpolation code
./interpic -t ${template_file} ${input_atm_ic_file} ${output_atm_ic_file}

# if input initial condition was from an FV grid, rename US->U, VS->V
# this is hard-coded above, so yes we need to rename US and VS
/projects/ccsm/nco/bin/ncrename -O -v US,U -v VS,V ${output_atm_ic_file}

# update configuration file
if [ $? -eq 0 ]; then
    echo "Successfully created ${output_atm_ic_file}."
else
    echo "Something went wrong."
    exit 1
fi

...

...

  • the steps below are for maint1-0 code base. Post-v1 release changes (to add phosphorus) broke existing land initial condition files (finidat) and may require changes to this methodology. 

  • the focus here is on creating an fsurdat file in cases where land use land cover change (LULCC) does NOT change. Additional steps will be needed to create a transient LULCC file.

  • questions for the land team are in red

Steps:

...

  • NOTE: The land surface generation tool is currently BROKEN in E3SM master, following addition of FAN and fertilizer mods (PR: 5981). A PR was issued to fix this by removing the unsupported FAN dataset from surfdata files, but was subsequently closed (PR: 6237). For the time being, land surface data can be generated by checking out git hash cd22d14bb8 (master immediately before 5981 was merged).

Steps:

  1. Create mapping files for each land surface type if needed. An (older and deprecated) example of doing this can be found here. Updated instructions follow:

    1. Obtain or generate a target grid file in SCRIP format. For these example, we will use a ne1024pg2 grid file, which we will need to create (note that most np4 grid files can be found within the inputdata repository, for example, the ne1024np4 grid file is at https://web.lcrc.anl.gov/public/e3sm/mapping/grids/ne1024np4_scrip_c20191023.nc). To generate the pg2 SCRIP file: 

      Code Block
      ${tempest_root}/bin/GenerateCSMesh --alt --res 1024 --file ne1024.g
${tempest_root}/bin/GenerateVolumetricMesh --in ne1024.g --out ne1024pg2.g --np 2 --uniform
${tempest_root}/bin/ConvertExodusToSCRIPConvertMeshToSCRIP --in ne1024pg2.g --out ne1024pg2_scrip.nc

    2. Get list of input grid files for each land surface input data file. This is done by running the components/elm/tools/mkmapdata/mkmapdata.sh script in debug mode to output a list of needed files (along with the commands that will be used to generate each map file; also make sure GRIDFILE is set to the SCRIP file from the above step): 

      Code Block
      languagebash
      cd ${e3sm_root}/components/elm/tools/mkmapdata
./mkmapdata.sh --gridfile ${GRIDFILE} --inputdata-path ${INPUTDATA_ROOT} --res ne1024pg2 --gridtype global --output-filetype 64bit_offset --debug -v --list

    3. Download needed input grid files. The above command will output a list of needed files to clm.input_data_list. We need to download all of these before calling the script without the debug flag to actually perform the mapping. This is possible using check_input_data in CIME, but needs to be done from a dummy case directory. So, one can create a dummy case, cd to that case, and then call ./check_input_data --data-list-dir <path where mkmapdata was run from> --download. However, this failed to connect to the CESM SVN server for me. So instead, I used the following one-off script: 

      Code Block
      #!/bin/bash
e3sm_inputdata_repository="https://web.lcrc.anl.gov/public/e3sm"
cesm_inputdata_repository="https://svn-ccsm-inputdata.cgd.ucar.edu/trunk"
inputdata_list=clm.input_data_list
cat $inputdata_list | while read line; do
    localpath=`echo ${line} | sed 's:.* = \(.*\):\1:'`
    url1=${e3sm_inputdata_repository}/`echo ${line} | sed 's:.*\(inputdata/lnd/.*\):\1:'`
    url2=${cesm_inputdata_repository}/`echo ${line} | sed 's:.*\(inputdata/lnd/.*\):\1:'`
    if [ ! -f ${localpath} ]; then
        echo "${url1} -> ${localpath}"
        mkdir -p `dirname ${localpath}`
        cd `dirname ${localpath}`
        # Try to download using first URL, if that     # Try to download using first URL, if that fails then use the second
        wget ${url1} || wget ${url2}
    else
        echo "${localpath} exists, skipping."
    fi
done

    4. Create mapping files. Should just be able to run the above mkmapdata.sh command without the –debug --list flags. We need to append the --outputfile-type 64bit_offset flag for our large files (no reason not to do this by default anyways). NOTE - This step requires NCL, which is no longer part of the E3SM unified environement. If the machine you are using does not have an NCL module, creating a custom environement that includes NCL is an easy work around. Fixing this issue to avoid the NCL dependency will require rewriting the rmdups.ncl and mkunitymap.ncl script in another language (python+xarray would make sense). We will also need to write a version of the gc_qarea() function, unless the geocat project writes a port that we can use (see geocat issue #31).

      Code Block
      ./mkmapdata.sh --gridfile ${GRIDFILE} --inputdata-path ${INPUTDATA_ROOT} --res ne1024pg2 --gridtype global --output-filetype 64bit_offset -v
    Compile surface dataset source code (NOTE: 
    1. fails then use the second
        wget ${url1} || wget ${url2}
    else
        echo "${localpath} exists, skipping."
    fi
done

    2. Create mapping files. Should just be able to run the above mkmapdata.sh command without the –debug --list flags. We need to append the --outputfile-type 64bit_offset flag for our large files (no reason not to do this by default anyways). NOTE - This step requires NCL, which is no longer part of the E3SM unified environement. If the machine you are using does not have an NCL module, creating a custom environement that includes NCL is an easy work around. Fixing this issue to avoid the NCL dependency will require rewriting the rmdups.ncl and mkunitymap.ncl script in another language (python+xarray would make sense). We will also need to write a version of the gc_qarea() function, unless the geocat project writes a port that we can use (see geocat issue #31).

      Code Block
      ./mkmapdata.sh --gridfile ${GRIDFILE} --inputdata-path ${INPUTDATA_ROOT} --res ne1024pg2 --gridtype global --output-filetype 64bit_offset -v

Notes for Perlmutter (2024) - If you come across an error using ESMF that includes “This functionality requires ESMF to be built with the PIO library enabled“ in the log file, then this means you are using a version of ESMF that is not compiled with MPI support. If using a conda env then you can check the type of build using conda list | grep esmf and look for “mpi” or “nompi” in the build tag. The ESMF library can also be problematic when creating the “HYDRO1K“ map (make sure to use the SCRIP version of that grid!). Recent attempts to create this map resulted in segmentation faults, which seem to be a problem only in recent versions. In particular, version 8.6 was found to be problematic, but rolling back to version 8.0.1 was successful.

  1. Compile surface dataset source code
    NOTE: previously, editing the makefile ${e3sm_root}/components/

...

  1. elm/tools/

...

  1. mksurfdata_map/src/Makefile.common

...

  1. was required on most machines

...

  1. , but this

...

  1. was fixed

...

  1. by https://github.com/E3SM-Project/E3SM/pull/2757):

    Code Block
    # Setup environment (should work on any E3SM-supported machine)
eval $(${e3sm_root}/cime/CIME/Tools/get_case_env)
${e3sm_root}/cime/CIME/scripts/configure --macros-format Makefile --mpilib mpi-serial
source .env_mach_specific.sh

# Build mksurfdata_map
cd ${e3sm_root}/components/elm/tools/mksurfdata_map/src
INC_NETCDF="`nf-config --includedir`" \
    LIB_NETCDF="`nc-config --libdir`" USER_FC="`nc-config --fc`

...

Note for Perlmutter (Jan 2023) - The build line above did not work on PM until it was modified as follows:

...

  1. " \
    USER_LDFLAGS="`nf-config --flibs`" make

    Note for Perlmutter (Mar 2024 - Walter Hannah) - the build worked using the command below:

    Code Block
    cd ${e3sm_root}/components/elm/tools/mksurfdata_map/src
${e3sm_root}/cime/CIME/scripts/configure && source .env_mach_specific.sh
make clean
INC_NETCDF="`nf-config --includedir`"  \
LIB_NETCDF="`nc-config --libdir`"  \
USER_FC="`nc-config --fc`"

...

  1.   \
USER_

...

  1. LDFLAGS="

...

  1. -L`nc-config -

...

  1. -

...

  1. libdir` -

...

  1. lnetcdf -

...

  1. lnetcdff" \
make


  2. Run the mksurfdata.pl script in "debug" mode to generate the namelist (use year 2010 on ne120np4 grids as an example). 

    Code Block
    # For supported resolutions
#(use year 2010 on ne120np4 grids as an example)
cd $e3sm_dir/components/elm/tools/mksurfdata_map
./mksurfdata.pl -res ne120np4 -y 2010 -d -dinlc /global/cfs/cdirs/e3sm/inputdata -usr_mapdir /global/cfs/cdirs/e3sm/inputdata/lnd/clm2/mappingdata/maps/ne120np4

# For unsupported, user-specified resolutions
# (use year 2010 on ne50np4 grid as an example)
# (Assuming the mapping files created in step 1 has a time stamp of '190409' in the filenames and the location of mapping files are '/whatever/directory/you/put/mapping/files')
./mksurfdata.pl -res usrspec -usr_gname ne50np4 -usr_gdate 190409 -y 2010 -d -dinlc /global/cfs/cdirs/e3sm/inputdata -usr_mapdir /whatever/directory/you/put/mapping/files

    (However, ./mksurfdata.pl -h shows -y is by default 2010. When running without "-y" option, standard output says sim_year 2000. I suspect the mksurfdata.pl help information is wrong. To be confirmed.)

  3. Modify namelist file
    (Should the correct namelist settings be automatically picked up if the default land build name list settings are modified accordingly?)

    Time-evolving Land use land cover change (LULCC) data should not be used for fixed-time compsets, but the LULCC information for that particular year should be used (right?)
    Manually change to mksrf_fvegtyp = '/global/cfs/cdirs/e3sm/inputdata/lnd/clm2/rawdata/AA_mksrf_landuse_rc_1850-2015_06062017_LUH2/AA_mksrf_landuse_rc_2010_06062017.nc' for the F2010 ne120 compset.

  4. Create the land surface data by interactive or batch job

    Code Block
    rm -f surfdata_ne120np4_simyr2010.bash
cat <<EOF >> surfdata_ne120np4_simyr2010.bash
#!/bin/bash

#SBATCH  --job-name=mksurfdata2010
#SBATCH  --account=acme
#SBATCH  --nodes=1
#SBATCH  --output=mksurfdata.o%j
#SBATCH  --exclusive
#SBATCH  --time=00:30:00
#SBATCH  --qos=debug

# Load modules
module load nco
module load ncl
module load cray-netcdf
module load cray-hdf5

# mksurfdata_map is dynamically linked
export LIB_NETCDF=$NETCDF_DIR/lib
export INC_NETCDF=$NETCDF_DIR/include
export USER_FC=ifort
export USER_CC=icc
export USER_LDFLAGS="-L$NETCDF_DIR/lib -lnetcdf -lnetcdff -lnetcdf_intel"
export USER_LDFLAGS=$USER_LDFLAGS" -L$HDF5_DIR/lib -lhdf5 -lhdf5_fortran -lhdf5_cpp -lhdf5_fortran_intel -lhdf5_hl_intel -lhdf5hl_fortran_intel"

cd /global/homes/t/tang30/ACME_code/MkLandSurf/components/clm/tools/clm4_5/mksurfdata_map

CDATE=c`date +%y%m%d` # current date

./mksurfdata_map < namelist
EOF

sbatch surfdata_ne120np4_simyr2010.bash

    The land surface data in NetCDF format will be created at current directory. (How to verify the file is correct?)


8. Generate a new land initial condition (finidat)

...

From the README for mkatmsrffile tool at components/cameam/tools/mkatmsrffile:

Atmospheric drydeposition at the surface depends on certain surface
properties including soil and land use properties. In most cases
these calculations can be handled in the land model and passed to he
atmosphere through the coupler. This is the default namelist setting
drydep_method='xactive_lnd'. However with modal areosols this method
is not adequate and we must recalculate these fields in the atmosphere
(see subroutine interp_map in mo_drydep.F90). For unstructured grids
it was determined to create this offline interpolation tool rather
than generalize the subroutine interp_map.

...

  1. Change directory to tool root:
    cd components/cameam/tools/mkatmsrffile

  2. Create a .env_mach_specific.sh by running
    ../../../../cime/tools/configure --macros-format=Makefile

  3. Get machine-specific environment settings via
    source .env_mach_specific.sh

  4. Make sure NETCDF_ROOT and FC environment variables are set right for your system, and build the executable:

    1. On Cori:  env NETCDF_ROOT=$NETCDF_DIR FC=ifort make

  5. Edit "nml_atmsrf" to update the input file paths

  6. Run the newly built executable


    Code Block
    ./mkatmsrffile


...

  1. TempestRemap for generating uniform grids
    (in Paul’s external git repo - may have its own tests?)

  2. SQuadGen for generating RRM grids
    (in Paul’s external repo - may have its own tests?)

  3. Generate topography via Atmospheric Topography Generation )

    1. needs utilities: components/cameam/tools/topo_tool/cube_to_target and comopnents/homme/test/tool

  4. run ncremap (an NCO command) to generate mapping files

  5. cime/tools/mapping/gen_domain_files

  6. mksurfdata.pl to generate the namelist needed to make fsurdat file

  7. use mksurfdata_map for fsurdat

  8. use the interpic_new tool to regrid atmos state to new grid for initial condition

...

  1. smoothtopo.job script used to run HOMME to apply dycore-specific smoothing to interpolated topography. It would be nice for this to be able to run via command line arguments rather than having to edit the script (which should make this easier to include in an automated workflow), and we should remove dependence on NCL since this is not guaranteed to be available.

    1. Replaced with “homme_tool”, 2020/5. see (see Atmospheric Topography Generation )

  2. makegrid.job script used to run HOMME+NCL to produce the non-optimized dualgrid and latlon descriptions of the SE grid. Again, it would be nice for this to be able to run via command line arguments rather than having to edit the script (which should make this easier to include in an automated workflow), and we should remove dependence on NCL since this is not guaranteed to be available.

    1. TR and PG2 grids make this obsolete - we now longer need the “dualgrid”.

  3. Land surface data scripts (TODO: add specifics about what needs to change here)

...