remap_restarts package

Overview

The remap_restarts package is a tool for remapping (or “regridding”) GEOS restart files to a different resolution and/or a different version of the associated model boundary conditions.

Step 1: Obtain model build and load required modules

The main script (remap_restarts.py) and the associated scripts and executables can be found in the install/bin directory of a GEOSgcm build. See the GEOSgcm wiki for help with building GEOSgcm.

To run remap_restarts.py, load the necessary modules (incl. python3) as follows:

      source g5_modules.sh           [bash]
      source g5_modules              [csh]

Step 2: Run remap_restarts.py

remap_restarts.py can be run in four different ways:

1. Use the interactive questionnaire (recommended):

      ./remap_restarts.py

The questionnaire concludes with the option to submit the remapping job. It also creates a yaml configuration file (remap_params.yaml) and a matching command line argument string (remap_restarts.CMD), which can be edited manually and used in the other two ways of running remap_restarts.py.

2. Use an existing yaml configuration file:

      ./remap_restarts.py config_file -c my_config.yaml

3. Use command line arguments:

      ./remap_restarts.py command_line -ymdh 2004041421 ...

4. Use land_only option to remap Catchment[CN] restart only:

      ./remap_restarts.py land_only

Help commands:

      ./remap_restarts.py -h
      ./remap_restarts.py config_file -h
      ./remap_restarts.py command_line -h

Additional information

Questionnaire

To create the configuration parameters, the interactive questionnaire asks a set of questions. Brief explanatory comments, pull-down menus, lists of possible answers, and/or defaults are provided as appropriate to assist the user.

To avoid unnecessary questions, the questions asked depend on the preceding answers. For example, the script asks about date/time only if the input restart directory contains restarts for multiple date/time subdirectories. Moreover, the script examines fvcore_internal_rst (if present) and extracts basic information about the horizontal resolution and number of levels.

Subsets of restarts

Subsets of restarts can be remapped separately by running:

• remap_upper.py (for atmospheric model restarts)
• remap_catchANDcn.py (for Catchment[CN] model restarts),
• remap_lake_landice_saltwater.py (for lake, landice, and [data] ocean restarts), and/or
• remap_analysis.py (for atmospheric analysis restarts).

Each of these scripts reads its configuration inputs from remap_params.yaml. See the Appendix below for a list of restart files in each subset.

Model boundary conditions

remap_restarts.py must know the model boundary conditions (BCs) associated with the input and new restart files. The script uses BCs in the revised layout (directory structure and file naming convention) introduced in late 2023. Recent and commonly used older versions of the BCs are provided in the revised layout in the following locations:

NCCS: /discover/nobackup/projects/gmao/bcs_shared/fvInput/ExtData/esm/tiles/
NAS:  /nobackup/gmao_SIteam/ModelData/bcs_shared/fvInput/ExtData/esm/tiles/

For more information on BCs, see GEOSgcm_GridComp Wiki.

History

remap_restarts.py replaces the (deprecated) legacy perl script regrid.pl. Results are binary identical when remap_restarts.py and regrid.pl are from the same build.

Note that regrid.pl uses BCs in the “legacy” layout (directory structure and file naming convention). If the BCs of interest are not available in the revised layout (see above), contact the GEOSgcm_GridComp gatekeepers for assistance.

Examples and tests

The ./tests sub-directory includes a script and several yaml configuration files that serve as examples and for use in 0-diff testing. The tests are set up for NCCS only. An overview of the tests is in the file test_remap_cases.yaml. To run the tests, source g5_modules (see above) and execute

      ./test_remap_restarts.py

The test script automatically compares the output against the archived baseline results. Individual test cases without the comparison can be run as described above, for example:

      ./remap_restarts.py config_file -c c180Toc360.yaml

(Note: The string '$NOBACKUP' in the sample file c180Toc360.yaml should be replaced manually with the user's desired output path.)

Appendix:

Fortran executables

remap_restarts.py is a python wrapper that uses helper scripts (named remap_*.py) and the following Fortran executables from a build of GEOSgcm:

   Atmospheric model: 
      fvrst.x                    interp_restarts.x       interp_restarts_bin.x

   Catchment[CN] land model: 
      mk_catchANDcnRestarts.x 

   Lake, landice, and (data) ocean: 
      SaltIntSplitter.x          mk_LakeLandiceSaltRestarts.x

   Atmospheric analysis: 
      dyn2dyn.x                  mkdrstdate.x

Subsets of restart files:

   Atmospheric model: 
      fvcore_internal_rst        moist_internal_rst      agcm_import_rst
      agcm_internal_rst          carma_internal_rst      achem_internal_rst
      geoschemchem_internal_rst  gmichem_internal_rst    gocart_internal_rst
      hemco_internal_rst         mam_internal_rst        matrix_internal_rst
      stratchem_internal_rst     pchem_internal_rst      tr_internal_rst
      ss_internal_rst            du_internal_rst         cabr_internal_rst
      cabc_internal_rst          caoc_internal_rst       ni_internal_rst
      su_internal_rst  

   Catchment[CN] land model: 
      catch_internal_rst         catchcnclm[XX]_internal_rst 

   Lake, landice, and (data) ocean: 
      lake_internal_rst          landice_internal_rst  openwater_internal_rst
      seaice_internal_rst        saltwater_internal_rst

   Atmospheric analysis: 
      [bkg]                      lcv

remap_restarts.py remaps whichever of the above restart files are present in the input restart directory.

Like regrid.pl, remap_restarts.py does not properly remap the [bkg.eta] atmospheric analysis files to the new ADAS grid. Rather, the remapping provides [bkg.eta] files on some grid. Because the ADAS can ingest [bkg.eta] files on any grid, the usual practice is to run one throw-away ADAS cycle to get the correct [bkg.eta] files.