API Reference

This page provides an auto-generated summary of xarray-simlab’s API. For more details and examples, refer to the relevant sections in the main part of the documentation.

Top-level functions

create_setup([model, clocks, master_clock, …]) Create a specific setup for model runs.

Dataset.xsimlab (xarray accessor)

This accessor extends xarray.Dataset with all the methods and properties listed below. Proper use of this accessor should be like:

>>> import xarray as xr         # first import xarray
>>> import xsimlab              # import xsimlab (the 'xsimlab' accessor is registered)
>>> ds = xr.Dataset()           # create or load an xarray Dataset
>>> ds.xsimlab.<meth_or_prop>   # access to the methods and properties listed below


Dataset.xsimlab.clock_coords Dictionary of xarray.DataArray objects corresponding to clock coordinates.
Dataset.xsimlab.master_clock_dim Dimension used as master clock for model runs.
Dataset.xsimlab.output_vars Returns a dictionary of clock dimension names (or None) as keys and output variable names - i.e.


Dataset.xsimlab.update_clocks([model, …]) Set or update clock coordinates.
Dataset.xsimlab.update_vars([model, …]) Update model input values and/or output variable names.
Dataset.xsimlab.filter_vars([model]) Filter Dataset content according to Model.
Dataset.xsimlab.run([model, safe_mode]) Run the model.


Creating a model

Model(processes) An immutable collection of process units that together form a computational model.

Creating a new model from an existing one

Model.clone() Clone the Model, i.e., create a new Model instance with the same process classes but different instances.
Model.update_processes(processes) Add or replace processe(s) in this model.
Model.drop_processes(keys) Drop processe(s) from this model.

Model introspection

Model implements an immutable mapping interface where keys are process names and values are objects of Process subclasses (attribute-style access is also supported).

Model.all_vars Returns all variables in the model as a list of (process_name, var_name) tuples (or an empty list).
Model.all_vars_dict Returns all variables in the model as a dictionary of lists of variable names grouped by process.
Model.input_vars Returns all variables that require setting a value before running the model.
Model.input_vars_dict Returns all variables that require setting a value before running the model.
Model.dependent_processes Returns a dictionary where keys are process names and values are lists of the names of dependent processes.
Model.visualize([show_only_variable, …]) Render the model as a graph using dot (require graphviz).

Running a model

In most cases, the methods listed below should not be used directly. For running simulations, it is preferable to use the Dataset.xsimlab accessor instead. These methods might be useful though, e.g., for debugging or for using Model objects with other interfaces.

Model.initialize() Run the ‘initialize’ stage of a simulation.
Model.run_step(step) Run a single ‘run_step()’ stage of a simulation.
Model.finalize_step() Run a single ‘finalize_step’ stage of a simulation.
Model.finalize() Run the ‘finalize’ stage of a simulation.


Creating a process

process([maybe_cls, autodoc]) A class decorator that adds everything needed to use the class as a process.

Process introspection and variables

process_info(process[, buf]) Concise summary of process variables and simulation stages implemented.
variable_info(process, var_name[, buf]) Get detailed information about a variable.
filter_variables(process[, var_type, …]) Filter the variables declared in a process.


variable([dims, intent, group, default, …]) Create a variable.
foreign(other_process_cls, var_name[, intent]) Create a reference to a variable that is defined in another process class.
group(name) Create a special variable which value returns an iterable of values of variables in a model that all belong to the same group.
on_demand([dims, group, description, attrs]) Create a variable that is computed on demand.