xso.xsimlabwrappers

Module Contents

Functions

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.

update_setup(model, old_setup, new_solver[, new_time])

Change existing model setup to another solver type,
xso.xsimlabwrappers.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.xsimlabwrappers.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

xso.xsimlabwrappers.update_setup(model, old_setup, new_solver, new_time=None)[source]

Change existing model setup to another solver type, with the possibility to update solver time as well.

Provides a convenient wrapper for Xarray-simlab’s :meth: update_vars and update_clocks. Currently it supports switching between the ‘stepwise’ solver and ‘odeint’ adaptive step-size solver.

Parameters:

  • model (xsimlab.Model) – The model object that was used to create the model setup.

  • old_setup (xarray.Dataset) – The previous model setup Dataset, to be updated.

  • new_solver (xso.SolverABC subclass) – The new solver, that the model setup should be updated to be compatible with.

Returns:

new_setup – The new model setup Dataset, that is compatible to be run with the supplied solver.

Return type:

xarray.Dataset