Add surface coupling design document

[andrewdnolan]

This PR adds the design document for the surface coupling within E3SM. Builds off the discussion during the Omega special topics meetings 05/06/26.

Checklist:

• Documentation:
  • Design document has been generated and added to the docs
  • Documentation has been built locally and changes look as expected
• Linting
  • Pre-commit run locally

[andrewdnolan]

I may have been a little heavy handed with the request for reviews. If you think there's someone else better suited to review, please feel free to reassign.

[xylar]

@andrewdnolan a few questions and comments to get things started.

[xylar]

Similar for salinity conversion from absolute to practical?

[andrewdnolan]

@alicebarthel can confirm and provide more details, but I believe the plan is to pass absolute salinity.

[cbegeman]

Are you thinking that each timestep we would call accumulateExportState from the timestepper?

[cbegeman]

I'm also wondering if it makes sense to have two different methods, accumulateExportState that handles the state fields and applies an average over the timesteps and accumulateExportFlux that integrates the flux over the timesteps. I'm also assuming that the flux fields are not a part of OceanState and so accumulateExportFlux would have different inputs than those given for accumulateExportState above.

[andrewdnolan]

With regards to when/where this will be called, I was not envisioning from the timestepper. I was imagining it would be called from the coupled overload to ocnRun.

The time step loop would look something like:

// fetch default OceanState, TimeStepper, and SurfaceCoupler
OceanState *DefOceanState   = OceanState::getDefault();
TimeStepper *DefTimeStepper = TimeStepper::getDefault();
SurfaceCoupler *DefSurfaceCoupler = SurfaceCoupler::getDefault();

// get coupling alarm 
Alarm *CouplingAlarm = DefTimeStepper->getCouplingAlarm();

// maybe these two should be combined (or called from each other), since they should always be called together.
DefSurfaceCoupler->importFromCoupler(....);
DefSurfaceCoupler->applyImportedState(....)'

while (Err == 0 && !(CouplingAlarm->isRinging())) {
   
   DefTimeStepper->doStep(DefOceanState, SimTime);

   DefSurfaceCoupler->accumulateExportState(....);
   
}

// if coupler tells us, force write restate stream

DefSurfaceCoupler->exportToCoupler(....);

I think what I've scoped out above matches the logic MPAS-Ocean's ocn_run_mct, see here:

https://github.com/E3SM-Project/E3SM/blob/d3a56abfd22e156a9e41d417dbdeedb6fb54d4cb/components/mpas-ocean/driver/ocn_comp_mct.F#L1173

Maybe adding this rough sketch of the run loop makes sent to add design document.

[andrewdnolan]

With regards to separate accumulateExportFlux and accumulateExportState, where flux fields are integrated and state fields are averaged, that's initially what I envisioned as well.

But after looking at ocn_export_mct, it doesn't seem like the breakdown between flux (integrated) and state (averaged) fields quite holds. Maybe I'm wrong about that, @jonbob could probably help clarify.

Either way I think the proposed accumulateExportState probably needs to renamed, since it kind of conflicts with the OceanState. Maybe we should go with something like accumulateExportFields (if we go with one single function) or accumulateExportStateFields and accumulateExportFluxFields (if we go with separate functions).

[cbegeman]

Thanks for clarifying. To me, the design doc scope could include how coupling routines will be called but you can make the call based on how you see the work being organized.