verification

This module contains functions to verify relevant Minterpy quantities.

minterpy.utils.verification.check_type(obj, expected_type)

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)

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)

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)

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)

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.is_real_scalar(x)

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)

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)

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)

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)

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)

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.standardize_query_points(xx, spatial_dimension, truncate_cols=False)

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 k, 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.

• truncate_cols (bool, optional) – If True, truncate columns to match spatial_dimension after conversion to array. Default is False.

Returns:

A two-dimensional array of numpy.float64 with a length of k 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

>>> standardize_query_points(1, 1)  # a scalar integer
array([[1.]])
>>> standardize_query_points([3., 4., 5.], 1)  # a list
array([[3.],
       [4.],
       [5.]])
>>> standardize_query_points([[3, 4, 5]], 3)  # a list of lists of integers
array([[3., 4., 5.]])
>>> standardize_query_points(np.array([1., 2., 3.]), 1)  # 1 dimension
array([[1.],
       [2.],
       [3.]])
>>> standardize_query_points(np.array([[1., 2.], [3., 4.]]), 2)  # 2 dims
array([[1., 2.],
       [3., 4.]])
>>> standardize_query_points(np.array([1, 2, 3]), 1)  # integer
array([[1.],
       [2.],
       [3.]])
>>> standardize_query_points(np.array([[1, 2, 3]]), 2, True)  # Truncate
array([[1., 2.]])
>>> standardize_query_points(np.array(["a", "b"]), 1) 
Traceback (most recent call last):
...
ValueError: could not convert string to float: ...

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)

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.verify_domain_bounds(bounds)

Verify that the given bounds for a domain are valid.

Valid domain bounds must satisfy the following conditions:

• Convertible to a 2D numeric array

• Shape of (m, 2) where m >= 1 (dimension is positive)

• Finite values (no NaN or inf)

• Non-empty

• Upper bounds strictly greater than lower bounds for all dimensions

Parameters:

bounds (array_like) – Domain bounds as either a 1D array [lower, upper] for a single dimension, or a 2D array of shape (m, 2) for m dimensions. Each row specifies [lower, upper] for one dimension.

Returns:

Validated domain bounds as a 2D array of shape (m, 2) with dtype FLOAT_DTYPE.

Return type:

numpy.ndarray

Raises:

InvalidDomainBoundsError – If the bounds violate any validation condition (see above).

Examples

>>> verify_domain_bounds(np.array([-1, 1]))  # 1D array, single dimension
array([[-1.,  1.]])
>>> verify_domain_bounds(np.array([[1, 2]]))  # Integer array (auto-converted)
array([[1., 2.]])
>>> verify_domain_bounds(np.array([[1., 2.], [2., 3.]]))  # 2D domain
array([[1., 2.],
       [2., 3.]])
>>> verify_domain_bounds([3, 2]) 
Traceback (most recent call last):
...
minterpy.utils.exceptions.InvalidDomainBoundsError: Upper bounds must be
strictly greater than lower bounds.
Invalid dimensions: [0]; Invalid bounds: [[3.0, 2.0]]

minterpy.utils.verification.verify_derivative_order(order, spatial_dimension)

Verify that the given order of derivatives are valid.

Valid orders of derivatives must satisfy the following conditions:

• Convertible to a 1D numeric array

• The length must match the spatial dimension (m)

• Integer values (whole numbers only, round floats like 2.0 are accepted and converted)

• Non-negative (all values are >=0, no NaN, no Inf)

Parameters:

• order (array_like) – Order of derivative for each dimension. An order must be specified for each spatial dimension. Non-integer values are accepted only if they represent whole numbers.

• spatial_dimension (int) – Expected number of dimensions (must be positive).

Returns:

Validated order of derivatives as a 1D array of shape (m,) with dtype INT_DTYPE.

Return type:

numpy.ndarray

Raises:

InvalidDerivativeOrderError – If the specification violate any validation condition (see above).

Examples

>>> verify_derivative_order(1, 1)  # Scalar, 1D
array([1])
>>> verify_derivative_order([1, 0, 1], 3)  # List as order, 3D
array([1, 0, 1])
>>> verify_derivative_order(np.array([1, 0, 2, 0]), 4)  # 4D
array([1, 0, 2, 0])
>>> verify_derivative_order([3, 2, 0], 2) 
Traceback (most recent call last):
...
minterpy.utils.exceptions.InvalidDerivativeOrderError: Order length 3 does
not match spatial dimension 2. Order of derivative for each dimension must
be specified.
>>> verify_derivative_order([3.2, 2.0], 2) 
Traceback (most recent call last):
...
minterpy.utils.exceptions.InvalidDerivativeOrderError: Order of derivatives
must be whole numbers. Invalid values: [3.2]
>>> verify_derivative_order([0, -1], 2) 
Traceback (most recent call last):
...
minterpy.utils.exceptions.InvalidDerivativeOrderError: Order of
derivatives must be non-negative. Negative values at dimensions: [1];
Invalid values: [-1]

minterpy.utils.verification.dummy(*args, **kwargs)

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