Add river routing module for offline (GEOSldas) simulations

[weiyuan-jiang]

Add river routing module for offline land modeling (GEOSldas). Replaces #1023

Successfully 0-diff tested by @biljanaorescanin on 10-Apr-2026 #1143 (comment)

Merged branch of #1149 into present PR to resolve anticipated conflict when merging present PR after #1149 (9d1a15f)

---

Left for future PRs:

• Run routing module within the AGCM and coupled model (AOGCM).
• Run only the routing module (but not Catchment) in GEOSldas.
• Include landice tiles in routing (GEOSldas and GCM).

Related PRs:

• Add river-routing restart assembling GEOS_Util#170
• Add river routing GEOSldas#850
• Add river routing grid comp GEOSldas_GridComp#145
• added pfaf index to MAPL_Locstream MAPL#4000 (merged 5 Dec 2025; included in MAPL v2.64)

---

Testing:

• TBD

---

List of tasks that remain to be addressed (in no particular order):

• Move Routing GC from Land GC to Surface GC (@weiyuan-jiang)
• Make sure Routing works when GEOSldas is run in cube-sphere tile space (@weiyuan-jiang, @zyj8881357)
• Add routing parameters into Route GC restart files (similar to, say, porosity in Catch restart) (@zyj8881357)
• Clean up files in Utils/Raster/preproc/routing_model/ (@zyj8881357)
• Remove GEOSroute_GridComp/offline/ and save files elsewhere (for reference when we address the option to run only the routing module but not Catchment in GEOSldas) (@zyj8881357)
• Add files from bcs preprocessing (river_inputs.bc, cell_area.nc?) into shared bcs directory and update location of these inputs in make_bcs scripts (@biljanaorescanin, @zyj8881357)
• What (if anything) is needed for river routing in Utils/remap_restart? (@weiyuan-jiang, @zyj8881357) Add river-routing restart assembling GEOS_Util#170

---

@YujiN, I am trying to bring back some codes in develop branch. The develop branch is not working as it is but I believe it would be more efficient. The runoff and the other variables are distributed as needed, which is way more efficient than allgatherV.

[zyj8881357]

@gmao-rreichle @weiyuan-jiang I have modified the routing model code to make it read the *.nc4 tile files.

[gmao-rreichle]

@zyj8881357 , @weiyuan-jiang : Sorry it took me so long to pick up the routing PR again. I have a few more cleanup questions, see below.
Merging the PR has gained some urgency because the SI team is planning to make relatively invasive changes across all GridComp F90 files under Surface. These changes will result in lots of conflicts with the present PR. Ideally, we can merge the present PR before the SI team makes their changes.

[gmao-rreichle]

@zyj8881357 :
Thanks for making the changes. I went through and resolved conversations when possible. I further cleaned up the module names for the outlets and routing constants. Note that there was a naming conflict after your most recent change, when both modules were named "routing_constant".
Here's a list of open issues:

1. Please try simulations for (i) a non-global domain on the EASE grid and (ii) a domain that includes landice tiles. Weiyuan isn't sure that the new *-Pfafstetter tile file for EASE works with non-global domains (#1143 (comment)), and I'm not sure if we ever tested a simulation with landice tiles.
2. Biljana mentioned you gave her a new routing_parameter.nc file. Are the new parameters based on SMAP NRv11.4? (#1143 (comment))
3. The program get_num_sub_catchment.f90 doesn't seem to use the info from the *-Pfafstetter tile file. Instead, it looks to me like it compute things from scratch based on raster information. What exactly do we need this program to do, and can it be done more cleanly using the *-Pfafstetter tile file?

cc: @weiyuan-jiang

[biljanaorescanin]

Testing summary:

1. PR was tested for one day AMIP, REPLAY and No Inc. REPLAY all were zero diff.
2. PR also passes regression test.

During testing besides this branch/PR I used:

Component	Current Tag	Target/Branch
GEOS_Util	(t) v2.1.12 (DH)	(b) main
MAPL	(t) v2.67.0 (DH)	(t) v2.68.0 (DH)