Edit on GitHub

SimOutput

The SimOutput module provides utilities for output operations including diagnostics and performance analysis.

Benchmarking Analysis

The benchmark analysis functions help compare performance metrics (e.g. SYPD, or simulated years per day) between different simulation runs. This information is formatted into a table format using PrettyTables.jl, and is sent to Slack automatically each time the "benchmarks" buildkite pipeline is run.

Functions

ClimaCoupler.SimOutput.get_run_info — Function
get_run_info(parsed_args, run_type)

Use the input parsed_args to get the job ID and artifacts directories for the GPU run of the given run_type.

run_type must be one of "coupled", "coupledio", "atmos", "atmosdiagedmf", "coupledprogedmfcoarse", or "coupledprogedmffine".

source

Simulation and Observation Data

These functions provide dictionaries mapping diagnostic variable names to preprocessed simulation and observational data for use in leaderboard comparisons. They are used by compute_leaderboard to load and prepare variables for comparison against observations.

For more information about adding variables to the leaderboard, see the Leaderboard documentation.

Functions

ClimaCoupler.SimOutput.get_sim_var_dict — Function
get_sim_var_dict(diagnostics_folder_path)

Return a dictionary mapping short names to OutputVar containing preprocessed simulation data. This is used by the function compute_leaderboard.

To add a variable for the leaderboard, add a key-value pair to the dictionary sim_var_dict whose key is the short name of the variable and the value is an anonymous function that returns a OutputVar. For each variable, any preprocessing should be done in the corresponding anonymous function which includes unit conversion.

The variable should have only three dimensions: latitude, longitude, and time.

source
ClimaCoupler.SimOutput.get_obs_var_dict — Function
get_obs_var_dict()

Return a dictionary mapping short names to OutputVar containing preprocessed observational data. This is used by the function compute_leaderboard.

To add a variable for the leaderboard, add a key-value pair to the dictionary obs_var_dict whose key is the short name of the variable and the value is an anonymous function that returns a OutputVar. The function must take in a start date which is used to align the times in the observational data to match the simulation data. The short name must be the same as in sim_var_dict in the function sim_var_dict. For each variable, any preprocessing is done in the corresponding anonymous function which includes unit conversion and shifting the dates.

The variable should have only three dimensions: latitude, longitude, and time.

source

Diagnostics Setup

ClimaCoupler.jl utilizes other packages in the CliMA ecosystem to generate and visualize diagnostics, namely ClimaDiagnostics.jl and ClimaAnalysis.jl.

Default AMIP diagnostics

We output a set of default diagnostics for all AMIP runs. These currently include the following fields:

Atmospheric quantiies:

  • air temperature at the bottom of the atmosphere (3D)
  • eastward near-surface wind (3D)
  • specific humidity (3D)
  • mass fraction of cloud liquid water (3D)
  • net top-of-atmosphere fluxes (3D)
  • precipitation (2D)
  • surface temperature (2D)

Coupler quantities

  • turbulent energy fluxes (2D)

These diagnostics are all averaged over a period of time that depends on the length of the overall simulation according to the following rule:

  • simulation length >= 90 days: 1-month mean
  • simulation length >= 30 days and < 90 days: 10-day mean
  • simulation length >= 1 day and < 30 days: 1-day mean
  • simulation length < 1 day: 1-hour mean

How to add a new diagnostic variable

Adding a diagnostic for a ClimaCoupler quantity

For diagnostics that come from coupler fields or that are computed using input from multiple component models, we set up the diagnostics by directly creating ClimaDiagnostics.jl objects.

Specifically, we first create a DiagnosticVariable object containing the variable's name, units, any comments, and the function to compute it. This is then used to create a ScheduledDiagnostic variable, which includes saving and output time information. Once we have created a ScheduledDiagnostic for each variable we're interested in, we collect them in a vector and pass this to our DiagnosticsHandler object.

An example of this process for the combined turbulent energy flux, F_turb_energy, can be found in src/SimOutput/diagnostics.jl in the SimOutput.diagnostics_setup function.

For more information about this process, please see the ClimaDiagnostics.jl documentation.

Adding a diagnostic for a CliMA component model quantity

Many of our current diagnostics are values that we access directly from a component model. To add a new diagnostic of this kind, you can add a new method add_diagnostic_variable! extending this function from the component model package's Diagnostics module.

For example, to add a diagnostic for the atmosphere model, you can extend ClimaAtmos.Diagnostics.add_diagnostic_variable! in that model's extension.

For more information about this function and the form it takes, please see the ClimaDiagnostics.jl documentation.

Visualizing diagnostics

ClimaCoupler.jl uses ClimaAnalysis.jl to parse and visualize the outputs saved using ClimaDiagnostics.jl.

For more information about ClimaAnalysis.jl, please see that package's documentation.

Functions

ClimaCoupler.SimOutput.diagnostics_setup — Function
diagnostics_setup(fields, output_dir, start_date, t_start, diagnostics_dt)

Set up the default diagnostics for an AMIP simulation, using ClimaDiagnostics. The diagnostics are saved to NetCDF files. Currently, this just includes a diagnostic for turbulent energy fluxes.

Return a DiagnosticsHandler object to coordinate the diagnostics.

source