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

Properties

Dataset.xsimlab.clock_coords

Mapping from clock dimensions to xarray.DataArray objects corresponding to their coordinates.

Dataset.xsimlab.clock_sizes

Mapping from clock dimensions to lengths.

Dataset.xsimlab.main_clock_dim

Dimension used as main clock for model runs.

Dataset.xsimlab.main_clock_coord

Main clock coordinate (as a xarray.DataArray object).

Dataset.xsimlab.nsteps

Number of simulation steps, computed from the main clock coordinate.

Dataset.xsimlab.output_vars

Returns a dictionary of output variable names - in the form of ('p_name', 'var_name') tuples - as keys and the clock dimension names (or None) on which to save snapshots as values.

Dataset.xsimlab.output_vars_by_clock

Returns a dictionary of output variables grouped by clock (keys).

Methods

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.reset_vars([model])

Set or reset Dataset variables with model input default values (if any).

Dataset.xsimlab.filter_vars([model])

Filter Dataset content according to Model.

Dataset.xsimlab.run([model, batch_dim, …])

Run the model.

Dataset.xsimlab.get_output_save_steps()

Returns save steps for each clock as boolean values.

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.

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

Returns all index variables in the model as a list of (process_name, var_name) tuples (or an empty list).

Model.index_vars_dict

Returns all index 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 and properties listed below should not be used directly. For running simulations, it is preferable to use the xarray extension instead, see Dataset.xsimlab (xarray accessor). These methods might be useful though, e.g., for using Model objects with other interfaces.

Model.state

Returns a mapping of model variables and their current value.

Model.update_state(input_vars[, validate, …])

Update the model’s state (only input variables) with new values.

Model.cache

Returns a mapping of model variables and some of their (meta)data cached for fastpath access.

Model.update_cache(var_key)

Update the model’s cache for a given model variable.

Model.execute(stage, runtime_context[, …])

Run one stage of a simulation.

Model.validate([p_names])

Run the variable validators of all or some of the processes in the model.

Process

Creating a process

process([maybe_cls, autodoc, apply_attrs])

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.

Process runtime methods

runtime([meth, args])

Function decorator applied to a method of a process class that is called during simulation runtime.

Variable

variable([dims, intent, global_name, group, …])

Create a variable.

MAIN_CLOCK

Singleton class to be used as a placeholder of the main clock dimension.

index(dims[, global_name, groups, …])

Create a variable aimed at indexing data.

any_object([global_name, groups, …])

Create a variable used to hold any arbitrary object that needs to be shared with other process classes.

foreign(other_process_cls, var_name[, intent])

Create a reference to a variable that is defined in another process class.

global_ref(name[, intent])

Create a reference to a variable that is defined somewhere else in a model with a unique, global name.

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.

group_dict(name)

Create a special variable which value returns a mapping of variables in a model that all belong to the same group.

on_demand([dims, group, groups, …])

Create a variable that is computed on demand.

Validators

See also attrs’ validators. Some additional validators for common usage are listed below. These are defined in xsimlab.validators.

in_bounds(bounds[, closed])

A validator that raises a ValueError if a given value is out of the given bounded interval.

is_subdtype(dtype)

A validator that raises a TypeError if a given array has a wrong dtype.

Model runtime monitoring

monitoring.ProgressBar([frontend])

Progress bar implementation using the tqdm package.

runtime_hook(stage[, level, trigger])

Decorator that allows to call a function or a method at one or more specific times during a simulation.

RuntimeHook(*args)

Base class for advanced, stateful simulation runtime hooks.

RuntimeSignal(value)

Signal controlling simulation runtime.