initial Interfacer cleanup

[juliasloan25]

Purpose

First steps of Interfacer cleanup. Some of it (e.g. restructuring) will be done in separate PRs so this one doesn't get too big.

closes #339

To-do

Content

get_field

• add get_field(surfacestub, :air_density)
• remove get_field(atmossim, :cv_m) and get_field(atmossim, :gas_constant_air)
• get_field, update_field: implement default for each variable we expect, output warning with maxlog = 1 for each
• alphabetize get_field and update_field functions for readability

surfacestub

• add stub_init function (just wrap SurfaceStub constructor)

renaming variables

• rename co2_gm -> co2 (explain in docs global mean)
• rename albedo -> surface_albedo (atmos update_field, surfaces get_field)
• rename clean_sst, clean_sic -> scale_sst, scale_sic
• rename get_model_state_vector -> get_model_prog_state

restructuring

• differentiate_turbulent_fluxes: dispatch on eisenman sea ice type, move to eisenman file (specific to that model)

docs

• note that update_field(::atmossim, turbulent_fluxes) required for partitionedfluxes option
• note: update_sim! can be optionally overwritten, but not required
• update_turb_fluxes_point required for surface model if using partitioned sf
• get_model_state_vector required for checkpointing
• note in docs: surface model precip only needs update, get not required
• explain that CO2 from atmos is expected to be global mean
• add units to docs

QA

• test update_field! warnings
• check docs rendering

To Do in future PRs

• component model files: rename each to <model>.jl, combine bucket_init and bucket_utils -> bucket.jl; separate required vs model-specific (internal) functions and objects in component model files - see restructure component models #647
• separate surfacestub from Interfacer/FieldExchanger move SurfaceStub to its own file #669
  • move surfacestub to separate file outside of Interfacer.jl, and include from Interfacer.jl so it's still in that module
  • same for FieldExchanger.jl

Remaining questions

• to run with partitioned fluxes, does the atmos model need to extend update_turbulent_fluxes_point? or just surface models as it is currently?
  • No, update_turbulent_fluxes_point is called by surface models only. Once the surfaces are updated and fluxes per each fractional surface calculated, the coupler combines the fluxes so that we have one flux value per atmos grid point, and we update atmos in the same way as for the CombinedStateFluxes. I will work on the flux calculation interface in a few weeks, with the aim of making this function more transparent and performant. :)
• Are fields in component models (e.g. those returned by get_field) expected to be 2d or just individual floats? Does it vary e.g. for surface albedo vs co2 global mean? (might want to clarify in docs)
  • We should be able to handle both, and (for now) co2 stays constant in space and variable in time.

---

• I have read and checked the items on the review checklist.

[LenkaNovak]

This looks great, Julia, thank you! I left a few comments. If you need help with any of TODOs, let me know once everything else is good to go and I can add the remaining info.