Public APIs

DiagnosticsHandler

A struct that contains the scheduled diagnostics, ancillary data and areas of memory needed to store and accumulate results.

orchestrate_diagnostics(integrator, diagnostic_handler::DiagnosticsHandler)

Loop over all the ScheduledDiagnostics in diagnostic_handler and run compute and output according to their schedule functions.

DiagnosticsCallback(diagnostics_handler::DiagnosticsHandler)

Translate a DiagnosticsHandler into a SciML callback ready to be used.

IntegratorWithDiagnostics(integrator,
                          scheduled_diagnostics;
                          state_name = :u,
                          cache_name = :p)

Return a new integrator with diagnostics defined by scheduled_diagnostics.

IntegratorWithDiagnostics is conceptually similar to defining a DiagnosticsHandler, constructing its associated DiagnosticsCallback, and adding such callback to a given integrator.

The new integrator is identical to the previous one with the only difference that it has a new callback called after all the other callbacks to accumulate/output diagnostics.

IntegratorWithDiagnostics ensures that the diagnostic callbacks are initialized and called after everything else is initialized and computed.

IntegratorWithDiagnostics assumes that the state is integrator.u and the cache is integrator.p. This behavior can be customized by passing the state_name and cache_name keyword arguments.

AbstractSchedule

AbstractSchedules are structs that behave like functions and are used for the purpose of defining a schedule to be used in ScheduledDiagnostics. They also may contain additional information.

short_name(schedule)

Short of name of the given schedule. Typically used in names of files/datasets.

long_name(schedule)

Long of name of the given schedule. Typically used in attributes.

DivisorSchedule

True when the iteration number is evenly divisible by a given number.

This is roughly equivalent to: "run this call back every N steps", with the difference that no initial offset is possible.

EveryStepSchedule()

Return a schedule that executes at the end of every step.

EveryDtSchedule

True every time the current time is larger than the previous time this schedule was true + Dt.

Note, this function performs no checks on whether the step is aligned with dt or not.

EveryCalendarDtSchedule

Returns true if dt has passed since the last time this schedule was true. dt here is a Dates.Period (e.g., Dates.Month(1)).

EveryCalendarDtSchedule(dt, t::ITime)

Construct an EveryCalendarDtSchedule from dt and t, where dt is a period or an ITime and t is an ITime. The start date of the schedule is epoch(t), and the last date on which the schedule returns true is date(t).

DiagnosticVariable(;
    compute!,
    short_name = "",
    long_name = "",
    standard_name = "",
    units = "",
    comments = ""
)

A recipe to compute a diagnostic variable from the state, along with some useful metadata.

The primary use for DiagnosticVariables is to be embedded in a ScheduledDiagnostic to compute diagnostics while the simulation is running.

The metadata is used exclusively by the output_writer in the ScheduledDiagnostic. It is responsibility of the output_writer to follow the conventions about the meaning of the metadata and their use.

In ClimaAtmos, we roughly follow the naming conventions listed in this file: https://airtable.com/appYNLuWqAgzLbhSq/shrKcLEdssxb8Yvcp/tblL7dJkC3vl5zQLb

Keyword arguments

• compute!: Function that computes the diagnostic variable from the state, cache, and time. In addition to these three arguments, compute! has to take four arguments, the destination where to write the result of the computation.

• compute: Function that computes the diagnostic variable from the state, cache, and time and returns either a Field or an un-evaluated expression (e.g., with LazyBroadcast.lazy).

• short_name: Name used to identify the variable in the output files and in the file names. Short but descriptive. ClimaAtmos follows the CMIP conventions and the diagnostics are identified by the short name.

• long_name: Name used to describe the variable in the output files.

• standard_name: Standard name, as in http://cfconventions.org/Data/cf-standard-names/71/build/cf-standard-name-table.html

• units: Physical units of the variable.

• comments: More verbose explanation of what the variable is, or comments related to how it is defined or computed.

short_name(dv::DiagnosticVariable)

Return the short name associated to the given DiagnosticVariable.

long_name(dv::DiagnosticVariable)

Return the long name associated to the given DiagnosticVariable.

descriptive_short_name(variable::DiagnosticVariable,
                       output_schedule_func,
                       reduction_time_func,
                       pre_output_hook!)

Return a compact, unique-ish, identifier generated from the given information. This function is useful for filenames and error messages.

descriptive_long_name(variable::DiagnosticVariable,
                      output_every,
                      reduction_time_func,
                      pre_output_hook!)

Return a verbose description of the given output variable.

This function is useful for attributes in output files.

ScheduledDiagnostic

Conceptually, a ScheduledDiagnostics is a DiagnosticVariable we want to compute in a given simulation. For example, it could be the temperature averaged over a day. We can have multiple ScheduledDiagnostics for the same DiagnosticVariable (e.g., daily and monthly average temperatures).

output_short_name(sd::ScheduledDiagnostic)

Return the short name to use for output of the ScheduledDiagnostic sd.

output_long_name(sd::ScheduledDiagnostic)

Return the long name to use for output of the ScheduledDiagnostic sd.

AbstractWriter

An object that knows how to save some output.

AbstractWriters have to provide one function, write_field!

The function has to have signature write_field!(writer::Writer, field, diagnostic, u, p, t)

It is up to the Writer to implement this.

The DictWriter is a writer that does not write to disk, but to memory (in a dictionary).

This is particularly useful for testing and debugging. This is not type stable (the underlying dictionary does not know in advance what types might be used).

NetCDFWriter

A struct to remap ClimaCore Fields to rectangular grids and save the output to NetCDF files.

HDF5Writer(output_dir)

Save a ScheduledDiagnostic to a HDF5 file inside the output_dir.

interpolate_field!(writer::NetCDFWriter, field, diagnostic, u, p, t)

Perform interpolation of field and save output in preallocated areas of writer.

write_field!(writer::DictWriter, field, diagnostic, u, p, t)

Add an entry to the writer at time t for the current diagnostic with value field.

DictWriter is backed by a dictionary. Most typically, the keys of this dictionary are either strings, the output_short_name of the diagnostic. If the output_short_name is not available, use the diagnostic itself. The values of this dictionary is another dictionary that maps the time t to the field at that value.

DictWriter implements a basic read-only dictionary interface to access the times and values.

write_field!(writer::HDF5Writer, field, diagnostic, u, p, t)

Save a ScheduledDiagnostic to a HDF5 file inside the output_dir.

The name of the file is determined by the output_short_name of the output ScheduledDiagnostic. New files are created for each timestep.

Fields can be read back using the InputOutput module in ClimaCore.

write_field!(writer::NetCDFWriter, field::Fields.Field, diagnostic, u, p, t)

Save the resampled field produced by diagnostic as directed by the writer.

Only the root process does something here.

Note: It assumes that the field is already resampled.

The target file is determined by output_short_name(diagnostic). If the target file already exists, append to it. If not, create a new file. If the file does not contain dimensions, they are added the first time something is written.

Time handling:

• For reduced diagnostics: timestamps are stored at the START of the reduction period, with time_bnds showing [start, end] of the period. For the first write, t=0 is assumed; for subsequent writes, the end of the previous period is used.
• For instantaneous diagnostics: timestamps are stored at the current time, with timebnds showing [previoustime, current_time].

Attributes are appended to the dataset:

• short_name
• long_name
• units
• comments
• start_date

default_num_points(space)

Return a tuple with number of points that are optimally suited to interpolate the given space.

"Optimally suited" here means approximately the same as the number of points as the given space.

close(writer::HDF5Writer)

Close all the files open in writer. (Currently no-op.)

close(writer::NetCDFWriter)

Close all the open files in writer.