unify surface variable naming

juliasloan25 · juliasloan25 · commit 0a025793d0de · 2025-02-14T13:22:16.000-08:00
diff --git a/NEWS.md b/NEWS.md
@@ -6,6 +6,10 @@ ClimaCoupler.jl Release Notes
 
 ### ClimaCoupler features
 
+### Coupler fields surface variable names all use `_sfc` PR[#1195](https://github.com/CliMA/ClimaCoupler.jl/pull/1195)
+`T_S`, `z0m_S`, and `z0b_S` are renamed to `T_sfc`, `z0m_sfc`, and `z0b_sfc`.
+This makes them consistent with the other surface fields, e.g. `ρ_sfc` and `q_sfc`.
+
 #### Driver function `setup_and_run` added PR[#1178](https://github.com/CliMA/ClimaCoupler.jl/pull/1178)
 A new function `setup_and_run` is added, which takes in a path to a config file,
 and contains all the code to initialize component models and run the simulation.
diff --git a/docs/src/interfacer.md b/docs/src/interfacer.md
@@ -106,7 +106,7 @@ following properties:
 | `surface_temperature` | temperature over the combined surface space | K |
 | `turbulent_fluxes` | turbulent fluxes (note: only required when using `PartitionedStateFluxes` option - see our `FluxCalculator` module docs for more information) | W m^-2 |
 
-- `calculate_surface_air_density(atmos_sim::Interfacer.AtmosModelSimulation, T_S::ClimaCore.Fields.Field)`:
+- `calculate_surface_air_density(atmos_sim::Interfacer.AtmosModelSimulation, T_sfc::ClimaCore.Fields.Field)`:
 A function to return the air density of the atmosphere simulation
 extrapolated to the surface, with units of [kg m^-3].
 
diff --git a/experiments/ClimaEarth/components/atmosphere/climaatmos.jl b/experiments/ClimaEarth/components/atmosphere/climaatmos.jl
@@ -190,7 +190,7 @@ function Interfacer.update_field!(sim::ClimaAtmosSimulation, ::Val{:surface_temp
     # note that this field is also being updated internally by the surface thermo state in ClimaAtmos
     # if turbulent fluxes are calculated, to ensure consistency. In case the turbulent fluxes are not
     # calculated, we update the field here.
-    sim.integrator.p.radiation.rrtmgp_model.surface_temperature .= CC.Fields.field2array(csf.T_S)
+    sim.integrator.p.radiation.rrtmgp_model.surface_temperature .= CC.Fields.field2array(csf.T_sfc)
 end
 # extensions required by FluxCalculator (partitioned fluxes)
 Interfacer.get_field(sim::ClimaAtmosSimulation, ::Val{:height_int}) =
@@ -272,14 +272,14 @@ function FieldExchanger.update_sim!(atmos_sim::ClimaAtmosSimulation, csf, turbul
 end
 
 """
-    FluxCalculator.calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_S::CC.Fields.Field)
+    FluxCalculator.calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_sfc::CC.Fields.Field)
 
 Extension for this function to calculate surface density.
 """
-function FluxCalculator.calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_S::CC.Fields.Field)
+function FluxCalculator.calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_sfc::CC.Fields.Field)
     thermo_params = get_thermo_params(atmos_sim)
     ts_int = Interfacer.get_field(atmos_sim, Val(:thermo_state_int))
-    FluxCalculator.extrapolate_ρ_to_sfc.(Ref(thermo_params), ts_int, Utilities.swap_space!(axes(ts_int.ρ), T_S))
+    FluxCalculator.extrapolate_ρ_to_sfc.(Ref(thermo_params), ts_int, Utilities.swap_space!(axes(ts_int.ρ), T_sfc))
 end
 
 # FluxCalculator.get_surface_params required by FluxCalculator (partitioned fluxes)
@@ -412,9 +412,9 @@ Returns a new `p` with the updated surface conditions.
 """
 function get_new_cache(atmos_sim::ClimaAtmosSimulation, csf)
     if hasmoisture(atmos_sim.integrator)
-        csf_sfc = (csf.T_S, csf.z0m_S, csf.z0b_S, csf.beta, csf.q_sfc)
+        csf_sfc = (csf.T_sfc, csf.z0m_sfc, csf.z0b_sfc, csf.beta, csf.q_sfc)
     else
-        csf_sfc = (csf.T_S, csf.z0m_S, csf.z0b_S, csf.beta)
+        csf_sfc = (csf.T_sfc, csf.z0m_sfc, csf.z0b_sfc, csf.beta)
     end
 
     p = atmos_sim.integrator.p
@@ -438,8 +438,8 @@ trigger flux calculation during Atmos `Interfacer.step!`. We only want to trigge
 timestep from ClimaCoupler.
 
 For debigging atmos, we can set the following atmos defaults:
- csf.z0m_S .= 1.0e-5
- csf.z0b_S .= 1.0e-5
+ csf.z0m_sfc .= 1.0e-5
+ csf.z0b_sfc .= 1.0e-5
  csf.beta .= 1
  csf = merge(csf, (;q_sfc = nothing))
 """
diff --git a/experiments/ClimaEarth/run_cloudless_aquaplanet.jl b/experiments/ClimaEarth/run_cloudless_aquaplanet.jl
@@ -173,9 +173,9 @@ ocean_sim = SlabOceanSimulation(
 
 ## coupler exchange fields
 coupler_field_names = (
-    :T_S,
-    :z0m_S,
-    :z0b_S,
+    :T_sfc,
+    :z0m_sfc,
+    :z0b_sfc,
     :ρ_sfc,
     :q_sfc,
     :surface_direct_albedo,
diff --git a/experiments/ClimaEarth/run_cloudy_aquaplanet.jl b/experiments/ClimaEarth/run_cloudy_aquaplanet.jl
@@ -196,9 +196,9 @@ ocean_sim = SlabOceanSimulation(
 
 ## coupler exchange fields
 coupler_field_names = (
-    :T_S,
-    :z0m_S,
-    :z0b_S,
+    :T_sfc,
+    :z0m_sfc,
+    :z0b_sfc,
     :ρ_sfc,
     :q_sfc,
     :surface_direct_albedo,
diff --git a/experiments/ClimaEarth/run_cloudy_slabplanet.jl b/experiments/ClimaEarth/run_cloudy_slabplanet.jl
@@ -240,9 +240,9 @@ ocean_sim = SlabOceanSimulation(
 
 ## coupler exchange fields
 coupler_field_names = (
-    :T_S,
-    :z0m_S,
-    :z0b_S,
+    :T_sfc,
+    :z0m_sfc,
+    :z0b_sfc,
     :ρ_sfc,
     :q_sfc,
     :surface_direct_albedo,
diff --git a/experiments/ClimaEarth/run_dry_held_suarez.jl b/experiments/ClimaEarth/run_dry_held_suarez.jl
@@ -142,9 +142,9 @@ boundary_space = ClimaCore.Spaces.horizontal_space(atmos_sim.domain.face_space)
 
 ## coupler exchange fields
 coupler_field_names = (
-    :T_S,
-    :z0m_S,
-    :z0b_S,
+    :T_sfc,
+    :z0m_sfc,
+    :z0b_sfc,
     :ρ_sfc,
     :q_sfc,
     :surface_direct_albedo,
diff --git a/experiments/ClimaEarth/run_moist_held_suarez.jl b/experiments/ClimaEarth/run_moist_held_suarez.jl
@@ -178,9 +178,9 @@ ocean_sim = Interfacer.SurfaceStub((;
 
 ## coupler exchange fields
 coupler_field_names = (
-    :T_S,
-    :z0m_S,
-    :z0b_S,
+    :T_sfc,
+    :z0m_sfc,
+    :z0b_sfc,
     :ρ_sfc,
     :q_sfc,
     :surface_direct_albedo,
diff --git a/experiments/ClimaEarth/setup_run.jl b/experiments/ClimaEarth/setup_run.jl
@@ -458,9 +458,9 @@ function setup_and_run(config_file = joinpath(pkgdir(ClimaCoupler), "config/ci_c
 
     ## coupler exchange fields
     coupler_field_names = (
-        :T_S,
-        :z0m_S,
-        :z0b_S,
+        :T_sfc,
+        :z0m_sfc,
+        :z0b_sfc,
         :ρ_sfc,
         :q_sfc,
         :surface_direct_albedo,
diff --git a/experiments/ClimaEarth/test/debug_plots_tests.jl b/experiments/ClimaEarth/test/debug_plots_tests.jl
@@ -45,12 +45,12 @@ plot_field_names(sim::Interfacer.SurfaceStub) = (:stub_field,)
         :F_turb_ρτyz,
         :P_liq,
         :P_snow,
-        :T_S,
+        :T_sfc,
         :ρ_sfc,
         :q_sfc,
         :beta,
-        :z0b_S,
-        :z0m_S,
+        :z0b_sfc,
+        :z0m_sfc,
         :radiative_energy_flux_toa,
     )
     atmos_names = (:atmos_field,)
diff --git a/experiments/ClimaEarth/user_io/debug_plots.jl b/experiments/ClimaEarth/user_io/debug_plots.jl
@@ -113,12 +113,12 @@ function debug(cs_fields::NamedTuple, dir, cs_fields_ref = nothing)
         :F_turb_ρτyz,
         :P_liq,
         :P_snow,
-        :T_S,
+        :T_sfc,
         :ρ_sfc,
         :q_sfc,
         :beta,
-        :z0b_S,
-        :z0m_S,
+        :z0b_sfc,
+        :z0m_sfc,
         :radiative_energy_flux_toa,
     )
     fig = Makie.Figure(size = (1500, 800))
diff --git a/src/FieldExchanger.jl b/src/FieldExchanger.jl
@@ -76,7 +76,7 @@ function import_atmos_fields!(csf, model_sims, boundary_space, turbulent_fluxes)
     end
 
     # surface density - needed for q_sat and requires atmos and sfc states, so it is calculated and saved in the coupler
-    dummmy_remap!(csf.ρ_sfc, FluxCalculator.calculate_surface_air_density(atmos_sim, csf.T_S)) # TODO: generalize for PartitionedStateFluxes (#445) (use individual T_S)
+    dummmy_remap!(csf.ρ_sfc, FluxCalculator.calculate_surface_air_density(atmos_sim, csf.T_sfc)) # TODO: generalize for PartitionedStateFluxes (#445) (use individual T_sfc)
 
     # radiative fluxes
     dummmy_remap!(csf.F_radiative, Interfacer.get_field(atmos_sim, Val(:radiative_energy_flux_sfc)))
@@ -105,7 +105,7 @@ function import_combined_surface_fields!(csf, model_sims, turbulent_fluxes)
 
     # surface fields
     combine_surfaces!(combined_field, model_sims, Val(:surface_temperature))
-    dummmy_remap!(csf.T_S, combined_field)
+    dummmy_remap!(csf.T_sfc, combined_field)
 
     combine_surfaces!(combined_field, model_sims, Val(:surface_direct_albedo))
     dummmy_remap!(csf.surface_direct_albedo, combined_field)
@@ -115,10 +115,10 @@ function import_combined_surface_fields!(csf, model_sims, turbulent_fluxes)
 
     if turbulent_fluxes isa FluxCalculator.CombinedStateFluxesMOST
         combine_surfaces!(combined_field, model_sims, Val(:roughness_momentum))
-        dummmy_remap!(csf.z0m_S, combined_field)
+        dummmy_remap!(csf.z0m_sfc, combined_field)
 
         combine_surfaces!(combined_field, model_sims, Val(:roughness_buoyancy))
-        dummmy_remap!(csf.z0b_S, combined_field)
+        dummmy_remap!(csf.z0b_sfc, combined_field)
 
         combine_surfaces!(combined_field, model_sims, Val(:beta))
         dummmy_remap!(csf.beta, combined_field)
@@ -142,11 +142,11 @@ function update_sim!(atmos_sim::Interfacer.AtmosModelSimulation, csf, turbulent_
 
     Interfacer.update_field!(atmos_sim, Val(:surface_direct_albedo), csf.surface_direct_albedo)
     Interfacer.update_field!(atmos_sim, Val(:surface_diffuse_albedo), csf.surface_diffuse_albedo)
-    Interfacer.update_field!(atmos_sim, Val(:surface_temperature), csf.T_S)
+    Interfacer.update_field!(atmos_sim, Val(:surface_temperature), csf.T_sfc)
 
     if turbulent_fluxes isa FluxCalculator.CombinedStateFluxesMOST
-        Interfacer.update_field!(atmos_sim, Val(:roughness_momentum), csf.z0m_S)
-        Interfacer.update_field!(atmos_sim, Val(:roughness_buoyancy), csf.z0b_S)
+        Interfacer.update_field!(atmos_sim, Val(:roughness_momentum), csf.z0m_sfc)
+        Interfacer.update_field!(atmos_sim, Val(:roughness_buoyancy), csf.z0b_sfc)
         Interfacer.update_field!(atmos_sim, Val(:beta), csf.beta) # not in this version of atmos
     end
 
diff --git a/src/FluxCalculator.jl b/src/FluxCalculator.jl
@@ -85,7 +85,7 @@ saved in that sim's cache. `csf` refers to the coupler fields.
 
 ```
 function atmos_turbulent_fluxes_most!(atmos_sim::ClimaAtmosSimulation, csf)
-    atmos_sim.cache.flux .= atmos_sim.c .* (csf.T_S .- atmos_sim.temperature)
+    atmos_sim.cache.flux .= atmos_sim.c .* (csf.T_sfc .- atmos_sim.temperature)
 end
 ```
 
@@ -95,11 +95,11 @@ atmos_turbulent_fluxes_most!(sim::Interfacer.ComponentModelSimulation, _) =
 
 
 """
-    calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_S::CC.Fields.Field)
+    calculate_surface_air_density(atmos_sim::ClimaAtmosSimulation, T_sfc::CC.Fields.Field)
 
 Extension for this  to to calculate surface density.
 """
-function calculate_surface_air_density(atmos_sim::Interfacer.AtmosModelSimulation, T_S::CC.Fields.Field)
+function calculate_surface_air_density(atmos_sim::Interfacer.AtmosModelSimulation, T_sfc::CC.Fields.Field)
     error("this function is required to be dispatched on" * Interfacer.name(atmos_sim) * ", but no method defined")
 end
 
diff --git a/test/field_exchanger_tests.jl b/test/field_exchanger_tests.jl
@@ -16,9 +16,9 @@ Interfacer.get_field(sim::DummySimulation, ::Val{:radiative_energy_flux_sfc}) =
 Interfacer.get_field(sim::DummySimulation, ::Val{:liquid_precipitation}) = sim.cache.liquid_precipitation
 Interfacer.get_field(sim::DummySimulation, ::Val{:snow_precipitation}) = sim.cache.snow_precipitation
 
-function FluxCalculator.calculate_surface_air_density(atmos_sim::DummySimulation, T_S::CC.Fields.Field)
-    FT = CC.Spaces.undertype(axes(T_S))
-    return T_S .* FT(0.0) .+ FT(1.0)
+function FluxCalculator.calculate_surface_air_density(atmos_sim::DummySimulation, T_sfc::CC.Fields.Field)
+    FT = CC.Spaces.undertype(axes(T_sfc))
+    return T_sfc .* FT(0.0) .+ FT(1.0)
 end
 
 
@@ -207,7 +207,7 @@ for FT in (Float32, Float64)
 
     @testset "import_atmos_fields! for FT=$FT" begin
         boundary_space = TestHelper.create_space(FT)
-        coupler_names = (:F_turb_energy, :F_turb_moisture, :F_radiative, :P_liq, :P_snow, :ρ_sfc, :T_S)
+        coupler_names = (:F_turb_energy, :F_turb_moisture, :F_radiative, :P_liq, :P_snow, :ρ_sfc, :T_sfc)
         atmos_names = (
             :turbulent_energy_flux,
             :turbulent_moisture_flux,
@@ -236,7 +236,8 @@ for FT in (Float32, Float64)
     @testset "import_combined_surface_fields! for FT=$FT" begin
         # coupler cache setup
         boundary_space = TestHelper.create_space(FT)
-        coupler_names = (:T_S, :z0m_S, :z0b_S, :surface_direct_albedo, :surface_diffuse_albedo, :beta, :q_sfc, :temp1)
+        coupler_names =
+            (:T_sfc, :z0m_sfc, :z0b_sfc, :surface_direct_albedo, :surface_diffuse_albedo, :beta, :q_sfc, :temp1)
 
         # coupler cache setup
         exchanged_fields = (
@@ -258,11 +259,11 @@ for FT in (Float32, Float64)
             coupler_fields =
                 NamedTuple{coupler_names}(ntuple(i -> CC.Fields.zeros(boundary_space), length(coupler_names)))
             FieldExchanger.import_combined_surface_fields!(coupler_fields, sims, t)
-            @test Array(parent(coupler_fields.T_S))[1] == results[1]
+            @test Array(parent(coupler_fields.T_sfc))[1] == results[1]
             @test Array(parent(coupler_fields.surface_direct_albedo))[1] == results[1]
             @test Array(parent(coupler_fields.surface_diffuse_albedo))[1] == results[1]
-            @test Array(parent(coupler_fields.z0m_S))[1] == results[i]
-            @test Array(parent(coupler_fields.z0b_S))[1] == results[i]
+            @test Array(parent(coupler_fields.z0m_sfc))[1] == results[i]
+            @test Array(parent(coupler_fields.z0b_sfc))[1] == results[i]
             @test Array(parent(coupler_fields.beta))[1] == results[i]
         end
     end
@@ -272,9 +273,9 @@ for FT in (Float32, Float64)
         boundary_space = TestHelper.create_space(FT)
         coupler_field_names = (
             :ρ_sfc,
-            :T_S,
-            :z0m_S,
-            :z0b_S,
+            :T_sfc,
+            :z0m_sfc,
+            :z0b_sfc,
             :surface_direct_albedo,
             :surface_diffuse_albedo,
             :beta,
diff --git a/test/flux_calculator_tests.jl b/test/flux_calculator_tests.jl
@@ -202,7 +202,7 @@ for FT in (Float32, Float64)
             model_sims = (; atmos_sim, ocean_sim, ocean_sim2)
 
             coupler_cache_names = (
-                :T_S,
+                :T_sfc,
                 :surface_direct_albedo,
                 :surface_diffuse_albedo,
                 :F_R_sfc,
