verification#

This module contains functions to verify relevant Minterpy quantities.

minterpy.utils.verification.verify_domain(domain, spatial_dimension)[source]#

Building and verification of domains.

This function builds a suitable domain as the cartesian product of a one- dimensional domain, or verifies the domain shape, of a multivariate domain is passed. If None is passed, the default domain is build from [-1,1].

Parameters:

  • domain (array_like, None) – Either one-dimensional domain (min,max), or a stack of domains for each domain with shape (spatial_dimension,2). If None is passed, the DEFAULT_DOMAIN is repeated for each spatial dimentsion.

  • spatial_dimension (int) – Dimentsion of the domain space.

Return verified_domain:

Stack of domains for each dimension with shape (spatial_dimension,2).

Return type:

np.ndarray

Raises:

ValueError – If no domain with the expected shape can be constructed from the input.

minterpy.utils.verification.check_type(obj, expected_type)[source]#

Check if the given input is of expected type.

Parameters:

  • obj (Any) – An instance to be checked.

  • expected_type (Type[Any]) – The expected type (i.e., class).

Raises:

TypeError – If the given instance is not of the expected type.

Notes

  • The purpose of this function is to unify type-checking procedure that raises an exception with a common message to avoid repetition across the codebase.

Examples

>>> check_type(1, int)  # 1 is an int
>>> check_type(np.array([1, 2]), np.ndarray)
>>> check_type("1.0", float)  # a string is not a float
Traceback (most recent call last):
...
TypeError: Expected <class 'float'>, but got <class 'str'> instead.
minterpy.utils.verification.check_dtype(a, expected_dtype)[source]#

Verify if the input array has the expected dtype.

Parameters:

  • a (np.ndarray) – Array to be checked.

  • expected_dtype (type) – The dtype which is check against.

Raises:

TypeError – if input array hasn’t the expected dtype.

minterpy.utils.verification.check_dimensionality(xx, dimensionality)[source]#

Verify the dimensionality of a given array.

Use this verification function when its expected dimensionality is known.

Parameters:

  • xx (np.ndarray) – A given array to verify.

  • dimensionality (Union[List[int], int]) – The expected dimensionality (i.e., the number of dimensions) of the array. If given in a list then multiple dimensionality is allowed.

Raises:

ValueError – If the input array is not of the expected dimension.

Return type:

None

Examples

>>> check_dimensionality(np.array([1, 2, 3]), dimensionality=1)
>>> yy = np.array([
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
... ])
>>> check_dimensionality(yy, dimensionality=2)
>>> check_dimensionality(yy, dimensionality=1)  # Wrong dimensionality
Traceback (most recent call last):
...
ValueError: 1-D array is expected; got instead 2-D.
>>> check_dimensionality(yy, dimensionality=[1, 2])
minterpy.utils.verification.check_shape(xx, shape)[source]#

Verify the shape of a given array.

Use this verification function when its expected shape (given as a tuple) is known.

Parameters:

  • xx (np.ndarray) – A given array to verify.

  • shape (Tuple[int, ...]) – The expected shape of the array.

Raises:

ValueError – If the input array is not of the expected shape.

Examples

>>> check_shape(np.array([1, 2, 3]), shape=(3, ))
>>> yy = np.array([
...     [1, 2, 3, 4],
...     [5, 6, 7, 8],
... ])
>>> check_shape(yy, shape=(2, 4))
>>> check_shape(yy, shape=(1, 5))  # Wrong shape
Traceback (most recent call last):
...
ValueError: Array of shape (1, 5) is expected; got instead (2, 4).
>>> check_shape(yy, shape=(2, 4, 1))  # Wrong dimensionality
Traceback (most recent call last):
...
ValueError: 3-D array is expected; got instead 2-D.
minterpy.utils.verification.check_values(xx, **kwargs)[source]#

Verify that the input has neither NaN nor inf values.

Parameters:

  • xx (Union[int, float, numpy.ndarray]) – The scalar or array to be checked.

  • **kwargs – Keyword arguments with Boolean as values, if True then the invalid value is allowed. The keys are nan (check for NaN values), inf (check for inf values), zero (check for 0 values), and negative (check for negative values). If any of those set to True, the given value will raise an exception. The default is NaN and inf values are not allowed, while zero or negative values are allowed.

Raises:

ValueError – If the scalar value or the given array contains any of the specified invalid values(e.g., NaN, inf, zero, or negative).

Examples

>>> check_values(10)  # valid
>>> check_values(np.nan)  # Default, no nan
Traceback (most recent call last):
...
ValueError: Invalid value(s) (NaN, inf, negative, zero).
>>> check_values(np.inf)  # Default, no inf
Traceback (most recent call last):
...
ValueError: Invalid value(s) (NaN, inf, negative, zero).
>>> check_values(np.zeros((3, 2)), zero=False)  # No zero value is allowed
Traceback (most recent call last):
...
ValueError: Invalid value(s) (NaN, inf, negative, zero).
>>> check_values(-10, negative=False)  # No negative value is allowed
Traceback (most recent call last):
...
ValueError: Invalid value(s) (NaN, inf, negative, zero).
minterpy.utils.verification.check_domain_fit(points)[source]#

Checks weather a given array of points is properly formatted and spans the standard domain \([-1,1]^m\).

Parameters:

points (np.ndarray, shape = (m, k)) – array to be checked. Here m is the dimenstion of the domain and k is the number of points.

Raises:

  • ValueError – if the grid points do not fit into the domain \([-1;1]^m\).

  • ValueError – if less than one point is passed.

minterpy.utils.verification.is_real_scalar(x)[source]#

Check if a given value is a real scalar number.

Parameters:

x (Union[int, float, numpy.integer, numpy.floating]) – The variable to be checked.

Returns:

True if the variable is a scalar (an int, float, numpy.integer, or numpy.floating), False otherwise.

Return type:

bool

Examples

>>> is_real_scalar(1)  # int
True
>>> is_real_scalar(10.0)  # float
True
>>> is_real_scalar(np.array([1])[0])  # numpy.int64
True
>>> is_real_scalar(np.array([1]))  # numpy.ndarray
False
>>> is_real_scalar(np.array([123.0])[0])  # numpy.float64
True
>>> is_real_scalar(1+5j)  # complex
False
minterpy.utils.verification.shape_eval_output(eval_output)[source]#

Shape the output of polynomial evaluation according to the convention.

Parameters:

eval_output (numpy.ndarray) – The output of polynomial evaluation as a one- or two-dimensional array to be shaped. The length of the array is N, i.e., the number of query points.

Returns:

The shaped array, a one-dimensional array for a polynomial with a single set of coefficients or a two-dimensional array for a polynomial with a multiple sets. The number of columns in the latter is the number of coefficient sets. Both have length of the number of query points.

Return type:

numpy.ndarray

Notes

  • The output array is at least one-dimensional.

Examples

>>> shape_eval_output(np.array([[1.0], [2.0], [3.0], [4.0]]))
array([1., 2., 3., 4.])
>>> shape_eval_output(np.array([[1.0, 2.0, 3.0, 4.0]]))
array([[1., 2., 3., 4.]])
>>> shape_eval_output(np.array([[1.0, 2.0], [3.0, 4.0]]))
array([[1., 2.],
       [3., 4.]])
minterpy.utils.verification.verify_spatial_dimension(spatial_dimension)[source]#

Verify if the value of a given spatial dimension is valid.

Parameters:

spatial_dimension (int) – Spatial dimension to verify; the value of a spatial dimension must be strictly positive (> 0). spatial_dimension may not necessarily be an int but it must be a single whole number.

Returns:

Verified spatial dimension. If the input is not an int, the function does a type conversion to an int if possible.

Return type:

int

Raises:

  • TypeError – If spatial_dimension is not of a correct type, i.e., its strict-positiveness cannot be verified or the conversion to int cannot be carried out.

  • ValueError – If spatial_dimension is, for example, not a positive or a whole number.

Examples

>>> verify_spatial_dimension(2)  # int
2
>>> verify_spatial_dimension(3.0)  # float but whole
3
>>> verify_spatial_dimension(np.array([1])[0])  # numpy.int64
1
minterpy.utils.verification.verify_poly_degree(poly_degree)[source]#

Verify if the value of a given polynomial degree is valid.

Parameters:

poly_degree (int) – Polynomial degree to verify; the value of a polynomial degree must be non-negative (>= 0). poly_degree may not necessarily be an int but it must be a single whole number.

Returns:

Verified polynomial degree. If the input is not an int, the function does a type conversion to an int if possible.

Return type:

int

Raises:

  • TypeError – If poly_degree is not of a correct type, i.e., its non-negativeness cannot be verified or the conversion to int cannot be carried out.

  • ValueError – If poly_degree is, for example, not a positive or a whole number.

Examples

>>> verify_poly_degree(0)  # int
0
>>> verify_poly_degree(1.0)  # float but whole
1
>>> verify_poly_degree(np.array([2])[0])  # numpy.int64
2
minterpy.utils.verification.verify_lp_degree(lp_degree)[source]#

Verify that the value of a given lp-degree is valid.

Parameters:

lp_degree (float) – A given \(p\) of the \(l_p\)-norm (i.e., \(l_p\)-degree) to verify. The value of an lp_degree must be strictly positive, but may not necessarily be a float.

Returns:

Verified lp-degree value. If the input is not a float, the function does a type conversion to a float if possible.

Return type:

float

Raises:

  • TypeError – If lp_degree is not of correct type, i.e., its strict-positiveness cannot be verified or the conversion to float cannot be carried out.

  • ValueError – If lp_degree is, for example, a non strictly positive value.

Examples

>>> verify_lp_degree(2.5)  # float
2.5
>>> verify_lp_degree(3)  # int
3.0
>>> verify_lp_degree(np.array([1])[0])  # numpy.int64
1.0
minterpy.utils.verification.verify_poly_coeffs(coeffs, num_monomials)[source]#

Verify that the given polynomial(s) coefficients are valid.

Parameters:

  • coeffs (numpy.ndarray) – The polynomial coefficients to verify. Other container sequences may be accepted as long as it can be converted to a numpy.ndarray of numpy.float64.

  • num_monomials (int) – The number of monomials in the polynomials, used as the basis to verify the length of the coefficients.

Returns:

Verified polynomial coefficients. If the input is not of numpy.float64, the function does a type conversion to the type if possible. This type is expected by Numba functions.

Return type:

numpy.ndarray

Raises:

  • TypeError – If coeffs is not of correct type or the conversion to numpy.ndarray or numpy.float64 cannot be carried out.

  • ValueError – If coeffs contains inf or nan’s or if the dimensionality of the coefficients is incorrect (not 1 or 2).

Examples

>>> verify_poly_coeffs(np.array([1, 2, 3]), 3)  # numpy.int64
array([1., 2., 3.])
>>> verify_poly_coeffs(np.array([10., 20.]), 2)  # numpy.float64
array([10., 20.])
>>> verify_poly_coeffs(np.array([[1., 2.], [3., 4.]]), 2)  # multi-dim
array([[1., 2.],
       [3., 4.]])
>>> verify_poly_coeffs(1.0, 1)  # a scalar
array([1.])
minterpy.utils.verification.verify_poly_domain(domain, spatial_dimension)[source]#

Verify that the given polynomial domain is valid.

Examples

>>> verify_poly_domain(np.array([[1], [2]]), 1)  # integer array
array([[1.],
       [2.]])
>>> verify_poly_domain(np.array([[1, 2], [2, 3]]), 2)
array([[1., 2.],
       [2., 3.]])
>>> verify_poly_domain([3, 2], 1) 
Traceback (most recent call last):
...
ValueError: The upper bounds must be strictly larger than the lower
bounds. Invalid values in the polynomial domain!
Parameters:
Return type:

ndarray

minterpy.utils.verification.verify_query_points(xx, spatial_dimension)[source]#

Verify if the values of the query points for evaluation are valid.

Parameters:

  • xx (numpy.ndarray) – A one- or two-dimensional array of query points at which a polynomial is evaluated. The length of the array is N, i.e., the number of query points.

  • spatial_dimension (int) – The spatial dimension of the polynomial (m). The shape of the query points array must be consistent with this.

Returns:

A two-dimensional array of numpy.float64 with a length of N and a number of columns of m. If the dtype of the array is not of numpy.float64, the function does a type conversion if possible.

Return type:

numpy.ndarray

Raises:

  • TypeError – If xx is not of a correct type.

  • ValueError – If xx is, for example, has an inconsistent number of columns or it contains nan’s.

Examples

>>> verify_query_points(1, 1)  # a scalar integer
array([[1.]])
>>> verify_query_points([3., 4., 5.], 1)  # a list
array([[3.],
       [4.],
       [5.]])
>>> verify_query_points([[3, 4, 5]], 3)  # a list of lists of integers
array([[3., 4., 5.]])
>>> verify_query_points(np.array([1., 2., 3.]), 1)  # 1 dimension
array([[1.],
       [2.],
       [3.]])
>>> verify_query_points(np.array([[1., 2.], [3., 4.]]), 2)  # 2 dimensions
array([[1., 2.],
       [3., 4.]])
>>> verify_query_points(np.array([1, 2, 3]), 1)  # integer
array([[1.],
       [2.],
       [3.]])
>>> verify_query_points(np.array(["a", "b"]), 1)
Traceback (most recent call last):
...
ValueError: could not convert string to float: 'a' Invalid values in query points array!

Notes

  • The conversion to numpy.float64 is required because some evaluation routines rely on Numba whose input types are pre-determined.

minterpy.utils.verification.verify_poly_power(power)[source]#

Verify if the value of a given polynomial power is valid.

This function verify the value of power in the expression poly**power.

Parameters:

power (int) – Polynomial power to verify; the value of a polynomial power must be a scalar non-negative (>= 0). poly_power may not necessarily be an int but it must be a single whole number.

Returns:

Verified polynomial power. If the input is not an int, the function does a type conversion to an int if possible.

Return type:

int

Raises:

  • TypeError – If poly_power is not of a correct type, e.g., it’s not a real scalar, or its non-negativeness cannot be verified, or the conversion to int cannot be carried out.

  • ValueError – If poly_degree is, for example, not a positive or a whole number.

Examples

>>> verify_poly_power(0)  # int
0
>>> verify_poly_power(1.0)  # float but whole
1
>>> verify_poly_power(np.array([2])[0])  # numpy.int64
2
minterpy.utils.verification.dummy(*args, **kwargs)[source]#

A placeholder function to indicate a feature that is not supported.

Warning

This feature is not implemented yet!

Raises:

NotImplementedError – Any time this function or method is called.

Return type:

None