Add river routing grid comp

[weiyuan-jiang]

Add river routing module. Replaces #131

If river routing grid comp is added, its checkpoint should be renamed and backed up.

Related PRs:
GEOS-ESM/GEOSgcm_GridComp#1143
GEOS-ESM/GEOSldas#850

Testing:

• Standard nightly 0-diff tests.
• Compare simulation (with routing) that has only land tiles with another simulation (with routing) that also has landice tiles (in addition to land tiles). The land and routing outputs for the two simulations should be zero-diff.

Left for another PR:

• enable ensemble functionality for routing
• enable routing of runoff from landice tiles

[github-actions]

This PR is being prevented from merging because you have added one of our blocking labels: Contingent - DNA, Needs Lead Approval, Contingent -- Do Not Approve. You'll need to remove it before this PR can be merged.

[gmao-rreichle]

@weiyuan-jiang, @zyj8881357 : When we add River Routing to GEOSlas, I would expect that we also modify the HISTORY template (GEOSldas_HIST.rc), as well as at least one config parameters that turns routing on/off (and possibly more). Do you have a list of what is still missing from this PR?

[weiyuan-jiang]

1. We need to find the permanent place for the BCS required by river-routing
2. We need this PR be approved ( Add river routing module for offline (GEOSldas) simulations GEOSgcm_GridComp#1143 ). Maybe we should integrate make_bcs with the scripts Yujin provided to create river-routing BCs and move them to the appropriate directories
3. Change this PR accordingly

[zyj8881357]

@weiyuan-jiang, @zyj8881357 : When we add River Routing to GEOSlas, I would expect that we also modify the HISTORY template (GEOSldas_HIST.rc), as well as at least one config parameters that turns routing on/off (and possibly more). Do you have a list of what is still missing from this PR?

We already have a option called RUN_ROUTE in our LDAS.rc that turns routing on/off (1/0) which also appears in our "exe"_input_filename template. I think we can continue to use this one (that is what we did in the PR).

If you'd like, we can add an option to turn on/off the reservoirs/lakes, but in my view, we don't need to do that because the reservoirs/lakes make the overall simulation better and we can keep less parameters in the config list.

[zyj8881357]

@weiyuan-jiang, @zyj8881357 : When we add River Routing to GEOSlas, I would expect that we also modify the HISTORY template (GEOSldas_HIST.rc), as well as at least one config parameters that turns routing on/off (and possibly more). Do you have a list of what is still missing from this PR?

In addition to what Weiyuan mentioned, we also need a place to store the raw input data for the pre-processing package that converts the raw data to the file "river_input.nc" that would be used by the make_bcs.

But maybe this can be done later because any changes in the make_bcs and routing model may affect the pre-processing package. We can first finalize the routing_model and make_bcs, and then work on the pre-processing package.

[gmao-rreichle]

@weiyuan-jiang, @zyj8881357 : This line suggests that the routing model could be set up with LDAS in ensemble mode. The same seems to be true for the landice model (see preceding block). However, the ensemble GridComp appears to be exclusively in the (non-glaciated) land tile space. Since the land, landice, and routing GridComps each work in different tile spaces, do we need to overhaul the ensemble GridComp to make the ensemble functionality work for routing and/or landice? I wonder how long it might take to do that. In the meantime, we could perhaps add a "stop" if NUM_ENSEMBLE>1 .and. (with_landice .or. RUN_ROUTE>0); that is, turn off the ensemble functionality unless the simulation includes only land tiles. Please advise, thanks

[zyj8881357]

"stop if NUM_ENSEMBLE>1 .and. (with_landice .or. RUN_ROUTE>0)" has been added.

[weiyuan-jiang]

This line will be changed

GEOSldas_GridComp/GEOSldas_App/ldas.py

Line 1007 in 211cb1d

routeRstFile = "/discover/nobackup/yzeng3/data/river_input_weiyuan/route_restart_package/"+"route_internal_rst."+y4m2[-2:]+"01_0000"

[gmao-rreichle]

@zyj8881357, @weiyuan-jiang : The standard routing configuration in GEOSldas uses a 1-hour time step for routing (RRM_DT: 3600 in GEOS_SurfaceGridComp.rc) and a heartbeat of 7.5 minutes. Do we have the following "assert" statements somewhere in the routing GC or in LDAS?

• assert that RRM_DT is a multiple of HEARTBEAT
• assert that segment length >= RRM_DT (a simulation with routing must complete at least one RRM_DT time step)

There may be other requirements that need to be verified.