# DiagnosticsMachine

ClimateMachine.DiagnosticsMachineModule
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.

source

### Diagnostic variables

ClimateMachine.DiagnosticsMachine.DiagnosticVarType
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.

source

### Kinds of diagnostic variables

ClimateMachine.DiagnosticsMachine.HorizontalAverageType
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).

source

### Creating diagnostic variables

ClimateMachine.DiagnosticsMachine.@pointwise_diagnosticMacro
@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
source
ClimateMachine.DiagnosticsMachine.@horizontal_averageMacro
@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.auxiliary,
curr_time,
)
D_t
end
d_h_tot[end] * states.prognostic.ρ
end
source

These use:

ClimateMachine.DiagnosticsMachine.generate_dv_interfaceFunction
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.

source
ClimateMachine.DiagnosticsMachine.generate_dv_functionFunction
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.

source

To generate:

ClimateMachine.DiagnosticsMachine.dv_argsFunction
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.

source
ClimateMachine.DiagnosticsMachine.dv_scaleFunction
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.

source

Diagnostic variable implementations must use the following type in their arguments:

### Creating diagnostics groups

ClimateMachine.DiagnosticsMachine.@diagnostics_groupMacro
@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.
source

### Defining new diagnostic variable kinds

New diagnostic variable kinds are being added. Currently, these must define the following functions (this list and the semantics of these functions are subject to change).

ClimateMachine.DiagnosticsMachine.dv_dg_points_indexFunction
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.

source
ClimateMachine.DiagnosticsMachine.dv_dg_elems_indexFunction
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.

source
ClimateMachine.DiagnosticsMachine.dv_dg_dimrangesFunction
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.

source
ClimateMachine.DiagnosticsMachine.dv_opFunction
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.

source