Add hooks for overriding surface radiative fluxes seen by land and ocean models

[spencerkclark]

Description

This PR adds hooks to enable overriding the surface radiative fluxes seen by the land and ocean models following ai2cm/fv3gfs-fortran#158 in AI2's fork of FV3GFS. This document contains a description of the thought process behind this code in FV3GFS, which has been used in several studies. In short it:

• Adds fields to a new data structure (IPD_Data%OverridesFromPythonWrapper) that are meant to hold data for overriding the surface radiative fluxes (namely the downward longwave, downward shortwave, and net shortwave radiative components).
• Creates pointers in the physics driver for these fluxes, which are set to either point to the adjusted values from the radiative transfer code (i.e. how the model normally runs) or the overriding fluxes, depending on the value of the gfs_physics_nml.override_surface_radiative_fluxes namelist parameter.
• Configures the radiative flux diagnostics to reflect what the surface felt, and adds additional diagnostics for the radiative fluxes output by the radiative transfer code when they are being overridden (i.e. the _from_rrtmg fields).

Note that this PR also must be coupled with a PR to NOAA-GFDL/atmos_drivers to follow through with passing the override_surface_radiative_fluxes namelist parameter to the diagnostics initialization routine (see NOAA-GFDL/atmos_drivers#31).

@lharris4 this should be the last set of PRs needed to obtain feature parity with our wrapper of FV3GFS. Since this does something science-related, I'm guessing it may require a more careful review.

How Has This Been Tested?

These changes have been tested in ai2cm/SHiELD-wrapper#5. There we test that overriding the fluxes changes the solution of the model, and that the diagnostics are updated as expected based on the overridden values. As expected, the answers for the model also do not change in configurations where gfs_physics_nml.override_surface_radiative_fluxes is .false. (the default).

Checklist:
Please check all whether they apply or not

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

[lharris4]

I agree with @bensonr. I think that using the existing Coupler type or a new override data type would be cleaner and avoids needing to change the FV3 state.

[spencerkclark]

Sounds good @lharris4. I'll pick this back up next week.

[spencerkclark]

@lharris4 @bensonr I went ahead and created a new type to hold this unusual fortran state called GFS_overrides_from_python_wrapper, and added some additional context in a comment.

For good measure I also made sure to use these potentially overridden values when assigning state to the Coupling type and state passed to the mixed layer ocean model (42dda21). These were areas that we did not worry about or did not exist in FV3GFS, but it seems like behavior one would want in such configurations.

The model compiles and the tests pass in ai2cm/SHiELD-wrapper#5 with these code updates. Things should be ready for re-review.

[lharris4]

Thanks so much for putting this together so quickly and doing such thorough testing. I don't see any problems with your code. I just have a couple of minor cosmetic suggestions and a few things I would be interested in making sure I understand correctly (hence 'minor revisions').

[spencerkclark]

Thanks @lharris4 and @bensonr for the review. I'll push some updates shortly.

[spencerkclark]

I think this should be ready for re-review. Spurred on by #31 (comment) and #31 (comment) I have refactored the diagnostics related code to always use the existing diagnostics buckets (fluxr, dlwsfci and the like) for RRTMG-related data, and always use newly added _override buckets for data from the overrides. This should hopefully make things a little more readable than before, where I was sometimes using existing buckets for overrides and sometimes not. I have addressed the other comments following my inline responses above.

[bensonr]

Thanks for making the suggested changes and adding appropriate comments. The logic behind the overrides is now easy to follow.

[lharris4]

Thanks for putting in the extra effort to answer my many questions. I think this is good to go.

[spencerkclark]

Excellent, thanks @lharris4! Should we be good to merge this and the related NOAA-GFDL/atmos_drivers#31 now?

[lharris4]

Glad to help :-) I think it should be good but I will defer to Rusty's team for the final word on the driver modifications.

…

On Wed, Nov 1, 2023 at 8:51 AM Spencer Clark ***@***.***> wrote: Excellent, thanks @lharris4 <https://github.com/lharris4>! Should we be good to merge this and the related NOAA-GFDL/atmos_drivers#31 <NOAA-GFDL/atmos_drivers#31> now? — Reply to this email directly, view it on GitHub <#31 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMUQRVF4J6K2CMTGN5TMF5TYCJAWRAVCNFSM6AAAAAA6I7XSMGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTOOBYHEYDGOJVGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>