nextorch.utils¶

Utility functions for Bayesian Optimization

PyTorch tensor to numpy array conversion
(Inverse) normalization
(Inverse) standardization
Mesh test points generation
Ordinal, categorical variable encoding/decoding

nextorch.utils.binary_search(nums: Union[list, nextorch.utils.Array, torch.Tensor], target: float) → int¶

Modified binary search return the index in the original array where all values of the elements to its left and itself are smaller than or equal to the target

Parameters

nums (ArrayLike1d) – sorted 1d array
target (float) – target value

Returns

ans – target index

Return type

int

nextorch.utils.create_X_mesh_2d(mesh_size: Optional[int] = 41) → Tuple[nextorch.utils.Matrix, nextorch.utils.Matrix, nextorch.utils.Matrix]¶

Create 2D mesh for testing

Parameters

mesh_size (int, optional) – mesh size, by default 41

Returns

X_test (Matrix) – X in 2D mesh, 2 columns
X1 (Matrix) – X1 for surface plots
X2 (Matrix) – X2 for surface plots

nextorch.utils.create_full_X_test_1d(X_ranges: Union[list, nextorch.utils.Matrix, torch.Tensor], x_index: Optional[int] = 0, fixed_values: Optional[Union[list, nextorch.utils.Array, torch.Tensor, float]] = None, fixed_values_real: Optional[Union[list, nextorch.utils.Array, torch.Tensor, float]] = None, baseline: Optional[str] = 'left', mesh_size: Optional[int] = 41) → nextorch.utils.Matrix¶

Choose two dimensions, create 2D mesh and keep the rest as fixed values. If no fixed value input, the baseline values are used at those dimensions

Parameters

X_ranges (MatrixLike2d) – list of x ranges
x_index (Optional[int], optional) – index of two x variables, by default [0]
fixed_values (Optional[Union[ArrayLike1d, float]], optional) – fixed values in other dimensions, in a unit scale, by default None
fixed_values_real (Optional[Union[ArrayLike1d, float]], optional) – fixed values in other dimensions, in a real scale, by default None
baseline (Optional[str], optional) – the choice of baseline, must be left, right or center
mesh_size (int, optional) – mesh size, by default 41

Returns

X_test – Test X in a unit scale

Return type

MatrixLike2d

nextorch.utils.create_full_X_test_2d(X_ranges: Union[list, nextorch.utils.Matrix, torch.Tensor], x_indices: Optional[List[int]] = [0, 1], fixed_values: Optional[Union[list, nextorch.utils.Array, torch.Tensor, float]] = None, fixed_values_real: Optional[Union[list, nextorch.utils.Array, torch.Tensor, float]] = None, baseline: Optional[str] = 'left', mesh_size: Optional[int] = 41) → Tuple[nextorch.utils.Matrix, nextorch.utils.Matrix, nextorch.utils.Matrix]¶

Choose two dimensions, create 2D mesh and keep the rest as fixed values. If no fixed value input, the baseline values are used at those dimensions

Parameters

X_ranges (MatrixLike2d) – list of x ranges
x_indices (Optional[List[int]], optional) – indices of two x variables, by default [0, 1]
fixed_values (Optional[Union[ArrayLike1d, float]], optional) – fixed values in other dimensions, in a unit scale, by default None
fixed_values_real (Optional[Union[ArrayLike1d, float]], optional) – fixed values in other dimensions, in a real scale, by default None
baseline (Optional[str], optional) – the choice of baseline, must be left, right or center
mesh_size (int, optional) – mesh size, by default 41

Returns

X_test (MatrixLike2d) – Test X in a unit scale
X1 (Matrix) – X1 for surface plots
X2 (Matrix) – X2 for surface plots

nextorch.utils.decode_xv(xv_encoded: Union[list, nextorch.utils.Array, torch.Tensor], encoding: Union[list, nextorch.utils.Array, torch.Tensor], values: Union[list, nextorch.utils.Array, torch.Tensor]) → Union[list, nextorch.utils.Array, torch.Tensor]¶

Decoded the data to ordinal or categorical values

Parameters

xv_encoded (ArrayLike1d) – encoded data array
encoding (ArrayLike1d) – encoding array
values (ArrayLike1d) – ordinal or categorical values

Returns

xv_decoded – data decoded, with the original ordinal or categorical values

Return type

ArrayLike1d

nextorch.utils.encode_to_real_ParameterSpace(X: Union[list, nextorch.utils.Matrix, torch.Tensor], parameter_space: nextorch.parameter.ParameterSpace, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a unit scale from the encoding space, converts it into a real scale Using ParameterSpace object

Parameters

X (MatrixLike2d) – original matrix in a real scale
parameter_space (ParameterSpace) – ParameterSpace object
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

nextorch.utils.encode_to_real_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_types: List[str], encodings: Union[list, nextorch.utils.Matrix, torch.Tensor], values_2D: Union[list, nextorch.utils.Matrix, torch.Tensor], all_continuous: Optional[bool] = True, X_ranges: Optional[Union[list, nextorch.utils.Matrix, torch.Tensor]] = None, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a unit scale from the encoding space, converts it into a real scale

Parameters

X (MatrixLike2d) – original matrix in a real scale
X_types (List[str]) – list of parameter types
encodings (MatrixLike2d) – encoding Matrix
values_2D (MatrixLike2d) – list of values for ordinal or categorical parameters
all_continuous (Optional[bool], Optional) – flag for all continuous parameters
X_ranges (Optional[MatrixLike2d], optional) – list of x ranges, by default None
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

Returns

Xreal – matrix scaled to a unit scale

Return type

numpy matrix

nextorch.utils.encode_xv(xv: Union[list, nextorch.utils.Array, torch.Tensor], encoding: Union[list, nextorch.utils.Array, torch.Tensor]) → Union[list, nextorch.utils.Array, torch.Tensor]¶

Convert original data to encoded data

Parameters

xv (ArrayLike1d) – original x array
encoding (ArrayLike1d) – encoding array

Returns

xv_encoded – encoded data array

Return type

ArrayLike1d

nextorch.utils.expand_list(list_1d: list) → list¶

Expand 1d list to 2d

Parameters: list_1d (list) – input list
Returns: list_2d – output 2d list
Return type: list

nextorch.utils.expand_ranges_X(X_ranges: Union[list, nextorch.utils.Matrix, torch.Tensor]) → list¶

Expand 1d X_range to 2d list

Parameters: X_ranges (MatrixLike2d) – list of x ranges (in 1d)
Returns: X_ranges – X ranges in 2d list
Return type: list
Raises: ValueError – Input type other than tensor/list/numpy matrix

nextorch.utils.fill_full_X_test(X_test_varying: Union[list, nextorch.utils.Matrix, torch.Tensor], X_ranges: Union[list, nextorch.utils.Matrix, torch.Tensor], x_indices: Optional[List[int]] = [0, 1], fixed_values: Optional[Union[list, nextorch.utils.Array, torch.Tensor, float]] = None, fixed_values_real: Optional[Union[list, nextorch.utils.Array, torch.Tensor, float]] = None, baseline: Optional[str] = 'left') → nextorch.utils.Matrix¶

Choose certain dimensions defined by x_indices, fill them with mesh test points and keep the rest as fixed values. If no fixed value input, the baseline values are used at those dimensions

Parameters

X_test_varying (MatrixLike2d) – mesh test points at dimensions defined by x_indices
X_ranges (MatrixLike2d) – list of x ranges
x_indices (Optional[List[int]], optional) – indices of two x variables, by default [0, 1]
fixed_values (Optional[Union[ArrayLike1d, float]], optional) – fixed values in other dimensions, in a unit scale, by default None
fixed_values_real (Optional[Union[ArrayLike1d, float]], optional) – fixed values in other dimensions, in a real scale, by default None
baseline (Optional[str], optional) – the choice of baseline, must be left, right or center

Returns

X_test – Test X in a unit scale

Return type

MatrixLike2d

Raises

ValueError – if the total dimensions do not add up to the system dimensionality

nextorch.utils.find_nearest_value(values: Union[list, nextorch.utils.Array, torch.Tensor], x: float) → Tuple[float, int]¶

find the nearest value in an array given a target value

Parameters

values (ArrayLike1d) – sorted array, in ascending order
x (float) – original value

Returns

ans (float) – Nearest value to the original
index_target (int) – index of the target in the given array

nextorch.utils.get_baseline_unit(n_dim: int, baseline: str) → List[float]¶

Get the baseline values from X_ranges in a unit scale

Parameters

X_ranges (MatrixLike2d) – list of x ranges
baseline (str) – the choice of baseline

Returns

a list of baseline values

Return type

List[float]

Raises

ValueError – if the input baseline is not in the default values

nextorch.utils.get_ranges_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor]) → list¶

Calculate the ranges for X matrix

Parameters: X (MatrixLike2d) – matrix or tensor
Returns: 2D list of ranges: [left bound, right bound]
Return type: list

nextorch.utils.inverse_standardize_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_mean: Union[list, nextorch.utils.Array, torch.Tensor], X_std: Union[list, nextorch.utils.Array, torch.Tensor], return_type: Optional[str] = 'tensor') → Union[list, nextorch.utils.Matrix, torch.Tensor]¶

Takes in an arrary/matrix/tensor X and returns the data in the real scale

Parameters

X (MatrixLike2d) – the original matrix or array
X_mean (Optional[ArrayLike1d], optional) – same type as X mean of each column in X, by default None, it will be computed here
X_std (Optional[ArrayLike1d], optional) – same type as X stand deviation of each column in X, by default None, it will be computed here
return_type (Optional[str], optional) – either ‘tensor’ or ‘np’

Returns

X_real – in real scale

Return type

MatrixLike2d, set by return_type

Raises

ValueError – if input return_type not defined

nextorch.utils.inverse_unitscale_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_ranges: Optional[Union[list, nextorch.utils.Matrix, torch.Tensor]] = None, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a unit scale and converts it into a real scale

Parameters

X (MatrixLike2d) – original matrix in a unit scale
X_ranges (Optional[MatrixLike2d], optional) – list of x ranges, by default None
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

Returns

Xunit – matrix scaled to a real scale

Return type

numpy matrix

nextorch.utils.inverse_unitscale_xv(xv: Union[list, nextorch.utils.Array, torch.Tensor], xi_range: Union[list, nextorch.utils.Array, torch.Tensor]) → Union[list, nextorch.utils.Array, torch.Tensor]¶

Takes in an x array in a unit scale and converts it to a real scale

Parameters

xv (ArrayLike1d) – x array in a unit scale
xi_range (ArrayLike1d) – range of x, [left bound, right bound]

Returns

xv – x in a real scale

Return type

ArrayLike1d, same type as xv

nextorch.utils.np_to_tensor(X: Union[list, nextorch.utils.Matrix, torch.Tensor]) → torch.Tensor¶

Converts numpy objects to tensor objects Returns a copy

Parameters: X (MatrixLike2D) – numpy objects
Returns: X – tensor objects
Return type: Tensor

nextorch.utils.prepare_full_X_real(X_test: Union[list, nextorch.utils.Matrix, torch.Tensor], X_ranges: Union[list, nextorch.utils.Matrix, torch.Tensor], x_indices: List[int], fixed_values_real: List[float]) → Union[list, nextorch.utils.Matrix, torch.Tensor]¶

Create a full X_test matrix given with varying x at dimensions defined by x_indices and fixed values at the rest dimensions

Parameters

X_test (MatrixLike2d) – X as mesh points, in a unit scale
X_ranges (MatrixLike2d) – list of x ranges
x_indices (Union[List[int], int]) – indices of varying x variables
fixed_values_real (Union[List[float], float]]) – fixed values in other dimensions, in a real scale

Returns

X_full – Test X in a real scale

Return type

MatrixLike2d

nextorch.utils.prepare_full_X_unit(X_test: Union[list, nextorch.utils.Matrix, torch.Tensor], n_dim: int, x_indices: List[int], fixed_values: List[float]) → Union[list, nextorch.utils.Matrix, torch.Tensor]¶

Create a full X_test matrix given with varying x at dimensions defined by x_indices and fixed values at the rest dimensions

Parameters

X_test (MatrixLike2d) – X_test as mesh points, in a unit scale
n_dim (int) – Dimensional of X, i.e., number of columns
x_indices (Union[List[int]]) – indices of varying x variables
fixed_values (Union[List[float]]) – fixed values in other dimensions, in a unit scale

Returns

X_full – Test X in a unit scale

Return type

MatrixLike2d

nextorch.utils.real_to_encode_ParameterSpace(X: Union[list, nextorch.utils.Matrix, torch.Tensor], parameter_space: nextorch.parameter.ParameterSpace, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a real scale from the relaxed continuous space, rounds (encodes) to the available values, and converts it into a unit scale. Using ParameterSpace object

Parameters

X (MatrixLike2d) – original matrix in a real scale
parameter_space (ParameterSpace) – ParameterSpace object
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

Returns

Xencode – matrix scaled to a unit scale

Return type

numpy matrix

nextorch.utils.real_to_encode_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_types: List[str], encodings: Union[list, nextorch.utils.Matrix, torch.Tensor], X_ranges: Optional[Union[list, nextorch.utils.Matrix, torch.Tensor]] = None, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a real scale from the relaxed continuous space, rounds (encodes) to the available values, and converts it into a unit scale

Parameters

X (MatrixLike2d) – original matrix in a real scale
X_types (List[str]) – list of parameter types
encodings (MatrixLike2d) – encoding Matrix
X_ranges (Optional[MatrixLike2d], optional) – list of x ranges, by default None
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

Returns

Xencode – matrix scaled to a unit scale

Return type

numpy matrix

nextorch.utils.standardize_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_mean: Optional[Union[list, nextorch.utils.Array, torch.Tensor]] = None, X_std: Optional[Union[list, nextorch.utils.Array, torch.Tensor]] = None, return_type: Optional[str] = 'tensor') → Union[list, nextorch.utils.Matrix, torch.Tensor]¶

Takes in an array/matrix X and returns the standardized data with zero mean and a unit variance

Parameters

X (MatrixLike2d) – the original matrix or array
X_mean (Optional[ArrayLike1d], optional) – same type as X mean of each column in X, by default None, it will be computed here
X_std (Optional[ArrayLike1d], optional) – same type as X stand deviation of each column in X, by default None, it will be computed here
return_type (Optional[str], optional) – either ‘tensor’ or ‘np’

Returns

X_standard – Standardized X matrix

Return type

MatrixLike2d, set by return_type

Raises

ValueError – if input return_type not defined

nextorch.utils.tensor_to_np(X: Union[list, nextorch.utils.Matrix, torch.Tensor]) → nextorch.utils.Matrix¶

Convert tensor objects to numpy array objects Returns a copy with no gradient information :param X: tensor objects :type X: MatrixLike2d

Returns: numpy objects
Return type: Matrix

nextorch.utils.transform_X_2d(X1: nextorch.utils.Matrix, X2: nextorch.utils.Matrix, X_ranges: nextorch.utils.Matrix) → Tuple[nextorch.utils.Matrix, nextorch.utils.Matrix]¶

Transform X1 and X2 in unit scale to real scales for plotting

Parameters

X1 (Matrix) – X for variable 1
X2 (Matrix) – X for variable 2
X_range (Matrix) – the ranges of two variables

Returns

X1 (Matrix) – X1 in a real scale
X2 (Matrix) – X2 in a real scale

nextorch.utils.transform_Y_mesh_2d(X: Union[list, nextorch.utils.Array, torch.Tensor], mesh_size: Optional[int] = 41) → nextorch.utils.Matrix¶

takes in 1 column of X tensor predict the Y values convert to real units and return a 2D numpy array in the size of mesh_size*mesh_size

Parameters

X (ArrayLike1d) – 1d tensor or numpy array
mesh_size (Optional[int], optional) – mesh size, by default 41

Returns

X_plot2D – in real units for plotting

Return type

numpy matrix

nextorch.utils.unit_to_encode_ParameterSpace(X: Union[list, nextorch.utils.Matrix, torch.Tensor], parameter_space: nextorch.parameter.ParameterSpace, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a unit scale from the relaxed continuous space, rounds (encodes) to the available values Using ParameterSpace object

Parameters

X (MatrixLike2d) – original matrix in a real scale
parameter_space (ParameterSpace) – ParameterSpace object
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

nextorch.utils.unit_to_encode_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_types: List[str], encodings: Union[list, nextorch.utils.Matrix, torch.Tensor], X_ranges: Optional[Union[list, nextorch.utils.Matrix, torch.Tensor]] = None, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a unit scale from the relaxed continuous space, rounds (encodes) to the available values

Parameters

X (MatrixLike2d) – original matrix in a real scale
X_types (List[str]) – List of parameter types
encodings (MatrixLike2d) – encoding Matrix
X_ranges (Optional[MatrixLike2d], optional) – list of x ranges, by default None
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

Returns

Xencode – matrix scaled to a unit scale

Return type

numpy matrix

nextorch.utils.unitscale_X(X: Union[list, nextorch.utils.Matrix, torch.Tensor], X_ranges: Optional[Union[list, nextorch.utils.Matrix, torch.Tensor]] = None, log_flags: Optional[list] = None, decimals: Optional[int] = None) → nextorch.utils.Matrix¶

Takes in a matrix in a real scale and converts it into a unit scale

Parameters

X (MatrixLike2d) – original matrix in a real scale
X_ranges (Optional[MatrixLike2d], optional) – list of x ranges, by default None
log_flags (Optional[list], optional) – list of boolean flags True: use the log scale on this dimensional False: use the normal scale by default None
decimals (Optional[int], optional) – Number of decimal places to keep by default None, i.e. no rounding up

Returns

Xunit – matrix scaled to a unit scale

Return type

numpy matrix

nextorch.utils.unitscale_xv(xv: Union[list, nextorch.utils.Array, torch.Tensor], xi_range: Union[list, nextorch.utils.Array, torch.Tensor]) → Union[list, nextorch.utils.Array, torch.Tensor]¶

Takes in an x array in a real scale and converts it to a unit scale

Parameters

xv (ArrayLike1d) – original x array
xi_range (ArrayLike1d) – range of x, [left bound, right bound]

Returns

xunit – normalized x in a unit scale

Return type

ArrayLike1d, same type as xv