Reference

check_extraneous_fields(::Type{T}, data::Dict{String,Any}) where {T<:AbstractModelComponent}

Check if the input dictionary contains any keys that are not part of the required fields for type T.

Arguments

• T: Type of model component to check fields against
• data: Dictionary containing fields to validate
• required_fields: List of required fields for the model component. This is typically obtained from get_required_fields(T) or fieldnames(T)

Throws

• ArgumentError: If any extraneous keys are found in the data dictionary

get_calculated_fields(::Type{T}) where {T<:AbstractModelComponent}

Get a list of calculated fields for a given model component type. Calculated fields are those that are computed based on other fields and should not be provided when creating a model component. By default, returns an empty list. Components should override this method if they have calculated fields.

Arguments

• T: Type of model component to get calculated fields for

Returns

• Vector{Symbol}: List of calculated field names

get_dimensions(::Type{T}, data) where {T<:AbstractModelComponent}

Return a dictionary of dimension specifications for a given model component type. By default returns an empty dictionary. This method should be overridden by concrete types to specify their required dimensions.

Arguments

• T: Type of the model component
• data: Data source containing dimension information

Returns

• Dict: Dictionary mapping variable names to their dimension specifications

get_optional_fields(::Type{T}) where {T<:AbstractModelComponent}

Get a list of optional fields for a given model component type. Optional fields are those that can be omitted when creating a model component. By default, returns an empty list. Components should override this method if they have optional fields.

Arguments

• T: Type of model component to get optional fields for

Returns

• Vector{Symbol}: List of optional field names

get_required_fields(::Type{T}) where {T<:AbstractModelComponent}

Returns an empty array of symbols representing required fields for a given AbstractModelComponent type. This is a default method that can be specialized for specific subtypes that need to define their own required fields.

Returns

• Vector{Symbol}: A vector of symbols with the fields required to initialize the AbstractModelComponent type

initialize(::Type{FT}, ::Type{T}, data::Dict{String,Any}, args...) where {FT<:AbstractFloat, T<:AbstractModelComponent}

Initialize model components with optional fields. The model component requires a keyword constructor.

Arguments

• ::Type{FT}: Floating point precision type (e.g., Float32 or Float64)
• ::Type{T}: Component type constructor that subclasses AbstractModelComponent
• data: Data source (e.g., Dict for Parameters, NCDataset for State/Auxiliary variables)
• args...: Additional arguments passed to preprocess_fields

Returns

• T{FT}: Initialized component struct of type T with floating point precision FT

initialize_field(
    ::Type{FT},
    data::NCDataset,
    name::String,
    dims::Tuple;
    default::Union{Nothing,Number} = nothing
) where {FT<:AbstractFloat}

Initialize a field array with specified dimensions and optionally set initial conditions.

Arguments

• FT: Float type to use for the field array (e.g., Float32, Float64)
• data: NCDataset containing source data
• name: Name of the variable in the dataset
• dims: Tuple specifying the dimensions of the field array
• default: Optional default value to use if no initial condition is found

Returns

• Array{FT}: Initialized array with the specified dimensions, filled with initial conditions if available

preprocess_fields(::Type{FT}, ::Type{T}, data, args...) where {FT<:AbstractFloat,T<:AbstractModelComponent}

Preprocess fields before the initialization of a given AbstractModelComponent type.

Arguments

• FT: Type parameter for floating point precision
• T: Type parameter for model components
• data: Input data to be preprocessed
• args...: Additional arguments

Returns

• Returns the input data without modifications

This is a default implementation that passes through the input data unchanged. Custom preprocessing can be implemented by defining methods for specific types.

preprocess_fields(
    ::Type{FT},
    ::Type{T},
    data::NCDataset
) where {FT<:AbstractFloat,T<:AbstractAuxiliaryVariables}

Initialize fields for auxiliary variables based on their dimension specifications.

Arguments

• FT: Float type to use for the fields
• T: Type of auxiliary variables
• data: NCDataset containing the source data

Returns

• Dict{String,Any}: Dictionary of initialized fields

validate_fields(::Type{T}, data) where {T<:AbstractModelComponent}
validate_fields(::Type{T}, data::Dict{String,Any}) where {T<:AbstractModelComponent}

Performs some checks on the fields passed to initialize the AbstractModelComponent type.

Returns

• nothing: If all fields are valid, the function returns nothing

AbstractModelComponent{FT<:AbstractFloat}

The base abstract type for all model components. Parametrized by the floating-point type FT used for numerical calculations.

AbstractIndividualModelComponent{FT<:AbstractFloat} <: AbstractModelComponent{FT}

Abstract type for individual model components that represent discrete entities in the model. These components operate on single points or objects without height-dependency.

Subtypes include parameters, state variables, forcing inputs, and auxiliary variables for individual model elements.

AbstractHeightDependentModelComponent{FT<:AbstractFloat} <: AbstractIndividualModelComponent{FT}

Abstract type for model components that vary with height or depth in a vertical profile. These components represent quantities that change along a vertical dimension and typically contain values at different height/depth levels.

AbstractModelComponentSet{FT<:AbstractFloat} <: AbstractModelComponent{FT}

Abstract type for collections of related model components. Component sets group multiple individual components of the same category together, providing organization and encapsulation of related model elements.

AbstractAuxiliaryVariables{FT<:AbstractFloat} <: AbstractIndividualModelComponent{FT}

Abstract type for auxiliary variables that provide additional information or intermediate calculations in the model. These variables are not part of the core model state but are used to support model calculations.

See AbstractAuxiliaryVariableSet for an example of usage.

AbstractHeightDependentAuxiliaryVariables{FT<:AbstractFloat} <: AbstractHeightDependentModelComponent{FT}

Abstract type for height-dependent auxiliary variables. These variables provide additional information or intermediate calculations that vary with height in the model.

See AbstractAuxiliaryVariableSet for an example of usage.

AbstractAuxiliaryVariableSet{FT<:AbstractFloat} <: AbstractModelComponentSet{FT}

Abstract type for collections of auxiliary variables. Auxiliary variable groups multiple auxiliary variables together, providing organization and encapsulation of related model elements.

Examples

Base.@kwdef struct HeightDependentHydrologicStateVariables{FT<:AbstractFloat} <:
                   AbstractHeightDependentModelComponent{FT}
    An::Matrix{FT} # Net CO₂ assimilation [μmol m⁻² s⁻¹]
    Dr::Matrix{FT} # Root distribution [-]
end

Base.@kwdef struct HydrologicAuxiliaryVariables{FT<:AbstractFloat} <:
                   AbstractAuxiliaryVariables{FT}
    high::HeightDependentHydrologicStateVariables{FT}
    low::HeightDependentHydrologicStateVariables{FT}

    alp_soil::Vector{FT} # Soil albedo [-]
    b_soil::Vector{FT} # Soil retention curve parameter [-]
end

Base.@kwdef struct BiogeochemistryAuxiliaryVariables{FT<:AbstractFloat} <:
                   AbstractAuxiliaryVariables{FT}
    BLit::Matrix{FT}
    NavlI::Matrix{FT}
end

Base.@kwdef struct AuxiliaryVariableSet{FT<:AbstractFloat} <:
                   AbstractAuxiliaryVariableSet{FT}
    hydrologic::HydrologicAuxiliaryVariables{FT}
    biogeochemistry::BiogeochemistryAuxiliaryVariables{FT}
end

AbstractForcingInputs{FT<:AbstractFloat} <: AbstractIndividualModelComponent{FT}

Abstract type for forcing inputs that drive the model. Forcing inputs represent external factors that influence the model behavior, such as meteorological or anthropogenic data.

See AbstractForcingInputSet for an example of usage.

AbstractHeightDependentForcingInputs{FT<:AbstractFloat} <: AbstractHeightDependentModelComponent{FT}

Abstract type for height-dependent forcing inputs. These inputs vary with height or depth in the model and control the behavior of the model at different levels.

See AbstractForcingInputSet for an example of usage.

AbstractForcingInputSet{FT<:AbstractFloat} <: AbstractModelComponentSet{FT}

Abstract type for collections of forcing inputs. Forcing input sets group multiple forcing inputs together, providing organization and encapsulation of related model elements.

Examples

Base.@kwdef struct AnthropogenicInputs{FT<:AbstractFloat} <: AbstractForcingInputs{FT}
    Salt::Vector{FT} # Salt concentration
    IrD::Vector{FT} # Drip irrigation
end

Base.@kwdef struct MeteorologicalInputs{FT<:AbstractFloat} <: AbstractForcingInputs{FT}
    Pr::Vector{FT} # Precipitation
    Ta::Vector{FT} # Air temperature at reference height
    Ws::Vector{FT} # Wind speed at reference height
end

Base.@kwdef struct ForcingInputSet{FT<:AbstractFloat} <: AbstractForcingInputSet{FT}
    anthropogenic::AnthropogenicInputs{FT}
    meteorological::MeteorologicalInputs{FT}
end

AbstractParameters{FT<:AbstractFloat} <: AbstractIndividualModelComponent{FT}

Abstract type for model parameters that define the model structure and behavior. Parameters are fixed values or coefficients that control the model dynamics.

See AbstractParameterSet for an example of usage.

AbstractHeightDependentParameters{FT<:AbstractFloat} <: AbstractHeightDependentModelComponent{FT}

Abstract type for height-dependent model parameters. These parameters vary with height or depth in the model and control the behavior of the model at different levels.

See AbstractParameterSet for an example of usage.

AbstractParameterSet{FT<:AbstractFloat} <: AbstractModelComponentSet{FT}

Abstract type for collections of model parameters. Parameter sets group multiple parameters together, providing organization and encapsulation of related model elements.

Examples

Base.@kwdef struct SoilParameters{FT<:AbstractFloat} <: AbstractParameters{FT}
    Osat::FT # Saturation moisture 0 kPa
    Ohy::FT # Hygroscopic Moisture Evaporation cessation 10000 kPa
end

Base.@kwdef struct HeightDependentVegetationParameters{FT<:AbstractFloat} <:
                   AbstractHeightDependentParameters{FT}
    Knit::FT # Canopy nitrogen decay coefficient
    FI::FT # Intrinsic quantum efficiency
end

Base.@kwdef struct VegetationParameters{FT<:AbstractFloat} <: AbstractParameters{FT}
    high::HeightDependentParameters{FT}
    low::HeightDependentParameters{FT}

    KcI::FT # Interception drainage rate coefficient.
    Sllit::FT # Specific leaf area of litter

end

Base.@kwdef struct ParameterSet{FT<:AbstractFloat} <: AbstractParameterSet{FT}
    soil::SoilParameters{FT}
    vegetation::VegetationParameters{FT}
end

AbstractStateVariables{FT<:AbstractFloat} <: AbstractIndividualModelComponent{FT}

Abstract type for model state variables that represent the internal state of the model. State variables are dynamic quantities that change over time and are used to track the model evolution.

See AbstractStateVariableSet for an example of usage.

AbstractHeightDependentStateVariables{FT<:AbstractFloat} <: AbstractHeightDependentModelComponent{FT}

Abstract type for height-dependent model state variables. These variables represent the internal state of the model that varies with height or depth in the model.

See AbstractStateVariableSet for an example of usage.

AbstractStateVariableSet{FT<:AbstractFloat} <: AbstractModelComponentSet{FT}

Abstract type for collections of model state variables. State variable sets group multiple state variables together, providing organization and encapsulation of related model elements.

Examples

Base.@kwdef struct HydrologicStateVariables{FT<:AbstractFloat} <:
                   AbstractStateVariables{FT}

    V::Matrix{FT} # Liquid water volume [mm]
    Tdp::Matrix{FT} # Soil temperature [°C]
end

Base.@kwdef struct HeightDependentVegetationStateVariables{FT<:AbstractFloat} <:
                   AbstractHeightDependentModelComponent{FT}
    AgeDL::Matrix{FT} # Average age of dead leaves
    B::Matrix{FT} # Biomass/carbon pools
end

Base.@kwdef struct VegetationStateVariables{FT<:AbstractFloat} <:
                   AbstractStateVariables{FT}
    high::HeightDependentVegetationStateVariables{FT}
    low::HeightDependentVegetationStateVariables{FT}
end

Base.@kwdef struct StateVariableSet{FT<:AbstractFloat} <:
                   AbstractStateVariableSet{FT}
    hydrologic::HydrologicStateVariables{FT}
    vegetation::VegetationStateVariables{FT}
end