Merge pull request #686 from CliMA/ln/missing-docstrings

Add missing docstrings

docs/src/conservation.md

@@ -2,15 +2,20 @@
 
 If the model is a physically closed system (e.g., in the `slabplanet` configuration with free slip conditions), it should conserve mass (including water), energy and momentum. The conservation checker logs global conservation.
 
-Only energy and water are currently implemented. 
+Only energy and water are currently implemented.
 
-Note that kinetic energy is not included in the calculation of the global energy, reflecting the formulation on `ClimaAtmos`, which assumes that kinetic energy is negligible in comparison with the moist static energy components. 
+Note that kinetic energy is not included in the calculation of the global energy, reflecting the formulation on `ClimaAtmos`, which assumes that kinetic energy is negligible in comparison with the moist static energy components.
 
-## Coupler Object API
+## ConservationChecker API
 
 ```@docs
 ClimaCoupler.ConservationChecker.EnergyConservationCheck
 ClimaCoupler.ConservationChecker.WaterConservationCheck
 ClimaCoupler.ConservationChecker.check_conservation!
 ClimaCoupler.ConservationChecker.plot_global_conservation
 ```
+
+## ConservationChecker Internal Functions
+```@docs
+ClimaCoupler.ConservationChecker.surface_water_gain_from_rates
+```

docs/src/diagnostics.md

@@ -1,8 +1,8 @@
 # Diagnostics
 
-This module contains functions for defining, gathering and outputting model diagnostics from the Coupler. 
+This module contains functions for defining, gathering and outputting model diagnostics from the Coupler.
 
-Note that `ClimaCoupler.Diagnostics` is deployed online (i.e., as the model runs), working with cached model data (usually) on the model grid. This does not include offline post-processing (i.e., manipulating saved model output after the model is run, such as regridding data to the latitude-longitude grid). See `ClimaCoupler.PostProcessor` for offline model data treatment. 
+Note that `ClimaCoupler.Diagnostics` is deployed online (i.e., as the model runs), working with cached model data (usually) on the model grid. This does not include offline post-processing (i.e., manipulating saved model output after the model is run, such as regridding data to the latitude-longitude grid). See `ClimaCoupler.PostProcessor` for offline model data treatment.
 
 ## Diagnostics API
 
@@ -14,6 +14,7 @@ Note that `ClimaCoupler.Diagnostics` is deployed online (i.e., as the model runs
     ClimaCoupler.Diagnostics.get_var
     ClimaCoupler.Diagnostics.accumulate_diagnostics!
     ClimaCoupler.Diagnostics.save_diagnostics
+    ClimaCoupler.Diagnostics.init_diagnostics
 ```
 
 

docs/src/fluxcalculator.md

@@ -16,5 +16,19 @@ Fluxes over a heterogeneous surface (e.g., from a gridpoint where atmospheric ce
     ClimaCoupler.FluxCalculator.CombinedStateFluxes
     ClimaCoupler.FluxCalculator.combined_turbulent_fluxes!
     ClimaCoupler.FluxCalculator.atmos_turbulent_fluxes!
+    ClimaCoupler.FluxCalculator.surface_inputs
+    ClimaCoupler.FluxCalculator.calculate_surface_air_density
+    ClimaCoupler.FluxCalculator.get_surface_params
+    ClimaCoupler.FluxCalculator.partitioned_turbulent_fluxes!
+    ClimaCoupler.FluxCalculator.differentiate_turbulent_fluxes!
+    ClimaCoupler.FluxCalculator.get_surface_fluxes_point!
+    ClimaCoupler.FluxCalculator.update_turbulent_fluxes_point!
+    ClimaCoupler.FluxCalculator.extrapolate_ρ_to_sfc
+    ClimaCoupler.FluxCalculator.surface_thermo_state
+```
+
+## FieldExchanger Internal Functions
 
+```@docs
+    ClimaCoupler.FluxCalculator.get_scheme_properties
 ```

docs/src/interfacer.md

@@ -187,3 +187,18 @@ function update_field!(sim::SurfaceStub, ::Val{:surface_temperature}, field::Fie
     sim.cache.T_sfc .= field
 end
 ```
+
+## Interfacer API
+```@docs
+    ClimaCoupler.Interfacer.CoupledSimulation
+    ClimaCoupler.Interfacer.AtmosModelSimulation
+    ClimaCoupler.Interfacer.SurfaceModelSimulation
+    ClimaCoupler.Interfacer.ComponentModelSimulation
+    ClimaCoupler.Interfacer.AbstractSimulation
+    ClimaCoupler.Interfacer.SurfaceStub
+    ClimaCoupler.Interfacer.stub_init
+    ClimaCoupler.Interfacer.float_type
+    ClimaCoupler.Interfacer.name
+    ClimaCoupler.Interfacer.get_field
+    ClimaCoupler.Interfacer.update_field!
+```

docs/src/regridder.md

@@ -18,7 +18,8 @@ ClimaCoupler.Regridder.remap_field_cgll_to_rll
 ClimaCoupler.Regridder.land_fraction
 ClimaCoupler.Regridder.update_surface_fractions!
 ClimaCoupler.Regridder.combine_surfaces!
-ClimaCoupler.Regridder.rcgll2latlonz
+ClimaCoupler.Regridder.cgll2latlonz
+ClimaCoupler.Regridder.combine_surfaces_from_sol!
 ```
 
 

docs/src/timemanager.md

@@ -11,10 +11,14 @@ ClimaCoupler.TimeManager.current_date
 ClimaCoupler.TimeManager.strdate_to_datetime
 ClimaCoupler.TimeManager.datetime_to_strdate
 ClimaCoupler.TimeManager.trigger_callback
+ClimaCoupler.TimeManager.AbstractFrequency
 ClimaCoupler.TimeManager.Monthly
 ClimaCoupler.TimeManager.EveryTimestep
 ClimaCoupler.TimeManager.trigger_callback!
+ClimaCoupler.TimeManager.CouplerCallback
 ClimaCoupler.TimeManager.HourlyCallback
 ClimaCoupler.TimeManager.MonthlyCallback
 ClimaCoupler.TimeManager.update_firstdayofmonth!
+ClimaCoupler.TimeManager.dt_cb
+ClimaCoupler.TimeManager.do_nothing
 ```

docs/src/utilities.md

@@ -7,7 +7,7 @@ modules in the coupler.
 ## Utilities API
 
 ```@docs
-ClimaCoupler.Utilities.CouplerSimulation
-ClimaCoupler.Utilities.float_type
 ClimaCoupler.Utilities.swap_space!
+ClimaCoupler.Utilities.get_comms_context
+ClimaCoupler.Utilities.get_device
 ```

experiments/AMIP/coupler_driver.jl

@@ -428,7 +428,7 @@ end
 #=
 ## Coupler Initialization
 The coupler needs to contain exchange information, manage the calendar and be able to access all component models. It can also optionally
-save online diagnostics. These are all initialized here and saved in a global `CouplerSimulation` struct, `cs`.
+save online diagnostics. These are all initialized here and saved in a global `CoupledSimulation` struct, `cs`.
 =#
 
 ## coupler exchange fields

src/Diagnostics.jl

@@ -13,8 +13,21 @@ using ClimaComms
 
 export get_var, init_diagnostics, accumulate_diagnostics!, save_diagnostics, TimeMean
 
+"""
+    AbstractOutputGroup
+
+Abstract type for ClimaCoupler's output diagnostics groups. Each diagnostic group should
+contain fields that are of the same type and size, so the extended methods for the group's
+operation functions work in the same way for all the fields.
+"""
 abstract type AbstractOutputGroup end
 
+"""
+    DiagnosticsGroup{S, NTO <: NamedTuple}
+
+Defines a concrete diagnostics group type with fields `field_vector`, `operations`, `save`,
+`output_dir` and `name_tag`.
+"""
 struct DiagnosticsGroup{S, NTO <: NamedTuple} <: AbstractOutputGroup
     field_vector::Fields.FieldVector
     operations::NTO
@@ -23,15 +36,33 @@ struct DiagnosticsGroup{S, NTO <: NamedTuple} <: AbstractOutputGroup
     name_tag::String
 end
 
+"""
+    AbstractDiagnosticsOperations
+
+Abstract type for operations to be performed on ClimaCoupler's diagnostics.
+"""
 abstract type AbstractDiagnosticsOperations end
 
+"""
+    TimeMean{C}
+
+Defines a concrete operation type for time-averaged diagnostics. The counter `ct`
+is used to accumulate the sum of the diagnostics.
+"""
 struct TimeMean{C} <: AbstractDiagnosticsOperations
     ct::C
 end
 # TODO: TemporalVariances, SpatialMean, SpatialVariances
 
 """
-    init_diagnostics(names::Tuple, space::Spaces.Space; save = EveryTimestep(), operations = (;), output_dir = "", name_tag = "" )
+    function init_diagnostics(
+        names::Tuple,
+        space::Spaces.AbstractSpace;
+        save = EveryTimestep(),
+        operations = (;),
+        output_dir = "",
+        name_tag = "",
+    )
 
 Initializes diagnostics groups.
 """
@@ -50,7 +81,8 @@ end
 """
     get_var(cs::CoupledSimulation, x)
 
-Defines variable extraction from the coupler simulation. User specific diagnostics should extend this function in the experiments folder.
+Defines variable extraction from the coupler simulation. User specific diagnostics
+should extend this function in the experiments folder.
 
 Example:
 
@@ -67,7 +99,8 @@ Accumulates user-defined diagnostics listed in the in the `field_vector` of each
 function accumulate_diagnostics!(cs::CoupledSimulation)
     for dg in cs.diagnostics
         if dg.operations.accumulate !== nothing
-            iterate_operations(cs, dg, collect_diags(cs, dg)) # TODO: avoid collecting at each timestep where not needed
+            # TODO: avoid collecting at each timestep where not needed
+            iterate_operations(cs, dg, collect_diags(cs, dg))
         end
     end
 end
@@ -94,7 +127,6 @@ end
 
 Applies iteratively all specified diagnostics operations.
 """
-
 function iterate_operations(cs::CoupledSimulation, dg::DiagnosticsGroup, new_diags::Fields.FieldVector)
     for op in dg.operations
         operation(cs, dg, new_diags, op)
@@ -104,7 +136,8 @@ end
 """
     operation(cs::CoupledSimulation, dg::DiagnosticsGroup, new_diags::Fields.FieldVector, ::TimeMean)
 
-Accumulates in time all entries in `new_diags` and saves the result in `dg.field_vector`, while increasing the `dg.ct` counter.
+Accumulates in time all entries in `new_diags` and saves the result in `dg.field_vector`, while
+increasing the `dg.ct` counter.
 """
 function operation(::CoupledSimulation, dg::DiagnosticsGroup, new_diags::Fields.FieldVector, ::TimeMean)
     dg.field_vector .+= new_diags
@@ -116,7 +149,8 @@ end
 """
     operation(cs::CoupledSimulation, dg::DiagnosticsGroup, new_diags::Fields.FieldVector, ::Nothing)
 
-Accumulates in time all entries in `new_diags` and saves the result in `dg.field_vector`, while increasing the `dg.ct` counter.
+Accumulates in time all entries in `new_diags` and saves the result in `dg.field_vector`, while
+increasing the `dg.ct` counter.
 """
 function operation(::CoupledSimulation, dg::DiagnosticsGroup, new_diags::Fields.FieldVector, ::Nothing)
     dg.field_vector .= new_diags

src/PostProcessor.jl

@@ -14,12 +14,41 @@ using ClimaCoupler: Regridder
 using ClimaCore: Fields
 
 # data types for postprocessing
+"""
+    PostProcessedData
+
+Abstract type for postprocessed data.
+"""
 abstract type PostProcessedData end
 
+"""
+    ZLatLonData <: PostProcessedData
+Concrete type for 3D data.
+"""
 struct ZLatLonData <: PostProcessedData end
+
+"""
+    ZLatData <: PostProcessedData
+Concrete type for 2D data with latitude and level.
+"""
 struct ZLatData <: PostProcessedData end
+
+"""
+    LatLonData <: PostProcessedData
+Concrete type for 2D data with latitude and longitude.
+"""
 struct LatLonData <: PostProcessedData end
+
+"""
+    LatData <: PostProcessedData
+Concrete type for 1D data with latitude.
+"""
 struct LatData <: PostProcessedData end
+
+"""
+    RawData <: PostProcessedData
+Concrete type for raw model data.
+"""
 struct RawData <: PostProcessedData end
 
 """

src/TimeManager.jl

@@ -26,7 +26,7 @@ export current_date,
 
 
 """
-    current_date(cs::CoupledSimulation, t::Int)
+    current_date(cs::Interfacer.CoupledSimulation, t::Int)
 
 Return the model date at the current timestep.
 
@@ -61,8 +61,23 @@ datetime_to_strdate(datetime::DateTime) =
     string(string(lpad(Dates.month(datetime), 2, "0"))) *
     string(lpad(Dates.day(datetime), 2, "0"))
 
+"""
+    AbstractFrequency
+
+This is an abstract type for the frequency of the callback function.
+"""
 abstract type AbstractFrequency end
+
+"""
+    Monthly
+A concrete type for the monthly frequency of the callback function.
+"""
 struct Monthly <: AbstractFrequency end
+
+"""
+    EveryTimestep
+A concrete type for the every-timestep frequency of the callback function.
+"""
 struct EveryTimestep <: AbstractFrequency end
 
 """
@@ -73,9 +88,13 @@ Returns `true` if the current date is equal to or exceeds the saved first of the
 # Arguments
 - `cs`: [CoupledSimulation] containing info about the simulation
 """
-trigger_callback(cs::CoupledSimulation, ::Monthly) = cs.dates.date[1] >= cs.dates.date1[1] ? true : false
+trigger_callback(cs::Interfacer.CoupledSimulation, ::Monthly) = cs.dates.date[1] >= cs.dates.date1[1] ? true : false
 
+"""
+    CouplerCallback
 
+This is an abstract type for ClimaCoupler's callback functions.
+"""
 abstract type CouplerCallback end
 
 """
@@ -119,6 +138,12 @@ $(DSE.FIELDS)
     data::Array = []
 end
 
+"""
+    dt_cb(cb::HourlyCallback)
+    dt_cb(cb::MonthlyCallback)
+
+This function returns the time interval for the callback function.
+"""
 dt_cb(cb::HourlyCallback) = Dates.Hour(cb.dt)
 dt_cb(cb::MonthlyCallback) = Dates.Month(cb.dt)