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]¶
One-dimensional 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 >= end
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 >= end
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 >= end
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 >= end
will be removed.
- Returns:
Series with enforced minimum and maximum
- Return type:
BaseSeries
or derived class
- differentiate(order=1)¶
Differentiate with the numerical order-differentiation.
The optional parameter
order
specifies the order of the derivative.The derivative is calulated as centered differencing in the interior and one-sided 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 order-differentiation 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 one-sided 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
- local_maxima(*args, include_edges=True, **kwargs)¶
Use SciPy’s
find_peaks
to find the local maxima.Unkown arguments are passed to
find_peaks
.If the signal is complex, the absolute value is taken.
If
include_edges
is True, the edges are considered among the possible maxima.- Returns:
Coordinate and value of the peaks.
- Return type:
Tuple of NumPy arrays
- local_minima(*args, include_edges=True, **kwargs)¶
Use SciPy’s
find_peaks
to find the local minima.Unkown arguments are passed to
find_peaks
.If the signal is complex, the absolute value is taken.
If
include_edges
is True, the edges are considered among the possible minima.- Returns:
Coordinate and value of the minima.
- Return type:
Tuple of NumPy arrays
- 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 Savitzky-Golay 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 Savitzky-Golay 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
- to_numpy()¶
Return the data as NumPy array. Equivalent to
self.y
.This function is here to enable compatibility matplotlib.
- 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 mesh-refined 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, accuracy_order=2)[source]¶
Return a list
HierarchicalGridData
that are the numerical order-differentiation 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 one-sided 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).
accuracy_order (int) – Order of accuracy of the finite difference scheme.
- 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
- 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, accuracy_order=2)[source]¶
Apply a numerical differentiatin along the specified direction.
The derivative is calulated as centered differencing in the interior and one-sided 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.
accuracy_order (int) – Order of accuracy of the finite difference scheme.
- Returns:
Derivative along the specified direction.
- Return type:
list of
HierarchicalGridData
- partial_differentiated(direction, order=1, accuracy_order=2)[source]¶
Return a
HierarchicalGridData
that is the numerical order-differentiation 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 one-sided 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.
accuracy_order (int) – Order of accuracy of the finite difference scheme.
- 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
- refinement_levels_merged(resample=False)[source]¶
Return a new
UniformGridData
with all the available data combined and resampled to a 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 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 coordinate-friendly 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]¶
Up-samples or down-samples 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 up-samples or down-samples 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 multi-dimensional 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, accuracy_order=2)[source]¶
Return a list
UniformGridData
that are the numerical order-differentiation 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 one-sided 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.
accuracy_order (int) – Order of accuracy of the finite difference scheme.
- 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 volume-weighted 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 volume-weighted 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 volume-weighted 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 volume-weighted 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, accuracy_order=2)[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 one-sided 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.
accuracy_order (int) – Order of accuracy of the finite difference scheme.
- partial_differentiated(direction, order=1, accuracy_order=2)[source]¶
Return a
UniformGridData
that is the numerical order-differentiation 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 one-sided 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.
accuracy_order (int) – Order of accuracy of the finite difference scheme.
- 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. Pre-existing 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:
- rotation180_symmetry_undo(dimension=0, plane=(0, 1), parity=1)[source]¶
Undo rotational 180 symmetry on the given plane for given dimension.
dimension identifies the region for which we only have half of the data (in Carpet it is always going to be 0–the x axis). plane specifies where we are performing the rotation (in Carpet it is always (0, 1)–rotation about the z axis). plane is specified by providing a tuple with the two dimensions involved in the rotation (one of the two has to be dimension).
This method works only if the data crosses the value 0 along the given dimension, and if the coordinates are symmetric with respect to the other dimension involved in the rotation.
We assume that the rotation will always be from the positive side to the negative. Pre-existing data in the negative side will be overwritten.
This will change the shape of the object.
- Parameters:
dimension (int) – Dimension about which to fill in missing data
plane (tuple of ints) – Plane on which the rotation occurs specified by specifying the two dimensions involved in the rotation.
parity (1 or -1) – Fill the data assuming that the function is even (parity = 1), or odd (parity = -1).
- Return type:
None
- rotation180_symmetry_undone(dimension=0, plane=(0, 1), parity=1)[source]¶
Return a new UniformGridData with rotational 180 symmetry undone.
dimension identifies the region for which we only have half of the data (in Carpet it is always going to be 0–the x axis). plane specifies where we are performing the rotation (in Carpet it is always (0, 1)–rotation about the z axis). plane is specified by providing a tuple with the two dimensions involved in the rotation (one of the two has to be dimension).
This method works only if the data crosses the value 0 along the given dimension, and if the coordinates are symmetric with respect to the other dimension involved in the rotation.
We assume that the rotation will always be from the positive side to the negative. Pre-existing data in the negative side will be overwritten.
This will change the shape of the object.
- Parameters:
dimension (int) – Dimension about which to fill in missing data
plane (tuple of ints) – Plane on which the rotation occurs specified by specifying the two dimensions involved in the rotation.
parity (1 or -1) – Fill the data assuming that the function is even (parity = 1), or odd (parity = -1).
- 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 NumPy-specific 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 one-dimensional).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