Add river-ocean two-way coupling feature

[fdongyu]

This development implements the river-ocean two-way coupling. This feature is turned off by default in our development and can be turned on by setting use_lnd_rof_two_way=.true. in user_nl_mosart. All e3sm_developer test suites passed.

This new feature enables two-way coupling between MPAS-O and MOSART. The water fluxes from MOSART to MPAS-O are treated the same as previously. The MPAS-O simulated sea surface height (ssh) time series are remapped to the MOSART outlet cells and are used as the downstream, dynamic water stage boundary of the specified outlets, which will further propagate to the upstream rivers. The two-way coupling is only configured for MOSART outlets specified by ocn_rof_coupling_ID=1 in the MOSART parameter input file (frivinp_rtm), while the other outlets in the model domain (ocn_rof_coupling_ID=0) are still one-way coupled. Another parameter in frivinp_rtm, vdatum_conversion, is also required to normalize the MPAS-O modeled ssh to MOSART water depth based on local river geometry.

[liho745]

The title/description of this PR can be revised to be more accurate. Since the ocean is only invoked as the boundary condition to the river, what'd done is here not strictly "two-way" coupling, but rather something like "effects of sea surface height changes on river dynamics". In my understanding, a real "two-way" coupling means both MPAS and MOSART run together and exchange fluxes in each coupling time step.

[fdongyu]

The title/description of this PR can be revised to be more accurate. Since the ocean is only invoked as the boundary condition to the river, what'd done is here not strictly "two-way" coupling, but rather something like "effects of sea surface height changes on river dynamics". In my understanding, a real "two-way" coupling means both MPAS and MOSART run together and exchange fluxes in each coupling time step.

I think this confusion may be due to the aforementioned manuscript, in which MPAS-O is not running together with MOSART. This manuscript is only used to demonstrate the advantage of creating a downstream boundary in MOSART and does not strictly implement the two-way coupling because the MPAS-O simulated sea surface height is not accurate enough. This branch, on the other hand, enables MOSART and MPAS-O running simultaneously and exchanging information through the coupler, i.e., at each coupling time step, MOSART uses the updated sea surface height from MPAS-O. It may be appropriate to still name this PR as river-ocean two-way coupling since a majority of code modifications are made in the coupler.

[liho745]

@fdongyu Thanks for the explanation. Could you further revise the PR description to 1) revise the part mentioning routingmethod since you've made the change in RtmMod.F90, 2) add a bit more details on what you mean by two-way coupling, e.g., something like "Adding two-way coupling between MPAS-O and MOSART. The water fluxes from MOSART to MPAS-O are still treated the same as previously. The MPAS-O simulated sea surface height (ssh) time series are remapped to the MOSART outlet cells and used as the downstream, dynamic water stage boundary of the specified outlets, which will further propagate to the upstream rivers...", 3) perhaps you don't need to mention the ICoM project or your manuscript here?

[fdongyu]

@fdongyu Thanks for the explanation. Could you further revise the PR description to 1) revise the part mentioning routingmethod since you've made the change in RtmMod.F90, 2) add a bit more details on what you mean by two-way coupling, e.g., something like "Adding two-way coupling between MPAS-O and MOSART. The water fluxes from MOSART to MPAS-O are still treated the same as previously. The MPAS-O simulated sea surface height (ssh) time series are remapped to the MOSART outlet cells and is used as the downstream, dynamic water stage boundary of the specified outlets, which will further propagate to the upstream rivers...", 3) perhaps you don't need to mention the ICoM project or your manuscript here?

Thanks @liho745, the description was edited accordingly.

[fdongyu]

@fdongyu, Use a namelist variable in the driver instead of the MOSART to determine if the two-way coupling is turned on. If the two-way coupling is on:

• Send ssh from the ocean to the coupler
• In MOSART, use index_x2r_So_ssh > 0 to figure out if the two-way coupling is turned on.

@donghuix made a similar change in PR #5017 in 715e501

Thanks, @bishtgautam. Modifications were made accordingly and all tests passed.

[bishtgautam]

@fdongyu Thanks for making edits. I think the many conflicts of this PR are due to the merge of @donghuix's recent PR. Can you now try to rebase your branch to avoid conflicts?

[fdongyu]

@fdongyu Thanks for making edits. I think the many conflicts of this PR are due to the merge of @donghuix's recent PR. Can you now try to rebase your branch to avoid conflicts?

@bishtgautam, this branch is now rebased to Donghui's recent PR. The conflicts are resolved and all developer tests passed too.

[jonbob]

@rljacob, @ambrad - are you OK with the resolution we came up with? I'd like to get this merged soon

[ambrad]

Hi @jonbob I think I'm on the reviewer list just b/c I made a comment at some point. You don't need to wait for my approval. I can't seem to take myself off the list.

[jonbob]

Thanks @ambrad -- sounds good

[jonbob]

Passes:

• ERS.ne11_oQU240.WCYCL1850NS.chrysalis_intel
• SMS_D_Ld1.ne30pg2_r05_EC30to60E2r2.WCYCL1850.chrysalis_intel
• PEM_Ln9.ne30pg2_EC30to60E2r2.WCYCL1850.chrysalis_intel with expected NML DIFFs

merged to next

[jonbob]

merged to master and expected NML DIFFs blessed, as well as new baselines requested for added test