domain#

This module contains the implementation of the Domain class.

The Domain class represents a rectangular domain in \(m\)-dimensional space and provides utilities for transformation between user-defined domains and the internal reference domain (currently \([-1, 1]^m\)).

Background information#

Internal polynomial representations of Minterpy are defined on an internal reference domain (currently \([-1, 1]^m\)). Users, however, are interested in approximating functions defined on custom rectangular domains \(\Omega = [a_1, b_1] \times \cdots \times [a_i, b_i] \times \cdots \times [a_m, b_m]\) where \(a_i\) and \(b_i\) are the lower and upper bounds of dimension \(i\), respectively. In other words, the domain \(\Omega\) is a cartesian product of intervals \([a_i, b_i]\) for \(i = 1, \dots, m\).

The transformations between these domains are essential for correct evaluation, differentiation, and integration of polynomials approximating functions in the user-defined domains.

More detailed background information can be found in User and Internal Domains.

Implementation details#

An instance of the Domain class consists of domain bounds as a two-dimensional array of shape (m, 2), where m is the spatial dimension. The first column contains the lower bounds and the second column the upper bounds across dimensions. Each row is the interval of each dimension. The bounds are finite real numbers, and the lower bounds are strictly smaller than the upper bounds.

The instance of the class provides:

Coordinate transformations to and from internal domain
Scaling factors for differentiation from chain rule
Scaling factors for integration (i.e., the determinant of the Jacobian)
Domain validation utilities

The transformations are separable: each spatial dimension is transformed independently of the other dimensions via an affine map.

How-To Guides#

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

class minterpy.core.domain.Domain(bounds)[source]#

A class representing the domain of the polynomials.

A domain of a polynomial is the set of all input points for which the polynomials are defined. A domain is defined by the lower and upper bounds per dimension. Currently, only domains with finite bounds are supported.

Parameters:: bounds (np.ndarray) – The domain bounds as a 2D array with shape (m, 2), where m is the spatial dimension. The first column contains the lower bounds and the second column the upper bounds across dimensions.

Properties

`bounds`	The domain bounds.
`internal_bounds`	The bounds of the internal domain.
`is_identity`	Check whether the domain is (approx) equal to the internal domain.
`is_uniform`	Check whether the domain is uniform.
`lowers`	The lower bounds of the domain.
`spatial_dimension`	Dimension of the domain space.
`uppers`	The upper bounds of the domain.
`widths`	The widths of the domain.

Methods

`contains`(xx[, internal])	Check whether the input points are contained in the domain.
`diff_factor`(order)	Compute the scaling factor for polynomial differentiation.
`expand_dim`(target)	Expand the dimension of the domain.
`identity`(spatial_dimension)	Create an instance with the default internal bounds.
`int_factor`()	Compute the scaling factor for polynomial integration.
`map_from_internal`(xx[, validate])	Map points in the internal domain to the original domain.
`map_to_internal`(xx[, validate])	Map input points to the internal domain.
`partial_matching`(other[, rtol, atol])	Compare two instances of domain up to the common dimension.
`uniform`(spatial_dimension, lower, upper)	Create an instance with uniform bounds.

classmethod uniform(spatial_dimension, lower, upper)[source]#

Create an instance with uniform bounds.

Creates a hyper-rectangular domain \([a, b]^m\) where \(a\) and \(b\) are the lower and upper bounds for each dimension, respectively.

Parameters:

spatial_dimension (int) – The number of dimensions for the space.
lower (float) – The lower bound of each dimension.
upper (float) – The upper bound of each dimension.

Returns:

A new instance of the Domain class initialized with uniform bounds, i.e., the same lower and upper bound for all dimensions.

Return type:

Domain

classmethod identity(spatial_dimension)[source]#

Create an instance with the default internal bounds.

The default internal bounds are \([-1, 1]^m\).

Parameters:: spatial_dimension (int) – The number of dimensions for the space.
Returns:: A new instance of the Domain class initialized with the default internal bounds, i.e., \([-1, 1]^m\) where \(m\) is the spatial dimension.
Return type:: Domain

property bounds: ndarray#

The domain bounds.

Returns:: The domain bounds as a 2D array with shape (m, 2), where m is the spatial dimension. The first column contains the lower bounds and the second column the upper bounds across dimensions.
Return type:: np.ndarray

property spatial_dimension#

Dimension of the domain space.

Returns:: The dimension of the domain space.
Return type:: int

property lowers: ndarray#

The lower bounds of the domain.

Returns:: The lower bounds of the domain as a one-dimensional array having shape (m, ).
Return type:: np.ndarray

property uppers: ndarray#

The upper bounds of the domain.

Returns:: The upper bounds of the domain as a one-dimensional array having shape (m, ).
Return type:: np.ndarray

property widths: ndarray#

The widths of the domain.

Returns:: The difference between the upper and lower bounds of the domain as a one-dimensional array having shape (m, ).
Return type:: np.ndarray

property is_identity: bool#

Check whether the domain is (approx) equal to the internal domain.

Returns:: True if the domain is an identity, False otherwise.
Return type:: bool

Notes

This check uses numerical tolerances (DEFAULT_RTOL and DEFAULT_ATOL) for robustness against floating-point errors.
When the domain is an identity, transformations and scaling factors computation can usually be skipped.

property is_uniform: bool#

Check whether the domain is uniform.

A uniform domain has the same lower and upper bounds in all dimensions, i.e., the domain has the form \([a, b]^m\) for some \(a\) and \(b\).

Returns:: True if the domain is uniform, False otherwise.
Return type:: bool

Notes

The dimension of a uniform domain can be expanded by extrapolating the bounds of the extra dimension from the bounds of the other dimensions.
A domain of dimension 1 is always uniform by definition.
An identity domain is currently always uniform, but not vice versa.
This check uses numerical tolerances (DEFAULT_RTOL and DEFAULT_ATOL) for robustness against floating-point errors.

property internal_bounds: ndarray#

The bounds of the internal domain.

Returns:: The bounds of the internal domain as a 2D array with shape (m, 2), where m is the spatial dimension. The first column contains the lower bounds and the second column the upper bounds across dimensions.
Return type:: np.ndarray

property _internal_lowers: ndarray#

The lower bounds of the internal domain.

Returns:: The lower bounds of the internal domain as a one-dimensional array having shape (m, ).
Return type:: np.ndarray

property _internal_uppers: ndarray#

The upper bounds of the internal domain.

Returns:: The upper bounds of the internal domain as a one-dimensional array having shape (m, ).
Return type:: np.ndarray

property _internal_widths: ndarray#

The widths of the internal domain.

Returns:: The difference between the upper and lower bounds of the internal domain as a one-dimensional array having shape (m, ).
Return type:: np.ndarray

map_to_internal(xx, validate=False)[source]#

Map input points to the internal domain.

The default internal domain is \([-1, 1]^m\).

Parameters:

xx (numpy.ndarray) – The input points to be mapped to the internal domain.
validate (bool, optional) – If True, validate that input points are within domain bounds, i.e., no extrapolation is allowed.

Returns:

The points in the internal domain, except when extrapolated (with validate=False).

Return type:

numpy.ndarray

map_from_internal(xx, validate=False)[source]#

Map points in the internal domain to the original domain.

The default internal domain is \([-1, 1]^m\).

Parameters:

xx (numpy.ndarray) – The input points in the internal domain to be mapped to the original domain.
validate (bool, optional) – If True, validate that input points are within domain bounds, i.e., no extrapolation is allowed.

Returns:

The points in the original domain.

Return type:

numpy.ndarray

int_factor()[source]#

Compute the scaling factor for polynomial integration.

Returns:: The scaling factor for polynomial integration.
Return type:: float

Notes

Here, we assume that the integration is carried out over all dimensions.

diff_factor(order)[source]#

Compute the scaling factor for polynomial differentiation.

Parameters:: order (numpy.ndarray) – A one-dimensional integer array specifying the order of derivatives along each dimension. The length of the array must be m where m is the spatial dimension of the polynomial.
Returns:: The scaling factor for polynomial differentiation.
Return type:: float

partial_matching(other, rtol=None, atol=None)[source]#

Compare two instances of domain up to the common dimension.

This method performs approximate equality checking between two domains using numerical tolerances, comparing only up to the minimum spatial dimension of the two domains. Both user-defined bounds and internal reference domain bounds are compared. This is useful for checking the compatibility of domains of different dimensions before, e.g., merging.

Parameters:

other (Domain) – An instance of Domain that is to be compared with the current instance.
rtol (float, optional) – The relative tolerance parameter. If not specified, the module-level default DEFAULT_RTOL is used.
atol (float, optional) – The absolute tolerance parameter. If not specified, the module-level default DEFAULT_ATOL is used.

Returns:

True if the two instances match up to the common dimension, False otherwise.

Return type:

bool

contains(xx, internal=False)[source]#

Check whether the input points are contained in the domain.

Parameters:

xx (numpy.ndarray) – A set of values to be checked.
internal (bool, optional) – Check against internal bounds instead of the domain bounds. The default is False.

Returns:

A boolean array indicating whether each point is contained in the domain.

Return type:

numpy.ndarray

expand_dim(target)[source]#

Expand the dimension of the domain.

Parameters:

target (Union[int, Domain]) – The target dimension to expand to. If an integer, it specifies the new dimension. If a Domain instance, it specifies the domain whose dimension to expand to.

Returns:

A new instance of the Domain class with expanded dimension.

Return type:

Domain

Raises:

ValueError – If the target dimension is smaller than the current dimension or an expansion to a target integer is attempted for a non-identity domain.
DomainMismatchError – If the target domain does not match the current domain.
TypeError – If the target is not an instance of Domain or int.

Notes

If the target domain is the current instance, the current instance is returned.

__eq__(other)[source]#

Compare two instances of Domain for exact equality in value.

Two instances of Domain class are considered equal in value if and only if their underlying bounds arrays are exactly equal. In other words, this is a strict comparison without any numerical tolerance.

Parameters:: other (Domain) – An instance of Domain that is to be compared with the current instance.
Returns:: True if the two instances are equal in value, False otherwise.
Return type:: bool

__or__(other)[source]#

Combine two instances of Domain via the | operator.

Two instances of Domain may be combined via the | operator if they are partially matched.

Parameters:: other (Domain) – An instance of Domain that is to be combined with the current instance.
Returns:: A new instance of Domain that is the result of the combination of the two instances.
Return type:: Domain
Raises:: DomainMismatchError – If the two domains are not partially matched.