Merge pull request #1255 from CliMA/js/constructors

juliasloan25 · web-flow · commit 4cb18239e096 · 2025-07-28T14:55:23.000-07:00
add constructors for CanopyModel + integrated models
diff --git a/NEWS.md b/NEWS.md
@@ -3,6 +3,7 @@ ClimaLand.jl Release Notes
 
 main
 -------
+- Add convenience constructors for CanopyModel and integrated models PR[#1255](https://github.com/CliMA/ClimaLand.jl/pull/1255)
 - Rename LandSimulationVisualization to LandSimulationVisualizationExt; add template for FluxnetSimulationsExt PR[#1259](https://github.com/CliMA/ClimaLand.jl/pull/1259)
 - Remove root_depths from the PrescribeGroundConditions struct, and treat these ground ``drivers" consistently with how we handle atmospheric forcing PR[#1199](https://github.com/CliMA/ClimaLand.jl/pull/1240)
 - Add constructors with default values for Canopy components PR[#1233](https://github.com/CliMA/ClimaLand.jl/pull/1233)
diff --git a/src/integrated/land.jl b/src/integrated/land.jl
@@ -36,6 +36,58 @@ struct LandModel{
     canopy::VM
     "The snow model to be used"
     snow::SnM
+    function LandModel{FT}(
+        canopy::VM,
+        snow::SnM,
+        soil::SM,
+        soilco2::MM,
+    ) where {
+        FT,
+        MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
+        SM <: Soil.EnergyHydrology{FT},
+        VM <: Canopy.CanopyModel{FT},
+        SnM <: Snow.SnowModel{FT},
+    }
+        prognostic_land_components = (:canopy, :snow, :soil, :soilco2)
+        top_soil_bc = soil.boundary_conditions.top
+        canopy_bc = canopy.boundary_conditions
+        snow_bc = snow.boundary_conditions
+
+        # Integrated model checks
+        @assert top_soil_bc.prognostic_land_components ==
+                prognostic_land_components
+        @assert canopy_bc.prognostic_land_components ==
+                prognostic_land_components
+        @assert snow_bc.prognostic_land_components == prognostic_land_components
+
+        @assert top_soil_bc.atmos == soilco2.drivers.atmos
+        @assert top_soil_bc.atmos == canopy_bc.atmos
+        @assert top_soil_bc.radiation == canopy_bc.radiation
+        @assert top_soil_bc.atmos == snow_bc.atmos
+        @assert top_soil_bc.radiation == snow_bc.radiation
+
+        @assert Domains.obtain_surface_domain(soil.domain) == canopy.domain
+        @assert Domains.obtain_surface_domain(soilco2.domain) == canopy.domain
+        @assert snow.domain == canopy.domain
+
+        @assert soil.parameters.earth_param_set ==
+                soilco2.parameters.earth_param_set
+        @assert soil.parameters.earth_param_set ==
+                canopy.parameters.earth_param_set
+        @assert soil.parameters.earth_param_set ==
+                snow.parameters.earth_param_set
+
+        # LandModel-specific checks
+        # Runoff and sublimation are also automatically included in the soil model
+        @assert RootExtraction{FT}() in soil.sources
+        @assert Soil.PhaseChange{FT}() in soil.sources
+        @assert canopy.hydraulics.transpiration isa
+                Canopy.PlantHydraulics.DiagnosticTranspiration{FT}
+        @assert canopy_bc.ground isa PrognosticGroundConditions{FT}
+        @assert soilco2.drivers.met isa Soil.Biogeochemistry.PrognosticMet
+
+        return new{FT, MM, SM, VM, SnM}(soilco2, soil, canopy, snow)
+    end
 end
 
 
@@ -179,8 +231,7 @@ function LandModel{FT}(;
         drivers = soilco2_drivers,
     )
 
-    args = (soilco2, soil, canopy, snow)
-    return LandModel{FT, typeof.(args)...}(args...)
+    return LandModel{FT}(canopy, snow, soil, soilco2)
 end
 
 """
diff --git a/src/integrated/soil_canopy_model.jl b/src/integrated/soil_canopy_model.jl
@@ -30,10 +30,51 @@ struct SoilCanopyModel{
     soil::SM
     "The canopy model to be used"
     canopy::VM
+    function SoilCanopyModel{FT}(
+        soilco2::MM,
+        soil::SM,
+        canopy::VM,
+    ) where {
+        FT,
+        MM <: Soil.Biogeochemistry.SoilCO2Model{FT},
+        SM <: Soil.EnergyHydrology{FT},
+        VM <: Canopy.CanopyModel{FT},
+    }
+        prognostic_land_components = (:canopy, :soil, :soilco2)
+        top_soil_bc = soil.boundary_conditions.top
+        canopy_bc = canopy.boundary_conditions
+
+        # Integrated model checks
+        @assert top_soil_bc.prognostic_land_components ==
+                prognostic_land_components
+        @assert canopy_bc.prognostic_land_components ==
+                prognostic_land_components
+
+        @assert top_soil_bc.atmos == soilco2.drivers.atmos
+        @assert top_soil_bc.atmos == canopy_bc.atmos
+        @assert top_soil_bc.radiation == canopy_bc.radiation
+
+        @assert Domains.obtain_surface_domain(soil.domain) == canopy.domain
+        @assert Domains.obtain_surface_domain(soilco2.domain) == canopy.domain
+
+        @assert soil.parameters.earth_param_set ==
+                soilco2.parameters.earth_param_set
+        @assert soil.parameters.earth_param_set ==
+                canopy.parameters.earth_param_set
+
+        # SoilCanopyModel-specific checks
+        # Runoff and sublimation are also automatically included in the soil model
+        @assert RootExtraction{FT}() in soil.sources
+        @assert Soil.PhaseChange{FT}() in soil.sources
+        @assert canopy.hydraulics.transpiration isa
+                Canopy.PlantHydraulics.DiagnosticTranspiration{FT}
+        @assert canopy_bc.ground isa PrognosticSoilConditions{FT}
+        @assert soilco2.drivers.met isa Soil.Biogeochemistry.PrognosticMet
+
+        return new{FT, MM, SM, VM}(soilco2, soil, canopy)
+    end
 end
 
-
-
 """
     SoilCanopyModel{FT}(;
         soilco2_type::Type{MM},
@@ -155,11 +196,7 @@ function SoilCanopyModel{FT}(;
         drivers = soilco2_drivers,
     )
 
-    return SoilCanopyModel{FT, typeof(soilco2), typeof(soil), typeof(canopy)}(
-        soilco2,
-        soil,
-        canopy,
-    )
+    return SoilCanopyModel{FT}(soilco2, soil, canopy)
 end
 
 """
diff --git a/src/standalone/Soil/Biogeochemistry/Biogeochemistry.jl b/src/standalone/Soil/Biogeochemistry/Biogeochemistry.jl
@@ -134,21 +134,29 @@ end
 
 """
 SoilCO2Model{FT}(;
-        parameters::SoilCO2ModelParameters{FT},
         domain::ClimaLand.AbstractDomain,
-        boundary_conditions::NamedTuple,
-        sources::Tuple,
         drivers::DT,
+        parameters = SoilCO2ModelParameters(FT),
+        boundary_conditions::BC = (
+            top = AtmosCO2StateBC(),
+            bottom = SoilCO2FluxBC((p, t) -> 0.0) # no flux
+        ),
+        sources::Tuple = (MicrobeProduction{FT}(),),
     ) where {FT, BC, DT}
 
 A constructor for `SoilCO2Model`.
+Defaults are provided for the parameters, boundary conditions, and sources.
+These can be overridden by providing the appropriate keyword arguments.
 """
 function SoilCO2Model{FT}(;
-    parameters::SoilCO2ModelParameters{FT},
     domain::ClimaLand.AbstractDomain,
-    boundary_conditions::BC,
-    sources::Tuple,
     drivers::DT,
+    parameters::SoilCO2ModelParameters{FT} = SoilCO2ModelParameters(FT),
+    boundary_conditions::BC = (
+        top = AtmosCO2StateBC(),
+        bottom = SoilCO2FluxBC((p, t) -> 0.0), # no flux
+    ),
+    sources::Tuple = (MicrobeProduction{FT}(),),
 ) where {FT, BC, DT}
     args = (parameters, domain, boundary_conditions, sources, drivers)
     SoilCO2Model{FT, typeof.(args)...}(args...)
diff --git a/src/standalone/Soil/Soil.jl b/src/standalone/Soil/Soil.jl
@@ -246,7 +246,7 @@ function EnergyHydrology{FT}(
         domain.space.subsurface,
         FT,
     ),
-    S_s = ClimaCore.Fields.zeros(domain.space.subsurface) .+ 1e-3,
+    S_s = ClimaCore.Fields.zeros(domain.space.subsurface) .+ FT(1e-3),
     z_0m = LP.get_default_parameter(FT, :soil_momentum_roughness_length),
     z_0b = LP.get_default_parameter(FT, :soil_scalar_roughness_length),
     emissivity = LP.get_default_parameter(FT, :emissivity_bare_soil),
diff --git a/src/standalone/Vegetation/Canopy.jl b/src/standalone/Vegetation/Canopy.jl
@@ -7,6 +7,7 @@ using LazyBroadcast: lazy
 using ClimaCore
 using ClimaCore.MatrixFields
 import ClimaCore.MatrixFields: @name, ⋅
+import ClimaUtilities.TimeVaryingInputs: AbstractTimeVaryingInput
 import ClimaUtilities.TimeManager: ITime, date
 import LinearAlgebra: I, dot
 using ClimaLand: AbstractRadiativeDrivers, AbstractAtmosphericDrivers
@@ -125,7 +126,7 @@ end
 """
     PlantHydraulicsModel{FT}(
         domain,
-        forcing::NamedTuple;
+        LAI::AbstractTimeVaryingInput;
         n_stem::Int = 0,
         n_leaf::Int = 1,
         h_stem::FT = FT(0),
@@ -147,8 +148,7 @@ end
 
 Creates a PlantHydraulicsModel on the provided domain, using default parameters.
 
-The required argument `forcing` should be a NamedTuple with the following field:
-- `LAI`: a function or ClimaUtilities TimeVaryingInput for leaf area index
+The required argument `LAI` should be a ClimaUtilities TimeVaryingInput for leaf area index.
 
 The following default parameters are used:
 - n_stem = 0 (unitless) - number of stem compartments
@@ -172,15 +172,15 @@ https://doi.org/10.1029/2023WR035481
 """
 function PlantHydraulicsModel{FT}(
     domain,
-    forcing::NamedTuple;
+    LAI::AbstractTimeVaryingInput;
     n_stem::Int = 0,
     n_leaf::Int = 1,
     h_stem::FT = FT(0),
     h_leaf::FT = FT(1),
     SAI::FT = FT(0),
     RAI::FT = FT(1),
     ai_parameterization = PlantHydraulics.PrescribedSiteAreaIndex{FT}(
-        forcing.LAI,
+        LAI,
         SAI,
         RAI,
     ),
@@ -476,6 +476,118 @@ function CanopyModel{FT}(;
     return CanopyModel{FT, typeof.(args)...}(args...)
 end
 
+"""
+    function CanopyModel{FT}(
+        domain::Union{
+            ClimaLand.Domains.Point,
+            ClimaLand.Domains.Plane,
+            ClimaLand.Domains.SphericalSurface,
+        },
+        forcing::NamedTuple,
+        LAI::AbstractTimeVaryingInput,
+        earth_param_set;
+        z_0m = FT(2),
+        z_0b = FT(0.2),
+        prognostic_land_components = (:canopy,),
+        autotrophic_respiration = AutotrophicRespirationModel{FT}(),
+        radiative_transfer = TwoStreamModel{FT}(domain),
+        photosynthesis = FarquharModel{FT}(domain),
+        conductance = MedlynConductanceModel{FT}(domain),
+        hydraulics = PlantHydraulicsModel{FT}(domain, forcing),
+        energy = BigLeafEnergyModel{FT}(),
+        sif = Lee2015SIFModel{FT}(),
+    ) where {FT, PSE}
+
+Creates a CanopyModel with the provided domain, forcing, and parameters.
+
+Defaults are provided for each canopy component model, which can be overridden
+by passing in a different instance of that type of model. Default parameters are also provided
+for each canopy component, and can be changed with keyword arguments. Please see the documentation
+of each component model for details on the default parameters.
+
+The required argument `forcing` should be a NamedTuple with the following field:
+- `atmos`: a PrescribedAtmosphere or CoupledAtmosphere object
+- `radiation`: a PrescribedRadiativeFluxes or CoupledRadiativeFluxes object
+- `ground`: a PrescribedGroundConditions, PrognosticGroundConditions, or PrognosticSoilConditions object
+
+The required argument `LAI` should be a ClimaUtilities TimeVaryingInput for leaf area index.
+
+When running the canopy model in standalone mode, set `prognostic_land_components = (:canopy,)`,
+while for running integrated land models, this should be a list of the individual models.
+This value of this argument must be the same across all components in the land model.
+"""
+function CanopyModel{FT}(
+    domain::Union{
+        ClimaLand.Domains.Point,
+        ClimaLand.Domains.Plane,
+        ClimaLand.Domains.SphericalSurface,
+    },
+    forcing::NamedTuple,
+    LAI::AbstractTimeVaryingInput,
+    earth_param_set;
+    z_0m = FT(2),
+    z_0b = FT(0.2),
+    prognostic_land_components = (:canopy,),
+    autotrophic_respiration = AutotrophicRespirationModel{FT}(),
+    radiative_transfer = TwoStreamModel{FT}(domain),
+    photosynthesis = FarquharModel{FT}(domain),
+    conductance = MedlynConductanceModel{FT}(domain),
+    hydraulics = PlantHydraulicsModel{FT}(domain, LAI),
+    energy = BigLeafEnergyModel{FT}(),
+    sif = Lee2015SIFModel{FT}(),
+) where {FT}
+    (; atmos, radiation, ground) = forcing
+
+    if typeof(energy) <: PrescribedCanopyTempModel{FT}
+        @info "Using the PrescribedAtmosphere air temperature as the canopy temperature"
+        @assert typeof(atmos) <: PrescribedAtmosphere{FT}
+    end
+
+    # Confirm that each spatially-varying parameter is on the correct domain
+    for p in map(
+        component -> propertynames(component.parameters),
+        [
+            autotrophic_respiration,
+            radiative_transfer,
+            photosynthesis,
+            conductance,
+            hydraulics,
+            energy,
+            sif,
+        ],
+    )
+        @assert !(p isa ClimaCore.Fields.Field) ||
+                axes(p) == domain.space.surface
+    end
+
+    boundary_conditions = AtmosDrivenCanopyBC(
+        atmos,
+        radiation,
+        ground,
+        prognostic_land_components,
+    )
+
+    # TODO: move z_0m, z_0b to ClimaParams so we can call `get_default_parameter`.
+    parameters = SharedCanopyParameters{FT, typeof(earth_param_set)}(
+        z_0m,
+        z_0b,
+        earth_param_set,
+    )
+    args = (
+        autotrophic_respiration,
+        radiative_transfer,
+        photosynthesis,
+        conductance,
+        hydraulics,
+        energy,
+        sif,
+        boundary_conditions,
+        parameters,
+        domain,
+    )
+    return CanopyModel{FT, typeof.(args)...}(args...)
+end
+
 ClimaLand.name(::CanopyModel) = :canopy
 
 """
diff --git a/test/integrated/full_land.jl b/test/integrated/full_land.jl
diff --git a/test/integrated/soil_canopy_lsm.jl b/test/integrated/soil_canopy_lsm.jl
diff --git a/test/standalone/Vegetation/canopy_model.jl b/test/standalone/Vegetation/canopy_model.jl
