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.

Generating Points Convention

The generating points are stored as a two-dimensional array of shape (n + 1, m):

• Columns represent spatial dimensions: each column contains the one-dimensional interpolation nodes for that specific dimension

• Rows represent polynomial degrees: row i contains nodes for polynomial degree i (from degree 0 to degree n)

Important: Currently, generating points must be defined in the normalized domain \([-1, 1]^m\). When a custom user domain is specified, the Grid handles transformation automatically during function evaluation.

Example structure for a 2D grid with maximum degree 3:

generating_points = [
    [x0_dim1, x0_dim2],  # Degree 0 nodes
    [x1_dim1, x1_dim2],  # Degree 1 nodes
    [x2_dim1, x2_dim2],  # Degree 2 nodes
    [x3_dim1, x3_dim2],  # Degree 3 nodes
]
# All values must be in [-1, 1]

The generating function, when provided, produces this array structure. Different generating function (e.g., Chebyshev-Lobatto, equidistant, Leja) creates different node distributions within \([-1, 1]\), each with distinct approximation properties.

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, domain=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.

• domain (Domain, optional) – The domain of the interpolation grid. This parameter is optional. If not specified, a normalized domain in the hypercube of \([-1, 1]^m\) is created.

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.

• Generating points array has shape (n + 1, m) where columns represent spatial dimensions and rows represent polynomial degrees. All values must be in the normalized domain \([-1, 1]^m\). Different generating functions create different node distributions within this normalized space.

• 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

domain	The domain associated with the Grid.
generating_function	The generating function of the interpolation Grid.
generating_points	The generating points of the interpolation Grid.
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 in the normalized domain.

Methods

add_exponents(exponents)	Add a set of exponents to the underlying multi-index set.
expand_dim(target)	Expand the dimension of the Grid to a target dimension or 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.
has_compatible_gen_function(other)	Check if two grids have a compatible generating function.
has_compatible_gen_points(other)	Check if two grids have compatible generating points.
is_compatible(other)	Check if two instances of Grid are compatible.
make_complete()	Complete the underlying multi-index set of the Grid instance.
make_downward_closed()	Make the underlying multi-index set downward-closed.

classmethod from_degree(spatial_dimension, poly_degree, lp_degree, generating_function=None, generating_points=None, domain=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.

• domain (Domain, optional) – The domain of the interpolation grid. This parameter is optional. If not specified, a normalized domain in the hypercube of \([-1, 1]^m\) is created.

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, domain=None)

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.

• domain (Domain, optional) – The domain of the interpolation grid. This parameter is optional. If not specified, a normalized domain in the hypercube of \([-1, 1]^m\) is created.

Returns:

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

Return type:

Grid

classmethod from_points(multi_index, generating_points, domain=None)

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.

• domain (Domain, optional) – The domain of the interpolation grid. This parameter is optional. If not specified, a normalized domain in the hypercube of \([-1, 1]^m\) is created.

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, domain=None)

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.

• domain (Domain, optional) – The domain of the interpolation grid. This parameter is optional. If not specified, a normalized domain in the hypercube of \([-1, 1]^m\) is created.

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 domain: Domain

The domain associated with the Grid.

The domain represents the rectangular bounds of the Grid.

Returns:

The domain of the interpolation grid.

Return type:

Domain

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 in the normalized domain.

The unisolvent nodes are provided in the normalized domain \([-1, 1]^m\).

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

Returns:

The unisolvent nodes in [-1, 1]^m 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

Notes

• When evaluating functions via grid(func), the nodes are automatically transformed to the user-defined domain.

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

Expand the dimension of the Grid to a target dimension or Grid.

This method creates a new Grid with a higher spatial dimension by expanding both the underlying multi-index set and the domain. The expansion can target either a specific integer dimension or match the dimension of another (compatible) Grid instance.

Parameters:

target (Union[Grid, int]) –

The target for for dimension expansion:

• If int: The new spatial dimension (must be >= current dimension). For non-normalized domains, expansion to an integer is not allowed.

• If Grid: Another Grid instance whose dimension to match. The grids must have compatible generating functions or points.

Returns:

A new Grid instance with expanded dimension, containing:

• Expanded multi-index set

• Expanded domain

• Compatible generating function or points

Return type:

Grid

Raises:

ValueError – If the target dimension is smaller than the current dimension, if expanding a non-normalized domain to an integer dimension, if the generating points cannot accommodate the target dimension, or if the Grid is not compatible with the target Grid.

has_compatible_gen_function(other)

Check if two grids have a compatible generating function.

Two grids have a compatible generating function if each has a generating function and they are an identical function.

Parameters:

other (Grid) – Another Grid instance to check compatibility with.

Returns:

True if the generating functions are compatible, False otherwise.

Return type:

bool

has_compatible_gen_points(other)

Check if two grids have compatible generating points.

Two grids have compatible generating points if their generating point arrays match in the common dimensions (columns) and common degrees (rows). Compatibility is checked by comparing the overlapping subarray.

Parameters:

other (Grid) – Another Grid instance to check compatibility with.

Returns:

True if the generating points are compatible in their common dimensions and degrees, False otherwise.

Return type:

bool

Notes

• Compatibility is checked only for the intersection of dimensions and degrees

• For example, a grid with 3D generating points can be compatible with a 2D grid if their first 2 dimensions match; or a grid with degree 5 can be compatible with degree 3 if the first 4 rows (degrees 0-3) match

is_compatible(other)

Check if two instances of Grid are compatible.

Two instances of Grid are compatible if they have:

• The same generating function (when both have one), OR

• Compatible generating points (matching values in common dimensions, i.e., columns and common degrees, i.e., rows)

Parameters:

other (Grid) – Another Grid instance to check compatibility with.

Returns:

True if the generating data is compatible, False otherwise.

Return type:

bool

Notes

• This method checks ONLY the compatibility of the underlying generating functions or points of the two instances of Grid.

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.

__copy__()

Creates a shallow copy of the instance.

This function is called when using the top-level function copy() on an instance of this class.

Returns:

A shallow copy of the current instance.

Return type:

Grid

See also

copy.copy

Copy operator from 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, the domain, 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 a function on the unisolvent nodes in the given domain.

The function is evaluated at the unisolvent nodes transformed from the canonical domain \([-1, 1]^m\) to the user-defined domain. This allows users to define functions in their natural coordinate system without manually handling domain transformations.

Parameters:

• fun (Callable) – The function to evaluate. Must accept as its first argument a two-dimensional array of shape (N, m) and return an array of length N, where N is the number of unisolvent nodes and m is the spatial dimension.

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

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

Returns:

The function values evaluated at the unisolvent nodes in the user domain. These values correspond to the coefficients of the polynomial in the Lagrange basis.

Return type:

numpy.ndarray

Notes

• The unisolvent nodes are automatically transformed from \([-1, 1]^m\) to the given domain before evaluation.

• If the domain is normalized (\([-1, 1]^m\)), there no transformation takes place.

__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, and

• both the underlying domains 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.

Multiplying two instances of Grid creates a product grid with a multi-index set that is the product of the underlying sets of the two operands, and a domain that is the union of the two underlying domains.

Parameters:

other (Grid) – The second Grid operand for multiplication.

Returns:

The product grid with:

• Product of the two multi-index sets

• Union of the two domains

• Compatible generating function or points

Return type:

Grid

Notes

• This operation provides the infrastructure for polynomial multiplication: if polynomial p1 is defined on grid1 and p2 on grid2, then their product (p1 * p2) is naturally defined on (grid1 * grid2).

__or__(other)

Combine two instances of Grid via the | operator.

Combining two instances of Grid creates a union grid with a multi-index set that is the union of the underlying sets of the two operands, and a domain that is the union of the two underlying domains.

Parameters:

other (Grid) – The second Grid operand for union.

Returns:

The union grid with:

• Union of the two multi-index sets

• Union of the two domains

• Compatible generating function or points

Return type:

Grid

Notes

• This operation provides the infrastructure for polynomial addition: if polynomial p1 is defined on grid1 and p2 on grid2, then their sum (p1 + p2) is naturally defined on (grid1 | grid2).

_combine_with(other, multi_index, domain)

Combine two compatible grids with specified multi-index and domain.

This is a low-level helper used by grid operations, e.g., __mul__, __or__. The multi-index set and domain are already computed by the caller; this method picks the compatible generating data and constructs a new instance of Grid.

Parameters:

• other (Grid) – The other grid to combine with

• multi_index (MultiIndexSet) – The multi-index for the result

• domain (Domain) – The domain for the result

Returns:

New grid constructed with the given multi-index and domain

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

_expand_to_grid(target)

Expand the dimension of the Grid to match that of a target Grid.

This method expands the dimension of the current Grid instance to match the spatial dimension of the target Grid. Both the underlying multi-index set and domain are expanded, and the grids must have compatible generating functions or points.

Parameters:

target (Grid) – The target Grid whose dimension to match. Must have compatible generating functions or points with the current Grid instance.

Returns:

A new instance of Grid with:

• Dimension matching the target Grid

• Expanded multi-index set

• Expanded domain

• Compatible generating function or points for both grids

Return type:

Grid

_expand_to_dimension(target)

Expand the dimension of the Grid to a target dimension.

This method expands the dimension of the current Grid instance to the specified dimension (given as integer). The domain must be normalized to allow expansion, as the new dimension is inferred to have the same normalized bounds.

Parameters:

target (int) – The target dimension to expand the Grid to. Must be greater than or equal to the current dimension.

Returns:

A new instance of Grid with:

• Dimension equal to the target dimension

• Expanded multi-index set

• Expanded domain

• Same generating function or points as the current instance

Return type:

Grid

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

_verify_generating_points(generating_points)

Validate generating points.

Parameters:

generating_points (np.ndarray) – The given generating points to validate, a 2D array of shape (n + 1, m) where n is the maximum degree of the the grid in any dimension and m is the maximum spatial dimension of the grid.

Returns:

Validated generating points.

Return type:

np.ndarray

Raises:

• ValueError – If the points are not of the correct dimension, contain NaN’s or inf’s, do not match with the dimension of the grid, the values per column are not unique, or the points are not within the internal domain.

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

Notes

• Generating points may contain more columns (i.e., spatial dimension) than the grid itself (as defined by the dimension of the multi-index set). If there’s no generating function, this indicates the maximum dimension the current grid can be expanded to.

_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, domain=None)

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

Parameters:

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

• domain (Domain, optional) – The domain of the new instance. If not specified, the domain of the current grid will be used.

Returns:

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

_pick_generating_data(other)

Pick generating data from two compatible grids.

This private method validates that the two grids have compatible generating functions or generating points, then selects the appropriate generating data to use for constructing a combined grid. If both grids have compatible generating functions, the generating function; otherwise, the larger set of generating points is used.

Parameters:

other (Grid) – Another instance of Grid to pick compatible generating data from.

Returns:

A tuple containing either (Only one element of the tuple will be non-None):

• (generating_function, None) if both grids have compatible functions

• (None, generating_points) if grids have compatible points.

Return type:

Tuple[Optional[GEN_FUNCTION], Optional[np.ndarray]]

Raises:

ValueError – If the grids are not compatible.

Notes

• This is a low-level helper method used internally by grid combination operations (__mul__, __or__, expand_dim). Compatibility is determined by the is_compatible() method.

__hash__ = None

__weakref__

list of weak references to the object (if defined)