Add sensible defaults for AtmosModel

Author: nefrathenrici

src/solver/type_getters.jl

@@ -86,28 +86,30 @@ function get_atmos(config::AtmosConfig, params)
     )
 
     atmos = AtmosModel(;
-        # Moisture & Clouds
+        # AtmosHydrology - Moisture, Precipitation & Clouds
         moisture_model,
         precip_model,
         cloud_model,
         noneq_cloud_formation_mode = implicit_noneq_cloud_formation ?
                                      Implicit() : Explicit(),
         call_cloud_diagnostics_per_stage,
 
-        # Forcing & Advection
+        # AtmosForcing
         forcing_type,
         subsidence = get_subsidence_model(parsed_args, radiation_mode, FT),
         external_forcing = get_external_forcing_model(parsed_args, FT),
+
+        # AtmosAdvection  
         ls_adv = get_large_scale_advection_model(parsed_args, FT),
         advection_test,
 
-        # Radiation
+        # AtmosRadiation
         radiation_mode,
         ozone,
         co2,
         insolation = get_insolation_form(parsed_args),
 
-        # Turbulence & Convection
+        # AtmosTurbconv - Turbulence & Convection
         scm_coriolis = get_scm_coriolis(parsed_args, FT),
         edmfx_model,
         turbconv_model = get_turbconv_model(FT, parsed_args, turbconv_params),
@@ -118,7 +120,7 @@ function get_atmos(config::AtmosConfig, params)
         sgs_mf_mode = implicit_sgs_mass_flux ? Implicit() : Explicit(),
         smagorinsky_lilly = get_smagorinsky_lilly_model(parsed_args),
 
-        # Gravity Waves
+        # AtmosGravityWave
         non_orographic_gravity_wave = get_non_orographic_gravity_wave_model(
             parsed_args,
             FT,
@@ -128,17 +130,17 @@ function get_atmos(config::AtmosConfig, params)
             FT,
         ),
 
-        # Diffusion & Sponges
-        vert_diff,
+        # AtmosSponge
         viscous_sponge = get_viscous_sponge_model(parsed_args, params, FT),
         rayleigh_sponge = get_rayleigh_sponge_model(parsed_args, params, FT),
 
-        # Surface
+        # AtmosSurface
         sfc_temperature = get_sfc_temperature_form(parsed_args),
         surface_model = get_surface_model(parsed_args),
         surface_albedo = get_surface_albedo_model(parsed_args, params, FT),
 
-        # Numerics and Top-level Options
+        # Top-level options (not grouped)
+        vert_diff,
         hyperdiff = get_hyperdiffusion_model(parsed_args, FT),
         numerics = get_numerics(parsed_args),
         disable_surface_flux_tendency = parsed_args["disable_surface_flux_tendency"],

src/solver/types.jl

@@ -517,12 +517,12 @@ Base.@kwdef struct EDMFXModel{
     scale_blending_method::SBM
 end
 
-# Grouped structures to reduce AtmosModel type parameters
+# Grouped structs to reduce AtmosModel type parameters
 
 """
     AtmosHydrology
 
-Groups moisture-related models and parameters.
+Groups moisture-related models and types.
 """
 Base.@kwdef struct AtmosHydrology{MM, PM, CM, NCFM, CCDPS}
     moisture_model::MM = nothing
@@ -535,7 +535,7 @@ end
 """
     AtmosForcing
 
-Groups forcing-related models and parameters.
+Groups forcing-related models and types.
 """
 Base.@kwdef struct AtmosForcing{F, S, EXTFORCING}
     forcing_type::F = nothing
@@ -546,7 +546,7 @@ end
 """
     AtmosRadiation
 
-Groups radiation-related models and parameters.
+Groups radiation-related models and types.
 """
 Base.@kwdef struct AtmosRadiation{RM, OZ, CO2, IN}
     radiation_mode::RM = nothing
@@ -558,7 +558,7 @@ end
 """
     AtmosAdvection
 
-Groups advection-related models and parameters.
+Groups advection-related models and types.
 """
 Base.@kwdef struct AtmosAdvection{LA, AT}
     ls_adv::LA = nothing
@@ -568,7 +568,7 @@ end
 """
     AtmosTurbconv
 
-Groups turbulence convection-related models and parameters.
+Groups turbulence convection-related models and types.
 """
 Base.@kwdef struct AtmosTurbconv{EC, EDMFX, TCM, SAM, SEDM, SNPM, SMM, SL}
     scm_coriolis::EC = nothing
@@ -584,7 +584,7 @@ end
 """
     AtmosGravityWave
 
-Groups gravity wave-related models and parameters.
+Groups gravity wave-related models and types.
 """
 Base.@kwdef struct AtmosGravityWave{NOGW, OGW}
     non_orographic_gravity_wave::NOGW = nothing
@@ -594,7 +594,7 @@ end
 """
     AtmosSponge
 
-Groups sponge-related models and parameters.
+Groups sponge-related models and types.
 """
 Base.@kwdef struct AtmosSponge{VS, RS}
     viscous_sponge::VS = nothing
@@ -604,7 +604,7 @@ end
 """
     AtmosSurface
 
-Groups surface-related models and parameters.
+Groups surface-related models and types.
 """
 Base.@kwdef struct AtmosSurface{ST, SM, SA}
     sfc_temperature::ST = nothing
@@ -722,19 +722,37 @@ end
 """
     AtmosModel(; kwargs...)
 
-Create an AtmosModel using a unified flat interface.
+Create an AtmosModel with sensible defaults.
 
-This constructor allows you to specify individual model components directly as 
-keyword arguments, which are automatically organized into the appropriate grouped 
-sub-structures internally. This interface is used by both interactive users and 
-the config system via `get_atmos()`.
+This constructor provides sensible defaults for a minimal dry atmospheric model with full customization through keyword arguments. 
 
-# Example: Basic dry model
+All model components are automatically organized into appropriate grouped sub-structs 
+internally:
+- [`AtmosHydrology`](@ref)
+- [`AtmosForcing`](@ref)
+- [`AtmosRadiation`](@ref)
+- [`AtmosAdvection`](@ref)
+- [`AtmosTurbconv`](@ref)
+- [`AtmosGravityWave`](@ref)
+- [`AtmosSponge`](@ref)
+- [`AtmosSurface`](@ref)
+- [`AtmosNumerics`](@ref)
+The one exception is the top-level `disable_surface_flux_tendency` field, which is not grouped.
+
+# Example: Minimal model (uses defaults)
+```julia
+model = AtmosModel()  # Creates a basic dry atmospheric model
+```
+
+# Example: Basic dry model with forcing
 ```julia
 model = AtmosModel(;
-    moisture_model = DryModel(),
-    surface_model = PrescribedSurfaceTemperature(),
-    precip_model = NoPrecipitation()
+    forcing_type = HeldSuarezForcing(),
+    hyperdiff = ClimaHyperdiffusion(; 
+        ν₄_vorticity_coeff = 1e15, 
+        ν₄_scalar_coeff = 1e15, 
+        divergence_damping_factor = 1.0
+    )
 )
 ```
 
@@ -743,95 +761,106 @@ model = AtmosModel(;
 model = AtmosModel(;
     moisture_model = EquilMoistModel(),
     precip_model = Microphysics0Moment(),
-    radiation_mode = RRTMGPI.AllSkyRadiation(
-        false, false, InteractiveCloudInRadiation(), false, false, false, false
-    ),
+    radiation_mode = RRTMGPI.AllSkyRadiation(),
     ozone = IdealizedOzone(),
     co2 = FixedCO2()
 )
 ```
 
-# Example: Model with hyperdiffusion and sponge layers
-```julia
-model = AtmosModel(;
-    moisture_model = NonEquilMoistModel(),
-    precip_model = Microphysics1Moment(),
-    hyperdiff = ClimaHyperdiffusion(; 
-        ν₄_vorticity_coeff = 1e15, 
-        ν₄_scalar_coeff = 1e15, 
-        divergence_damping_factor = 1.0
-    ),
-    rayleigh_sponge = RayleighSponge(; zd = 12000.0, α_uₕ = 4.0, α_w = 2.0),
-    disable_surface_flux_tendency = false
-)
-```
+# Default Configuration
+The default AtmosModel provides:
+- **Dry atmosphere**: DryModel() with NoPrecipitation()
+- **Basic surface**: PrescribedSurfaceTemperature() with ZonallySymmetricSST()
+- **Simple clouds**: GridScaleCloud()
+- **Idealized insolation**: IdealizedInsolation()
+- **Conservative numerics**: First-order upwinding with Explicit() timestepping
+- **No advanced physics**: No radiation, turbulence, or forcing by default
 
-# Available Parameters
+# Available Structs
 
-## Moisture & Clouds
+## AtmosHydrology
 - `moisture_model`: DryModel(), EquilMoistModel(), NonEquilMoistModel()
 - `precip_model`: NoPrecipitation(), Microphysics0Moment(), Microphysics1Moment(), Microphysics2Moment()
 - `cloud_model`: GridScaleCloud(), QuadratureCloud(), SGSQuadratureCloud()
 - `noneq_cloud_formation_mode`: Explicit(), Implicit()
 - `call_cloud_diagnostics_per_stage`: nothing or CallCloudDiagnosticsPerStage()
 
-## Radiation
+## AtmosRadiation
 - `radiation_mode`: RRTMGPI.ClearSkyRadiation(), RRTMGPI.AllSkyRadiation(), etc.
 - `ozone`: IdealizedOzone(), PrescribedOzone()
 - `co2`: FixedCO2(), MaunaLoaCO2()
 - `insolation`: IdealizedInsolation(), TimeVaryingInsolation(), etc.
 
-## Forcing & Advection
+## AtmosForcing
 - `forcing_type`: nothing, HeldSuarezForcing()
 - `subsidence`: nothing or Subsidence() instances
 - `external_forcing`: nothing or external forcing objects
+
+## AtmosAdvection
 - `ls_adv`: nothing or LargeScaleAdvection() instances
 - `advection_test`: nothing or boolean
 
-## Turbulence & Convection
+## AtmosTurbconv
 - `scm_coriolis`: nothing or SCMCoriolis() instances
 - `edmfx_model`: EDMFXModel() instances
 - `turbconv_model`: nothing, PrognosticEDMFX(), DiagnosticEDMFX(), EDOnlyEDMFX()
 - `sgs_adv_mode`, `sgs_entr_detr_mode`, `sgs_nh_pressure_mode`, `sgs_mf_mode`: Explicit(), Implicit()
 - `smagorinsky_lilly`: nothing or SmagorinskyLilly()
 
-## Gravity Waves
+## AtmosGravityWave
 - `non_orographic_gravity_wave`: nothing or NonOrographicGravityWave() instances  
 - `orographic_gravity_wave`: nothing or OrographicGravityWave() instances
 
-## Diffusion & Sponges
-- `vert_diff`: nothing, VerticalDiffusion(), DecayWithHeightDiffusion()
+## AtmosSponge
 - `viscous_sponge`: nothing or ViscousSponge() instances
 - `rayleigh_sponge`: nothing or RayleighSponge() instances
 
-## Surface
+## AtmosSurface
 - `sfc_temperature`: ZonallySymmetricSST(), ZonallyAsymmetricSST(), RCEMIPIISST(), ExternalTVColumnSST()
 - `surface_model`: PrescribedSurfaceTemperature(), PrognosticSurfaceTemperature()
 - `surface_albedo`: ConstantAlbedo(), RegressionFunctionAlbedo(), CouplerAlbedo()
 
 ## Top-level Options  
+- `vert_diff`: nothing, VerticalDiffusion(), DecayWithHeightDiffusion()
 - `hyperdiff`: nothing or ClimaHyperdiffusion() instances
-- `numerics`: nothing or AtmosNumerics() instances (includes `diff_mode`: Explicit(), Implicit())
+- `numerics`: AtmosNumerics() instances (includes `diff_mode`: Explicit(), Implicit())
 - `disable_surface_flux_tendency`: Bool
 
 # Notes
-- All parameters are optional and have sensible defaults
 - This unified interface is used by both interactive users and the config system
-- Parameters are automatically grouped into appropriate sub-structures
-- Unknown parameter names produce helpful error messages listing all available options
-- Property access works both ways: `model.moisture_model` and `model.moisture.moisture_model`
-- The Atmos prefix is kind of annoying and could be removed
-
-# Todo 
-- improve documentation
-- add exports?
-- remove the Atmos prefix for grouped types?
+- Arguments are automatically grouped into appropriate sub-structs
+- Unknown argument names produce helpful error messages listing all available options
+- Property access works both ways: `model.moisture_model` and `model.hydrology.moisture_model`
 """
 function AtmosModel(; kwargs...)
+    # TODO: Break this into separate functions for defaults and kwarg processing 
+    # this is hard to understand and maintain
+
+    # Set defaults that create a minimal viable atmospheric model
+    default_args = (
+        moisture_model = DryModel(),
+        precip_model = NoPrecipitation(),
+        cloud_model = GridScaleCloud(),
+        surface_model = PrescribedSurfaceTemperature(),
+        sfc_temperature = ZonallySymmetricSST(),
+        insolation = IdealizedInsolation(),
+        numerics = AtmosNumerics(
+            energy_upwinding = Val(:first_order),
+            tracer_upwinding = Val(:first_order),
+            edmfx_upwinding = Val(:first_order),
+            edmfx_sgsflux_upwinding = Val(:none),
+            test_dycore_consistency = nothing,
+            limiter = nothing,
+            diff_mode = Explicit(),
+        ),
+
+        # Top-level
+        disable_surface_flux_tendency = false,
+    )
+
     # Process keyword arguments: categorize into grouped types (e.g., hydrology -> AtmosHydrology)
     # vs direct AtmosModel fields (e.g., hyperdiff, numerics). Use GROUPED_PROPERTY_MAP to organize grouped types
-    # into appropriate nested structs, then construct AtmosModel with all top-level fields.
-
+    # into appropriate grouped structs, then construct AtmosModel with all top-level fields.
     group_kwargs = Dict{Symbol, Dict{Symbol, Any}}()
     for (_, group_field) in ATMOS_MODEL_GROUPS
         group_kwargs[group_field] = Dict{Symbol, Any}()
@@ -840,8 +869,21 @@ function AtmosModel(; kwargs...)
     # Kwargs for direct AtmosModel fields (hyperdiff, numerics, vert_diff, disable_surface_flux_tendency)
     atmos_model_kwargs = Dict{Symbol, Any}()
 
-    # Sort kwargs into appropriate groups
+    # Make all kwargs: apply defaults for any missing kwargs, then sort into appropriate groups
+    all_kwargs = Dict{Symbol, Any}()
+
+    # First add defaults
+    for (key, default_value) in pairs(default_args)
+        all_kwargs[key] = default_value
+    end
+
+    # Then add user kwargs (overriding defaults)
     for (key, value) in kwargs
+        all_kwargs[key] = value
+    end
+
+    # Sort kwargs into appropriate groups
+    for (key, value) in all_kwargs
         if haskey(GROUPED_PROPERTY_MAP, key)
             group_field = GROUPED_PROPERTY_MAP[key]
             group_kwargs[group_field][key] = value
@@ -851,7 +893,7 @@ function AtmosModel(; kwargs...)
             available_grouped = sort(collect(keys(GROUPED_PROPERTY_MAP)))
             available_direct = sort([
                 fn for fn in fieldnames(AtmosModel) if fn ∉ [
-                    :moisture,
+                    :hydrology,
                     :forcing,
                     :radiation,
                     :advection,
@@ -998,7 +1040,6 @@ function NonEquilMoistAtmosModel(; kwargs...)
     return AtmosModel(; defaults..., kwargs...)
 end
 
-# ============================================================================
 
 abstract type AbstractCallbackFrequency end
 struct EveryNSteps <: AbstractCallbackFrequency