Python routines

boututils

  • class Datafile provides a convenient way to read and write NetCDF files. There are many different NetCDF libraries available for Python, so this class tries to provide a consistent interface to many of them.

  • deriv()

  • determineNumberOfCPUs()

  • file_import() reads the contents of a NetCDF file into a dictionary

  • integrate()

  • launch()

  • linear_regression()

  • showdata() visualises and animates 2D data (time + 1 spatial dimension) or 3D data (time + 2 spatial dimensions). The animation object can be returned, or the animation can be saved to a file or displayed on screen.

  • boutwarnings contains functions to raise warning messages. alwayswarn() by default prints the warning every time it is called. defaultwarn() by default prints the warning only the first time an instance of it is called. This module is a wrapper for the Python warnings module, so printing the warnings can be controlled using warnings.simplefilter() or warnings.filterwarnings().

Generic routines, useful for all data

boutdata

  • collect() provides an interface to read BOUT++ data outputs, returning NumPy arrays of data. It deals with the processor layout, working out which file contains each part of the domain.

    from boutdata.collect import collect

t = collect("t_array")  # Collect the time values

  • pol_slice() takes a 3 or 4-D data set for a toroidal equilibrium, and calculates a slice through it at fixed toroidal angle.

  • gen_surface() is a generator for iterating over flux surfaces

Routines for exchanging data to/from BOUT++

class boutdata.BoutArray(input_array, attributes={})

Wrapper for ndarray with extra attributes for BOUT++ fields.

Parameters:

  • input_array (array_like) – Data to convert to BoutArray

  • attributes (dict) – Dictionary of extra attributes for BOUT++ fields

    Notably, these attributes should contain bout_type. Possible values are:

    • scalar

    • Field2D

    • Field3D

    If the variable is an evolving variable (i.e. has a time dimension), then it is appended with a “_t”

static dims_from_type(type)
static get_dims_type()
static type_from_dims(dims)
boutdata.alwayswarn(message)
boutdata.attributes(varname, path='.', prefix='BOUT.dmp')

Return a dictionary of variable attributes in an output file

Parameters:

  • varname (str) – Name of the variable

  • path (str, optional) – Path to data files (default: “.”)

  • prefix (str, optional) – File prefix (default: “BOUT.dmp”)

Returns:

A dictionary of attributes of varname

Return type:

dict

boutdata.build_and_log(test)

Run make and redirect the output to a log file. Prints input

On Windows, does nothing because executable should have already been built

boutdata.collect(varname, xind=None, yind=None, zind=None, tind=None, path='.', yguards=False, xguards=True, info=True, prefix='BOUT.dmp', strict=False, tind_auto=False, datafile_cache=None)

Collect a variable from a set of BOUT++ outputs.

Parameters:

  • varname (str) – Name of the variable

  • xind, yind, zind, tind (int, slice or list of int, optional) – Range of X, Y, Z or time indices to collect. Either a single index to collect, a list containing [start, end] (inclusive end), or a slice object (usual python indexing). Default is to fetch all indices

  • path (str, optional) – Path to data files (default: “.”)

  • prefix (str, optional) – File prefix (default: “BOUT.dmp”)

  • yguards (bool or “include_upper”, optional) – Collect Y boundary guard cells? (default: False) If yguards==”include_upper” the y-boundary cells from the upper (second) target are also included.

  • xguards (bool, optional) – Collect X boundary guard cells? (default: True) (Set to True to be consistent with the definition of nx)

  • info (bool, optional) – Print information about collect? (default: True)

  • strict (bool, optional) – Fail if the exact variable name is not found? (default: False)

  • tind_auto (bool, optional) – Read all files, to get the shortest length of time_indices. Useful if writing got interrupted (default: False)

  • datafile_cache (datafile_cache_tuple, optional) – Optional cache of open DataFile instances: namedtuple as returned by create_cache. Used by BoutOutputs to pass in a cache so that we do not have to re-open the dump files to read another variable (default: None)

Examples

>>> collect(name)
BoutArray([[[[...]]]])
boutdata.determineNumberOfCPUs()

Number of virtual or physical CPUs on this system

i.e. user/real as output by time(1) when called with an optimally scaling userspace-only program

Taken from a post on stackoverflow: https://stackoverflow.com/questions/1006289/how-to-find-out-the-number-of-cpus-in-python

Returns:

The number of CPUs

Return type:

int

boutdata.launch(command, runcmd=None, nproc=None, mthread=None, output=None, pipe=False, verbose=False)

Launch parallel MPI jobs

>>> status = launch(command, nproc, output=None)
Parameters:

  • command (str) – The command to run

  • runcmd (str, optional) – Command for running parallel job; defaults to what getmpirun() returns”

  • nproc (int, optional) – Number of processors (default: all available processors)

  • mthread (int, optional) – Number of omp threads (default: the value of the OMP_NUM_THREADS environment variable

  • output (str, optional) – Name of file to save output to

  • pipe (bool, optional) – If True, return the output of the command

  • verbose (bool, optional) – Print the full command to be run before running it

Returns:

tuple – The return code, and either command output if pipe=True else None

Return type:

(int, str)

boutdata.launch_safe(command, *args, **kwargs)

‘Safe’ version of launch.

Raises an RuntimeError exception if the command is not successful

Parameters:

  • command (str) – The command to run

  • *args, **kwargs – Optional arguments passed to shell

boutdata.shell(command, pipe=False)

Run a shell command

Parameters:

  • command (list of str) – The command to run, split into (shell) words

  • pipe (bool, optional) – Grab the output as text, else just run the command in the background

Returns:

tuple – The return code, and either command output if pipe=True else None

Return type:

(int, str)

boutdata.shell_safe(command, *args, **kwargs)

‘Safe’ version of shell.

Raises a RuntimeError exception if the command is not successful

Parameters:

  • command (str) – The command to run

  • *args, **kwargs – Optional arguments passed to shell