xsimlab.on_demand¶

xsimlab.on_demand(dims=(), group=None, groups=None, description='', attrs=None, encoding=None)¶

Create a variable that is computed on demand.

Instead of being computed systematically at every step of a simulation or at initialization, its value is only computed (or re-computed) each time when it is needed.

Like other variables, such variable should be declared in a process class. Additionally, it requires its own method to compute its value, which must be defined in the same class and decorated (e.g., using @myvar.compute if the name of the variable is myvar).

These variables may be useful, e.g., for model diagnostics.

Parameters

dims (str or tuple or list, optional) – Dimension label(s) of the variable. An empty tuple corresponds to a scalar variable (default), a string or a 1-length tuple corresponds to a 1-d variable and a n-length tuple corresponds to a n-d variable. A list of str or tuple items may also be provided if the variable accepts different numbers of dimensions.
group (str, optional) – Variable group (depreciated, use groups instead).
groups (str or list, optional) – Variable group(s).
description (str, optional) – Short description of the variable.
attrs (dict, optional) – Dictionnary of additional metadata (e.g., standard_name, units, math_symbol…).
encoding (dict, optional) – Dictionary specifying how to encode this variable’s data into a serialized format (i.e., as a zarr dataset). Currently used keys include ‘dtype’, ‘compressor’, ‘fill_value’, ‘order’, ‘filters’ and ‘object_codec’. See zarr.creation.create() for details about these options. Other keys are ignored.

Notes

An on-demand variable is always an output variable (i.e., intent=’out’).

Its computation usually involves other variables, although this is not required.

It is possible to cache its value at each simulation stage, by applying the compute decorator like this: @myvar.compute(cache=True). This is useful if the variable is meant to be accessed many times in other processes.