xso

Submodules

Package Contents

Functions

component([cls])

A component decorator that adds everything needed to use the class

variable([foreign, flux, negative, list_input, dims, ...])

Create a state variable.

parameter([foreign, dims, description, attrs])

Create a parameter.

forcing([foreign, setup_func, dims, description, attrs])

Create a forcing variable.

flux([flux_func, dims, group, group_to_arg, ...])

Create a flux function.

index([foreign, dims, description, attrs])

Create an index.

create(components[, time_unit])

Creates xsimlab Model instance, from dict of XSO components,

setup(solver, model, input_vars[, output_vars, time])

Create a specific setup for model runs.
xso.component(cls=None)[source]

A component decorator that adds everything needed to use the class as a XSO component. It is a wrapper for the xarray-simlab process decorator.

A component represents a logical unit with the model, and usually implements:

  • A set of XSO variables, defined as class attributes, e.g. xso.variable, xso.parameter,

xso.forcing or xso.flux. - One or more methods that can be functions defining a xso.flux or a xso.forcing.

Parameters:

cls (class, optional) – Allows applying this decorator either as @xso.component or @xso.component(*args).

Returns:

cls – The decorated class that is a fully functional xso.component.

Return type:

class

xso.variable(foreign=False, flux=None, negative=False, list_input=False, dims=None, description='', attrs={})[source]

Create a state variable.

This can be a local state variable for the component, or a reference to a state variable initialized in another component. A flux function can be applied to that variable.

The variable stores a single state variable, if no dimension (argument: dims) is supplied, but can also define an array or matrix of state variables, depending on the argument. In the model it is always assigned to a single label, and can only be used in a flux with appropriate dimensionality.

Parameters:

  • foreign (boolean, optional) – Defines whether the variable is initialized and labeled in the component, or is simply a reference to a variable in another component.

  • flux (str, optional) – Name of the flux function defined in this component, the result of which is applied to this state variable.

  • negative (boolean, optional) – If true, the result of the flux function is substracted, if false, it is added to the variable.

  • list_input (list, optional) – If it is a foreign variable, a list of labels of other state variables can be supplied, as a handy way of applying the same flux to multiple variables.

  • 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.

  • description (str, optional) – Short description of the variable.

  • attrs (dict, optional) – Dictionnary of additional metadata (e.g., standard_name, units, math_symbol…).

xso.parameter(foreign=False, dims=(), description='', attrs=None)[source]

Create a parameter.

This can be a local parameter for the component, or a reference to a parameter initialized in another component.

The parameter can be of variable dimensionality.

Parameters:

  • foreign (boolean, optional) – Defines whether the parameter is initialized and labeled in the component, or is simply a reference to a variable in another component.

  • dims (str or tuple or list, optional) – Dimension label(s) of the forcing. 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.

  • description (str, optional) – Short description of the parameter.

  • attrs (dict, optional) – Dictionnary of additional metadata (e.g., standard_name, units, math_symbol…).

xso.forcing(foreign=False, setup_func=None, dims=(), description='', attrs={})[source]

Create a forcing variable.

This can be a local forcing variable for the component, or a reference to a forcing variable initialized in another component. A setup function can be registered to supply the forcing value.

The forcing can be of variable dimensionality.

Parameters:

  • foreign (boolean, optional) – Defines whether the variable is initialized and labeled in the component, or is simply a reference to a variable in another component.

  • setup_func (str, optional) – Name of the forcing setup function defined in this component, the result of which is defines this forcing. This allows supplying a forcing as a mathematical function, which is dynamically computed at each time-step, instead of a fixed array of values.

  • dims (str or tuple or list, optional) – Dimension label(s) of the forcing. 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.

  • description (str, optional) – Short description of the forcing.

  • attrs (dict, optional) – Dictionnary of additional metadata (e.g., standard_name, units, math_symbol…).

xso.flux(flux_func=None, *, dims=(), group=None, group_to_arg=None, description='', attrs={})[source]

Create a flux function.

This is a function decorator that registers a method within a component as a flux (i.e. term in the ODE). It ta

The parameter can be of variable dimensionality.

Parameters:

  • flux_func (decorator argument) – Allows decorator to be used with and without arguments.

  • dims (str or tuple or list, optional) – Dimension label(s) of the forcing. 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) – Output of flux is stored in xsimlab group variable, to be referenced in other fluxes, via the group_to_arg argument. This way the flux output can be routed to multiple other fluxes, for more complex mathematical constructs.

  • group_to_arg (str, optional) – The string supplied is used as a reference for an xsimlab group variable. This group variable collects the output of fluxes in other components, that have defined the same string label for the group argument. The values thus collected are inserted into the function as a variable of the same name, for further computations.

  • description (str, optional) – Short description of the flux.

  • attrs (dict, optional) – Dictionnary of additional metadata (e.g., standard_name, units, math_symbol…).

xso.index(foreign=False, dims=(), description='', attrs=None)[source]

Create an index.

This has to be be a local index for the component.

The index can be of variable dimensionality.

Parameters:

  • foreign (boolean, optional) – Defines whether the parameter is initialized and labeled in the component, or is simply a reference to a variable in another component.

  • dims (str or tuple or list, optional) – Dimension label(s) of the forcing. 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.

  • description (str, optional) – Short description of the parameter.

  • attrs (dict, optional) – Dictionnary of additional metadata (e.g., standard_name, units, math_symbol…).

xso.create(components, time_unit='d')[source]

Creates xsimlab Model instance, from dict of XSO components, automatically adding the necessary model backend, solver and time components.

It is a simple wrapper of the xsimlab Model constructor, and returns a fully functional Xarray-simlab model object with the XSO core, Solver and Time components added.

Parameters:

  • components (dict) – Dictionary with component names as keys and classes (decorated with component()) as values.

  • time_unit (str, optional) – Unit of time to be used in the model. Default is ‘d’ for days. This has to be supplied at model creation, since the time unit is written to the immutable metadata of the model object.

Returns:

model – Xarray-simlab model object with the XSO core, Solver and Time components added.

Return type:

xsimlab.Model

xso.setup(solver, model, input_vars, output_vars=None, time=None)[source]

Create a specific setup for model runs.

This function wraps xsimlab’s create_setup and adds a dummy clock parameter necessary for model execution. This convenient function creates a new xarray.Dataset object with everything needed to run a model (i.e., input values, time steps, output variables to save at given times) as data variables, coordinates and attributes.

Parameters:

  • solver (xso.SolverABC subclass) – Solver backend to be used at model runtime.

  • model (xsimlab.Model) – Create a simulation setup for this model.

  • input_vars (dict, optional) – Dictionary with values given for model inputs. Entries of the dictionary may look like: - 'foo': {'bar': value, ...} or - ('foo', 'bar'): value or - 'foo__bar': value where foo is the name of a existing process in the model and bar is the name of an (input) variable declared in that process. Values are anything that can be easily converted to xarray.Variable objects, e.g., single values, array-like, (dims, data, attrs) tuples or xarray objects. For array-like values with no dimension labels, xarray-simlab will look in model variables metadata for labels matching the number of dimensions of those arrays.

  • output_vars (dict, optional) – Dictionary with model variable names to save as simulation output. Entries of the dictionary look similar than for input_vars (see here above), except that here value must correspond to the dimension of a clock coordinate (i.e., new output values will be saved at each time given by the coordinate labels) or None (i.e., only one value will be saved at the end of the simulation).

  • solver_kwargs (dict, optional) – Additional keyword arguments to pass to the solver backend. This is directly passed to the solving function and can be used to adjust parameters for solver backends that allow this, such as the IVPSolver backend.

Returns:

dataset – A new Dataset object with model inputs as data variables or coordinates (depending on their given value) and clock coordinates. The names of the input variables also include the name of their process (i.e., ‘foo__bar’).

Return type:

xarray.Dataset