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 and FrequencySeries 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]. If init or end 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]. If init or end 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]. If init or end 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]. If init or end 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 if ext=1, raise a ValueError if ext=2, or if ext=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 if ext=1, raise a ValueError if ext=2, or if ext=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:

BaseSeries

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 order order.

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 order order.

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 from self.

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:

UniformGridData

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:

HierarchicalGridData

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 if ext=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 if ext=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:

UniformGridData

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:

UniformGridData

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:

UniformGridData

ghost_zones_remove()[source]

Remove all the ghost zones.

ghost_zones_removed()[source]

Return a new HierarchicalGridData with all the ghost zones removed.

Returns:

New HierarchicalGridData without ghostzones.

Return type:

HierarchicalGridData

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, ie order=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:

HierarchicalGridData

mask_apply(mask, ignore_existing=False)[source]

Apply given mask.

If a previous mask already exists, the new mask will be added on top, unless ignore_existing is True.

Parameters:

  • mask (list of NumPy array) – List of arrays of booleans (one per component) that identify where the data is invalid. This can be obtained with the method mask().

  • ignore_existing (bool) – If True, overwrite any previously existing mask.

mask_equal(value)

Mask where data is equal to given value.

mask_greater(value)

Mask where data is greater to given value.

mask_greater_equal(value)

Mask where data is greater or equal to given value.

mask_inside(value1, value2)

Mask where data is inside the given values.

mask_invalid()

Mask where data is invalid (NaNs of infs).

mask_less(value)

Mask where data is less to given value.

mask_less_equal(value)

Mask where data is less or equal to given value.

mask_not_equal(value)

Mask where data is not equal to given value.

mask_outside(value1, value2)

Mask where data is outside the given values.

masked_equal(value)

Return a new objected masked where data is equal to given value.

masked_greater(value)

Return a new objected masked where data is greater to given value.

masked_greater_equal(value)

Return a new objected masked where data is greater or equal to given value.

masked_inside(value1, value2)

Return a new objected masked where data is inside the given values.

masked_invalid()

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

masked_less(value)

Return a new objected masked where data is less to given value.

masked_less_equal(value)

Return a new objected masked where data is less or equal to given value.

masked_not_equal(value)

Return a new objected masked where data is not equal to given value.

masked_outside(value1, value2)

Return a new objected masked where data is outside the given values.

property max_refinement_level

Return the number of the finest refinement level.

Alias for num_finest_level().

Returns:

Index of the finest level.

Return type:

int

merge_refinement_levels(resample=False)[source]

DEPRECATED.

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, ie order=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:

HierarchicalGridData

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:

UniformGridData

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 where cut is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, if cut is [None, 2], the cut will be with y = 2.

If resample is True, you can cut at any point and we will compute the values with multilinear interpolation. If resample 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 where cut is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, if cut is [None, 2], the cut will be with y = 2.

If resample is True, you can cut at any point and we will compute the values with multilinear interpolation. If resample 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 given shape, x0, and dx or x1.

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 specified UniformGrid.

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 a UniformGrid (in grid attribute) and the actual data (in the data 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 constructor from_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 with shape = 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

copy()[source]

Return a deep of self.

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 current dx (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 current dx (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:

UniformGridData

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 if ext=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 if ext=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_remove()[source]

Remove dimensions which are only one gridpoint large.

flat_dimensions_removed()[source]

Return a new UniformGridData with dimensions of one grid point removed.

Returns:

New UniformGridData without flat dimensions.

Return type:

UniformGridData

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:

UniformGridData

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_remove()[source]

Remove all the ghost zones.

ghost_zones_removed()[source]

Return a new UniformGridData with all the ghost zones removed.

Returns:

New UniformGridData without ghostzones.

Return type:

UniformGridData

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, ie order=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:

UniformGridData

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, ie order=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, ie order=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:

UniformGridData

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:

UniformGridData

resampled(new_grid, ext=2, piecewise_constant=False)[source]

Return a new UniformGridData resampled to new_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:

UniformGridData

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:

UniformGridData

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 append bz or gz to the extension. All the unknown arguments are passed to np.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 where cut is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, if cut is [None, 2], the cut will be with y = 2.

If resample is True, you can cut at any point and we will compute the values with multilinear interpolation. If resample 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 where cut is None, that dimension is kept, where it is a number, the data is cut fixing that coordinate. For example, for a 2D array, if cut is [None, 2], the cut will be with y = 2.

If resample is True, you can cut at any point and we will compute the values with multilinear interpolation. If resample 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:

UniformGridData

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 and FrequencySeries and has more or less the same features.

Returns:

Data as a Series.

Return type:

GridSeries

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