geomexp.utils package

Submodules

geomexp.utils.validation module

Input validation utilities for the geomexp package.

Centralised validation functions used throughout the library to enforce parameter constraints and provide consistent, informative error messages.

geomexp.utils.validation.validate_data_array(X)

Validate and coerce input data to a 2-D float64 array.

Parameters:

X (object) – Input data, coerced via numpy.asarray().

Return type:

ndarray

Returns:

Validated array of shape (n_samples, n_features) with dtype float64.

Raises:

ValueError – If the resulting array is not 2-D or has zero features.

geomexp.utils.validation.validate_n_clusters(n_clusters, n_samples=None)

Validate the number of clusters.

Parameters:

• n_clusters (int) – Requested number of clusters.

• n_samples (int | None) – If provided, also checks that n_clusters <= n_samples.

Raises:

ValueError – If n_clusters < 1 or exceeds n_samples.

Return type:

None

geomexp.utils.validation.validate_positive_int(value, name)

Validate that a parameter is a positive integer.

Parameters:

• value (int) – The value to check.

• name (str) – Parameter name for the error message.

Raises:

• TypeError – If value is not an integer.

• ValueError – If value < 1.

Return type:

None

geomexp.utils.validation.validate_tolerance(tol)

Validate a convergence tolerance (must be non-negative).

Parameters:

tol (float) – Tolerance value.

Raises:

ValueError – If tol < 0.

Return type:

None

geomexp.utils.validation.validate_index_radius(r)

Validate the index radius constraint \(r \in [0, 1)\).

Parameters:

r (float) – Index radius value.

Raises:

ValueError – If r is outside \([0, 1)\).

Return type:

None

geomexp.utils.validation.validate_positive_float(value, name)

Validate that a parameter is strictly positive.

Parameters:

• value (float) – The value to check.

• name (str) – Parameter name for the error message.

Raises:

ValueError – If value <= 0.

Return type:

None

geomexp.utils.validation.validate_weights(weights)

Validate a 1-D array of positive quadrature weights.

Parameters:

weights (object) – Weight array, coerced via numpy.asarray().

Return type:

ndarray

Returns:

Validated 1-D float64 array.

Raises:

ValueError – If the array is not 1-D or contains non-positive entries.

geomexp.utils.validation.validate_gram_matrix(G)

Validate a Gram matrix (must be square, 2-D, and positive semi-definite).

Checks PSD by verifying that all eigenvalues are \(\geq -\epsilon\) where \(\epsilon\) is a small tolerance scaled by the matrix norm.

Parameters:

G (object) – Gram matrix, coerced via numpy.asarray().

Return type:

ndarray

Returns:

Validated 2-D float64 array.

Raises:

ValueError – If the matrix is not square, not 2-D, or not positive semi-definite.

Module contents

Utility functions for the geomexp package.

geomexp.utils.validate_data_array(X)

Validate and coerce input data to a 2-D float64 array.

Parameters:

X (object) – Input data, coerced via numpy.asarray().

Return type:

ndarray

Returns:

Validated array of shape (n_samples, n_features) with dtype float64.

Raises:

ValueError – If the resulting array is not 2-D or has zero features.

geomexp.utils.validate_gram_matrix(G)

Validate a Gram matrix (must be square, 2-D, and positive semi-definite).

Checks PSD by verifying that all eigenvalues are \(\geq -\epsilon\) where \(\epsilon\) is a small tolerance scaled by the matrix norm.

Parameters:

G (object) – Gram matrix, coerced via numpy.asarray().

Return type:

ndarray

Returns:

Validated 2-D float64 array.

Raises:

ValueError – If the matrix is not square, not 2-D, or not positive semi-definite.

geomexp.utils.validate_index_radius(r)

Validate the index radius constraint \(r \in [0, 1)\).

Parameters:

r (float) – Index radius value.

Raises:

ValueError – If r is outside \([0, 1)\).

Return type:

None

geomexp.utils.validate_n_clusters(n_clusters, n_samples=None)

Validate the number of clusters.

Parameters:

• n_clusters (int) – Requested number of clusters.

• n_samples (int | None) – If provided, also checks that n_clusters <= n_samples.

Raises:

ValueError – If n_clusters < 1 or exceeds n_samples.

Return type:

None

geomexp.utils.validate_positive_float(value, name)

Validate that a parameter is strictly positive.

Parameters:

• value (float) – The value to check.

• name (str) – Parameter name for the error message.

Raises:

ValueError – If value <= 0.

Return type:

None

geomexp.utils.validate_positive_int(value, name)

Validate that a parameter is a positive integer.

Parameters:

• value (int) – The value to check.

• name (str) – Parameter name for the error message.

Raises:

• TypeError – If value is not an integer.

• ValueError – If value < 1.

Return type:

None

geomexp.utils.validate_tolerance(tol)

Validate a convergence tolerance (must be non-negative).

Parameters:

tol (float) – Tolerance value.

Raises:

ValueError – If tol < 0.

Return type:

None

geomexp.utils.validate_weights(weights)

Validate a 1-D array of positive quadrature weights.

Parameters:

weights (object) – Weight array, coerced via numpy.asarray().

Return type:

ndarray

Returns:

Validated 1-D float64 array.

Raises:

ValueError – If the array is not 1-D or contains non-positive entries.