Reference on kuibit.grid_data¶
The grid_data
module provides representations of data on uniform
grids as well as for data on refined grid hierarchies. Standard arithmetic
operations are supported for those data grids, further methods to interpolate
and resample. The number of dimensions is arbitrary.
The important classes defined here are
 UniformGridData
represents data on a uniform grid.
 HierarchicalGridData
represents data on a refined grid
hierarchy (AMR).
A UniformGridData
object contains a UniformGrid
one.
Similarly, a HierarchicalGridData
contains multiple
UniformGridData
.
We also define GridSeries
. This is intended to be used for 1D grid
data and it is a way to use the infrastructure for Series
for grid data. The
reason this is useful is that Series
are much simpler and leaner to work
with.

class
kuibit.grid_data.
GridSeries
(x, y, _=None)[source]¶ Onedimensional grid data, handled with the Series infrastructure.
When the data is one dimensional, sometimes it is more convenient to treat it a series instead of grid data. This class is uses the same infrastructure as
TimeSeries
andFrequencySeries
and has more or less the same features. Variables
x – Coordinates.
y – Values.
Constructor.
The third argument can be anything. It is required to ensure compatibility with other series, but it is not used.
 Parameters
x (1D NumPy array) – Coordinates.
y (1D NumPy array) – Values.

abs_max
()¶ Return the maximum of the absolute value

abs_min
()¶ Return the minimum of the absolute value

abs_nanmax
()¶ Return the maximum of the absolute value ignoring NaNs

abs_nanmin
()¶ Return the minimum of the absolute value ignoring NaNs

clip
(init=None, end=None)¶ Remove data outside the the interval
[init, end]
. Ifinit
orend
are not specified or None, it does not remove anything from this side. Parameters
init (float or None) – Data with
x <= init
will be removed.end (float or None) – Data with
x >= init
will be removed.

clipped
(init=None, end=None)¶ Return a series with data removed outside the interval
[init, end]
. Ifinit
orend
are not specified or None, it does not remove anything from this side. Parameters
init (float or None) – Data with
x <= init
will be removed.end (float or None) – Data with
x >= init
will be removed.
 Returns
Series with enforced minimum and maximum
 Return type
BaseSeries
or derived class

copy
()¶ Return a deep copy.
 Returns
Deep copy of the series.
 Return type
BaseSeries
or derived class

crop
(init=None, end=None)¶ Remove data outside the the interval
[init, end]
. Ifinit
orend
are not specified or None, it does not remove anything from this side. Parameters
init (float or None) – Data with
x <= init
will be removed.end (float or None) – Data with
x >= init
will be removed.

cropped
(init=None, end=None)¶ Return a series with data removed outside the interval
[init, end]
. Ifinit
orend
are not specified or None, it does not remove anything from this side. Parameters
init (float or None) – Data with
x <= init
will be removed.end (float or None) – Data with
x >= init
will be removed.
 Returns
Series with enforced minimum and maximum
 Return type
BaseSeries
or derived class

differentiate
(order=1)¶ Differentiate with the numerical orderdifferentiation.
The optional parameter
order
specifies the order of the derivative.The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
 Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).

differentiated
(order=1)¶ Return a series that is the numerical orderdifferentiation of the present series.
The optional parameter
order
specifies the order of the derivative.The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
 Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
 Returns
New series with derivative.
 Return type
BaseSeries
or derived class

evaluate_with_spline
(x, ext=2)¶ Evaluate the spline on the points
x
.Values outside the interval are extrapolated if
ext=0
, set to 0 ifext=1
, raise aValueError
ifext=2
, or ifext=3
, return the boundary value.This method is meant to be used only if you want to use a different ext for a specific call, otherwise, just use __call__.
 Parameters
x (1D NumPy array of float) – Array of x where to evaluate the series or single x.
ext (int) – How to deal values outside the bounaries. Values outside the interval are extrapolated if
ext=0
, set to 0 ifext=1
, raise a ValueError ifext=2
, or ifext=3
, return the boundary value.
 Returns
Values of the series evaluated on the input x.
 Return type
1D NumPy array or float

property
index
¶ Fake pandas properties, to make Series objects plottable by matplotlib.

integrate
(dx=None)¶ Integrate series with method of the rectangles.
The spacing
dx
can be optionally provided. If provided, it will be used (increasing performance), otherwise it will be computed internally.

integrated
(dx=None)¶ Return a series that is the integral computed with method of the rectangles.
The spacing
dx
can be optionally provided. If provided, it will be used (increasing performance), otherwise it will be computed internally. Parameters
dx (float or None) – Delta x in the independent variable. If None it will be computed internally.
 Returns
New series with the cumulative integral.
 Return type
BaseSeries
or derived class

is_complex
()¶ Return whether the data is complex.
 Returns
True if the data is complex, false if it is not.
 Return type
bool

is_masked
()¶ Return whether the x or y are masked.
 Returns
True if the x or y are masked, false if it is not.
 Return type
bool

is_regularly_sampled
()¶ Return whether the series is regularly sampled.
If the series is only one point, an error is raised.
 Returns
Is the series regularly sampled?
 Return type
bool

property
mask
¶ Return where the data is valid (according to the mask).
 Returns
Array of True/False of the same length of the data. False where the data is valid, true where is not.
 Return type
1D array of bool

mask_applied
(mask, ignore_existing=False)¶ Return a new series with given mask applied to the data.
If a previous mask already exists, the new mask will be added on top, unless
ignore_existing
is True. Parameters
mask (1D NumPy array) – Array of booleans that identify where the data is invalid. This can be obtained with the method
mask()
.ignore_existing (bool) – If True, overwrite any previously existing mask.
 Returns
New series with mask applied.
 Return type

mask_apply
(mask, ignore_existing=False)¶ Apply given mask.
If a previous mask already exists, the new mask will be added on top, unless
ignore_existing
is True. Parameters
mask (1D NumPy array) – Array of booleans that identify where the data is invalid. This can be obtained with the method
mask()
.ignore_existing (bool) – If True, overwrite any previously existing mask.

mask_equal
(value)¶ Mask where data is equal to given value.

mask_greater
(value)¶ Mask where data is greater to given value.

mask_greater_equal
(value)¶ Mask where data is greater or equal to given value.

mask_inside
(value1, value2)¶ Mask where data is inside the given values.

mask_invalid
()¶ Mask where data is invalid (NaNs of infs).

mask_less
(value)¶ Mask where data is less to given value.

mask_less_equal
(value)¶ Mask where data is less or equal to given value.

mask_not_equal
(value)¶ Mask where data is not equal to given value.

mask_outside
(value1, value2)¶ Mask where data is outside the given values.

mask_remove
()¶ Remove masked values.

mask_removed
()¶ Remove masked value.
Return a new series with valid values only.
 Returns
A new series with only valid values.
 Return type
BaseSeries
or derived class

masked_equal
(value)¶ Return a new objected masked where data is equal to given value.

masked_greater
(value)¶ Return a new objected masked where data is greater to given value.

masked_greater_equal
(value)¶ Return a new objected masked where data is greater or equal to given value.

masked_inside
(value1, value2)¶ Return a new objected masked where data is inside the given values.

masked_invalid
()¶ Return a new objected masked where data is invalid (NaNs or infs).

masked_less
(value)¶ Return a new objected masked where data is less to given value.

masked_less_equal
(value)¶ Return a new objected masked where data is less or equal to given value.

masked_not_equal
(value)¶ Return a new objected masked where data is not equal to given value.

masked_outside
(value1, value2)¶ Return a new objected masked where data is outside the given values.

nans_remove
()¶ Filter out nans/infinite values.

nans_removed
()¶ Filter out nans/infinite values. Return a new series with finite values only.
 Returns
A new series with only finite values.
 Return type
BaseSeries
or derived class

resample
(new_x, ext=2, piecewise_constant=False)¶ Resample the series to new independent variable new_x.
If you want to resample without using the spline, and you want a nearest neighbor resampling, pass the keyword
piecewise_constant=True
. This may be a good choice for data with large discontinuities, where the splines are ineffective. Parameters
new_x (1D NumPy array or list of float) – New independent variable.
ext (0 for extrapolation, 1 for returning zero, 2 for ValueError, 3 for extending the boundary) – How to handle points outside the interval.
piecewise_constant (bool) – Do not use splines, use the nearest neighbors.

resampled
(new_x, ext=2, piecewise_constant=False)¶ Return a new series resampled from this to new_x.
You can specify the details of the spline with the method make_spline.
If you want to resample without using the spline, and you want a nearest neighbor resampling, pass the keyword
piecewise_constant=True
. This may be a good choice for data with large discontinuities, where the splines are ineffective. Parameters
new_x (1D NumPy array or list of float) – New independent variable.
ext (0 for extrapolation, 1 for returning zero, 2 for
ValueError
, 3 for extending the boundary) – How to handle points outside the data interval.piecewise_constant (bool) – Do not use splines, use the nearest neighbors.
 Returns
Resampled series.
 Return type
BaseSeries
or derived class

save
(file_name, *args, **kwargs)¶ Saves into simple ASCII format with 2 columns
(x, y)
for real valued data and 3 columns(x, Re(y), Im(y))
for complex valued data.Unknown arguments are passed to
NumPy.savetxt
. Parameters
file_name (str) – Path (with extension) of the output file.

savgol_smooth
(window_size, order=3)¶ Smooth the series with a SavitzkyGolay filter with window of size
window_size
and orderorder
.This is just like a regular “Moving average” filter, but instead of just calculating the average, a polynomial (usually 2nd or 4th order) fit is made for every point, and only the “middle” point is chosen. Since 2nd (or 4th) order information is concerned at every point, the bias introduced in “moving average” approach at local maxima or minima, is circumvented.
 Parameters
window_size (int) – Number of points of the smoothing window (needs to be odd).
order (int) – Order of the filter.

savgol_smoothed
(window_size, order=3)¶ Return a smoothed series with a SavitzkyGolay filter with window of size
window_size
and orderorder
.This is just like a regular “Moving average” filter, but instead of just calculating the average, a polynomial (usually 2nd or 4th order) fit is made for every point, and only the “middle” point is chosen. Since 2nd (or 4th) order information is concerned at every point, the bias introduced in “moving average” approach at local maxima or minima, is circumvented.
 Parameters
window_size (int) – Number of points of the smoothing window (needs to be odd).
order (int) – Order of the filter.
 Returns
New smoothed series.
 Return type
BaseSeries
or derived class

spline_differentiate
(order=1)¶ Differentiate the series using the spline representation.
The optional parameter
order
specifies the order of the derivative.Warning
The values at the boundary are typically not accurate.
 Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).

spline_differentiated
(order=1)¶ Return a series that is the derivative of the current one using the spline representation.
The optional parameter
order
specifies the order of the derivative.Warning
The values at the boundary are typically not accurate.
 Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
 Returns
New series with derivative
 Return type
BaseSeries
or derived class

property
values
¶ Fake pandas properties, to make Series objects plottable by matplotlib.

x_at_abs_maximum_y
()¶ Return the value of x when abs(y) is maximum.
 Returns
Value of x when abs(y) is maximum.
 Return type
float

x_at_abs_minimum_y
()¶ Return the value of x when abs(y) is minimum.
 Returns
Value of x when abs(y) is minimum.
 Return type
float

x_at_maximum_y
()¶ Return the value of x when y is maximum.
 Returns
Value of x when y is maximum.
 Return type
float

x_at_minimum_y
()¶ Return the value of x when y is minimum.
 Returns
Value of x when y is minimum.
 Return type
float

property
xmax
¶ Return the maximum of the independent variable x.
 Rvalue
Maximum of x
 Return type
float

property
xmin
¶ Return the minimum of the independent variable x.
 Rvalue
Minimum of x.
 Return type
float

class
kuibit.grid_data.
HierarchicalGridData
(uniform_grid_data)[source]¶ Represents data defined on meshrefined grids, consisting of one or more regular datasets with different grid spacings.
All the arithmetic operations and binary operators are defined for this class, as well as interpolation and resampling.
Upon initialization, we try to merge together all the components (output from different MPI processes), so there is one
UniformGridData
per refinement level. In case of grids with more than one center of refinement, this is currently not possible, so we keep all the components around. In this, ghost zone information may be discarded. Variables
grid_data_dict – Mapping between refinement levels and components at that refinement level.
Constructor.
Here we try to merge the different components, if we can.
 Parameters
uniform_grid_data (list of
UniformGridData
) – List of regular datasets.

abs_max
()¶ Return the maximum of the absolute value

abs_min
()¶ Return the minimum of the absolute value

abs_nanmax
()¶ Return the maximum of the absolute value ignoring NaNs

abs_nanmin
()¶ Return the minimum of the absolute value ignoring NaNs

property
all_components
¶ Return a list with all the components.
This is useful to create a new
HierarchicalGridData
fromself
. Returns
List of all the components.
 Return type
list of
UniformGridData

property
coarsest_dx
¶ Return the grid spacing of the coarsest level.
 Returns
Grid spacing of the coarsest level.
 Return type
1d NumPy array

property
coarsest_level
¶ Return the coarsest level, if it is a single grid.
 Returns
Coarsest level.
 Return type

coordinates
()[source]¶ Return coordinates as a list of
HierarchicalGridData
.Useful for computations involving coordinates.
 Returns
Coordinates.
 Return type
list of
HierarchicalGridData

coordinates_at_maximum
(absolute=True)[source]¶ Return the point with maximum value.
 Returns
Coordinate at where the value is maximum. If
absolute
is True, then the absolute value is first taken. Return type
1D NumPy array

coordinates_at_minimum
(absolute=True)[source]¶ Return the point with minimum value.
 Returns
Coordinate at where the value is minimum. If
absolute
is True, then the absolute value is first taken. Return type
1D NumPy array

copy
()[source]¶ Return a deep copy.
 Returns
Deep copy of the
HierarchicalGridData
. Return type

dx_at_level
(level)[source]¶ Return the grid spacing at the specified refinement level.
 Parameters
level (int) – Refinement level number.
 Returns
Spacing at the given refinement level.
 Return type
1d NumPy array

evaluate_with_spline
(x, ext=2, piecewise_constant=False)[source]¶ Evaluate the spline on the points
x
.Values outside the interval are set to 0 if ext=1, or a
ValueError
is raised ifext=2
.This method is meant to be used only if you want to use a different
ext
for a specific call, otherwise, just use __call__. Parameters
x (1D NumPy array of float, or
UniformGrid
) – Points where to evaluate the data.ext (int) – How to deal values outside the bounaries. Values outside the interval are set to 0 if
ext=1
, or an error is raised ifext=2
.
 Returns
Values of the data evaluated on the input
x
. Return type
1D NumPy array or float

finest_component_at_point
(coordinate, no_checks=False)[source]¶ Return the number and the component index of the most refined level that contains the given coordinate.
 Parameters
coordinate (tuple or NumPy array with the same dimension) – Point.
no_checks (bool) – Do not perform sanity checks on the input (for speed).
 Returns
Component with highest resolution at point
 Return type

property
finest_dx
¶ Return the grid spacing of the finest level.
 Returns
Grid spacing of the finest level.
 Return type
1d NumPy array

property
finest_level
¶ Return the finest level, if it is a single grid.
 Returns
Finest level.
 Return type

property
first_component
¶ Return the first component of the coarsest refinement level.
 Returns
First component of the coarsest level.
 Return type
:py:class:~UniformGridData

get_level
(ref_level)[source]¶ Return the data at a given refinement level.
 Parameters
ref_level (int) – Number of refinement level.
 Returns
Data at given refinement level.
 Return type

ghost_zones_removed
()[source]¶ Return a new
HierarchicalGridData
with all the ghost zones removed. Returns
New
HierarchicalGridData
without ghostzones. Return type

gradient
(order=1)[source]¶ Return a list
HierarchicalGridData
that are the numerical orderdifferentiation of the present grid_data along all the directions. (order = number of derivatives, ieorder=2
is second derivative)The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
The output has the same shape of self.
 Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
 Returns
list of
HierarchicalGridData
with partial derivative along all the directions. Return type
list of
HierarchicalGridData

is_complex
()[source]¶ Return whether the data is complex.
 Returns
True if the data is complex, false if it is not.
 Return type
bool

is_masked
()[source]¶ Return whether the data is masked.
 Returns
True if the data is masked, false if it is not.
 Return type
bool

iter_from_finest
()[source]¶ Iterator over the components, sorted by refinement level, from the finest to the coarsest.
 Returns
Refinement level number, component index, and data.
 Return type
generator of tuples (int, int,
UniformGridData
)

property
iteration
¶ The iteration of the coarsest refinement level.
 Returns
Iteration number of the coarsest refinement level.
 Return type
int

property
mask
¶ Return where the data is valid (according to the mask).
 Returns
List of arrays of True/False, one per component in the same order as
all_components()
. Return type
list of arrays of bool

mask_applied
(mask, ignore_existing=False)[source]¶ Return a new grid data with given mask applied to the data.
If a previous mask already exists, the new mask will be added on top, unless
ignore_existing
is True. Parameters
mask (list of NumPy array) – List of arrays of booleans (one per component) that identify where the data is invalid. This can be obtained with the method
mask()
.ignore_existing (bool) – If True, overwrite any previously existing mask.
 Returns
New grid data with mask applied.
 Return type

mask_apply
(mask, ignore_existing=False)[source]¶ Apply given mask.
If a previous mask already exists, the new mask will be added on top, unless
ignore_existing
is True. Parameters
mask (list of NumPy array) – List of arrays of booleans (one per component) that identify where the data is invalid. This can be obtained with the method
mask()
.ignore_existing (bool) – If True, overwrite any previously existing mask.

mask_equal
(value)¶ Mask where data is equal to given value.

mask_greater
(value)¶ Mask where data is greater to given value.

mask_greater_equal
(value)¶ Mask where data is greater or equal to given value.

mask_inside
(value1, value2)¶ Mask where data is inside the given values.

mask_invalid
()¶ Mask where data is invalid (NaNs of infs).

mask_less
(value)¶ Mask where data is less to given value.

mask_less_equal
(value)¶ Mask where data is less or equal to given value.

mask_not_equal
(value)¶ Mask where data is not equal to given value.

mask_outside
(value1, value2)¶ Mask where data is outside the given values.

masked_equal
(value)¶ Return a new objected masked where data is equal to given value.

masked_greater
(value)¶ Return a new objected masked where data is greater to given value.

masked_greater_equal
(value)¶ Return a new objected masked where data is greater or equal to given value.

masked_inside
(value1, value2)¶ Return a new objected masked where data is inside the given values.

masked_invalid
()¶ Return a new objected masked where data is invalid (NaNs or infs).

masked_less
(value)¶ Return a new objected masked where data is less to given value.

masked_less_equal
(value)¶ Return a new objected masked where data is less or equal to given value.

masked_not_equal
(value)¶ Return a new objected masked where data is not equal to given value.

masked_outside
(value1, value2)¶ Return a new objected masked where data is outside the given values.

property
max_refinement_level
¶ Return the number of the finest refinement level.
Alias for
num_finest_level()
. Returns
Index of the finest level.
 Return type
int

merge_refinement_levels
(resample=False)[source]¶ Combine all the available data and resample it grid that encompasses all the components and has resolution of the finest refinement level.
When
resample
is True, data from coarser refinement levels is resampled with multilinear interpolation, otherwise the nearest neighbors are used.Warning
For most practical purposes, using this function is an overkill. This can be a very expensive operation and require a lot of memory. Prefer
to_UniformGridData()
when possible. The only real reasonable application of this function is with small simluations or 1D data. Parameters
resample (bool) – If True, resample the data with multilinear interpolation, otherwise, use nearest neighbors.
 Returns
New
UniformGridData
with the resolution of the finest refinement level. Return type

property
num_coarsest_level
¶ Return the number of the coarsest refinement level.
 Returns
Index of the coarsest level.
 Return type
int

property
num_dimensions
¶ Return the number of dimensions.
 Returns
Number of dimensions.
 Return type
int

property
num_extended_dimensions
¶ Return the number of dimensions with more than one cell.
 Returns
Number of dimensions with more than one gridpoint.
 Return type
int

property
num_finest_level
¶ Return the number of the finest refinement level.
 Returns
Index of the finest level.
 Return type
int

partial_differentiate
(direction, order=1)[source]¶ Apply a numerical differentiatin along the specified direction.
The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
The output has the same shape of
self
. Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
direction (int) – Direction of the partial derivative.
 Returns
Derivative along the specified direction.
 Return type
list of
HierarchicalGridData

partial_differentiated
(direction, order=1)[source]¶ Return a
HierarchicalGridData
that is the numerical orderdifferentiation of the present grid_data along a given direction. (order = number of derivatives, ieorder=2
is second derivative)The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
The output has the same shape of
self
. Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
direction (int) – Direction of the partial derivative.
 Returns
New
HierarchicalGridData
with derivative. Return type

property
refinement_levels
¶ Return a list with the refinement levels available.
 Returns
List of refinement levels available.
 Return type
list of ints

property
shape
¶ Return the number of components per each refinement level.
For example, if data has three levels, with 1 component in the first, 2 in the second, and three in the fifth, shape will be {1: 1, 2: 2, 5: 3}
This method is useful for quick high level comparison between two
HierachicalGridData
. Returns
Dictionary with keys the refinement level numbers and values the number of components at that level.
 Return type
dictionary

slice
(cut, resample=False)[source]¶ Slice the data along given direction.
cut
specifies how to slice the data. It has to be an array with the same number of dimensions of the data. In the entries wherecut
is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, ifcut
is[None, 2]
, the cut will be withy = 2
.If
resample
is True, you can cut at any point and we will compute the values with multilinear interpolation. Ifresample
is False, we will use the data already available.In doing this, dimensions that are only one grid point are lost.
 Parameters
cut (array or list with dimension) – How to slice the array. None entries mean “keep that dimension”.
resample (bool) – Whether to use multilinear interpolation to compute the data or simply use the value of the closest point.

sliced
(cut, resample=False)[source]¶ Return a new
HierarchicalGridData
obtained slicing the current one.cut
specifies how to slice the data. It has to be an array with the same number of dimensions of the data. In the entries wherecut
is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, ifcut
is[None, 2]
, the cut will be withy = 2
.If
resample
is True, you can cut at any point and we will compute the values with multilinear interpolation. Ifresample
is False, we will use the data already available.In doing this, dimensions that are only one grid point are lost.
 Parameters
cut (array or list with dimension) – How to slice the array. None entries mean “keep that dimension”.
resample (bool) – Whether to use multilinear interpolation to compute the data or simply use the value of the closest point.
 Returns
A sliced
HierachicalGridData
. Return type
HierachicalGridData

property
time
¶ The time of the coarsest refinement level.
 Returns
Time of the coarsest refinement level.
 Return type
float

to_UniformGridData
(shape, x0, x1=None, dx=None, resample=False, **kwargs)[source]¶ Combine the refinement levels into a
UniformGridData
specified by the givenshape
,x0
, anddx
orx1
.Additional arguments are sent to the constructor of
UniformGrid
.If
resample
is True, the data is resampled with multilinear interpolation. Parameters
shape (1d NumPy array) – Number of points across all the dimensions.
x0 (1d NumPy array, or None) – Origin.
x1 (1d NumPy array, or None) – Grid corner. If None, it will be inferred.
dx (1d NumPy array, or None) – Grid spacing. If None, it will be inferred.
resample (bool) – If True, resample the data with multilinear interpolation, otherwise, use nearest neighbors.

to_UniformGridData_from_grid
(grid, resample=False)[source]¶ Combine the refinement levels into a
UniformGridData
on the specifiedUniformGrid
.If
resample
is True, the data is resampled with multilinear interpolation. Parameters
grid (
UniformGrid
.) – Grid onto which to resample the data.resample (bool) – If True, resample the data with multilinear interpolation, otherwise, use nearest neighbors.

property
x0
¶ Origin of the coarsest grid, if it is a single component.
 Returns
Origin of the coarsest grid, if it is a single component.
 Return type
1d NumPy array

property
x1
¶ Corner of the coarsest grid, if it is a single component.
 Returns
Corner of the coarsest grid, if it is a single component.
 Return type
1d NumPy array

class
kuibit.grid_data.
UniformGridData
(grid, data)[source]¶ Represents a rectangular data grid with coordinates, supporting common arithmetic operations.
UniformGridData
is a combination of aUniformGrid
(ingrid
attribute) and the actual data (in thedata
attribute).UniformGridData
makes sure that all the operations on these objects are intuitive, meaningful, and consistent.A
UniformGridData
can be initialized with the default constructor (which takes grid and data), of with the alternative constructorfrom_grid_structure()
(which takes grid details and data). Variables
grid – Uniform grid over which the data is defined.
data – The actual data.
invalid_spline – Whether the spline stored is valid.
spline_real – Spline representation of the real part of the data.
spline_imag – Spline representation of the imaginary part of the data.
 Parameters
grid (
UniformGrid
) – Uniform grid over which the data is defined.data (A NumPy array.) – The data.

abs_max
()¶ Return the maximum of the absolute value

abs_min
()¶ Return the minimum of the absolute value

abs_nanmax
()¶ Return the maximum of the absolute value ignoring NaNs

abs_nanmin
()¶ Return the minimum of the absolute value ignoring NaNs

average
()¶ Compute the mean of the data over the whole volume of the grid.
 Returns
Arithmetic mean of the data.
 Return type
float (or complex if data is complex)

property
component
¶ Component number.
 Returns
Component number.
 Return type
int

coordinates
()[source]¶ Return coordinates of the grid points as list of
UniformGridData
.This can be used for computations involving the coordinates.
 Returns
Coordinates along each direction.
 Return type
list of
UniformGridData

coordinates_at_maximum
(absolute=True)[source]¶ Return the point with maximum value.
 Returns
Coordinate at where the value is maximum. If
absolute
is True, then the absolute value is first taken. Return type
1D NumPy array

coordinates_at_minimum
(absolute=True)[source]¶ Return the point with minimum value.
 Returns
Coordinate at where the value is minimum. If
absolute
is True, then the absolute value is first taken. Return type
1D NumPy array

coordinates_from_grid
(as_meshgrid=False, as_same_shape=False)[source]¶ Return coordinates of the grid points.
This is equivalent to
self.grid.coordinates()
.If
as_meshgrid
is True, the coordinates are returned as NumPy meshgrid. Otherwise, return the coordinates of the grid points as 1D arrays (schematically, [array for x coordinates, array for y coordinates, …]).If
as_same_shape
is True return the coordinates as an array with the same shape of self and with values the coordinates. This is useful for computations involving the coordinates. Parameters
as_meshgrid (bool) – If True, return the coordinates as meshgrid.
as_same_shape (bool) – If True, return the coordinates as a list or coordinates with the same shape of self and with values of a given coordinate. For instance, if
self.num_dimension = 3
there will be three lists withshape = self.shape
.
 Returns
Grid coordinates.
 Return type
list of NumPy arrays with the same shape as grid

coordinates_meshgrid
()[source]¶ Return coordinates of the grid points as NumPy meshgrid.
This is syntactic sugar useful for plotting with matplotlib.
 Returns
Grid coordinates.
 Return type
list of NumPy arrays

property
data_xyz
¶ Return the data, but transposed.
This is useful when plotting, because we store data in a matrix form, which is the transposed of what we are used to thinking about coordinates (ie, the first index is not
x
). Returns
Data in a coordinatefriendly form.
 Return type
NumPy array

property
delta
¶ Grid spacing.
Alias for
dx()
. Returns
Cell size across each dimension.
 Return type
1d NumPy array

property
dx
¶ Grid spacing.
 Returns
Cell size across each dimension.
 Return type
1d NumPy array

dx_change
(new_dx, piecewise_constant=False)[source]¶ Upsamples or downsamples the grid data.
Missing data is obtained with splines.
new_dx
has to be an integer multiple of the currentdx
(or vice versa).If
piecewise_constant=True
, the missing information is obtained with from the nearest neighbors. Parameters
new_dx (1d NumPy array) – Do not use splines, use the nearest neighbors.
piecewise_constant (bool) – Do not use splines, use the nearest neighbors.

dx_changed
(new_dx, piecewise_constant=False)[source]¶ Return a new
UniformGridData
with the same grid extent, but with a new spacing. This effectively upsamples or downsamples the grid.Missing data is obtained with splines.
new_dx
has to be an integer multiple of the currentdx
(or vice versa).If
piecewise_constant=True
, the missing information is obtained with from the nearest neighbors. Parameters
new_dx (1d NumPy array) – Do not use splines, use the nearest neighbors.
piecewise_constant (bool) – Do not use splines, use the nearest neighbors.
 Returns
Data with new grid spacing
new_dx
. Return type

evaluate_with_spline
(x, ext=2, piecewise_constant=False)[source]¶ Evaluate the spline on the points
x
.Values outside the interval are set to 0 if
ext=1
, or aValueError
is raised ifext=2
.This method is meant to be used only if you want to use a different ext for a specific call, otherwise, just use __call__.
 Parameters
x (1D NumPy array of float, or
UniformGrid
) – Points where to evaluate the data.ext (int) – How to deal values outside the boundaries. Values outside the interval are set to 0 if
ext=1
, or an error is raised ifext=2
.
 Returns
Values of the data evaluated on the input
x
. Return type
1D NumPy array or float

property
extended_dimensions
¶ Return an array of bools with whether a dimension has more than one point or not.
 Returns
Dimensions with more than one point.
 Return type
1d NumPy of bools

flat_dimensions_removed
()[source]¶ Return a new
UniformGridData
with dimensions of one grid point removed. Returns
New
UniformGridData
without flat dimensions. Return type

fourier_transform
()[source]¶ Perform the multidimensional Fourier transform on the data.
We follow NumPy’s conventions, with the exception that we normalize the amplitude with
dx
.If the signal is complex, we also shift the negative components to be in the negative part of the signal.
 Returns
Fourier transform.
 Return type

classmethod
from_grid_structure
(data, x0, x1=None, dx=None, ref_level= 1, component= 1, num_ghost=None, time=None, iteration=None)[source]¶  Parameters
x0 (1d NumPy array or list of float.) – Position of cell center with lowest coordinate.
dx (1d NumPy array or list of float.) – If not None, specifies grid spacing, else grid spacing is computed from x0, x1, and shape.
data (A NumPy array.) – The data.
ref_level (int) – Refinement level if this belongs to a hierarchy, else 1.
component (int) – Component number if this belongs to a hierarchy, else 1.
num_ghost (1d NumPy arrary or list of int.) – Number of ghost zones (default=0)
time (float or None) – Time if that makes sense, else None.
iteration (float or None) – Iteration if that makes sense, else None.

ghost_zones_removed
()[source]¶ Return a new
UniformGridData
with all the ghost zones removed. Returns
New
UniformGridData
without ghostzones. Return type

gradient
(order=1)[source]¶ Return a list
UniformGridData
that are the numerical orderdifferentiation of the present grid_data along all the directions. (order
= number of derivatives, ieorder=2
is second derivative)The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
The output has the same shape of
self
. Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
direction (int) – Direction of the partial derivative.
 Returns
list of
UniformGridData
with partial derivative along the directions. Return type
list of
UniformGridData

histogram
(weights=None, min_value=None, max_value=None, num_bins=400, **kwargs)[source]¶ Return the 1D Histogram of the data.
 Parameters
weights (
UniformGridData
or NumPy array of same shape or None.) – The weight for each cell. Default is one.min_value (float or None) – Lower bound of data to consider. Default is data range.
max_value (float or None) – Upper bound of data to consider. Default is data range.
num_bins (int > 1) – Number of bins to create.
 Returns
The positions of the data bins and the distribution.
 Return type
tuple of two 1D NumPy arrays.

integral
()[source]¶ Compute the integral over the whole volume of the grid.
 Returns
The integral computed as volumeweighted sum.
 Return type
float (or complex if data is complex)

is_complex
()[source]¶ Return whether the data is complex.
 Returns
True if the data is complex, false if it is not.
 Return type
bool

is_masked
()[source]¶ Return whether the data is masked.
 Returns
True if the data is masked, false if it is not.
 Return type
bool

property
iteration
¶ Iteration number
 Returns
Iteration number.
 Return type
float

property
mask
¶ Return where the data is valid (according to the mask).
 Returns
Array of True/False of the same shape of the data. False where the data is valid, True where is not.
 Return type
array of bool

mask_applied
(mask, ignore_existing=False)[source]¶ Return a new
UniformGridData
with given mask applied to the data.If a previous mask already exists, the new mask will be added on top, unless
ignore_existing
is True. Parameters
mask (NumPy array) – Array of booleans that identify where the data is invalid. This can be obtained with the method
mask()
.ignore_existing (bool) – If True, overwrite any previously existing mask.
 Returns
New grid data with mask applied.
 Return type

mask_apply
(mask, ignore_existing=False)[source]¶ Apply the given mask.
If a previous mask already exists, the new mask will be added on top, unless
ignore_existing
is True. Parameters
mask (NumPy array) – Array of booleans that identify where the data is invalid. This can be obtained with the method
mask()
.ignore_existing (bool) – If True, overwrite any previously existing mask.

mask_equal
(value)¶ Mask where data is equal to given value.

mask_greater
(value)¶ Mask where data is greater to given value.

mask_greater_equal
(value)¶ Mask where data is greater or equal to given value.

mask_inside
(value1, value2)¶ Mask where data is inside the given values.

mask_invalid
()¶ Mask where data is invalid (NaNs of infs).

mask_less
(value)¶ Mask where data is less to given value.

mask_less_equal
(value)¶ Mask where data is less or equal to given value.

mask_not_equal
(value)¶ Mask where data is not equal to given value.

mask_outside
(value1, value2)¶ Mask where data is outside the given values.

masked_equal
(value)¶ Return a new objected masked where data is equal to given value.

masked_greater
(value)¶ Return a new objected masked where data is greater to given value.

masked_greater_equal
(value)¶ Return a new objected masked where data is greater or equal to given value.

masked_inside
(value1, value2)¶ Return a new objected masked where data is inside the given values.

masked_invalid
()¶ Return a new objected masked where data is invalid (NaNs or infs).

masked_less
(value)¶ Return a new objected masked where data is less to given value.

masked_less_equal
(value)¶ Return a new objected masked where data is less or equal to given value.

masked_not_equal
(value)¶ Return a new objected masked where data is not equal to given value.

masked_outside
(value1, value2)¶ Return a new objected masked where data is outside the given values.

mean
()[source]¶ Compute the mean of the data over the whole volume of the grid.
 Returns
Arithmetic mean of the data.
 Return type
float (or complex if data is complex)

norm1
()[source]¶ Compute the norm over the whole volume of the grid.
\(\u\_1 = \sum \u\ dv\)
 Returns
The norm2 computed as volumeweighted sum.
 Return type
float (or complex if data is complex)

norm2
()[source]¶ Compute the norm over the whole volume of the grid.
\(\u\_2 = (\sum \u\^2 dv)^1/2\)
 Returns
The norm2 computed as volumeweighted sum.
 Return type
float (or complex if data is complex)

norm_p
(order)[source]¶ Compute the norm of order
p
over the whole volume of the grid.\(\u\_p = (\sum \u\^p dv)^1/p\)
 Parameters
order (int) – Order of the norm.
 Returns
The norm2 computed as volumeweighted sum.
 Return type
float (or complex if data is complex)

property
num_dimensions
¶ Number of dimensions of the grid.
 Returns
Number of dimensions of the grid.
 Return type
float

property
num_extended_dimensions
¶ Return the number of dimensions with size larger than one gridpoint.
 Returns
The number of extended dimensions (the ones with more than one cell).
 Return type
int

property
num_ghost
¶ Number of ghost zones.
 Returns
Number of ghost zones across each dimension.
 Return type
1d NumPy array

property
origin
¶ Lower corner.
Alias for
x0()
. Returns
Center of lowest corner grid point.
 Return type
1d NumPy array

partial_differentiate
(dimension, order=1)[source]¶ Derive the data with numerical finite difference along a given direction (
order
= number of derivatives, ieorder=2
is second derivative).The derivative is calulated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
The output has the same shape of
self
. Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
direction (int) – Direction of the partial derivative.

partial_differentiated
(direction, order=1)[source]¶ Return a
UniformGridData
that is the numerical orderdifferentiation of the present grid_data along a given direction. (order
= number of derivatives, ieorder=2
is second derivative)The derivative is calculated as centered differencing in the interior and onesided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.
The output has the same shape of
self
. Parameters
order (int) – Order of derivative (e.g. 2 = second derivative).
direction (int) – Direction of the partial derivative.
 Returns
New
UniformGridData
with derivative. Return type

percentiles
(fractions, weights=None, relative=True, min_value=None, max_value=None, num_bins=400)[source]¶ Find values for which a given fraction(s) of the data is smaller.
Optionally, the cells can have an optional weight, and absolute counts can be used instead of fraction.
 Parameters
fractions (list or array of floats) – List of fraction/absolute values.
weights (
UniformGridData
or NumPy array of same shape or None.) – The weight for each cell. Default is one.relative (bool) – Whether fractions refer to relative or absolute count.
min_value (float or None) – Lower bound of data to consider. Default is data range.
max_value (float or None) – Upper bound of data to consider. Default is data range.
num_bins (integer > 1) – Number of bins to create.
 Returns
Data values corresponding to the given fractions.
 Return type
1D NumPy array

property
ref_level
¶ Refinement level number.
 Returns
Refinement level number.
 Return type
int

reflection_symmetry_undo
(dimension, parity=1)[source]¶ Undo reflection symmetry for the given dimension.
This method works only if the data crosses the value 0 along the given dimension.
This will change the shape of the object.
 Parameters
dimension (int) – Dimension that has to be reflected.
parity (1 or 1) – Fill the data assuming that the function is even (parity = 1), or odd (parity = 1).

reflection_symmetry_undone
(dimension, parity=1)[source]¶ Return a new UniformGridData with reflection symmetry undo for the given dimension.
The parameter
parity
determines how to fill the data.This method works only if the data crosses the value 0 along the given dimension.
We assume that the reflection will always be from the positive side to the negative. Preexisting data in the negative side will be overwritten.
This will change the shape of the object.
 Parameters
dimension (int) – Dimension that has to be reflected.
parity (1 or 1) – Fill the data assuming that the function is even (parity = 1), or odd (parity = 1).
 Returns
New
UniformGridData
with values explicitly set for reflected data. Return type

resampled
(new_grid, ext=2, piecewise_constant=False)[source]¶ Return a new
UniformGridData
resampled tonew_grid
.If you want to resample without using the spline, and you want a nearest neighbor resampling, pass the keyword
piecewise_constant=True
. This may be a good choice for data with large discontinuities, where the splines are ineffective. Parameters
new_grid (1D NumPy array or list of float) – New independent variable.
ext (1 for returning zero, 2 for
ValueError
,) – How to handle points outside the data interval.piecewise_constant (bool) – Do not use splines, use the nearest neighbors.
 Returns
Resampled data.
 Return type

save
(file_name, *args, **kwargs)[source]¶ Save data and grid information to a file.
Unless the file extension is
npz
, the output file will ASCII. In this case, compression is supported. To enable compression, just appendbz
orgz
to the extension. All the unknown arguments are passed tonp.savetxt
. The backend used in this case does not support writing 3D or larger arrays to disk as ASCII, so all the arrays are reshaped to 1D.If the file extension is
npz
, then save the grid with this NumPyspecific format (compressed).If you look for performance, use
npz
, if you want a file that you can easily read everywhere, use ASCII.The file output with this method can be read with the
load_UniformGridData()
function. Parameters
file_name (str) – Path (with extension) of the output file.

property
shape
¶ Number of cells across each dimension.
 Returns
Number of cells across each dimension.
 Return type
1d NumPy array

slice
(cut, resample=False)[source]¶ Slice the data along given direction.
cut
specifies how to slice the data. It has to be an array with the same number of dimensions of the data. In the entries wherecut
is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, ifcut
is[None, 2]
, the cut will be withy = 2
.If
resample
is True, you can cut at any point and we will compute the values with multilinear interpolation. Ifresample
is False, we will use the data already available.In doing this, dimensions that are only one grid point are lost.
 Parameters
cut (array or list with dimension) – How to slice the array. None entries mean “keep that dimension”.
resample (bool) – Whether to use multilinear interpolation to compute the data or simply use the value of the closest point.

sliced
(cut, resample=False)[source]¶ Return a new
UniformGridData
obtained slicing the current one.cut
specifies how to slice the data. It has to be an array with the same number of dimensions of the data. In the entries wherecut
is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, ifcut
is[None, 2]
, the cut will be withy = 2
.If
resample
is True, you can cut at any point and we will compute the values with multilinear interpolation. Ifresample
is False, we will use the data already available.In doing this, dimensions that are only one grid point are lost.
 Parameters
cut (array or list with dimension) – How to slice the array. None entries mean “keep that dimension”.
resample (bool) – Whether to use multilinear interpolation to compute the data or simply use the value of the closest point.
 Returns
A sliced
UniformGridData
. Return type

property
time
¶ Time.
 Returns
Time.
 Return type
float

to_GridSeries
()[source]¶ Return a
GridSeries
(if the data is onedimensional).When the data is one dimensional, sometimes it is more convenient to treat it a series instead of grid data. This class is uses the same infrastructure as
TimeSeries
andFrequencySeries
and has more or less the same features. Returns
Data as a Series.
 Return type

property
x0
¶ Lower corner.
 Returns
Center of lowest corner grid point.
 Return type
1d NumPy array

property
x1
¶ Upper corner.
 Returns
Center of top corner grid point.
 Return type
1d NumPy array