xsimlab.variable¶

xsimlab.variable(dims=(), intent='in', global_name=None, group=None, groups=None, default=NOTHING, validator=None, converter=None, static=False, description='', attrs=None, encoding=None)¶

Create a variable.

Variables store useful metadata such as dimension labels, a short description, a default value, validators or custom, user-provided metadata.

Variables are the primitives of the modeling framework, they define the interface of each process in a model.

Variables should be declared exclusively as class attributes in process classes (i.e., classes decorated with process()).

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.
intent ({'in', 'out', 'inout'}, optional) – Defines whether the variable is an input (i.e., the process needs the variable’s value for its computation), an output (i.e., the process computes a value for the variable) or both an input/output (i.e., the process may update the value of the variable). (default: input).
global_name (str, optional) – Name that may be used to retrieve this variable from other processes in a model with global_ref() (model-wise implicit reference). This name must be unique among all global names found in a model.
group (str, optional) – Variable group (depreciated, use groups instead).
groups (str or list, optional) – Variable group(s).
default (any, optional) – Single default value for the variable, ignored when intent='out' (default: NOTHING). A default value may also be set using a decorator.
validator (callable or list of callable, optional) –
Function that could be called before or during a simulation (or when creating a new process instance) to check the value given for the variable. The function must accept three arguments:
- the process instance (useful for accessing the value of other variables in that process)
- the variable object (useful for accessing the variable metadata)
- the value to be validated.
The function should throw an exception in case where an invalid value is given. If a list is passed, its items are all are treated as validators. The validator can also be set using decorator notation.
converter (callable, optional) – Callable that is called when setting a value for this variable, and that converts the value to the desired format. The callable must accept one argument and return one value. The value is converted before being passed to the validator, if any.
static (bool, optional) – If True, the value of the (input) variable must be set once before the simulation starts and cannot be further updated externally (default: False). Note that it doesn’t prevent updating the value internally, i.e., from within the process class in which the variable is declared if intent is set to ‘out’ or ‘inout’, or from another process class (foreign variable).
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.