multi_index#

This module contains the implementation of the MultiIndexSet class.

The MultiIndexSet class represents the multi-index sets of exponents that define the multivariate polynomials regardless of their chosen basis.

Background information#

Multi-index sets \(A \subseteq \mathbb{N}^m\) generalize the notion of polynomial degree to multiple dimensions \(m \in \mathbb{N}\). More detailed background information can be found in Multi-index sets and polynomial degree.

Implementation details#

An instance of MultiIndexSet class consists of two main properties: the set of exponents and the \(l_p\)-degree (i.e., the \(p\) in the \(l_p\)-norm of the exponents).

The set of exponents is always given as a two-dimensional array of non-negative integers of shape (N, m) where N corresponds to the number of elements and m corresponds to the spatial dimension of the set. The \(l_p\)-degree is always given as a scalar of type float.

How-To Guides#

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

class minterpy.core.multi_index.MultiIndexSet(exponents, lp_degree)[source]#

Bases: object

A class to represent the set of multi-indices.

The instances of this class provide the data structure for the exponents of multi-dimensional polynomials independently of the chosen basis in the polynomial space.

Parameters:

exponents (numpy.ndarray) – Set of exponents given as a two-dimensional non-negative integer array of shape (N, m), where N is the number of multi-index elements (i.e., exponents) and m is the number of spatial dimension. Each row of the array indicates the vector of exponents. To create an empty set, an empty two-dimensional array may be passed.
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\)).

Notes

If the set of exponents is not given as an integer array, it is converted to an integer array once the instance has been constructed.
The resulting polynomial degree corresponds to the minimum degree that would include the given set of exponents with respect to the \(l_p\)-degree.

Properties

`exponents`	Array of exponents in the form of multi-indices.
`is_complete`	Return `True` if the `exponents` array is complete.
`is_downward_closed`	Return `True` if the `exponents` array is downward-closed.
`lp_degree`	\(p\) of \(l_p\)-norm used to define the multi-index set.
`max_exponent`	The maximum exponent of the multi-index set.
`max_exponents`	The maximum exponents per dimension of the multi-index set.
`poly_degree`	The polynomial degree of the multi-index set.
`spatial_dimension`	The dimension of the domain space.

Methods

`add_exponents`(exponents[, inplace])	Add a set of exponents lexicographically into this instance.
`contains_these_exponents`(exponents[, expand_dim])	Return `True` if this instance contains a given set of exponents.
`expand_dim`(target_dimension[, inplace])	Expand the dimension of the multi-index set.
`from_degree`(spatial_dimension, poly_degree)	Create an instance from given spatial dim., poly., and lp-degrees.
`is_disjoint`(other[, expand_dim])	Return `True` if this instance is disjoint with another.
`is_propsubset`(other[, expand_dim])	Return `True` if this instance is a proper subset of another.
`is_propsuperset`(other[, expand_dim])	Return `True` if this instance is a proper subset of another.
`is_subset`(other[, expand_dim])	Return `True` if this instance is a subset of another.
`is_superset`(other[, expand_dim])	Return `True` if this instance is a superset of another.
`make_complete`([inplace])	Create a complete multi-index set from the current exponents.
`make_downward_closed`([inplace])	Create a downward-closed multi-index set from the current exponents.
`multiply`(other[, inplace])	Multiply an instance of `MultiIndexSet` with another.
`union`(other[, inplace])	Create a union between this instance with another.

classmethod from_degree(spatial_dimension, poly_degree, lp_degree=DEFAULT_LP_DEG)[source]#

Create an instance from given spatial dim., poly., and lp-degrees.

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, optional) – \(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\)). If not specified, lp_degree is assigned with the value of \(2.0\).

Returns:

An instance of MultiIndexSet in the given spatial_dimension with a complete set of exponents with respect to the given poly_degree and lp_degree.

Return type:

MultiIndexSet

property exponents: ndarray#

Array of exponents in the form of multi-indices.

Returns:: A two-dimensional integer array of exponents in the form of lexicographically sorted (ordered) multi-indices. This is a read-only property and defined at construction.
Return type:: numpy.ndarray

Notes

Each row corresponds to the exponent of a multi-dimensional polynomial basis while, each column corresponds to the exponent of a given dimension of a multi-dimensional polynomial basis.

property lp_degree: float#

\(p\) of \(l_p\)-norm used to define the multi-index set.

Returns:: The \(p\) of the \(l_p\)-norm (i.e., the \(l_p\)-degree) that is used to define the multi-index set. This property is read-only and defined at construction.
Return type:: float

property poly_degree: int#

The polynomial degree of the multi-index set.

Returns:: The polynomial degree of the multi-index set. This property is read-only and inferred from a given multi-index set and lp-degree.
Return type:: int

property spatial_dimension: int#

The dimension of the domain space.

Returns:: The dimension of the domain space, on which a polynomial described by this instance of MultiIndexSet lives. It is equal to the number of elements in each element of multi-indices (i.e., the number of columns of the array of multi-indices)
Return type:: int

property is_complete: bool#

Return True if the exponents array is complete.

Returns:: True if the exponents array is complete and False otherwise.
Return type:: bool

Notes

For a definition of completeness, refer to the relevant section of the Minterpy Documentation.

property is_downward_closed#

Return True if the exponents array is downward-closed.

Returns:: True if the exponents array is downward-closed and False otherwise.
Return type:: bool

Notes

Many Minterpy routines like DDS, Newton-evaluation, etc. strictly require a downward-closed exponent array (i.e., an array without lexicographical “holes”) to work.
Refer to the Fundamentals section of the Minterpy Documentation for the definition of multi-index sets.

property max_exponent: int | None#

The maximum exponent of the multi-index set.

Returns:: The maximum exponent over all dimensions of the multi-index set. If the index set is empty, None is returned.
Return type:: int, optional

property max_exponents: ndarray | None#

The maximum exponents per dimension of the multi-index set.

Returns:: The maximum exponents per dimension of the multi-index set given as one-dimensional array of length m (the spatial dimension). If the index set is empty, None is returned.
Return type:: numpy.ndarray, optional

add_exponents(exponents, inplace=False)[source]#

Add a set of exponents lexicographically into this instance.

Parameters:

exponents (numpy:numpy.ndarray) – Array of exponents to be added. The set of exponents must be of integer type.
inplace (bool, optional) – Flag to determine whether the current instance is modified in-place with the complete exponents. If inplace is False, a new MultiIndexSet instance is created. The default is False.

Returns:

The multi-index set with an updated set of exponents. If inplace is set to True, then the modification is carried out in-place without an explicit output (it returns None).

Return type:

MultiIndexSet, optional

Notes

The array of added exponents must be of integer types; non-integer types will be converted to integer.
If the current MultiIndexSet exponents already include the added set of exponents and inplace is set to False (the default) a shallow copy is created.

contains_these_exponents(exponents, expand_dim=False)[source]#

Return True if this instance contains a given set of exponents.

Parameters:

exponents (numpy.ndarray) – A two-dimensional array of exponents (multi-indices) to be checked.
expand_dim (bool, optional) – Flag to allow the dimension of an instance is expanded if there is a difference.

Returns:

True if all the multi-indices in exponents are contained in the current instance; False otherwise.

Return type:

bool

expand_dim(target_dimension, inplace=False)[source]#

Expand the dimension of the multi-index set.

After expansion, the value of exponents in the new dimension is 0.

Parameters:

target_dimension (int) – The new spatial dimension. It must be larger than or equal to the current spatial dimension of the multi-index set.
inplace (bool, optional) – Flag to determine whether the current instance is modified in-place with the expanded dimension. If inplace is False, a new MultiIndexSet instance is created. The default is False.

Returns:

The multi-index set with an expanded dimension. If inplace is set to True, then the modification is carried out in-place without an explicit output.

Return type:

MultiIndexSet, optional

Raises:

ValueError – If the new dimension is smaller than the current spatial dimension of the MultiIndexSet instance.

Notes

If the new dimension is the same as the current spatial dimension of the MultiIndexSet instance, setting inplace to False (the default) creates a shallow copy.

is_disjoint(other, expand_dim=False)[source]#

Return True if this instance is disjoint with another.

Parameters:

other (MultiIndexSet) – The other instance of multi-index set.
expand_dim (bool, optional) – Flag to allow the spatial dimension of an instance to be expanded if there is a difference.

Raises:

ValueError – If the number of spatial dimensions of the two sets are not the same and expand_dim is set to False.

Return type:

bool

Notes

The spatial dimension of the sets is irrelevant if one of the sets is empty.

is_subset(other, expand_dim=False)[source]#

Return True if this instance is a subset of another.

Parameters:

other (MultiIndexSet) – The superset instance.
expand_dim (bool, optional) – Flag to allow the spatial dimension of an instance to be expanded if there is a difference.

Returns:

True if the instance is a subset of another; False otherwise.

Return type:

bool

Notes

The spatial dimension of the sets is irrelevant if one of the sets is empty.

is_propsubset(other, expand_dim=False)[source]#

Return True if this instance is a proper subset of another.

Parameters:

other (MultiIndexSet) – The superset instance.
expand_dim (bool, optional) – Flag to allow the dimension of an instance is expanded if there is a difference.

Returns:

True if the instance is a proper subset of another; False otherwise.

Return type:

bool

Notes

The spatial dimension of the sets is irrelevant if one of the sets is empty.

is_superset(other, expand_dim=False)[source]#

Return True if this instance is a superset of another.

Parameters:

other (MultiIndexSet) – The subset instance.
expand_dim (bool, optional) – Flag to allow the spatial dimension of an instance to be expanded if there is a difference.

Returns:

True if the instance is a superset of another; False otherwise.

Return type:

bool

Notes

The spatial dimension of the sets is irrelevant if one of the sets is empty.

is_propsuperset(other, expand_dim=False)[source]#

Return True if this instance is a proper subset of another.

Parameters:

other (MultiIndexSet) – The subset instance.
expand_dim (bool, optional) – Flag to allow the spatial dimension of an instance to be expanded if there is a difference.

Returns:

True if the instance is a proper superset of another; False otherwise.

Return type:

bool

Notes

The spatial dimension of the sets is irrelevant if one of the sets is empty.

make_complete(inplace=False)[source]#

Create a complete multi-index set from the current exponents.

Parameters:: inplace (bool, optional) – Flag to determine whether the current instance is modified in-place with the complete exponents. If inplace is False, a new MultiIndexSet instance is created. The default is False.
Returns:: The multi-index set with a complete set of exponents. If inplace is set to True, then the modification is carried out in-place without an explicit output.
Return type:: MultiIndexSet, optional

Notes

If the current MultiIndexSet exponents are already complete, setting inplace to False (the default) creates a shallow copy.

make_downward_closed(inplace=False)[source]#

Create a downward-closed multi-index set from the current exponents.

Parameters:: inplace (bool, optional) – Flag to determine whether the current instance is modified in-place with the downward-closed set of exponents. If inplace is False, a new MultiIndexSet instance is created. The default is False.
Returns:: The multi-index set with the downward-closed set of exponents. If inplace is set to True, then the modification is carried out in-place without an explicit output.
Return type:: MultiIndexSet, optional

Notes

If the current MultiIndexSet exponents are already complete, setting inplace to False (the default) creates a shallow copy.

multiply(other, inplace=False)[source]#

Multiply an instance of MultiIndexSet with another.

Parameters:

other (MultiIndexSet) – The second operand of the multi-index set multiplication (i.e., other in self * other).
inplace (bool, optional) – Flag to determine whether the current instance is modified in-place with the product of the two multi-indices. If inplace is set to False, a new MultiIndexSet instance is created. The default is set to False.

Returns:

The multi-index set having the product of the two sets of exponents. If inplace is set to True, then the modification is carried out in-place without an explicit output.

Return type:

MultiIndexSet, optional

union(other, inplace=False)[source]#

Create a union between this instance with another.

Parameters:

other (MultiIndexSet) – The second operand of the multi-index set union (i.e., other in self | other).
inplace (bool, optional) – Flag to determine whether the current instance is modified in-place with the union of the two multi-indices. If inplace is set to False, a new MultiIndexSet instance is created. The default is set to False.

Returns:

The multi-index set having the union of the two sets of exponents. If inplace is set to True, then the modification is carried out in-place without an explicit output.

Return type:

MultiIndexSet, optional

Notes

If the operands are equal in value, setting inplace to False (the default) creates a shallow copy.
The spatial dimension of the sets is irrelevant if one of the sets is empty.

__str__()[source]#: Return str(self).

__repr__()[source]#: Return repr(self).

__len__()[source]#: Return the cardinality of the multi-index set.

__contains__(item)[source]#

Check if an element is contained by a MultiIndexSet instance.

Parameters:: item (np.ndarray) – An element of multi-index set, a one-dimensional integer array, to check whether it is contained in this MultiIndexSet instance.
Returns:: True if the item is an element of the instance, and False otherwise.
Return type:: bool

Notes

Containment check is very forgiving; wrong type, wrong dimension, multi-element checks will not raise an exception but simply return False.
If the dimension is not consistent then expansion is allowed with zero padding.

__eq__(other)[source]#

Check the equality of MultiIndexSet instances via == operator.

Two instances of MultiIndexSet class is equal in value if and only if both the underlying \(l_p\)-degree values are equal and the exponents are also equal.

Parameters:: other (MultiIndexSet) – An instance of MultiIndexSet 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)[source]#

Multiply an instance of MultiIndexSet with another via * op.

Parameters:: other (MultiIndexSet) – The second operand of the multi-index set multiplication.
Returns:: The product of two multi-index sets. If the \(l_p\)-degrees of the operands are different, then the larger \(l_p\)-degree becomes the \(l_p\)-degree of the product set. If the dimension differs, the product set has the dimension of the set with the larger dimension.
Return type:: MultiIndexSet

__imul__(other)[source]#

Multiply inplace an instance of MultiIndexSet with another.

Parameters:: other (MultiIndexSet) – The second operand of the multi-index set multiplication.
Returns:: The product of two multi-index sets. If the \(l_p\)-degrees of the operands are different, then the larger \(l_p\)-degree becomes the \(l_p\)-degree of the product set. If the dimension differs, the product set has the dimension of the set with the larger dimension.
Return type:: MultiIndexSet

__ge__(other)[source]#

Check if this instance is a subset of another via >= operator.

Notes

The checking does not keep the spatial dimensions of both instances strictly. If there’s a dimension mismatch, a dimension expansion is carried out.
To carry out subset check without dimension expansion, use the method is_subset() instead.

Parameters:: other (MultiIndexSet)
Return type:: bool

__gt__(other)[source]#

Check if this instance is a subset of another via > operator.

Notes

The checking does not keep the spatial dimensions of both instances strictly. If there’s a dimension mismatch, a dimension expansion is carried out.
To carry out subset check without dimension expansion, use the method is_subset() instead.

Parameters:: other (MultiIndexSet)
Return type:: bool

__hash__ = None#

__le__(other)[source]#

Check if this instance is a subset of another via <= operator.

Notes

The checking does not keep the spatial dimensions of both instances strictly. If there’s a dimension mismatch, a dimension expansion is carried out.
To carry out subset check without dimension expansion, use the method is_subset() instead.

Parameters:: other (MultiIndexSet)
Return type:: bool

__weakref__#: list of weak references to the object (if defined)

__lt__(other)[source]#

Check if this instance is a proper subset of another via < op.

Notes

The checking does not keep the spatial dimensions of both instances strictly. If there’s a dimension mismatch, a dimension expansion is carried out.
To carry out subset check without dimension expansion, use the method is_subset() instead.

Parameters:: other (MultiIndexSet)
Return type:: bool

__or__(other)[source]#

Combine an instance of MultiIndexSet with another via | oper.

Parameters:: other (MultiIndexSet) – The second operand of the multi-index set union.
Returns:: The union of two multi-index sets. If the \(l_p\)-degrees of the operands are different, then the larger \(l_p\)-degree becomes the \(l_p\)-degree of the union set. If the dimension differs, the union set has the dimension of the set with the larger dimension.
Return type:: MultiIndexSet

__ior__(other)[source]#

Combine an instance of MultiIndexSet with another inplace via op.

Parameters:: other (MultiIndexSet) – The second operand of the multi-index set union.
Returns:: The union of two multi-index sets, updating the left-hand-side operand. If the \(l_p\)-degrees of the operands are different, then the larger \(l_p\)-degree becomes the \(l_p\)-degree of the union set. If the dimension differs, the union set has the dimension of the set with the larger dimension.
Return type:: MultiIndexSet

__deepcopy__(memo)[source]#

Create of a deepcopy.

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

Returns:: A deep copy of the current instance.
Return type:: MultiIndexSet

Notes

Some properties of MultiIndexSet are lazily evaluated, this custom implementation of copy.deepcopy allows the values of already computed properties to be copied.
A deep copy contains a deep copy of the property exponents.