Hybrid channel routing with two options: flux exchanges simultaneously or sequentially

[kumdonoaa]

Until now, the MC and reservoir modules have been running on the same simulation time steps, allowing for the exchange of flow between the two modules at each time step during runtime. However, the diffusive module has been running for the entire simulation period without exchanging flow or depth with the MC and reservoir modules during this time. In other words, the diffusive module can only run after the simultaneous execution of the MC and reservoir modules has been completed.

This PR introduces a functionality that allows the diffusive module to run on the same simulation time steps as the MC and reservoir modules, enabling simultaneous flux exchange between MC and diffusive modules or diffusive and reservoir modules. It achieves this by creating a standalone module for generating hydraulic lookup tables of channel cross sections and a lightweight diffusive kernel that operates from the start to the end of the common simulation time interval.

Update1:
While this functionality enables simultaneous flux exchanges among different routing domains, it increases compute time due to the feedback loop that occurs at each time step between the domains. To address this, a new functionality was added to reduce compute time by running one domain (e.g., the MC domain) completely for the entire simulation period, and then running the other domain (e.g., the Diffusive domain) for the same period. This approach ensures that the results from the Diffusive or MC domain are correctly passed to the downstream domain during runtime, optimizing performance while maintaining accuracy. As a result, the compute time of this new hybrid routing functionality is nearly the same as the current approach of running the MC and reservoir modules together, followed by the diffusive module.

Additions

To activate the hybrid routing, 'parallel_compute_method' = serial-hybrid-routing and 'compute_kernel' = V02-structured-hybrid-routing in the config yaml file

Removals

Changes

Testing

1. The flow and water depth results obtained using diffusive.f90 (run for the entire simulation period) were compared with those from diffusive_lightweight.f90 (run only for the same time steps as the MC or reservoir module). This comparison was conducted on a simple, small channel network domain, Cedar Bayou. The flow and water depth values computed at the tailwater of the diffusive domain for both cases are plotted here, showing identical results in the figures.
   In the legend, 'MC and then diffusive' refers to the use of diffusive.f90 with parallel_compute_method set to 'serial' and compute_kernel set to 'V02-structured', while 'hybrid_routing' represents the use of diffusive_lightweight.f90 with parallel_compute_method set to 'serial-hybrid-routing' and compute_kernel set to 'V02-structured-hybrid-routing' in the configuration YAML file.

Screenshots

Notes

Todos

Checklist

• PR has an informative and human-readable title
• Changes are limited to a single goal (no scope creep)
• Code can be automatically merged (no conflicts)
• Code follows project standards (link if applicable)
• Passes all existing automated tests
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future todos are captured in comments
• Visually tested in supported browsers and devices (see checklist below 👇)
• Project documentation has been updated (including the "Unreleased" section of the CHANGELOG)
• Reviewers requested with the Reviewers tool ➡️

Testing checklist

Target Environment support

• Windows
• Linux
• Browser

Accessibility

• Keyboard friendly
• Screen reader friendly

Other

• Is useable without CSS
• Is useable without JS
• Flexible from small to large screens
• No linting errors or warnings
• JavaScript tests are passing