xbout.load.open_boutdataset

xbout.load.open_boutdataset(datapath='./BOUT.dmp.*.nc', inputfilepath=None, geometry=None, gridfilepath=None, grid_mismatch='raise', chunks=None, keep_xboundaries=True, keep_yboundaries=False, run_name=None, info=True, is_restart=None, **kwargs)

Load a dataset from a set of BOUT output files, including the input options file. Can also load from a grid file or from restart files.

Note that when reloading a Dataset that was saved by xBOUT, the state of the saved Dataset is restored, and the values of keep_xboundaries, keep_yboundaries, and run_name are ignored. geometry is treated specially, and can be passed when reloading a Dataset (along with gridfilepath if needed).

Troubleshooting

Variable conflicts: sometimes, for example when loading data from multiple restarts, some variables may have conflicts (e.g. a source term was changed between some of the restarts, but the source term is saved as time-independent, without a t-dimension). In this case one workaround is to pass a list of variable names to the keyword argument drop_vars to ignore the variables with conflicts, e.g. if "S1" and "S2" have conflicts:

ds = open_boutdataset("data*/boutdata.nc", drop_variables=["S1", "S2"])

will open a Dataset which is missing "S1" and "S2" (drop_variables is an argument of xarray.open_dataset that is passed down through kwargs.)

type datapath:

param datapath:

Path to the data to open. Can point to either a set of one or more dump files, or a single grid file.

To specify multiple dump files you must enter the path to them as a single glob, e.g. ‘./BOUT.dmp.*.nc’, or for multiple consecutive runs in different directories (in order) then ‘./run*/BOUT.dmp.*.nc’.

If a list or tuple of xr.Dataset is passed, they will be combined with xr.combine_nested() instead of loading data from disk (intended for unit testing).

type datapath:

str or (list or tuple of xr.Dataset), optional

type chunks:

param chunks:

type chunks:

dict, optional

type inputfilepath:

param inputfilepath:

type inputfilepath:

str, optional

type geometry:

param geometry:

The geometry type of the grid data. This will specify what type of coordinates to add to the dataset, e.g. ‘toroidal’ or ‘cylindrical’.

If not specified then will attempt to read it from the file attrs. If still not found then a warning will be thrown, which can be suppressed by passing info=False.

To define a new type of geometry you need to use the register_geometry decorator. You are encouraged to do this for your own BOUT++ physics module, to apply relevant normalisations.

type geometry:

str, optional

type gridfilepath:

param gridfilepath:

The path to a grid file, containing any variables needed to apply the geometry specified by the ‘geometry’ option, which are not contained in the dump files. This may either be the path of the grid file itself, or the directory relative to which the grid from the settings file can be found.

type gridfilepath:

str, optional

type grid_mismatch:

param grid_mismatch:

How to handle if the grid is not the grid that has been used for the simulation. Can be “raise” to raise a RuntimeError, “warn” to raise a warning, or ignore to ignore the mismatch silently.

type grid_mismatch:

str, optional

type keep_xboundaries:

param keep_xboundaries:

If true, keep x-direction boundary cells (the cells past the physical edges of the grid, where boundary conditions are set); increases the size of the x dimension in the returned data-set. If false, trim these cells.

type keep_xboundaries:

bool, optional

type keep_yboundaries:

param keep_yboundaries:

If true, keep y-direction boundary cells (the cells past the physical edges of the grid, where boundary conditions are set); increases the size of the y dimension in the returned data-set. If false, trim these cells.

type keep_yboundaries:

bool, optional

type run_name:

param run_name:

Name to give to the whole dataset, e.g. ‘JET_ELM_high_resolution’. Useful if you are going to open multiple simulations and compare the results.

type run_name:

str, optional

type info:

param info:

type info:

bool or "terse", optional

type is_restart:

param is_restart:

Restart files require some special handling (e.g. working around variables that are not present in restart files). By default, this special handling is enabled if the files do not have a time dimension and restart is present in the file name in datapath. This option can be set to True or False to explicitly enable or disable the restart file handling.

type is_restart:

bool, optional

type kwargs:

param kwargs:

Keyword arguments are passed down to xarray.open_mfdataset, which in turn passes extra kwargs down to xarray.open_dataset.

type kwargs:

optional

returns:

ds

rtype:

xarray.Dataset