DiagnosticsMachine

DiagnosticsMachine

This module provides the infrastructure to extract diagnostics from a ClimateMachine simulation. Two key abstractions are defined: diagnostic variables and diagnostic groups. The StdDiagnostics module makes use of these to define many standard variables and groups which may be used directly by experiments. DiagnosticsMachine may be used by experiments to define specialized variables and groups.

init(mpicomm, param_set, dg, Q, starttime, output_dir)

Save the parameters into Settings, a container for simulation information necessary for all diagnostics groups.

DiagnosticVar

The base type for all diagnostic variables.

Various kinds of diagnostic variables (such as HorizontalAverage) are defined as abstract sub-types of this type and implement the group of functions listed at the end for use by the diagnostics group code generator.

A particular diagnostic variable is defined as a concrete sub-type of one of the kinds of diagnostic variables. The type itself is generated as are the group of functions below.

A diagnostic variable is always associated with a ClimateMachine configuration type, so as to allow the same name to be used by different configurations.

PointwiseDiagnostic

A diagnostic with the same dimensions as the original grid (DG or interpolated). Mostly used to directly copy out prognostic or auxiliary state variables.

HorizontalAverage

Targeted at AtmosLES configurations, produces a vector of length z of averages for the horizontal planes in the domain, where z is the interpolated grid height or the DG gridsx3id` over the nodes and elements (duplicates are not removed).

@pointwise_diagnostic(
    impl,
    config_type,
    name,
    units,
    long_name,
    standard_name,
    project = false,
)

Define name a point-wise diagnostic variable for config_type, with the specified attributes and the given implementation. If project is true, the variable will be projected along unit vectors (for cubed shell topologies) after interpolation.

Example

@pointwise_diagnostic(
    AtmosGCMConfigType,
    thv,
    "K",
    "virtual potential temperature",
    "virtual_potential_temperature",
) do (
    moisture::Union{EquilMoist, NonEquilMoist},
    atmos::AtmosModel,
    states::States,
    curr_time,
    cache,
)
    ts = get!(cache, :ts) do
        recover_thermo_state(atmos, states.prognostic, states.auxiliary)
    end
    virtual_pottemp(ts)
end

@horizontal_average(
    impl,
    config_type,
    name,
    units,
    long_name,
    standard_name,
    scale = nothing,
)

Define name, a horizontal average diagnostic variable for config_type with the specified attributes and the given implementation. In order to produce a density-weighted average, scale must be specified as the name of the horizontal average diagnostic variable for density.

Example

@horizontal_average(
    AtmosLESConfigType,
    w_ht_sgs,
    "kg kg^-1 m s^-1",
    "vertical sgs flux of total specific enthalpy",
    "",
    rho,
) do (atmos::AtmosModel, states::States, curr_time, cache)
    ts = get!(cache, :ts) do
        recover_thermo_state(atmos, states.prognostic, states.auxiliary)
    end
    D_t = get!(cache, :D_t) do
        _, D_t, _ = turbulence_tensors(
            atmos,
            states.prognostic,
            states.gradient_flux,
            states.auxiliary,
            curr_time,
        )
        D_t
    end
    d_h_tot = -D_t .* states.gradient_flux.∇h_tot
    d_h_tot[end] * states.prognostic.ρ
end

generate_dv_interface(
    dvtype,
    config_type,
    name,
    units,
    long_name,
    standard_name,
)

Generate the type for a diagnostic variable, add an instance of the type into AllDiagnosticVars, and generate dv_name and dv_attrib.

generate_dv_function(dvtype, config_type, name, impl)

Generate dv_args for a diagnostic variable as well as the implementation function: dv_<dvtype>, adding the configuration type and the diagnostic variable type as the first two parameters for dispatch.

The implementation must be defined as:

f(
    [<component-name>::<component-type>,]
    bl::<balance-law-type>,
    states::States,
    curr_time::Float64,
    cache::Dict{Symbol, Any},
)

Where <component-name> is the name of the property within the balance law type, <component-type> and <balance-law-type> are used for dispatch, and cache may be used to store intermediate computations.

generate_dv_scale(dvtype, config_type, name, scale)

Generate dv_scale for a diagnostic variable, returning the diagnostic variable with which it is to be scaled.

generate_dv_project(dvtype, config_type, name, scale)

Generate dv_project for a diagnostic variable, returning true if the diagnostic variable is to be projected.

dv_name(::CT, ::DVT) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns the name of the diagnostic variable as a String. Generated.

dv_attrib(::CT, ::DVT) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns a Dict of diagnostic variable attributes, primarily for NetCDF. Generated.

dv_args(::CT, ::DVT) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns a tuple of (arg_name, arg_type, slurp, default) (as returned by MacroTools.splitarg for the arguments specified by the implementation of the diagnostic variable.

dv_scale(::CT, ::DVT) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

If scaling was specified for the diagnostic variable, return the diagnostic variable with which the scaling should be done, otherwise return nothing.

dv_project(::CT, ::DVT) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Return true if the specified diagnostic variable should be projected after interpolation.

States

Composite of the various states, used as a parameter to diagnostic variable implementations.

@diagnostics_group

Generate the functions needed to establish and use a DiagnosticsGroup containing the named DiagnosticVars. In particular, this creates name(), which creates the diagnostics group.

Arguments

• name: a string that uniquely identifies the group.
• config_type: a ClimateMachineConfigType.
• params_type: a subtype of DiagnosticsGroupParams or Nothing. An instance of this type is created in dgngrp.params when the group is set up.
• init_fun: a function that is called when the group is initialized (called with (dgngrp, curr_time);may be (_...) -> nothing). Use this to initialize any required state, such as in dgngrp.params.
• interpolate: one of InterpolateBeforeCollection, InterpolateAfterCollection or NoInterpolation.
• dvarnames: one or more diagnostic variables. Together with the config_type, identify the DiagnosticVars to be included in the group.

dv_dg_points_length(::CT, ::Type{DVT}) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns an expression that evaluates to the length of the points dimension of a DG array of the diagnostic variable type.

dv_dg_points_index(::CT, ::Type{DVT}) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns an expression that, within a @traverse_dg_grid, evaluates to an index into the points dimension of a DG array of the diagnostic variable type.

dv_dg_elems_length(::CT, ::Type{DVT}) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns an expression that evaluates to the length of the elements dimension of a DG array of the diagnostic variable type.

dv_dg_elems_index(::CT, ::Type{DVT}) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns an expression that, within a @traverse_dg_grid, evaluates to an index into the elements dimension of a DG array of the diagnostic variable type.

dv_dg_dimnames(::CT, ::Type{DVT}) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns a tuple of the names of the dimensions of the diagnostic variable type for when interpolation is not used.

dv_dg_dimranges(::CT, ::Type{DVT}) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns a tuple of expressions that evaluate to the range of the dimensions for the diagnostic variable type for when interpolation is not used.

dv_op(::CT, ::Type{DVT}, lhs, rhs) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}

Returns an expression that, within a @traverse_dg_grid, evaluates to an assignment of rhs to lhs, where rhs is the implementation of the diagnostic variable and lhs is the appropriate location in the array containing the computed diagnostic variable values.

dv_reduce(::CT, ::Type{DVT}, array_name) where {
    CT <: ClimateMachineConfigType,
    DVT <: DiagnosticVar,
}