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(include_edges=True, *args, **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(include_edges=True, *args, **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