boutdata package¶
Module contents¶
Routines for exchanging data to/from BOUT++
-
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.
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, optional) – Collect Y boundary guard cells? (default: False)
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([[[[...]]]])
Submodules¶
boutdata.cbdtoeqdsk module¶
boutdata.collect module¶
-
boutdata.collect.
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.collect.
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, optional) – Collect Y boundary guard cells? (default: False)
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.collect.
create_cache
(path, prefix)¶ Create a list of DataFile objects to be passed repeatedly to collect.
- Parameters
path (str) – Path to data files
prefix (str) – File prefix
- Returns
namedtuple – The cache of DataFiles in a namedtuple along with the file_list, and parallel and suffix attributes
- Return type
(list of str, bool, str, list of
DataFile
)
-
boutdata.collect.
dimensions
(varname, path='.', prefix='BOUT.dmp')¶ Return the names of dimensions of a variable 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
The elements of the tuple give the names of corresponding variable dimensions
- Return type
tuple of strs
-
boutdata.collect.
findFiles
(path, prefix)¶ Find files matching prefix in path.
Netcdf (“.nc”, “.ncdf”, “.cdl”) and HDF5 (“.h5”, “.hdf5”, “.hdf”) files are searched.
- Parameters
path (str) – Path to data files
prefix (str) – File prefix
- Returns
tuple – The first element of the tuple is the list of files, the second is whether the files are a parallel dump file and the last element is the file suffix.
- Return type
(list of str, bool, str)
-
boutdata.collect.
findVar
(varname, varlist)¶ Find variable name in a list
First does case insensitive comparison, then checks for abbreviations.
Returns the matched string, or raises a ValueError
- Parameters
varname (str) – Variable name to look for
varlist (list of str) – List of possible variable names
- Returns
The closest match to varname in varlist
- Return type
str
boutdata.data module¶
Provides a class BoutData which makes access to code inputs and outputs easier. Creates a tree of maps, inspired by approach used in OMFIT
-
boutdata.data.
BoutData
(path='.', prefix='BOUT.dmp', caching=False, **kwargs)¶ Returns a dictionary, containing the contents of a BOUT++ output directory.
Does not allow writing, only reading of data. By default there is no cache, so each time a variable is read it is collected; if caching is set to True variables are stored once they are read.
- Parameters
path (str, optional) – Path to data files (default: “.”)
prefix (str, optional) – File prefix (default: “BOUT.dmp”)
caching (bool, float, optional) – Switches on caching of data, so it is only read into memory when first accessed (default False) If caching is set to a number, it gives the maximum size of the cache in GB, after which entries will be discarded in first-in-first-out order to prevent the cache getting too big. If the variable being returned is bigger than the maximum cache size, then the variable will be returned without being added to the cache, and the rest of the cache will be left (default: False)
DataFileCaching (bool, optional) – Switch for creation of a cache of DataFile objects to be passed to collect so that DataFiles do not need to be re-opened to read each variable (default: True)
**kwargs – Keyword arguments that are passed through to collect()
- Returns
Contents of a BOUT++ output directory, including options and output files
- Return type
dict
Examples
>>> d = BoutData(".") # Current directory
>>> d.keys() # List all valid keys
>>> print(d["options"]) # Prints tree of options
>>> d["options"]["nout"] # Value of nout in BOUT.inp file
>>> print(d["outputs"]) # Print available outputs
>>> d["outputs"]["ne"] # Read "ne" from data files
>>> d = BoutData(".", prefix="BOUT.dmp", caching=True) # Turn on caching
-
class
boutdata.data.
BoutOptions
(name='root', parent=None)¶ This class represents a tree structure. Each node (BoutOptions object) can have several sub-nodes (sections), and several key-value pairs.
- Parameters
name (str, optional) – Name of the root section (default: “root”)
parent (BoutOptions, optional) – A parent BoutOptions object (default: None)
Examples
>>> optRoot = BoutOptions() # Create a root
Specify value of a key in a section “test” If the section does not exist then it is created
>>> optRoot.getSection("test")["key"] = 4
Get the value of a key in a section “test” If the section does not exist then a KeyError is raised
>>> print(optRoot["test"]["key"]) 4
To pretty print the options
>>> print(optRoot) root |- test | |- key = 4
-
as_dict
()¶ Return a nested dictionary of all the options.
-
evaluate_scalar
(name)¶ Evaluate (recursively) scalar expressions
-
getSection
(name)¶ Return a section object. If the section does not exist then it is created
- Parameters
name (str) – Name of the section to get/create
- Returns
A new section with the original object as the parent
- Return type
-
keys
()¶ Returns all keys, including sections and values
-
path
()¶ Returns the path of this section, joining together names of parents
-
sections
()¶ Return a list of sub-sections
-
values
()¶ Return a list of values
-
class
boutdata.data.
BoutOptionsFile
(filename='BOUT.inp', name='root', gridfilename=None, nx=None, ny=None, nz=None)¶ Parses a BOUT.inp configuration file, producing a tree of BoutOptions.
Slight differences from ConfigParser, including allowing values before the first section header.
- Parameters
filename (str, optional) – Path to file to read
name (str, optional) – Name of root section (default: “root”)
gridfilename (str, optional) – If present, path to gridfile from which to read grid sizes (nx, ny, nz)
nx, ny (int, optional) –
Specify sizes of grid, used when evaluating option strings
Cannot be given if gridfilename is specified
Must both be given if either is
If neither gridfilename nor nx, ny are given then will try to find nx, ny from (in order) the ‘mesh’ section of options, outputfiles in the same directory is the input file, or the grid file specified in the options file (used as a path relative to the current directory)
nz (int, optional) – Use this value for nz when evaluating option expressions, if given. Overrides values found from input file, output files or grid files
Examples
>>> opts = BoutOptionsFile("BOUT.inp") >>> print(opts) # Print all options in a tree root |- nout = 100 |- timestep = 2 ...
>>> opts["All"]["scale"] # Value "scale" in section "All" 1.0
-
evaluate
(name)¶ Evaluate (recursively) expressions
Sections and subsections must be given as part of ‘name’, separated by colons
- Parameters
name (str) – Name of variable to evaluate, including sections and subsections
-
write
(filename=None, overwrite=False)¶ Write to BOUT++ options file
This method will throw an error rather than overwriting an existing file unless the overwrite argument is set to true. Note, no comments from the original input file are transferred to the new one.
- Parameters
filename (str) – Path of the file to write (defaults to path of the file that was read in)
overwrite (bool) – If False then throw an exception if ‘filename’ already exists. Otherwise, just overwrite without asking. (default False)
-
class
boutdata.data.
BoutOutputs
(path='.', prefix='BOUT.dmp', suffix=None, caching=False, DataFileCaching=True, **kwargs)¶ Emulates a map class, represents the contents of a BOUT++ dmp files. Does not allow writing, only reading of data. By default there is no cache, so each time a variable is read it is collected; if caching is set to True variables are stored once they are read. Extra keyword arguments are passed through to collect.
- Parameters
path (str, optional) – Path to data files (default: “.”)
prefix (str, optional) – File prefix (default: “BOUT.dmp”)
suffix (str, optional) – File suffix (default: None, searches all file extensions)
caching (bool, float, optional) – Switches on caching of data, so it is only read into memory when first accessed (default False) If caching is set to a number, it gives the maximum size of the cache in GB, after which entries will be discarded in first-in-first-out order to prevent the cache getting too big. If the variable being returned is bigger than the maximum cache size, then the variable will be returned without being added to the cache, and the rest of the cache will be left (default: False)
DataFileCaching (bool, optional) – Switch for creation of a cache of DataFile objects to be passed to collect so that DataFiles do not need to be re-opened to read each variable (default: True)
**kwargs – keyword arguments that are passed through to _caching_collect()
Examples
>>> d = BoutOutputs(".") # Current directory >> d.keys() # List all valid keys ['iteration', 'zperiod', 'MYSUB', ... ]
>>> d.dimensions["ne"] # Get the dimensions of the field ne ('t', 'x', 'y', 'z')
>>> d["ne"] # Read "ne" from data files BoutArray([[[[...]]]])
>>> d = BoutOutputs(".", prefix="BOUT.dmp", caching=True) # Turn on caching
-
evolvingVariables
()¶ Return a list of names of time-evolving variables
-
keys
()¶ Return a list of available variable names
-
redistribute
(npes, nxpe=None, mxg=2, myg=2, include_restarts=True)¶ Create a new set of dump files for npes processors.
Useful for restarting simulations using more or fewer processors.
Existing data and restart files are kept in the directory “redistribution_backups”. redistribute() will fail if this directory already exists, to avoid overwriting anything
- Parameters
npes (int) – Number of new files to create
nxpe (int, optional) – If nxpe is None (the default), then an ‘optimal’ number will be selected automatically
mxg, myg (int, optional) – Number of guard cells in x, y (default: 2)
include_restarts (bool, optional) – If True, then restart.redistribute will be used to redistribute the restart files also (default: True)
boutdata.gen_surface module¶
Flux surface generator for tokamak grid files
-
boutdata.gen_surface.
gen_surface
(grid)¶ Generator for iterating over flux surfaces
- Parameters
grid (DataFile) – An input grid file to read to find flux surfaces
- Yields
tuple ((int, list of int, bool)) – A tuple containing the x index, list of y indices and whether this flux surface is periodic
boutdata.griddata module¶
boutdata.input module¶
Fourier transform data for input to BOUT++
-
boutdata.input.
transform3D
(arr)¶ Fourier transforms a 3D array in the Z dimension
BOUT++ can take 3D inputs to be Fourier transformed in the Z direction.
- Parameters
arr (array_like) – Input 3-D array
- Returns
A 3D array [x,y,kz] where kz is organised in the standard FFT order, with constant (DC, kz=0) component first, followed by real/imaginary pairs.
kz = [0, (real, imag), (real, imag), …]
- Return type
array_like
boutdata.mayavi2 module¶
boutdata.mms module¶
boutdata.pol_slice module¶
-
boutdata.pol_slice.
pol_slice
(var3d, gridfile, n=1, zangle=0.0, nyInterp=None)¶ Takes a 3D variable, and returns a 2D slice at fixed toroidal angle
- Parameters
var3d (array_like) – The input array. Should be 3D
gridfile (str) – The gridfile containing the coordinate system to used
n (int, optional) – The number of times the data must be repeated for a full torus, e.g. n=2 is half a torus
zangle (float, optional) – The (real) toroidal angle of the result
nyInterp (int, optional) – The number of y (theta) points to use in the final result.
- Returns
A 2D-slice of var3d interpolated at a fixed toroidal angle
- Return type
array
boutdata.processor_rearrange module¶
Routines for redistributing files over different numbers of processors
-
boutdata.processor_rearrange.
create_processor_layout
(old_processor_layout, npes, nxpe=None)¶ Convert one processor layout into another one with a different total number of processors
If nxpe is None, use algorithm from BoutMesh to select optimal nxpe. Otherwise, check nxpe is valid (divides npes)
- Parameters
old_processor_layout (processor_layout) – The processor layout to convert
npes (int) – The new total number of procesors
nxpe (int, optional) – The number of procesors in x to use
- Returns
A description of the processor layout and grid sizes
- Return type
-
boutdata.processor_rearrange.
get_processor_layout
(boutfile, has_t_dimension=True, mxg=2, myg=2)¶ Given a BOUT.restart.* or BOUT.dmp.* file (as a DataFile object), return the processor layout for its data
- Parameters
boutfile (DataFile) – Restart or dump file to read
has_t_dimension (bool, optional) – Does this file have a time dimension?
mxg, myg (int, optional) – Number of x, y guard cells
- Returns
A description of the processor layout and grid sizes
- Return type
-
class
boutdata.processor_rearrange.
processor_layout
(nxpe, nype, npes, mxsub, mysub, nx, ny, mz, mxg, myg)¶ A namedtuple describing the processor layout, including grid sizes and guard cells
- Parameters
nxpe, nype (int) – The number of processors in x and y
npes (int) – The total number of procesors
mxsub, mysub (int) – The size of the grid in x and y on a single processor
nx, ny, mz (int) – The total size of the grid in x, y and z
mxg (int) – The number of guard cells in x and y
-
boutdata.processor_rearrange.
processor_layout_
¶ alias of
boutdata.processor_rearrange.BOUT_processor_layout
boutdata.restart module¶
Routines for manipulating restart files
-
boutdata.restart.
addnoise
(path='.', var=None, scale=1e-05)¶ Add random noise to restart files
Warning
Modifies restart files in place! This is in contrast to most of the functions in this module!
- Parameters
path (str, optional) – Path to restart files (default: current directory)
var (str, optional) – The variable to modify. By default all 3D variables are modified
scale (float) – Amplitude of the noise. Gaussian noise is used, with zero mean and this parameter as the standard deviation
-
boutdata.restart.
addvar
(var, value, path='.')¶ Adds a variable with constant value to all restart files.
Warning
Modifies restart files in place! This is in contrast to most of the functions in this module!
This is useful for restarting simulations whilst turning on new equations. By default BOUT++ throws an error if an evolving variable is not in the restart file. By setting an option the variable can be set to zero. This allows it to start with a non-zero value.
- Parameters
var (str) – The name of the variable to add
value (float) – Constant value for the variable
path (str, optional) – Input path to data files (default: current directory)
-
boutdata.restart.
create
(averagelast=1, final=- 1, path='data', output='./', informat='nc', outformat=None)¶ Create restart files from data (dmp) files.
- Parameters
averagelast (int, optional) – Number of time points (counting from
final
, inclusive) to average over (default is 1 i.e. just take last time-point)final (int, optional) – The last time point to use (default is last, -1)
path (str, optional) – Path to original restart files (default: “data”)
output (str, optional) – Path to write new restart files (default: current directory)
informat (str, optional) – File extension of original files (default: “nc”)
outformat (str, optional) – File extension of new files (default: use the same as
informat
)
-
boutdata.restart.
normal
(loc=0.0, scale=1.0, size=None)¶ Draw random samples from a normal (Gaussian) distribution.
The probability density function of the normal distribution, first derived by De Moivre and 200 years later by both Gauss and Laplace independently 2, is often called the bell curve because of its characteristic shape (see the example below).
The normal distributions occurs often in nature. For example, it describes the commonly occurring distribution of samples influenced by a large number of tiny, random disturbances, each with its own unique distribution 2.
Note
New code should use the
normal
method of adefault_rng()
instance instead; please see the random-quick-start.- Parameters
loc (float or array_like of floats) – Mean (“centre”) of the distribution.
scale (float or array_like of floats) – Standard deviation (spread or “width”) of the distribution. Must be non-negative.
size (int or tuple of ints, optional) – Output shape. If the given shape is, e.g.,
(m, n, k)
, thenm * n * k
samples are drawn. If size isNone
(default), a single value is returned ifloc
andscale
are both scalars. Otherwise,np.broadcast(loc, scale).size
samples are drawn.
- Returns
out – Drawn samples from the parameterized normal distribution.
- Return type
ndarray or scalar
See also
scipy.stats.norm
probability density function, distribution or cumulative density function, etc.
Generator.normal
which should be used for new code.
Notes
The probability density for the Gaussian distribution is
\[p(x) = \frac{1}{\sqrt{ 2 \pi \sigma^2 }} e^{ - \frac{ (x - \mu)^2 } {2 \sigma^2} },\]where \(\mu\) is the mean and \(\sigma\) the standard deviation. The square of the standard deviation, \(\sigma^2\), is called the variance.
The function has its peak at the mean, and its “spread” increases with the standard deviation (the function reaches 0.607 times its maximum at \(x + \sigma\) and \(x - \sigma\) 2). This implies that normal is more likely to return samples lying close to the mean, rather than those far away.
References
- 1
Wikipedia, “Normal distribution”, https://en.wikipedia.org/wiki/Normal_distribution
- 2(1,2,3)
P. R. Peebles Jr., “Central Limit Theorem” in “Probability, Random Variables and Random Signal Principles”, 4th ed., 2001, pp. 51, 51, 125.
Examples
Draw samples from the distribution:
>>> mu, sigma = 0, 0.1 # mean and standard deviation >>> s = np.random.normal(mu, sigma, 1000)
Verify the mean and the variance:
>>> abs(mu - np.mean(s)) 0.0 # may vary
>>> abs(sigma - np.std(s, ddof=1)) 0.1 # may vary
Display the histogram of the samples, along with the probability density function:
>>> import matplotlib.pyplot as plt >>> count, bins, ignored = plt.hist(s, 30, density=True) >>> plt.plot(bins, 1/(sigma * np.sqrt(2 * np.pi)) * ... np.exp( - (bins - mu)**2 / (2 * sigma**2) ), ... linewidth=2, color='r') >>> plt.show()
Two-by-four array of samples from N(3, 6.25):
>>> np.random.normal(3, 2.5, size=(2, 4)) array([[-4.49401501, 4.00950034, -1.81814867, 7.29718677], # random [ 0.39924804, 4.68456316, 4.99394529, 4.84057254]]) # random
-
boutdata.restart.
redistribute
(npes, path='data', nxpe=None, output='.', informat=None, outformat=None, mxg=2, myg=2)¶ Resize restart files across NPES processors.
Does not check if new processor arrangement is compatible with the branch cuts. In this respect
restart.split()
is safer. However, BOUT++ checks the topology during initialisation anyway so this is not too serious.- Parameters
npes (int) – Number of processors for the new restart files
path (str, optional) – Path to original restart files (default: “data”)
nxpe (int, optional) – Number of processors to use in the x-direction (determines split: npes = nxpe * nype). Default is None which uses the same algorithm as BoutMesh (but without topology information) to determine a suitable value for nxpe.
output (str, optional) – Location to save new restart files (default: current directory)
informat (str, optional) – Specify file format of old restart files (must be a suffix understood by DataFile, e.g. ‘nc’). Default uses the format of the first ‘BOUT.restart.*’ file listed by glob.glob.
outformat (str, optional) – Specify file format of new restart files (must be a suffix understood by DataFile, e.g. ‘nc’). Default is to use the same as informat.
- Returns
- Return type
True on success
-
boutdata.restart.
resize
(newNx, newNy, newNz, mxg=2, myg=2, path='data', output='./', informat='nc', outformat=None, method='linear', maxProc=None, mute=False)¶ Increase/decrease the number of points in restart files.
NOTE: Can’t overwrite WARNING: Currently only implemented with uniform BOUT++ grid
- Parameters
newNx, newNy, newNz (int) – nx, ny, nz for the new file (including ghost points)
mxg, myg (int, optional) – Number of ghost points in x, y (default: 2)
path (str, optional) – Input path to data files
output (str, optional) – Path to write new files
informat (str, optional) – File extension of input
outformat ({None, str}, optional) – File extension of output (default: use the same as
informat
)method ({‘linear’, ‘nearest’}, optional) – What interpolation method to be used
maxProc ({None, int}, optional) – Limits maximum processors to use when interpolating if set
mute (bool, optional) – Whether or not output should be printed from this function
- Returns
return – True on success, else False
- Return type
bool
-
boutdata.restart.
resize3DField
(var, data, coordsAndSizesTuple, method, mute)¶ Resize 3D fields
To be called by resize.
Written as a function in order to call it using multiprocess. Must be defined as a top level function in order to be pickable by the multiprocess.
See the function resize for details
-
boutdata.restart.
resizeY
(newy, path='data', output='.', informat='nc', outformat=None, myg=2)¶ Increase the number of Y points in restart files
Note
Can’t overwrite
- Parameters
newy (int) – ny for the new file
path (str, optional) – Path to original restart files (default: “data”)
output (str, optional) – Path to write new restart files (default: current directory)
informat (str, optional) – File extension of original files (default: “nc”)
outformat (str, optional) – File extension of new files (default: use the same as
informat
)myg (int, optional) – Number of ghost points in y (default: 2)
- Returns
- Return type
True on success, else False
-
boutdata.restart.
resizeZ
(newNz, path='data', output='./', informat='nc', outformat=None)¶ Increase the number of Z points in restart files
Note
Can’t overwrite
Will not yield a result close to the original if there are asymmetries in the z-direction
- Parameters
newNz (int) – nz for the new file
path (str, optional) – Path to original restart files (default: “data”)
output (str, optional) – Path to write new restart files (default: current directory)
informat (str, optional) – File extension of original files (default: “nc”)
outformat (str, optional) – File extension of new files (default: use the same as
informat
)
- Returns
- Return type
True on success, else False
-
boutdata.restart.
scalevar
(var, factor, path='.')¶ Scales a variable by a given factor, modifying restart files in place
Warning
Modifies restart files in place! This is in contrast to most of the functions in this module!
- Parameters
var (str) – Name of the variable
factor (float) – Factor to multiply
path (str, optional) – Path to the restart files (default: current directory)
boutdata.settings module¶
Parse BOUT.inp settings file
-
boutdata.settings.
get
(filename, name, section=None)¶ Find and return a single value from a BOUT.inp settings file
- Parameters
filename (str) – Name of the settings file
name (str) – The name of the setting
section (str, optional) – The section to look in (default: the global section)
Note that names and sections are case insensitive
- Returns
Value of the setting. If not found, raises a ValueError
- Return type
str
Examples
>>> settings.get("BOUT.inp", "nout") '100'
>>> settings.get("BOUT.inp", "compress", section="highbeta") 'true'
boutdata.shiftz module¶
-
boutdata.shiftz.
shiftz
(var, zangle, zperiod=1.0)¶ Shift a variable in Z, changing between field-aligned and orthogonal X-Z coordinates. This mainly used for tokamak simulations in field-aligned coordinates.
- Parameters
var (array_like) –
- Data to be shifted
4D [t,x,y,z] 3D [x,y,z] or [t,x,z] 2D [x,z]
zangle (array_like) –
- The shift angle
2D [x,y] (if var is 4D or 3D [x,y,z]) 1D [x] (if var is 3D [t,x,z] or 2D)
zperiod (float, optional) – The fraction of 2pi covered by the variable in Z. This corresponds to the ZPERIOD variable in BOUT.inp and multiplies the kz wavenumbers by this factor.
- Returns
A numpy array of the same size and shape as var
- Return type
ndarray
Examples
>>> from boutdata import collect >>> from boututils.datafile import DataFile >>> from boutdata.shiftz import shiftz >>> n = collect("Ne") # Read 4D variable [t,x,y,z] >>> d = DataFile("grid.nc") # Read the grid file >>> nxz = shiftz(n, d["zShift"], zperiod=4)
nxz is now in orthogonal X-Z coordinates (X is psi).
Note that in older grid files “qinty” is used rather than “zShift”.
Module contents¶
Routines for exchanging data to/from BOUT++
-
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.
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, optional) – Collect Y boundary guard cells? (default: False)
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([[[[...]]]])