From 37c2f4f721a5aef3a7636492eaab1ffb849ead3c Mon Sep 17 00:00:00 2001 From: LenkaNovak Date: Mon, 11 Mar 2024 12:24:40 -0700 Subject: [PATCH] add docstrings rev --- docs/src/conservation.md | 11 +++++-- docs/src/diagnostics.md | 5 ++-- docs/src/fluxcalculator.md | 14 +++++++++ docs/src/interfacer.md | 15 ++++++++++ docs/src/regridder.md | 3 +- docs/src/timemanager.md | 4 +++ docs/src/utilities.md | 4 +-- experiments/AMIP/coupler_driver.jl | 2 +- src/Diagnostics.jl | 46 ++++++++++++++++++++++++++---- src/PostProcessor.jl | 29 +++++++++++++++++++ src/TimeManager.jl | 29 +++++++++++++++++-- 11 files changed, 145 insertions(+), 17 deletions(-) diff --git a/docs/src/conservation.md b/docs/src/conservation.md index e1e8fb7caa..eeec100cdf 100644 --- a/docs/src/conservation.md +++ b/docs/src/conservation.md @@ -2,11 +2,11 @@ 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 @@ -14,3 +14,8 @@ ClimaCoupler.ConservationChecker.WaterConservationCheck ClimaCoupler.ConservationChecker.check_conservation! ClimaCoupler.ConservationChecker.plot_global_conservation ``` + +## ConservationChecker Internal Functions +```@docs +ClimaCoupler.ConservationChecker.surface_water_gain_from_rates +``` \ No newline at end of file diff --git a/docs/src/diagnostics.md b/docs/src/diagnostics.md index 5e23249285..93ec335eb4 100644 --- a/docs/src/diagnostics.md +++ b/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 ``` diff --git a/docs/src/fluxcalculator.md b/docs/src/fluxcalculator.md index d2f9016be8..f77af1d570 100644 --- a/docs/src/fluxcalculator.md +++ b/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 ``` diff --git a/docs/src/interfacer.md b/docs/src/interfacer.md index b9e76f11ee..bdf4b44798 100644 --- a/docs/src/interfacer.md +++ b/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! +``` diff --git a/docs/src/regridder.md b/docs/src/regridder.md index 5b823c2a09..dc52a11555 100644 --- a/docs/src/regridder.md +++ b/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! ``` diff --git a/docs/src/timemanager.md b/docs/src/timemanager.md index 5a8bd6e2ea..ed47e791cf 100644 --- a/docs/src/timemanager.md +++ b/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 ``` diff --git a/docs/src/utilities.md b/docs/src/utilities.md index c1d18fc4c5..c87b83f5f1 100644 --- a/docs/src/utilities.md +++ b/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 ``` diff --git a/experiments/AMIP/coupler_driver.jl b/experiments/AMIP/coupler_driver.jl index 5a89f5401e..ef564b622d 100644 --- a/experiments/AMIP/coupler_driver.jl +++ b/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 diff --git a/src/Diagnostics.jl b/src/Diagnostics.jl index 6104ba599b..e905b32d56 100644 --- a/src/Diagnostics.jl +++ b/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 diff --git a/src/PostProcessor.jl b/src/PostProcessor.jl index 309dba4fe9..06259379c4 100644 --- a/src/PostProcessor.jl +++ b/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 """ diff --git a/src/TimeManager.jl b/src/TimeManager.jl index 876b115bda..22b7d504f2 100644 --- a/src/TimeManager.jl +++ b/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)