# 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 >= init 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 >= init will be removed.

Returns

Series with enforced minimum and maximum

Return type

BaseSeries or derived class

copy()

Return a deep copy.

Returns

Deep copy of the series.

Return type

BaseSeries or derived class

crop(init=None, end=None)

Remove data outside the the interval [init, end]. 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 >= init 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 >= init 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

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

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
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)[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).

Returns

list of HierarchicalGridData with partial derivative along all the directions.

Return type
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]

Combine all the available data and resample it grid that encompasses all the components and has resolution of the finest refinement level.

When resample is True, data from coarser refinement levels is resampled with multilinear interpolation, otherwise the nearest neighbors are used.

Warning

For most practical purposes, using this function is an overkill. This can be a very expensive operation and require a lot of memory. Prefer to_UniformGridData() when possible. The only real reasonable application of this function is with small simluations or 1D data.

Parameters

resample (bool) – If True, resample the data with multilinear interpolation, otherwise, use nearest neighbors.

Returns

New UniformGridData with the resolution of the finest refinement level.

Return type

UniformGridData

property num_coarsest_level

Return the number of the coarsest refinement level.

Returns

Index of the coarsest level.

Return type

int

property num_dimensions

Return the number of dimensions.

Returns

Number of dimensions.

Return type

int

property num_extended_dimensions

Return the number of dimensions with more than one cell.

Returns

Number of dimensions with more than one gridpoint.

Return type

int

property num_finest_level

Return the number of the finest refinement level.

Returns

Index of the finest level.

Return type

int

partial_differentiate(direction, order=1)[source]

Apply a numerical differentiatin along the specified direction.

The derivative is calulated as centered differencing in the interior and 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.

Returns

Derivative along the specified direction.

Return type
partial_differentiated(direction, order=1)[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.

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

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)[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.

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)[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.

partial_differentiated(direction, order=1)[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.

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

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