Skip to main content

Collect data from BOUT++ runs in python using xarray

Project description

xBOUT

Build Status Documentation Status DOI

Documentation: https://xbout.readthedocs.io

Examples: https://github.com/boutproject/xBOUT-examples

xBOUT provides an interface for collecting the output data from a BOUT++ simulation into an xarray dataset in an efficient and scalable way, as well as accessor methods for common BOUT++ analysis and plotting tasks.

Currently only in alpha (until 1.0 released) so please report any bugs, and feel free to raise issues asking questions or making suggestions.

Installation

With pip:

pip install --user xbout

With conda:

conda install -c conda-forge xbout

You can test your installation of xBOUT by running pytest --pyargs xbout.

xBOUT requires other python packages, which will be installed when you run one of the above install commands if they are not already installed on your system.

Loading your data

The function open_boutdataset() uses xarray & dask to collect BOUT++ data spread across multiple NetCDF files into one contiguous xarray dataset.

The data from a BOUT++ run can be loaded with just

bd = open_boutdataset('./run_dir*/BOUT.dmp.*.nc', inputfilepath='./BOUT.inp')

open_boutdataset() returns an instance of an xarray.Dataset which contains BOUT-specific information in the attrs, so represents a general structure for storing all of the output of a simulation, including data, input options and (soon) grid data.

BoutDataset Accessor Methods

xBOUT defines a set of accessor methods on the loaded Datasets and DataArrays, which are called by ds.bout.method().

This is where BOUT-specific data manipulation, analysis and plotting functionality is stored, for example

ds['n'].bout.animate2D(animate_over='t', x='x', y='z')

density

or

ds.bout.create_restarts(savepath='.', nxpe=4, nype=4)

Extending xBOUT for your BOUT module

The accessor classes BoutDatasetAccessor and BoutDataArrayAccessor are intended to be subclassed for specific BOUT++ modules. The subclass accessor will then inherit all the .bout accessor methods, but you will also be able to override these and define your own methods within your new accessor.

For example to add an extra method specific to the STORM BOUT++ module:

from xarray import register_dataset_accessor
from xbout.boutdataset import BoutDatasetAccessor

@register_dataset_accessor('storm')
class StormAccessor(BoutAccessor):
    def __init__(self, ds_object):
        super().__init__(ds_object)

    def special_method(self):
        print("Do something only STORM users would want to do")

ds.storm.special_method()
Out [1]: Do something only STORM users would want to do

There is included an example of a StormDataset which contains all the data from a STORM simulation, as well as extra calculated quantities which are specific to the STORM module.

Contributing

Feel free to raise issues about anything, or submit pull requests, though I would encourage you to submit an issue before writing a pull request. For a general guide on how to contribute to an open-source python project see xarray's guide for contributors.

The existing code was written using Test-Driven Development, and I would like to continue this, so please include pytest tests with any pull requests.

If you write a new accessor, then this should really live with the code for your BOUT module, but it could potentially be added as an example to this repository too.

Developers

Clone the repository with:

git clone git@github.com:boutproject/xBOUT.git

The recommended way to work with xBOUT from the git repo is to do an editable install with pip. Run this command from the xBOUT/ directory:

pip install --user -e .

which will also install all the required dependencies. Dependencies can also be installed using pip

pip install --user -r requirements.txt

or conda

conda install --file requirements.txt

It is possible to use xBOUT by adding the xBOUT/ directory to your $PYTHONPATH.

Test by running pytest in the xBOUT/ directory.

Development plan

Things which definitely need to be included (see the 1.0 milestone):

  • More tests, both with and against the original boutdata.collect()
  • Speed test against old collect

Things which would be nice and I plan to do:

  • Infer concatenation order from global indexes (see issue)
  • Real-space coordinates
  • Variable names and units (following CF conventions)
  • Unit-aware arrays
  • Variable normalisations

Things which might require a fair amount of effort by another developer but could be very powerful:

  • Using real-space coordinates to create tokamak-shaped plots
  • Support for staggered grids using xgcm
  • Support for encoding topology using xgcm
  • API for applying BoutCore operations (hopefully using xr.apply_ufunc)

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

xbout-0.3.6.tar.gz (4.8 MB view details)

Uploaded Source

Built Distribution

xbout-0.3.6-py3-none-any.whl (140.6 kB view details)

Uploaded Python 3

File details

Details for the file xbout-0.3.6.tar.gz.

File metadata

  • Download URL: xbout-0.3.6.tar.gz
  • Upload date:
  • Size: 4.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for xbout-0.3.6.tar.gz
Algorithm Hash digest
SHA256 5b766bce5311ef830dbb6e9ba0a2a0a7629b5e27f615a6f26eb5187933da030d
MD5 f4970400bb7c6d2380b222c0bb98302a
BLAKE2b-256 78bcf9b2157f4cef968cdf6cec7e8aa44e13a30a1cdeb12d0d51a36accac5b86

See more details on using hashes here.

File details

Details for the file xbout-0.3.6-py3-none-any.whl.

File metadata

  • Download URL: xbout-0.3.6-py3-none-any.whl
  • Upload date:
  • Size: 140.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for xbout-0.3.6-py3-none-any.whl
Algorithm Hash digest
SHA256 cba92995315e9ca775b2484b69e58e3e15c0769b34e18c304583b0403075cfca
MD5 8d9c44da16db9a687699a33287dc1c2c
BLAKE2b-256 290bed9d09876fb3dbb7f181e4718f1d45363dd445ae3bebc6dd204985d381cb

See more details on using hashes here.

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