Package: xbout
xBOUTDocumentation:https://xbout.readthedocs.ioExamples:https://github.com/boutproject/xBOUT-examplesxBOUT provides an interface for collecting the output data from aBOUT++simulation into anxarraydataset 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.InstallationWith pip:pipinstall--userxboutWith conda:condainstall-cconda-forgexboutYou can test your installation ofxBOUTby runningpytest --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 dataThe functionopen_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 justbd=open_boutdataset('./run_dir*/BOUT.dmp.*.nc',inputfilepath='./BOUT.inp')open_boutdataset()returns an instance of anxarray.Datasetwhich
contains BOUT-specific information in theattrs, so represents a
general structure for storing all of the output of a simulation,
including data, input options and (soon) grid data.BoutDataset Accessor MethodsxBOUT defines a set ofaccessormethods on the loaded Datasets and DataArrays, which are called byds.bout.method().This is where BOUT-specific data manipulation, analysis and plotting
functionality is stored, for exampleds['n'].bout.animate2D(animate_over='t',x='x',y='z')ords.bout.create_restarts(savepath='.',nxpe=4,nype=4)Extending xBOUT for your BOUT moduleThe accessor classesBoutDatasetAccessorandBoutDataArrayAccessorare intended to be subclassed for specific BOUT++ modules. The subclass
accessor will then inherit all the.boutaccessor 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 theSTORMBOUT++
module:fromxarrayimportregister_dataset_accessorfromxbout.boutdatasetimportBoutDatasetAccessor@register_dataset_accessor('storm')classStormAccessor(BoutAccessor):def__init__(self,ds_object):super().__init__(ds_object)defspecial_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 doThere is included an example of aStormDatasetwhich contains all the data from aSTORMsimulation, as well as
extra calculated quantities which are specific to the STORM module.ContributingFeel 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 seexarray's guide for contributors.The existing code was written using Test-Driven Development, and I would
like to continue this, so please includepytesttests 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.DevelopersClone the repository with:gitclonegit@github.com:boutproject/xBOUT.gitThe recommended way to work withxBOUTfrom the git repo is to do an editable
install with pip. Run this command from thexBOUT/directory:pipinstall--user-e.which will also install all the required dependencies. Dependencies can also be
installed using pippipinstall--user-rrequirements.txtor condaconda install --file requirements.txtIt is possible to usexBOUTby adding thexBOUT/directory to your$PYTHONPATH.Test by runningpytestin thexBOUT/directory.Development planThings which definitely need to be included (see the 1.0 milestone):More tests, both with
and against the originalboutdata.collect()Speed test against old collectThings which would be nice and I plan to do:Infer concatenation order from global indexes (seeissue)Real-space coordinatesVariable names and units (following CF conventions)Unit-aware arraysVariable normalisationsThings which might require a fair amount of effort by another developer but
could be very powerful:Using real-space coordinates to create tokamak-shaped plotsSupport for staggered grids using xgcmSupport for encoding topology using xgcmAPI for applying BoutCore operations (hopefully usingxr.apply_ufunc)