Utilities

ropt.config.utils

Utilities for checking and converting configuration values.

This module provides helper functions primarily designed for use within Pydantic model validation logic. These functions facilitate the conversion of configuration inputs into standardized, immutable NumPy arrays and handle common validation tasks like checking enum values or broadcasting arrays to required dimensions.

normalize

normalize(array: NDArray[float64]) -> NDArray[np.float64]

Normalize a NumPy array so its elements sum to one.

Parameters:

Name	Type	Description	Default
array	NDArray[float64]	The input NumPy array (1D).	required

Returns:

Type	Description
NDArray[float64]	A new immutable NumPy array with the same shape as the input, where
NDArray[float64]	the elements have been scaled to sum to 1.0.

Raises:

Type	Description
ValueError	If the sum of the input array elements is not positive (i.e., less than or equal to machine epsilon).

immutable_array

immutable_array(
    array_like: ArrayLike, **kwargs: Any
) -> NDArray[Any]

Convert input to an immutable NumPy array.

This function takes various array-like inputs (e.g., lists, tuples, other NumPy arrays) and converts them into a NumPy array. It then sets the writeable flag of the resulting array to False, making it immutable.

Parameters:

Name	Type	Description	Default
array_like	ArrayLike	The input data to convert (e.g., list, tuple, NumPy array).	required
kwargs	Any	Additional keyword arguments passed directly to numpy.array.	{}

Returns:

Type	Description
NDArray[Any]	A new NumPy array, with its writeable flag set to False.

broadcast_arrays

broadcast_arrays(*args: Any) -> tuple[NDArray[Any], ...]

Broadcast arrays to a common shape and make them immutable.

This function takes multiple NumPy arrays (or array-like objects) and uses numpy.broadcast_arrays to make them conform to a common shape according to NumPy's broadcasting rules. Each resulting array is then made immutable by setting its writeable flag to False.

Parameters:

Name	Type	Description	Default
args	Any	A variable number of NumPy arrays or array-like objects.	()

Returns:

Type	Description
tuple[NDArray[Any], ...]	A tuple containing the broadcasted, immutable NumPy arrays.

broadcast_1d_array

broadcast_1d_array(
    array: NDArray[Any], name: str, size: int
) -> NDArray[Any]

Broadcast an array to a 1D array of a specific size and make it immutable.

This function takes an input array and attempts to broadcast it to a one-dimensional array of the specified size using NumPy's broadcasting rules. If successful, the resulting array is made immutable.

This is useful for ensuring configuration parameters (like weights or magnitudes) have the correct dimension corresponding to the number of variables, objectives, etc., allowing users to provide a single scalar value that applies to all elements.

Parameters:

Name	Type	Description	Default
array	NDArray[Any]	The input NumPy array or array-like object.	required
name	str	A descriptive name for the array (used in error messages).	required
size	int	The target size (number of elements) for the 1D array.	required

Returns:

Type	Description
NDArray[Any]	A new, immutable 1D NumPy array of the specified size.

Raises:

Type	Description
ValueError	If the input array cannot be broadcast to the target size.

check_enum_values

check_enum_values(
    value: NDArray[ubyte], enum_type: type[IntEnum]
) -> None

Check if enum values in a NumPy array are valid members of an IntEnum.

This function verifies that all integer values within the input NumPy array correspond to valid members of the specified IntEnum type.

Parameters:

Name	Type	Description	Default
value	NDArray[ubyte]	A NumPy array containing integer values (typically np.ubyte) representing potential enum members.	required
enum_type	type[IntEnum]	The IntEnum class to validate against.	required

Raises:

Type	Description
ValueError	If any value in the value array does not correspond to a member of the enum_type.

ropt.config.validated_types

Annotated types for Pydantic models providing input conversion and validation.

These types leverage Pydantic's BeforeValidator to automatically convert input values (like lists or scalars) into standardized, immutable NumPy arrays or Python collections (sets, tuples) during model initialization.

NumPy Array Types:

• Array1D: Converts input to an immutable 1D np.float64 array.
• Array2D: Converts input to an immutable 2D np.float64 array.
• ArrayEnum: Converts input to an immutable 1D np.ubyte array (suitable for integer enum values).
• Array1DInt: Converts input to an immutable 1D np.intc array.
• Array1DBool: Converts input to an immutable 1D np.bool_ array.

Collection Types:

• ItemOrSet[T]: Ensures the value is a set[T], converting single items or sequences.
• ItemOrTuple[T]: Ensures the value is a tuple[T, ...], converting single items or sequences.

Array1D module-attribute

Array1D = Annotated[
    NDArray[float64], BeforeValidator(_convert_1d_array)
]

Convert to an immutable 1D numpy array of floating point values.

Array2D module-attribute

Array2D = Annotated[
    NDArray[float64], BeforeValidator(_convert_2d_array)
]

Convert to an immutable 2D numpy array of floating point values.

ArrayEnum module-attribute

ArrayEnum = Annotated[
    NDArray[ubyte], BeforeValidator(_convert_enum_array)
]

Convert to an immutable numpy array of numerical enumeration values.

Array1DInt module-attribute

Array1DInt = Annotated[
    NDArray[intc], BeforeValidator(_convert_1d_array_intc)
]

Convert to an immutable 1D numpy array of integer values.

Array1DBool module-attribute

Array1DBool = Annotated[
    NDArray[bool_], BeforeValidator(_convert_1d_array_bool)
]

Convert to an immutable 1D numpy array of boolean values.

ItemOrSet module-attribute

ItemOrSet = Annotated[set[T], BeforeValidator(_convert_set)]

Convert to single value to a set containing that value, passes sets unchanged.

ItemOrTuple module-attribute

ItemOrTuple = Annotated[
    tuple[T, ...], BeforeValidator(_convert_tuple)
]

Convert to single value to a tuple containing that value, passes sets unchanged.