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 (merged)
GEOS-ESM/GEOSgcm_GridComp#1375 (merged)
GEOS-ESM/GEOSldas#850

Testing:

• Standard nightly 0-diff tests completed by @biljanaorescanin on 3 May 2026 (Update pre-processing package for routing model GEOSgcm_GridComp#1375 (comment))
• Two simulations (with routing) with and without landice tiles were compared and found to be zero-diff for land and routing outputs by @zyj8881357 on 21 April 2026.
• New routing functionality tested again by @zyj8881357 on 3 May 2026 (Add river routing grid comp #145 (comment)).

Left for another PR:

• enable ensemble functionality for routing (see 6ea9bbf)
• enable routing of runoff from landice tiles

[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.

[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.

[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"

@zyj8881357 Is the line ready for change?

[zyj8881357]

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"

@zyj8881357 Is the line ready for change?

@weiyuan-jiang Yes. The path is /discover/nobackup/projects/gmao/bcs_shared/restarts/surface/route/v202601/ . Could you please help me to update it in the code? I am not familiar with the string variable for dir "/discover/nobackup/projects/gmao/bcs_shared/" in the script. Thank you!

[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"

@zyj8881357 Is the line ready for change?

@weiyuan-jiang Yes. The path is /discover/nobackup/projects/gmao/bcs_shared/restarts/surface/route/v202601/ . Could you please help me to update it in the code? I am not familiar with the string variable for dir "/discover/nobackup/projects/gmao/bcs_shared/" in the script. Thank you!

I realized that we don't support RESTART=0 any more. I removed it and gave users a hint

[gmao-rreichle]

@weiyuan-jiang @zyj8881357 , see comments below

[zyj8881357]

• 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.

I have done this test. The runs with and without landice tiles are zero-diff for land and route.

[gmao-rreichle]

@zyj8881357 @biljanaorescanin
I think the current routing PRs are now ready for final testing:
GEOS-ESM/GEOSgcm_GridComp#1375
#145 (this PR)
GEOS-ESM/GEOSldas#850

@biljanaorescanin : When you get a chance, please run the usual 0-diff tests for LDAS and the GCM

@zyj8881357 : Please do one more check of a routing simulation with the latest GEOSgcm_GridComp and GEOSldas_GridComp branches.

cc: @weiyuan-jiang

[zyj8881357]

@zyj8881357 @biljanaorescanin I think the current routing PRs are now ready for final testing: GEOS-ESM/GEOSgcm_GridComp#1375 #145 (this PR) GEOS-ESM/GEOSldas#850

@biljanaorescanin : When you get a chance, please run the usual 0-diff tests for LDAS and the GCM

@zyj8881357 : Please do one more check of a routing simulation with the latest GEOSgcm_GridComp and GEOSldas_GridComp branches.

cc: @weiyuan-jiang

@gmao-rreichle I have finished both the zero-diff and scientific test with the latest GEOSgcm_GridComp and GEOSldas_GridComp branches. They work well and can produce reasonable discharge output against with the observations.