Computing and saving diagnostics

I want to compute and output a diagnostic variable

From a YAML file

If you configure your simulation with YAML files, there are two important options. When output_default_diagnostics is set to true, the default diagnostics for the given atmospheric model will be output. Note that they might be incompatible with your simulation (e.g., you want to output hourly maxima when the timestep is 4 hours).

Second, you can specify the diagnostics you want to output directly in the diagnostics section of your YAML file. For instance:

diagnostics:
  - short_name: rhoa
    output_name: a_name
    period: 3hours
    writer: nc
  - reduction_time: average
    short_name: rhoa
    period: 12hours
    writer: h5
    compute_every: 2steps

This adds two diagnostics (both for rhoa). The period keyword identifies the period over which to compute the reduction and how often to save to disk. output_name is optional, and if provided, it identifies the name of the output file. The compute_every keyword identifies how often the field should be computed; it applies only when a reduction_time is specified. Without a reduction, the field is computed on the output schedule.

For multiple diagnostics with the same specs, you can also pass a vector of short_names directly, as in

diagnostics:
  - short_name: [rhoa, ua, ta]
    reduction_time: average
    period: 12hours

The default writer is NetCDF. If writer is nc or netcdf, the output is remapped non-conservatively on a Cartesian grid and saved to a NetCDF file. Remapping is most commonly used for cubed-sphere runs; column and box configurations are also supported.

Writing in pressure coordinates

You can write diagnostics to NetCDF files in pressure coordinates by setting pressure_coordinates to true. This replaces the vertical dimension z in the NetCDF files with the dimension pressure_level. For more information about writing diagnostics in pressure coordinates, see the documentation in ClimaDiagnostics.

diagnostics:
  - short_name: [pfull, wa, va, rv, hus, ke]
    period: 1days
    pressure_coordinates: true

From a script

The simplest way to get started with diagnostics is to use the defaults for your atmospheric model. ClimaAtmos defines a function default_diagnostics. You can execute this function on an AtmosModel or on any of its fields to obtain a list of diagnostics ready to be passed to the simulation. So, for example

model = ClimaAtmos.AtmosModel(; microphysics_model = ClimaAtmos.DryModel())

diagnostics = ClimaAtmos.default_diagnostics(
    model, duration, start_date, t_start;
    output_writer, topography,
)
# => List of diagnostics that include the ones specified for the DryModel

(DiagnosticsConfig(; default = true) is the higher-level entry point that supplies these arguments for you.)

Technically, the diagnostics are represented as ScheduledDiagnostic objects, which contain information about what variable has to be computed, how often, where to save it, and so on (read below for more information on this). You can construct your own lists of ScheduledDiagnostics starting from the variables defined by ClimaAtmos. The DiagnosticVariables in ClimaAtmos are identified by their short, unique names, so that you can access them directly with the function get_diagnostic_variable. One way to do so is by using the provided convenience functions for common operations, e.g., continuing the previous example

append!(
    diagnostics,
    daily_maxs(FT, "rhoa", "ta"; output_writer, start_date, t_start),
)

Now diagnostics will also contain the instructions to compute the daily maxima of the air density (rhoa) and air temperature (ta).

The diagnostics built into ClimaAtmos are collected in Available diagnostic variables.

If you are using ClimaAtmos with a script-based interface, you have complete flexibility in your diagnostics. Read the section about the low-level interface to see how to implement custom diagnostics, reductions, or writers.

The low-level interface

See the ClimaDiagnostics documentation for more information about the low-level interface.

The NetCDF output

The NetCDF writer in ClimaAtmos saves different diagnostics to different files in the same output folder. Files are named after a combination of the diagnostic variable short_name and the details of the temporal reduction. Inside each NetCDF file, there is only one diagnostic variable, along with the various dimensions (e.g., lat, lon, and z/z_reference).

When topography is present, a new 1D dimension z_reference is defined. This dimension does not have direct physical meaning but can be assumed to be the "z" axis. Along with this dimension, a new variable z is saved to the NetCDF file. In this case, z is a multidimensional array (in general 3D), and z[i, j, k] gives the elevation above sea level of the point with indices [i, j, k].

Adding a new diagnostic variable

Defining new diagnostic variables is developer territory; see Adding a Diagnostic Variable in the Developer Guide.