xarray-simlab-ode

The xso framework for building and solving models based on ordinary differential equations (ODEs), an extension of xarray-simlab.

Xarray-simlab provides a generic framework for building computational models in a modular fashion and an xarray extension for setting and running simulations using xarray's Dataset structure.

Xarray-simlab-ode (XSO) extends the framework with a set of variables, processes and a solver backend, suited towards ODE-based models. It is designed for flexible, interactive and reproducible modeling workflows. XSO was developed as the foundation of the Phydra library for plankton community models.

Installation

$ pip install xso

In a nutshell

A highly simplified model based on ordinary differential equations is shown below.

1. Create new model components by writing compact Python classes:

import xso

@xso.component
class Variable:
    var = xso.variable(description='basic state variable', attrs={'units':'µM'})

@xso.component
class LinearGrowth:
    var_ext = xso.variable(foreign=True, flux='growth', description='external state variable')
    rate = xso.parameter(description='linear growth rate', attrs={'units':'$d^{-1}$'})

    @xso.flux
    def growth(self, var_ext, rate):
        return var_ext * rate

2. Create a new model just by providing a dictionary of model components:

model = xso.create({'Var':Variable,'Growth':LinearGrowth}, time_unit='d')

3. Create an input xarray.Dataset, run the model and get an output xarray.Dataset:

import numpy as np

input_ds = xso.setup(solver='solve_ivp',
                     model=model,
                     time=np.arange(1,10,.1),
                     input_vars={
                         'Var':{'value_label':'X', 'value_init':1},
                         'Growth':{'var_ext':'X', 'rate':1.},
                     })

with model:
    output_ds = input_ds.xsimlab.run()

4.Perform model setup, pre-processing, run, post-processing and visualization in a functional style, using method chaining:

with model:
    batchout_ds = (input_ds
     .xsimlab.update_vars(
         input_vars={'Growth': {'rate': ('batch', [0.9, 1.0, 1.1, 1.2])}}
     )
     .xsimlab.run(parallel=True, batch_dim='batch')
     .swap_dims({'batch':'Growth__rate'})
     .Var__var_value.plot.line(x='time')
     )

Documentation

Documentation is hosted on ReadTheDocs: https://xarray-simlab-ode.readthedocs.io

Contributing

The package is in the early stages of development, and contributions are very welcome. See GitHub Issues for specific issues, or raise your own. Code contributions can be made via Pull Requests on GitHub. Check out the contributing guidelines for more specific information.

License

xarray-simlab-ode was created by Benjamin Post. It is licensed under the terms of the BSD 3-Clause license.

Credits

Xarray-simlab-ode is an extension of xarray-simlab, created by Benoît Bovy.