boututils package#
Module contents#
Generic routines, useful for all data
Submodules#
boututils.analyse_equil_2 module#
boututils.anim module#
Animate graph with mayavi
boututils.ask module#
Ask a yes/no question and return the answer.
- boututils.ask.query_yes_no(question, default='yes')#
Ask a yes/no question via input() and return their answer.
Answers are case-insensitive.
Probably originally from https://code.activestate.com/recipes/577058/ via https://stackoverflow.com/a/3041990/2043465
- Parameters:
question (str) – Question to be presented to the user
default ({“yes”, “no”, None}) – The presumed answer if the user just hits <Enter>. It must be “yes” (the default), “no” or None (meaning an answer is required of the user).
- Returns:
True if the answer was “yes” or “y”, False if “no” or “n”
- Return type:
bool
boututils.boutarray module#
Wrapper for ndarray with extra attributes for BOUT++ fields.
- class boututils.boutarray.BoutArray(input_array, attributes={})#
Bases:
ndarray
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)#
boututils.boutgrid module#
- boututils.boutgrid.aligned_points(grid, nz=1, period=1.0, maxshift=0.4)#
- boututils.boutgrid.create_grid(grid, data, period=1)#
Create a structured grid which can be plotted with Mayavi or saved to a VTK file.
Example
from boutdata.collect import collect from boututils.file_import import file_import from boututile import boutgrid
# Load grid file g = file_import(“bout.grd.nc”)
# Load 3D data (x,y,z) data = collect(“P”, tind=-1)[0,:,:,:]
# Create a structured grid sgrid = boutgrid.create_grid(g, data, 1)
# Write structured grid to file w = tvtk.XMLStructuredGridWriter(input=sgrid, file_name=’sgrid.vts’) w.write()
# View the structured grid boutgrid.view3d(sgrid)
- boututils.boutgrid.view3d(sgrid)#
boututils.boutwarnings module#
Wrappers for warnings functions.
Allows raising warnings that are always printed by default.
- exception boututils.boutwarnings.AlwaysWarning(*args, **kwargs)#
- boututils.boutwarnings.alwayswarn(message)#
- boututils.boutwarnings.defaultwarn(message)#
boututils.calculus module#
Derivatives and integrals of periodic and non-periodic functions
B.Dudson, University of York, Nov 2009
- boututils.calculus.deriv(*args, **kwargs)#
Take derivative of 1D array
result = deriv(y) result = deriv(x, y)
keywords
periodic = False Domain is periodic
- boututils.calculus.deriv2D(data, axis=-1, dx=1.0, noise_suppression=True)#
Takes 1D or 2D Derivative of 2D array using convolution
result = deriv2D(data) result = deriv2D(data, dx)
output is 2D (if only one axis specified) output is 3D if no axis specified [nx,ny,2] with the third dimension being [dfdx, dfdy]
keywords: axis = 0/1 If no axis specified 2D derivative will be returned dx = 1.0 axis spacing, must be 2D if 2D deriv is taken - default is [1.0,1.0] noise_suppression = True
noise suppressing coefficients used to take derivative - default = True
- boututils.calculus.integrate(var, periodic=False)#
Integrate a 1D array
Return array is the same size as the input
- boututils.calculus.old_div(a, b)#
- boututils.calculus.simpson_integrate(data, dx, dy, kernel=0.0, weight=1.0)#
Integrates 2D data to one value using the simpson method and matrix convolution
result = simpson_integrate(data,dx,dy)
keywords:
- kernel - can be supplied if the simpson matrix is calculated ahead of time
if not supplied, is calculated within this function
- if you need to integrate the same shape data over and over, calculated
- it ahead of time using:
kernel = simpson_matrix(Nx,Ny,dx,dy)
- weight - can be used to scale data if single number
can be used to mask data if weight is array (same size as data)
- boututils.calculus.simpson_matrix(Nx, Ny, dx, dy)#
Creates a 2D matrix of coefficients for the simpson_integrate function
- Call ahead of time if you need to perform integration of the same size data with the
same dx and dy
Otherwise, simpson_integrate will automatically call this
boututils.closest_line module#
- boututils.closest_line.closest_line(n, x, y, ri, zi, mind=None)#
boututils.crosslines module#
boututils.datafile module#
File I/O class
A wrapper around various NetCDF libraries and h5py, used by BOUT++ routines. Creates a consistent interface across machines
Supported libraries:
h5py
(for HDF5 files)netCDF4
(preferred NetCDF library)
Note
NetCDF and HDF5 include unlimited dimensions, but this library is just for very simple I/O operations. Educated guesses are made for the dimensions.
- class boututils.datafile.DataFile(filename=None, write=False, create=False, format='NETCDF4', **kwargs)#
File I/O class
A wrapper around various NetCDF libraries and h5py, used by BOUT++ routines. Creates a consistent interface across machines
- Parameters:
filename (str, optional) – Name of file to open. If no filename supplied, you will need to call
open
and supplyfilename
therewrite (bool, optional) – If True, open the file in read-write mode (existing files will be appended to). Default is read-only mode
create (bool, optional) – If True, open the file in write mode (existing files will be truncated). Default is read-only mode
format (str, optional) – Name of a filetype to use (e.g.
NETCDF3_CLASSIC
,NETCDF3_64BIT
,NETCDF4
,HDF5
)
- attributes(varname)#
Return a dictionary of attributes
- Parameters:
varname (str) – The name of the variable
- Returns:
The attribute names and their values
- Return type:
dict
- bout_type(varname)#
Return the name of the BOUT++ type of a variable
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”
- Parameters:
varname (str) – The name of the variable
- Returns:
The name of the BOUT++ type
- Return type:
str
- close()#
Close a file and flush data to disk
- dimensions(varname)#
Return the names of all the dimensions of a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The names of the variable’s dimensions
- Return type:
tuple of str
- get(name, default=None)#
- impl = None#
- list()#
List all variables in the file
- Returns:
A list containing all the names of the variables
- Return type:
list of str
- list_file_attributes()#
- ndims(varname)#
Return the number of dimensions for a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The number of dimensions
- Return type:
int
- open(filename, write=False, create=False, format='NETCDF3_CLASSIC')#
Open the file
- Parameters:
filename (str, optional) – Name of file to open
write (bool, optional) – If True, open the file in read-write mode (existing files will be appended to). Default is read-only mode
create (bool, optional) – If True, open the file in write mode (existing files will be truncated). Default is read-only mode
format (str, optional) – Name of a filetype to use (e.g.
NETCDF3_CLASSIC
,NETCDF4
,HDF5
)
- read(name, ranges=None, asBoutArray=True)#
Read a variable from the file
- Parameters:
name (str) – Name of the variable to read
ranges (list of slice objects, optional) – Slices of variable to read, can also be converted from lists or tuples of (start, stop, stride). The number of elements in
ranges
should be equal to the number of dimensions of the variable you wish to read. Seesize
for how to get the dimensionsasBoutArray (bool, optional) – If True, return the variable as a
BoutArray
(the default)
- Returns:
The variable from the file (
BoutArray
ifasBoutArray
is True)- Return type:
ndarray or
BoutArray
- read_file_attribute(name)#
- size(varname)#
Return the size of each dimension of a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The size of each dimension
- Return type:
tuple of int
- sync()#
Write pending changes to disk.
- write(name, data, info=False)#
Write a variable to file
If the variable is not a
BoutArray
with thebout_type
attribute, a guess will be made for the dimensions- Parameters:
name (str) – Name of the variable to use in the file
data (
BoutArray
or ndarray) – An array containing the variable datainfo (bool, optional) – If True, print information about what is being written to file
- Return type:
None
- write_file_attribute(name, value)#
- class boututils.datafile.DataFile_HDF5(filename=None, write=False, create=False, format=None)#
- attributes(varname)#
Return a dictionary of attributes
- Parameters:
varname (str) – The name of the variable
- Returns:
The attribute names and their values
- Return type:
dict
- close()#
Close a file and flush data to disk
- dimensions(varname)#
Return the names of all the dimensions of a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The names of the variable’s dimensions
- Return type:
tuple of str
- handle = None#
- list()#
List all variables in the file
- Returns:
A list containing all the names of the variables
- Return type:
list of str
- list_file_attributes()#
- ndims(varname)#
Return the number of dimensions for a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The number of dimensions
- Return type:
int
- open(filename, write=False, create=False, format=None)#
Open the file
- Parameters:
filename (str, optional) – Name of file to open
write (bool, optional) – If True, open the file in read-write mode (existing files will be appended to). Default is read-only mode
create (bool, optional) – If True, open the file in write mode (existing files will be truncated). Default is read-only mode
format (str, optional) – Name of a filetype to use (e.g.
NETCDF3_CLASSIC
,NETCDF4
,HDF5
)
- read(name, ranges=None, asBoutArray=True)#
Read a variable from the file
- Parameters:
name (str) – Name of the variable to read
ranges (list of slice objects, optional) – Slices of variable to read, can also be converted from lists or tuples of (start, stop, stride). The number of elements in
ranges
should be equal to the number of dimensions of the variable you wish to read. Seesize
for how to get the dimensionsasBoutArray (bool, optional) – If True, return the variable as a
BoutArray
(the default)
- Returns:
The variable from the file (
BoutArray
ifasBoutArray
is True)- Return type:
ndarray or
BoutArray
- read_file_attribute(name)#
- size(varname)#
Return the size of each dimension of a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The size of each dimension
- Return type:
tuple of int
- sync()#
Write pending changes to disk.
- write(name, data, info=False)#
Write a variable to file
If the variable is not a
BoutArray
with thebout_type
attribute, a guess will be made for the dimensions- Parameters:
name (str) – Name of the variable to use in the file
data (
BoutArray
or ndarray) – An array containing the variable datainfo (bool, optional) – If True, print information about what is being written to file
- Return type:
None
- write_file_attribute(name, value)#
- class boututils.datafile.DataFile_netCDF(filename=None, write=False, create=False, format='NETCDF3_CLASSIC', **kwargs)#
- attributes(varname)#
Return a dictionary of attributes
- Parameters:
varname (str) – The name of the variable
- Returns:
The attribute names and their values
- Return type:
dict
- close()#
Close a file and flush data to disk
- dimensions(varname)#
Return the names of all the dimensions of a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The names of the variable’s dimensions
- Return type:
tuple of str
- handle = None#
- list()#
List all variables in the file
- Returns:
A list containing all the names of the variables
- Return type:
list of str
- list_file_attributes()#
- ndims(varname)#
Return the number of dimensions for a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The number of dimensions
- Return type:
int
- open(filename, write=False, create=False, format='NETCDF3_CLASSIC')#
Open the file
- Parameters:
filename (str, optional) – Name of file to open
write (bool, optional) – If True, open the file in read-write mode (existing files will be appended to). Default is read-only mode
create (bool, optional) – If True, open the file in write mode (existing files will be truncated). Default is read-only mode
format (str, optional) – Name of a filetype to use (e.g.
NETCDF3_CLASSIC
,NETCDF4
,HDF5
)
- read(name, ranges=None, asBoutArray=True)#
Read a variable from the file.
- read_file_attribute(name)#
- size(varname)#
Return the size of each dimension of a variable
- Parameters:
varname (str) – The name of the variable
- Returns:
The size of each dimension
- Return type:
tuple of int
- sync()#
Write pending changes to disk.
- write(name, data, info=False)#
Write a variable to file
If the variable is not a
BoutArray
with thebout_type
attribute, a guess will be made for the dimensions- Parameters:
name (str) – Name of the variable to use in the file
data (
BoutArray
or ndarray) – An array containing the variable datainfo (bool, optional) – If True, print information about what is being written to file
- Return type:
None
- write_file_attribute(name, value)#
boututils.efit_analyzer module#
boututils.fft_deriv module#
boututils.fft_integrate module#
- boututils.fft_integrate.fft_integrate(y, loop=None)#
- boututils.fft_integrate.test_integrate()#
boututils.file_import module#
Import an entire BOUT++ DataFile into memory
- boututils.file_import.file_import(name)#
Read all variables from file into a dictionary
- Parameters:
name (str) – Name of file to read
- Returns:
Dictionary containing all the variables in the file
- Return type:
dict
boututils.geqdsk module#
- class boututils.geqdsk.Geqdsk#
- get(varname)#
- getAll()#
- getAllVars()#
- getDescriptor(varname)#
- openFile(filename)#
open geqdsk file and parse its content
- boututils.geqdsk.main()#
boututils.idl_tabulate module#
- boututils.idl_tabulate.idl_tabulate(x, f, p=5)#
boututils.int_func module#
boututils.linear_regression module#
- boututils.linear_regression.linear_regression(x, y)#
Simple linear regression of two variables
y = a + bx
a, b = linear_regression(x, y)
boututils.local_min_max module#
- boututils.local_min_max.detect_local_maxima(arr)#
Takes an array and detects the peaks using the local maximum filter. Returns a boolean mask of the troughs (i.e. 1 when the pixel’s value is the neighborhood maximum, 0 otherwise)
- boututils.local_min_max.detect_local_minima(arr)#
Takes an array and detects the troughs using the local maximum filter. Returns a boolean mask of the troughs (i.e. 1 when the pixel’s value is the neighborhood maximum, 0 otherwise)
boututils.mode_structure module#
boututils.moment_xyzt module#
boututils.options module#
Module to allow BOUT.inp files to be read into python and manipulated with ease.
Nick Walkden, June 2015 nick.walkden@ccfe.ac.uk
- class boututils.options.BOUTOptions(inp_path=None)#
Class to store and interact with options from BOUT++
- Parameters:
inp_path (str, optional) – Path to BOUT++ options file
Examples
Instantiate with
>>> myOpts = BOUTOptions() >>> myOpts.read_inp('path/to/input/file')
or
>>> myOpts = BOUTOptions('path/to/input/file')
To get a list of sections use
>>> section_list = myOpts.list_sections >>> # Also print to screen: >>> section_list = myOpts.list_sections(verbose=True)
Each section of the input is stored as a dictionary attribute so that, if you want all the settings in the section [ddx]:
>> ddx_opt_dict = myOpts.ddx
and access individual settings by
>>> ddx_setting = myOpts.ddx['first']
Any settings in BOUT.inp without a section are stored in
>>> root_dict = myOpts.root
- add_section(section)#
Add a section to the options
- Parameters:
section (str) – The name of a new section
- list_sections(verbose=False)#
Return all the sections in the options
- Parameters:
verbose (bool, optional) – If True, print sections to screen
- read_inp(inp_path='')#
Read a BOUT++ input file
- Parameters:
inp_path (str, optional) – Path to the input file (default: current directory)
- remove_section(section)#
Remove a section from the options
- Parameters:
section (str) – The name of a section to remove
boututils.plotdata module#
- boututils.plotdata.plotdata(data, x=None, y=None, title=None, xtitle=None, ytitle=None, output=None, range=None, fill=True, mono=False, colorbar=True, xerr=None, yerr=None)#
Plot 1D or 2D data, with a variety of options.
- boututils.plotdata.test()#
Test the plotdata routine.
boututils.radial_grid module#
boututils.read_geqdsk module#
- boututils.read_geqdsk.read_geqdsk(file)#
boututils.run_wrapper module#
Collection of functions which can be used to make a BOUT++ run
- boututils.run_wrapper.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
- boututils.run_wrapper.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
- boututils.run_wrapper.getmpirun(default='mpirun -np')#
- Return environment variable named MPIRUN, if it exists else return
a default mpirun command
- Parameters:
default (str, optional) – An mpirun command to return if
MPIRUN
is not set in the environment
- boututils.run_wrapper.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 variableoutput (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)
- boututils.run_wrapper.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
- boututils.run_wrapper.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)
- boututils.run_wrapper.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
boututils.showdata module#
Visualisation and animation routines
Written by Luke Easy le590@york.ac.uk Last Updated 19/3/2015 Additional functionality by George Breyiannis 26/12/2014
- boututils.showdata.showdata(vars, titles=[], legendlabels=[], surf=[], polar=[], tslice=0, t_array=None, movie=0, fps=28, dpi=200, intv=1, Ncolors=25, x=[], y=[], global_colors=False, symmetric_colors=False, hold_aspect=False, cmap=None, clear_between_frames=None, return_animation=False, window_title='')#
A Function to animate time dependent data from BOUT++
To animate multiple variables on different axes:
>>> showdata([var1, var2, var3])
To animate more than one line on a single axes:
>>> showdata([[var1, var2, var3]])
The default graph types are: 2D (time + 1 spatial dimension) arrays = animated line plot 3D (time + 2 spatial dimensions) arrays = animated contour plot.
To use surface or polar plots:
>>> showdata(var, surf=1) >>> showdata(var, polar=1)
Can plot different graph types on different axes. Default graph types will be used depending on the dimensions of the input arrays. To specify polar/surface plots on different axes:
>>> showdata([var1, var2], surf=[1, 0], polar=[0, 1])
Movies require FFmpeg (for .mp4) and/or ImageMagick (for .gif) to be installed. The ‘movie’ option can be set to 1 (which will produce an mp4 called ‘animation.mp4’), to a name with no extension (which will produce an mp4 called ‘<name>.mp4’)
The
tslice
variable is used to control the time value that is printed on each frame of the animation. If the input data matches the time values found within BOUT++’s dmp data files, then these time values will be used. Otherwise, an integer counter is used.The
cmap
variable (if specified) will set the colormap used in the plot cmap must be a matplotlib colormap instance, or the name of a registered matplotlib colormapDuring animation click once to stop in the current frame. Click again to continue.
- Parameters:
vars (array_like or list of array_like) – Variable or list of variables to plot
titles (str or list of str, optional) – Title or list of titles for each axis
legendlabels (str or list of str, optional) – Legend or list of legends for each variable
surf (list of int) – Which axes to plot as a surface plot
polar (list of int) – Which axes to plot as a polar plot
tslice (list of int) – Use these time values from a dump file (see above)
t_array (array) – Pass in t_array using this argument to use the simulation time in plot titles. Otherwise, just use the t-index.
movie (int) – If 1, save the animation to file
fps (int) – Number of frames per second to use when saving animation
dpi (int) – Dots per inch to use when saving animation
intv (int) – ???
Ncolors (int) – Number of levels in contour plots
x, y (array_like, list of array_like) – X, Y coordinates
global_colors (bool) – If “vars” is a list the colorlevels are determined from the maximum of the maxima and and the minimum of the minima in all fields in vars
symmetric_colors (bool) – Colour levels are symmetric
hold_aspect (bool) – Use equal aspect ratio in plots
cmap (colormap) – A matplotlib colormap instance to use
clear_between_frames (bool, optional) –
Default (None) - all plots except line plots will clear between frames
True - all plots will clear between frames
False - no plots will clear between frames
return_animation (bool) – Return the matplotlib animation instance
window_title (str) – Give a title for the animation window
boututils.spectrogram module#
Creates spectrograms using the Gabor transform to maintain time and frequency resolution
written by: Jarrod Leddy updated: 23/06/2016
- boututils.spectrogram.spectrogram(data, dx, sigma, clip=1.0, optimise_clipping=True, nskip=1.0)#
Creates spectrograms using the Gabor transform to maintain time and frequency resolution
Note
Very early and very late times will have some issues due to the method - truncate them after taking the spectrogram if they are below your required standards
Note
If you are seeing issues at the top or bottom of the frequency range, you need a longer time series
written by: Jarrod Leddy updated: 23/06/2016
- Parameters:
data (array_like) – The time series you want spectrogrammed
dt (float) – Time resolution
sigma (float) – Used in the Gabor transform, will balance time and frequency resolution suggested value is 1.0, but may need to be adjusted manually until result is as desired:
If bands are too tall raise sigma
If bands are too wide, lower sigma
clip (float, optional) – Makes the spectrogram run faster, but decreases frequency resolution. clip is by what factor the time spectrum should be clipped by –> N_new = N / clip
optimise_clip (bool) – If true (default) will change the data length to be 2^N (rounded down from your inputed clip value) to make FFT’s fast
nskip (float) – Scales final time axis, skipping points over which to centre the gaussian window for the FFTs
- Returns:
tuple – A tuple containing the spectrogram, frequency and time
- Return type:
(array_like, array_like, array_like)
- boututils.spectrogram.test_spectrogram(n, d, s)#
Function used to test the performance of spectrogram with various values of sigma
- Parameters:
n (int) – Number of points
d (float) – Grid spacing
s (float) – Initial sigma
boututils.surface_average module#
boututils.volume_integral module#
boututils.watch module#
Routines for watching files for changes
- boututils.watch.watch(files, timeout=None, poll=2)#
Watch a given file or collection of files until one changes. Uses polling.
- Parameters:
files (str or list of str) – Name of one or more files to watch
timeout (int, optional) – Timeout in seconds (default is no timeout)
poll (int, optional) – Polling interval in seconds (default: 2)
- Returns:
The name of the first changed file, or None if timed out before any changes
- Return type:
str
Examples
To watch one file, timing out after 60 seconds:
>>> watch('file1', timeout=60)
To watch 2 files, never timing out:
>>> watch(['file1', 'file2'])
Author: Ben Dudson <benjamin.dudson@york.ac.uk>