[REFACTOR] Clean-up composite types

[hsolleder]

Description

The current version of the model components includes state, auxiliary variables, parameters and forcing inputs of various levels. However, this nomenclature is redundant and could/should be stored on side of the concrete package. AbstractStateVariableSet and AbstractAuxiliaryVariableSet, for instance, differ only by the "flavor" of variables (fields) of these composite types.

Overall, we can distinguish three composite types

• container for array-like and scalars only (e.g., parameters, height-dependent hydrologic auxiliary variable)
• container for containers only (e.g., parameterset)
• containers for containers as well as array-like and scalars (e.g. hydrologic state variables in TethysChloris.jl)

Any concrete composite type representing variables of Tethys-Chloris will be a subtype of one of these three types. Therefore, I suggest replacing the current structure of the model components with a simpler structure, namely

• Keep AbstractModelComponent
• Add three abstract subtypes of AbstractModelComponent (names up for discussion)
  • AbstractHybridModelComponent
  • AbstractVariablesModelComponent
  • AbstractSetModelComponnet

Thoughts @sphamba ?

[sphamba]

@hsolleder If there are methods that are specific to each subtype, that could be useful. Otherwise, I think they would all fall into the category for "containers for containers, array-like, and scalars". If one day, someone wants to convert a HybridModelComponent or a VariablesModelComponent into a SetModelCompenent, it should not be made too complicated (i.e. need to change the code at too many places).

[hsolleder]

@sphamba Correction: I would create either two abstract subtypes, and make the container for array-like a subtype of the hybrid, or make he container-only and array-only subtypes of AbstractModelComponent... or even create no subtypes and only use AbstractModelComponent

The use cases I see are the following

1. Relaxing the typing in the functions

Currently, TethysChloris.jl requires highly specific model components as parameters, but these requirements are too strict (relates to this UrbanTethysChloris.jl issue).

For instance, the biogeo_leakage function requires BiogeochemistryParameters to be passed as an argument

biogeo_leakage(
    B::Vector{FT},
    Lk::FT,
    V::FT,
    BiogeoPar::ModelComponents.Parameters.BiogeochemistryParameters{FT},
) where {FT<:AbstractFloat}

However, this function uses only 7 of the 50+ array-like fields of BiogeochemistryParameters. Instead of requiring this specific type, we could relax our requirement and simply ask for a AbstractVariablesModelComponent{FT} (or even a AbstractModelComponent{FT}, while checking at the start of the function that the required fields for this function to work properly are present (or letting the function crash). This would enable users to create their own composite types, adding fields as they please.

The reason this hierarchy of composite types and subtypes was created was thematic, and remains useful to initialize the model components (and potentially dispatch). For instance, for model variables in UrbanTethyscChloris, creating

abstract type AbstractModelVariables{FT<:AbstractFloat} <: AbstractIndividualModelComponent{FT} end

makes sense because a lot of model variables can be initalized as arrays filled with zeros, using one of the two specializations

function TethysChlorisCore.preprocess_fields(
    ::Type{FT}, ::Type{T}, data::Dict{String,Any}, params::Tuple
) where {FT<:AbstractFloat,T<:AbstractModelVariables}
    processed = Dict{String,Any}()

    vars = String.(fieldnames(T))

    for var in vars
        processed[var] = zeros(FT, ())
    end

    return processed
end

function TethysChlorisCore.preprocess_fields(
    ::Type{FT}, ::Type{T}, data::Dict{String,Any}, params::Tuple, args...
) where {FT<:AbstractFloat,T<:AbstractModelVariables}
    processed = Dict{String,Any}()

    dimensions = get_dimensions(T, data, params, args...)

    for (var, dims) in dimensions
        processed[var] = zeros(FT, dims)
    end

    return processed
end

This initialization is the same as that of AuxiliaryVariables in TethysChloris.jl. A similar approach is taking for state variables in TethysChloris.jl, but given the variety of initial conditions, a specialization of preprocess_fields is written for each state variable set.

2. Writing high-level generic functions

Rather than having to specialize countless functions because of the large number of subtypes, having these three subtypes would allow to specialize some of the functions and clean-up the code.

Initialization

Currently, containers of containers initialize the nested containers in preprocess_fields. I guess this is acceptable, but could be streamlined to include an initialization of nested composite types in initialize, potentially allowing the automatization of this initialization, as well as integrating the initial conditions.

Currently, preprocess_fields is used both to create new array-like fields based on the input values (e.g. for CellProperties in TethysChloris.jl)

function TethysChlorisCore.preprocess_fields(
    ::Type{FT},
    ::Type{CellProperties},
    data::Dict{String,Any},
) where {FT<:AbstractFloat}
    processed = copy(data)

    Slo_top = FT(data["Slo_top"])
    cellsize = FT(data["cellsize"])
    processed["Asur"] = 1.0 / cos(atan(Slo_top))
    processed["Slo_pot"] = Slo_top
    processed["aTop"] = 1000.0 * cellsize^2 / cellsize
    processed["cosalp"] = cos(atan(Slo_top))
    processed["sinalp"] = sin(atan(Slo_top))
    processed["aTop_scaled"] = processed["aTop"] * processed["Asur"] / processed["Ared"]

    return processed
end

as it is to initialize nested composite types

function TethysChlorisCore.preprocess_fields(
    ::Type{FT},
    ::Type{VegetationParameters},
    data::Dict{String,Any},
) where {FT<:AbstractFloat}
    processed = copy(data)

    # Initialize each component
    processed["low"] = initialize_heightdependent_parameters(FT, data["low"])
    processed["high"] = initialize_heightdependent_parameters(FT, data["high"])

    return processed
end

or to initialize array-like fields to the correct dimensions.

getindex and setindex

In UrbanTethysChloris, the current implementation of the getindex and setindex specialization for model variables is the following

function Base.getindex(
    obj::T, idx::Int
) where {FT<:AbstractFloat,T<:AbstractHumidityVariablesSubset{FT,1}}
    scalar_type = typeof(obj).name.wrapper{FT,0}
    fieldvals = Dict{Symbol,Any}()
    for field in fieldnames(typeof(obj))
        fieldvals[field] = fill(getproperty(obj, field)[idx])
    end
    return scalar_type(; fieldvals...)
end

function Base.setindex!(
    obj::T, value::S, idx::Int
) where {
    FT<:AbstractFloat,
    T<:AbstractHumidityVariablesSubset{FT,1},
    S<:AbstractHumidityVariablesSubset{FT,0},
}
    for field in fieldnames(typeof(obj))
        getproperty(obj, field)[idx] = getproperty(value, field)
    end
    return obj
end

This approach will only work containers of array-like fields, as it will fail with containers of containers, and hybrid structs. For instance, the containers of containers for humidity-related variables requires another specialized initialization

function Base.getindex(
    obj::T, idx::Int
) where {FT<:AbstractFloat,T<:AbstractHumidityVariables{FT,1}}
    scalar_type = typeof(obj).name.wrapper{FT,0}
    fieldvals = Dict{Symbol,Any}()
    for field in fieldnames(typeof(obj))
        fieldvals[field] = getindex(getproperty(obj, field), idx)
    end
    return scalar_type(; fieldvals...)
end

function Base.setindex!(
    obj::T, value::S, idx::Int
) where {
    FT<:AbstractFloat,T<:AbstractHumidityVariables{FT,1},S<:AbstractHumidityVariables{FT,0}
}
    for field in fieldnames(typeof(obj))
        getproperty(obj, field)[idx] = getproperty(value, field)
    end
    return obj
end

Furthermore, since humidity variables and radiation flux variables are subtypes of different abstract types, this requires code duplication.