grid

This module contains the implementation of the Grid class.

The Grid class represents the interpolation grid on which interpolating polynomials live.

Background information

An interpolation grid is defined by its multi-index set, generating points, and generating function. The generating function, when provided, defines the generating points, which are the one-dimensional interpolation nodes in each dimension. The multi-index set, together with the generating points, specifies the unisolvent nodes—these are the points where the function to be interpolated is evaluated.

More detailed background information can be found in Interpolation at Unisolvent Nodes.

How-To Guides

The relevant section of the docs contains several how-to guides related to instances of the Grid class demonstrating their usages and features.

---

class minterpy.core.grid.Grid(multi_index, generating_function=None, generating_points=None)

A class representing the nodes on which interpolating polynomials live.

Instances of this class provide the data structure for the unisolvent nodes, i.e., points in a hypercube that uniquely determine a multi-dimensional interpolating polynomial (of a specified multi-index set).

Parameters:

• multi_index (MultiIndexSet) – The multi-index set of exponents of multi-dimensional polynomials that the Grid should support.

• generating_function (Union[GEN_FUNCTION, str], optional) – The generating function to construct an array of generating points. One of the built-in generating functions may be selected via a string as a key to a dictionary. This parameter is optional; if neither this parameter nor generating_points is specified, the default generating function based on the Leja-ordered Chebyshev-Lobatto nodes is selected.

• generating_points (numpy.ndarray, optional) – The generating points of the interpolation grid, a two-dimensional array of floats whose columns are the generating points per spatial dimension. The shape of the array is (n + 1, m) where n is the maximum degree of all one-dimensional polynomials (i.e., the maximum exponent) and m is the spatial dimension. This parameter is optional. If not specified, the generating points are created from the default generating function. If specified, then the points must be consistent with any non-None generating function.

Notes

• The Callable as a generating_function must accept as its arguments two integers, namely, the maximum exponent (n) of all of the multi-index set of polynomial exponents and the spatial dimension (m). Furthermore, it must return an array of shape (n + 1, m) whose values are unique per column.

• The multi-index set to construct a Grid instance may not be downward-closed. However, building a MultiIndexTree used in the transformation between polynomials in the Newton and Lagrange bases requires a downward-closed multi-index set.

• The notion of unisolvent nodes, strictly speaking, relies on the downward-closedness of the multi-index set. If the set is not downward-closed then unisolvency cannot be guaranteed.

Properties

generating_function	The generating function of the interpolation Grid.
generating_points	The generating points of the interpolation Grid.
has_generating_function	Return True if the instance has a generating function.
is_complete	Return True if the instance has a complete multi-index set.
is_downward_closed	Return True if the instance has a downward-closed multi-indices.
max_exponent	The maximum exponent of the interpolation grid.
multi_index	The multi-index set of exponents associated with the Grid.
spatial_dimension	Dimension of the domain space.
tree	The used MultiIndexTree.
unisolvent_nodes	The array of unisolvent nodes.

Methods

add_exponents(exponents)	Add a set of exponents to the underlying multi-index set.
expand_dim(target_dimension)	Expand the dimension of the Grid.
from_degree(spatial_dimension, poly_degree, ...)	Create an instance of Grid with a complete multi-index set.
from_function(multi_index, generating_function)	Create an instance of Grid with a given generating function.
from_points(multi_index, generating_points)	Create an instance of Grid from an array of generating points.
from_value_set(multi_index, generating_values)	Create an instance of Grid from an array of generating values.
is_compatible(other)	Return True if the instance is compatible with another.
make_complete()	Complete the underlying multi-index set of the Grid instance.
make_downward_closed()	Make the underlying multi-index set downward-closed.
merge(other, multi_index)	Merge two instances of Grid with a new multi-index set.

classmethod from_degree(spatial_dimension, poly_degree, lp_degree, generating_function=None, generating_points=None)

Create an instance of Grid with a complete multi-index set.

A complete multi-index set denoted by \(A_{m, n, p}\) contains all the exponents \(\boldsymbol{\alpha}=(\alpha_1,\ldots,\alpha_m) \in \mathbb{N}^m\) such that the \(l_p\)-norm \(|| \boldsymbol{\alpha} ||_p \leq n\), where:

• \(m\): the spatial dimension

• \(n\): the polynomial degree

• \(p\): the l_p-degree

Parameters:

• spatial_dimension (int) – Spatial dimension of the multi-index set (\(m\)); the value of spatial_dimension must be a positive integer (\(m > 0\)).

• poly_degree (int) – Polynomial degree of the multi-index set (\(n\)); the value of poly_degree must be a non-negative integer (\(n \geq 0\)).

• lp_degree (float) – \(p\) of the \(l_p\)-norm (i.e., the \(l_p\)-degree) that is used to define the multi-index set. The value of lp_degree must be a positive float (\(p > 0\)).

• generating_function (Union[GEN_FUNCTION, str], optional) – The generating function to construct an array of generating points. One of the built-in generating functions may be selected via a string key. This parameter is optional; if neither this parameter nor generating_points is specified, the default generating function based on the Leja-ordered Chebyshev-Lobatto nodes is selected.

• generating_points (numpy.ndarray, optional) – The generating points of the interpolation grid, a two-dimensional array of floats whose columns are the generating points per spatial dimension. The shape of the array is (n + 1, m) where n is the maximum degree of all one-dimensional polynomials (i.e., the maximum exponent) and m is the spatial dimension. This parameter is optional. If not specified, the generating points are created from the default generating function. If specified, then the points must be consistent with any non-None generating function.

Returns:

A new instance of the Grid class initialized with a complete multi-index set (\(A_{m, n, p}\)) and with the given generating function and generating points.

Return type:

Grid

classmethod from_function(multi_index, generating_function)

Create an instance of Grid with a given generating function.

Parameters:

• multi_index (MultiIndexSet) – The multi-index set of exponents of multi-dimensional polynomials that the Grid should support.

• generating_function (Union[GEN_FUNCTION, str]) – The generating function to construct an array of generating points. The function should accept as its arguments two integers, namely, the maximum exponent of the multi-index set of exponents and the spatial dimension and returns an array of shape (n + 1, m) where n is the one-dimensional polynomial degree and m is the spatial dimension. Alternatively, a string as a key to dictionary of built-in generating functions may be specified.

Returns:

A new instance of the Grid class initialized with the given generating function.

Return type:

Grid

classmethod from_points(multi_index, generating_points)

Create an instance of Grid from an array of generating points.

Parameters:

• multi_index (MultiIndexSet) – The multi-index set of exponents of multi-dimensional polynomials that the Grid should support.

• generating_points (numpy.ndarray) – The generating points of the interpolation grid, a two-dimensional array of floats whose columns are the generating points per spatial dimension. The shape of the array is (n + 1, m) where n is the maximum polynomial degree in all dimensions (i.e., the maximum exponent) and m is the spatial dimension. The values in each column must be unique.

Returns:

A new instance of the Grid class initialized with the given multi-index set and generating points.

Return type:

Grid

classmethod from_value_set(multi_index, generating_values)

Create an instance of Grid from an array of generating values.

A set of generating values is one-dimensional interpolation points.

Parameters:

• multi_index (MultiIndexSet) – The multi-index set of polynomial exponents that defines the Grid. The set, in turn, defines the polynomials the Grid can support.

• generating_values (numpy.ndarray) – The one-dimensional generating points of the interpolation grid, a one-dimensional array of floats of length (n + 1, ) where n is the maximum exponent of the multi-index set. The values in the array must be unique.

Returns:

A new instance of the Grid class initialized with the given multi-index set and generating values.

Return type:

Grid

Notes

• An array of generating points are created based on tiling the generating values to the required spatial dimension.

property multi_index: MultiIndexSet

The multi-index set of exponents associated with the Grid.

The multi-index set of a Grid indicates the largest interpolating polynomial the Grid can support.

Returns:

A multi-index set of polynomial exponents associated with the Grid.

Return type:

MultiIndexSet

property generating_function: Callable[[int, int], ndarray] | None

The generating function of the interpolation Grid.

Returns:

The generating function of the interpolation Grid which is used to construct the array of generating points.

Return type:

Optional[GEN_FUNCTION]

Notes

• If the generating function is None then the Grid may not be manipulated that results in a grid of a higher degree or dimension.

property generating_points: ndarray

The generating points of the interpolation Grid.

The generating points of the interpolation grid are one two main ingredients of constructing unisolvent nodes (the other being the multi-index set of exponents).

Returns:

A two-dimensional array of floats whose columns are the generating points per spatial dimension. The shape of the array is (n + 1, m) where n is the maximum exponent of the multi-index set of exponents and m is the spatial dimension.

Return type:

numpy.ndarray

property max_exponent: int

The maximum exponent of the interpolation grid.

Returns:

The maximum exponent of the interpolation grid is the maximum degree of any one-dimensional polynomials the grid can support.

Return type:

int

property unisolvent_nodes: ndarray

The array of unisolvent nodes.

For a definition of unisolvent nodes, see The Notion of Unisolvence in the docs.

Returns:

The unisolvent nodes as a two-dimensional array of floats. The shape of the array is (N, m) where N is the number of elements in the multi-index set and m is the spatial dimension.

Return type:

numpy.ndarray

property spatial_dimension

Dimension of the domain space.

This attribute is propagated from multi_index.

Returns:

The dimension of the domain space, where the polynomial will live on.

Return type:

int

property tree

The used MultiIndexTree.

Returns:

The MultiIndexTree which is connected to this Grid instance.

Return type:

MultiIndexTree

property has_generating_function: bool

Return True if the instance has a generating function.

Returns:

True if the instance has a generating function assigned to it, and False otherwise.

Return type:

bool

property is_complete: bool

Return True if the instance has a complete multi-index set.

Returns:

True if the underlying multi-index set of the instance is a complete index set and False otherwise.

Return type:

bool

property is_downward_closed: bool

Return True if the instance has a downward-closed multi-indices.

Returns:

True if the underlying multi-index set of the instance is a downward-closed set and False otherwise.

Return type:

bool

add_exponents(exponents)

Add a set of exponents to the underlying multi-index set.

Parameters:

exponents (numpy:numpy.ndarray) – Array of integers to be added. A single element of multi-index set may be specified as a one-dimensional array with the length of the spatial dimension. Multiple elements must be specified as a two-dimensional array with the spatial dimension as the number of columns

Returns:

A new instance of Grid with the updated multi-index set.

Return type:

Grid

Notes

• The set of exponents are added lexicographically.

expand_dim(target_dimension)

Expand the dimension of the Grid.

Parameters:

target_dimension (Union[Grid, int]) – The new spatial dimension. It must be larger than or equal to the current dimension of the Grid. Alternatively, another instance of Grid whose dimension is higher can also be specified as a target dimension.

Returns:

The Grid with expanded dimension.

Return type:

Grid

Raises:

ValueError – If an instance is expanded to a dimension that cannot be supported either by the available generating function or generating points. If the target dimension is a Grid, the exception is raised when there are inconsistencies in either generating function or points.

is_compatible(other)

Return True if the instance is compatible with another.

Two grids are compatible if they have the same generating function (if exists) and the generating points up to a common dimension.

Parameters:

other (Grid) – The other instance to check its compatibility with the current instance.

Returns:

True if the current instance is compatible with the given instance; False otherwise.

Return type:

bool

make_complete()

Complete the underlying multi-index set of the Grid instance.

Returns:

A new instance of Grid whose underlying multi-index set is a complete set with respect to the spatial dimension, polynomial degree, and \(l_p\)-degree.

Return type:

Grid

Notes

• Calling the function always returns a new instance. If the index-set is already complete, a deep copy of the current instance is returned.

make_downward_closed()

Make the underlying multi-index set downward-closed.

Returns:

A new instance of Grid whose underlying multi-index set is a downward-closed set.

Return type:

Grid

Notes

• Calling the function always returns a new instance. If the index-set is already downward-closed, a deep copy of the current instance is returned.

merge(other, multi_index)

Merge two instances of Grid with a new multi-index set.

Parameters:

• other (Grid) – Another instance of Grid to merge with the current instance.

• multi_index (MultiIndexSet) – The multi-index set of the merged instance.

Returns:

The merged instance with the given multi-index set.

Return type:

Grid

Raises:

ValueError – If the generating functions of the instances are incompatible with each other (if both are specified) or if the generating points are incompatible with each other (if an instance is missing a generating function).

__copy__()

Creates of a shallow copy.

This function is called, if one uses the top-level function copy() on an instance of this class.

Returns:

The copy of the current instance.

Return type:

Grid

See also

copy.copy

copy operator form the python standard library.

__deepcopy__(mem)

Create of a deepcopy.

This function is called, if one uses the top-level function deepcopy() on an instance of this class.

Returns:

A deepcopy of the current instance where the underlying multi-index set and the generating points are deepcopied.

Return type:

Grid

See also

copy.deepcopy

copy function from the Python standard library.

__call__(fun, *args, **kwargs)

Evaluate the given function on the unisolvent nodes of the grid.

Parameters:

• fun (Callable) – The given function to evaluate. The function must accept as its first argument a two-dimensional array and return as its output an array of the same length as the input array.

• *args – Additional positional arguments passed to the given function.

• **kwargs – Additional keyword arguments passed to the given function.

Returns:

The values of the given function evaluated on the unisolvent nodes (i.e., the coefficients of the polynomial in the Lagrange basis).

Return type:

numpy.ndarray

__eq__(other)

Compare two instances of Grid for exact equality in value.

Two instances of Grid class is equal in value if and only if:

• both the underlying multi-index sets are equal, and

• both the generating points are equal, and

• both the generating functions are equal.

Parameters:

other (Grid) – An instance of Grid that is to be compared with the current instance.

Returns:

True if the two instances are equal in value, False otherwise.

Return type:

bool

__mul__(other)

Multiply two instances of Grid via the * operator.

Parameters:

other (Grid) – The second operand of the grid multiplication.

Returns:

The product of two grids; the underlying multi-index set is the product of the multi-index sets of the operands.

Return type:

Grid

__or__(other)

Combine two instances of Grid via the | operator.

Parameters:

other (Grid) – The second operand of the grid union.

Returns:

The union of two grids; the underlying multi-index set is the union of the multi-index sets of the operands.

Return type:

Grid

_create_generating_points()

Construct generating points from the generating function.

Returns:

The generating points of the interpolation grid, a two-dimensional array of floats whose columns are the generating points per spatial dimension. The shape of the array is (n + 1, m) where n is the maximum exponent of the multi-index set of exponents and m is the spatial dimension.

Return type:

numpy.ndarray

_verify_generating_points()

Verify if the generating points are valid.

Raises:

• ValueError – If the points are not of the correct dimension, contains NaN’s or inf’s, do not fit the standard domain, or the values per column are not unique.

• TypeError – If the points are not given in the correct type.

_verify_matching_gen_function_and_points()

Verify if the generation function and points match.

Raises:

ValueError – If the generating function generates different points than then ones that are provided.

_verify_grid_max_exponent()

Verify if the Grid max. exponent is consistent with the multi-index.

Raises:

ValueError – If the maximum exponent of the Grid is smaller than the maximum exponent of the multi-index set of polynomial exponents.

Notes

• While it perhaps makes sense to store the maximum exponent of each dimension as the instance property instead of the maximum over all dimensions, this has no use because the generating points have a uniform length in every dimension. For instance, if the maximum exponent per dimension of a two-dimensional polynomial are [5, 3], the stored generating points remain (5, 2) instead of two arrays having lengths of 5 and 3, respectively.

_new_instance(multi_index)

Construct new grid instance with a new multi-index set.

Parameters:

multi_index (MultiIndexSet) – The multi-index set of the new instance.

Returns:

The new instance of Grid with the given multi-index set.

Return type:

Grid

Notes

• The new instance will have the same underlying generating function and generating points.

• If the new multi-index set cannot be accommodated either by the generating function or the generating points, an exception will be raised.

__hash__ = None

__weakref__

list of weak references to the object (if defined)