Public APIs
ClimaDiagnostics
ClimaDiagnostics.IntegratorWithDiagnostics
— FunctionIntegratorWithDiagnostics(integrator,
scheduled_diagnostics)
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.
Schedules
ClimaDiagnostics.Schedules.AbstractSchedule
— TypeAbstractSchedule
AbstractSchedule
s 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.
ClimaDiagnostics.Schedules.short_name
— Functionshort_name(schedule)
Short of name of the given schedule
. Typically used in names of files/datasets.
ClimaDiagnostics.Schedules.long_name
— Functionlong_name(schedule)
Long of name of the given schedule
. Typically used in attributes.
ClimaDiagnostics.Schedules.DivisorSchedule
— TypeDivisorSchedule
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.
ClimaDiagnostics.Schedules.EveryStepSchedule
— FunctionEveryStepSchedule()
Return a schedule that executes at the end of every step.
ClimaDiagnostics.Schedules.EveryDtSchedule
— TypeEveryDtSchedule
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.
ClimaDiagnostics.Schedules.EveryCalendarDtSchedule
— TypeEveryCalendarDtSchedule
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)
).
This schedule was introduced in version 0.2.4
.
DiagnosticVariables
ClimaDiagnostics.DiagnosticVariables.DiagnosticVariable
— TypeDiagnosticVariable(;
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 DiagnosticVariable
s 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 compute the diagnostic variable from the state. It has to take two arguments: theintegrator
, and a pre-allocated area of memory where to write the result of the computation. It the no pre-allocated area is available, a new one will be allocated. To avoid extra allocations, this function should perform the calculation in-place (i.e., using.=
).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.htmlunits
: Physical units of the variable.comments
: More verbose explanation of what the variable is, or comments related to how it is defined or computed.
ClimaDiagnostics.DiagnosticVariables.short_name
— Functionshort_name(dv::DiagnosticVariable)
Return the short name associated to the given DiagnosticVariable
.
Missing docstring for ClimaDiagnostics.DiagnosticVariables.long_name
. Check Documenter's build log for details.
ClimaDiagnostics.DiagnosticVariables.descriptive_short_name
— Functiondescriptive_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.
ClimaDiagnostics.DiagnosticVariables.descriptive_long_name
— Functiondescriptive_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.
ScheduledDiagnostics
ClimaDiagnostics.ScheduledDiagnostics.ScheduledDiagnostic
— TypeScheduledDiagnostic
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).
ClimaDiagnostics.ScheduledDiagnostics.output_short_name
— Functionoutput_short_name(sd::ScheduledDiagnostic)
Return the short name to use for output of the ScheduledDiagnostic
sd
.
ClimaDiagnostics.ScheduledDiagnostics.output_long_name
— Functionoutput_long_name(sd::ScheduledDiagnostic)
Return the long name to use for output of the ScheduledDiagnostic
sd
.
Writers
ClimaDiagnostics.AbstractWriter
— TypeAbstractWriter
An object that knows how to save some output.
AbstractWriter
s 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.
ClimaDiagnostics.Writers.DictWriter
— TypeThe 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).
ClimaDiagnostics.Writers.NetCDFWriter
— TypeNetCDFWriter
A struct to remap ClimaCore
Fields
to rectangular grids and save the output to NetCDF files.
ClimaDiagnostics.Writers.HDF5Writer
— TypeHDF5Writer(output_dir)
Save a ScheduledDiagnostic
to a HDF5 file inside the output_dir
.
TODO: This is a very barebone HDF5Writer!
Missing docstring for ClimaDiagnostics.Writers.interpolate_field!
. Check Documenter's build log for details.
ClimaDiagnostics.Writers.write_field!
— Functionwrite_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.
HDF5Writer(output_dir)
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.
Field
s 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.
Attributes are appended to the dataset:
short_name
long_name
units
comments
start_date
Base.close
— Functionclose(writer::HDF5Writer)
Close all the files open in writer
. (Currently no-op.)
close(writer::NetCDFWriter)
Close all the open files in writer
.