Skip to main content

generic framework and xarray extension for computer model simulations

Project description

Build Status Coverage Status Documentation Status Citation

xarray-simlab is a Python library that provides both a generic framework for building computational models in a modular fashion and a xarray extension for setting and running simulations using the xarray’s Dataset structure. It is designed for fast, interactive and exploratory modeling.

xarray-simlab is well integrated with other libraries of the PyData ecosystem such as dask and zarr.

In a nutshell

The Conway’s Game of Life example shown below is adapted from this blog post by Jake VanderPlas.

  1. Create new model components by writing compact Python classes, i.e., very much like dataclasses:

import numpy as np
import xsimlab as xs

@xs.process
class GameOfLife:
    world = xs.variable(
        dims=('x', 'y'), intent='inout', encoding={'fill_value': None}
    )

    def run_step(self):
        nbrs_count = sum(
            np.roll(np.roll(self.world, i, 0), j, 1)
            for i in (-1, 0, 1) for j in (-1, 0, 1)
            if (i != 0 or j != 0)
        )
        self._world_next = (nbrs_count == 3) | (self.world & (nbrs_count == 2))

    def finalize_step(self):
        self.world[:] = self._world_next


@xs.process
class Glider:
    pos = xs.variable(dims='point_xy', description='glider position')
    world = xs.foreign(GameOfLife, 'world', intent='out')

    def initialize(self):
        x, y = self.pos

        kernel = [[1, 0, 0],
                  [0, 1, 1],
                  [1, 1, 0]]

        self.world = np.zeros((10, 10), dtype=bool)
        self.world[x:x+3, y:y+3] = kernel
  1. Create a new model just by providing a dictionary of model components:

model = xs.Model({'gol': GameOfLife,
                  'init': Glider})
  1. Create an input xarray.Dataset, run the model and get an output xarray.Dataset:

input_dataset = xs.create_setup(
    model=model,
    clocks={'step': np.arange(9)},
    input_vars={'init__pos': ('point_xy', [4, 5])},
    output_vars={'gol__world': 'step'}
)

output_dataset = input_dataset.xsimlab.run(model=model)
>>> output_dataset
<xarray.Dataset>
Dimensions:     (point_xy: 2, step: 9, x: 10, y: 10)
Coordinates:
  * step        (step) int64 0 1 2 3 4 5 6 7 8
Dimensions without coordinates: point_xy, x, y
Data variables:
    init__pos   (point_xy) int64 4 5
    gol__world  (step, x, y) bool False False False False ... False False False
  1. Perform model setup, pre-processing, run, post-processing and visualization in a functional style, using method chaining:

import matplotlib.pyplot as plt

with model:
    (input_dataset
     .xsimlab.update_vars(
         input_vars={'init__pos': ('point_xy', [2, 2])}
     )
     .xsimlab.run()
     .gol__world.plot.imshow(
         col='step', col_wrap=3, figsize=(5, 5),
         xticks=[], yticks=[],
         add_colorbar=False, cmap=plt.cm.binary)
    )
doc/_static/gol.png

Documentation

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

License

3-clause (“Modified” or “New”) BSD license, see License file.

xarray-simlab uses short parts of the code of the xarray, pandas and dask libraries. Their licenses are reproduced in the “licenses” directory.

Acknowledgment

This project is supported by the Earth Surface Process Modelling group of the GFZ Helmholtz Centre Potsdam.

Citation

If you use xarray-simlab in a scientific publication, we would appreciate a citation.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xarray-simlab-0.5.0.tar.gz (146.8 kB view details)

Uploaded Source

Built Distribution

xarray_simlab-0.5.0-py3-none-any.whl (85.3 kB view details)

Uploaded Python 3

File details

Details for the file xarray-simlab-0.5.0.tar.gz.

File metadata

  • Download URL: xarray-simlab-0.5.0.tar.gz
  • Upload date:
  • Size: 146.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.9.1

File hashes

Hashes for xarray-simlab-0.5.0.tar.gz
Algorithm Hash digest
SHA256 92de9fbd55e045b0d0eacbc7334a86108ecd5376973b1ed20b600bbc6521c2d6
MD5 40b205ad84feb0b86386e3169ebe61d1
BLAKE2b-256 5bc3ea7ae075a27ee1bd6bb7995de77c7ac7132e34ca6e611a038ef28d8c78e2

See more details on using hashes here.

Provenance

File details

Details for the file xarray_simlab-0.5.0-py3-none-any.whl.

File metadata

  • Download URL: xarray_simlab-0.5.0-py3-none-any.whl
  • Upload date:
  • Size: 85.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/49.2.1 requests-toolbelt/0.9.1 tqdm/4.56.0 CPython/3.9.1

File hashes

Hashes for xarray_simlab-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 708e988baf393299b74720f28af364f50cb29449196c3bbd85812decb58d5bd9
MD5 72d4da3baaa85dbc2c101be90b9f94c1
BLAKE2b-256 c52372de6ab41634968a54af3a6dc2b9d6318425a07872c09e8c12a020685b1e

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page