vopy.utils

vopy.utils.binary_entropy(x: numpy.ndarray) numpy.ndarray

Calculate the binary entropy of a given probability.

This method computes the binary entropy for each element in the input array x. Binary entropy is a measure of the uncertainty associated with a Bernoulli random variable.

Parameters:

x (np.ndarray) – An array of probabilities.

Returns:

An array of binary entropy values corresponding to the input probabilities.

Return type:

np.ndarray

vopy.utils.generate_sobol_samples(dim: int, n: int) numpy.ndarray

This method generates n samples from a Sobol sequence of dimension dim. n should be a power of 2 in order to generate a balanced sequence.

Parameters:
  • dim (int) – The dimension of the Sobol sequence.

  • n (int) – The number of samples to generate.

Returns:

An array of Sobol sequence samples.

Return type:

np.ndarray

vopy.utils.get_2d_w(cone_degree: float) numpy.ndarray

This function generates a 2D cone matrix W with boundaries at an angle cone_angle and symmetric around \(y=x\).

Parameters:

cone_angle (float) – The angle of the cone in degrees.

Returns:

A 2x2 numpy array where each row is a normalized normal vector.

Return type:

numpy.ndarray

vopy.utils.get_alpha(rind: int, W: numpy.ndarray) numpy.ndarray

Compute alpha_rind for row rind of W.

Parameters:
  • rind (int) – The row index of W for which to compute alpha.

  • W (numpy.ndarray) – The cone matrix.

Returns:

The computed alpha value for the specified row of W.

Return type:

numpy.ndarray

vopy.utils.get_alpha_vec(W: numpy.ndarray) numpy.ndarray

The alpha vector is computed using the get_alpha function for each row index.

Parameters:

W (numpy.ndarray) – The cone matrix.

Returns:

An ndarray of shape (n_constraint, 1) representing the computed alpha vector.

Return type:

numpy.ndarray

vopy.utils.get_bigmij(vi: numpy.ndarray, vj: numpy.ndarray, W: numpy.ndarray) float

This method calculates the M(i,j) value, which is used to measure the difference between two designs vi and vj based on the constraint matrix W.

Parameters:
  • vi (np.ndarray) – A D-vector representing the design vector i.

  • vj (np.ndarray) – A D-vector representing the design vector j.

  • W (np.ndarray) – A (n_constraint, D) ndarray representing the constraint matrix.

Returns:

The computed M(i,j) value.

Return type:

float

vopy.utils.get_closest_indices_from_points(pts_to_find: Iterable, pts_to_check: Iterable, return_distances: bool = False, squared: bool = False) numpy.ndarray | tuple[numpy.ndarray, numpy.ndarray]

This method calculates the closest indices in pts_to_check for each point in pts_to_find using Euclidean distances. Optionally, it can return the distances as well.

Parameters:
  • pts_to_find (np.ndarray) – An array of points for which the closest indices need to be found.

  • pts_to_check (np.ndarray) – An array of points to check against.

  • return_distances (bool, optional) – If True, the method also returns the distances to the closest points.

  • squared (bool, optional) – If True, the squared Euclidean distances are used and returned.

Returns:

An array of the closest indices, or a tuple containing the closest indices and the distances.

Return type:

Union[np.ndarray, tuple[np.ndarray, np.ndarray]]

vopy.utils.get_delta(mu: numpy.ndarray, W: numpy.ndarray, alpha_vec: numpy.ndarray) numpy.ndarray

This method computes \(\Delta^*_i\) gap value for each point in the input array mu. \(\Delta^*_i\) is calculated based on the provided constraint matrix W and the alpha vector alpha_vec.

Parameters:
  • mu (np.ndarray) – An array of shape (n_points, D) representing the points.

  • W (np.ndarray) – An array of shape (n_constraint, D) representing the constraint matrix.

  • alpha_vec (np.ndarray) – An array of shape (n_constraint, 1) representing the alphas of W.

Returns:

An array of shape (n_points, 1) containing \(\Delta^*_i\) for each point.

Return type:

np.ndarray

vopy.utils.get_noisy_evaluations_chol(means: numpy.ndarray, cholesky_cov: numpy.ndarray) numpy.ndarray

This method generates noisy samples from a multivariate normal distribution using the provided means and Cholesky decomposition of the covariance matrix. It is used for vectorized multivariate normal sampling.

Parameters:
  • means (np.ndarray) – An array of mean values for the multivariate normal distribution.

  • cholesky_cov (np.ndarray) – The Cholesky decomposition of the covariance matrix, this is a 2D array.

Returns:

An array of noisy samples.

Return type:

np.ndarray

vopy.utils.get_smallmij(vi: numpy.ndarray, vj: numpy.ndarray, W: numpy.ndarray, alpha_vec: numpy.ndarray) float

This method calculates the m(i,j) value, which is used to measure the difference between two designs vi and vj based on the constraint matrix W and the alpha vector alpha_vec.

Parameters:
  • vi (np.ndarray) – A D-vector representing the design vector i.

  • vj (np.ndarray) – A D-vector representing the design vector j.

  • W (np.ndarray) – A (n_constraint, D) ndarray representing the constraint matrix.

  • alpha_vec (np.ndarray) – A (n_constraint, 1) ndarray representing the alphas of W.

Returns:

The computed m(i,j) value.

Return type:

float

vopy.utils.get_uncovered_set(p_inds: Iterable, p_hat_inds: Iterable, mu: numpy.ndarray, eps: float, W: numpy.ndarray) list

Identify the set of elements in p_inds that are not covered by any element in p_hat_inds.

This function checks each element in p_inds to see if it is covered by any element in p_hat_inds based on the provided mu, eps, and W parameters.

Parameters:
  • p_inds (Iterable) – Array of indices representing the Pareto elements to check for coverage.

  • p_hat_inds (Iterable) – Array of indices representing the estimated Pareto elements that may cover elements in p_inds.

  • mu (np.ndarray) – (N, D) array where each row corresponds to a designs D-dim feature vector.

  • eps (float) – Coverage slackness.

  • W (np.ndarray) – An (n_constraint, D) array representing the cone matrix.

Returns:

List of indices from p_inds that are not covered by any element in p_hat_inds.

Return type:

list

vopy.utils.get_uncovered_size(pareto_pts: numpy.ndarray, pareto_hat_pts: numpy.ndarray, eps: float, W: numpy.ndarray) int

Identify the set of elements in pareto_pts that are not covered by any element in pareto_hat_pts.

This function checks each element in pareto_pts to see if it is covered by any element in pareto_hat_pts based on the provided mu, eps, and W parameters.

Parameters:
  • pareto_pts (np.ndarray) – An (N_pareto, D) array of Pareto elements to check for coverage.

  • pareto_hat_pts (np.ndarray) – An (N_pareto_hat, D) array of estimated Pareto elements to check if they cover any element of pareto_pts.

  • eps (float) – Coverage slackness.

  • W (np.ndarray) – An (n_constraint, D) array representing the cone matrix.

Returns:

Number of points from pareto_pts that are not covered by any element in pareto_hat_pts.

Return type:

int

vopy.utils.hyperrectangle_check_intersection(lower1: numpy.ndarray, upper1: numpy.ndarray, lower2: numpy.ndarray, upper2: numpy.ndarray) bool

This function takes the lower and upper bounds of two hyperrectangles and determines if they intersect. A hyperrectangle is defined by its lower and upper points in an n-dimensional space.

Parameters:
  • lower1 (np.ndarray) – Lower bounds of the first hyperrectangle.

  • upper1 (np.ndarray) – Upper bounds of the first hyperrectangle.

  • lower2 (np.ndarray) – Lower bounds of the second hyperrectangle.

  • upper2 (np.ndarray) – Upper bounds of the second hyperrectangle.

Returns:

True if the hyperrectangles intersect, False otherwise.

Return type:

bool

vopy.utils.hyperrectangle_get_region_matrix(lower: numpy.ndarray, upper: numpy.ndarray) tuple[numpy.ndarray, numpy.ndarray]

This method takes an n-dimensional lower bound array and an n-dimensional upper bound array, and constructs a matrix form for the hyperrectangle. For all points x inside the region of the hyperrectangle, the condition region_matrix @ x >= region_boundary holds true.

Parameters:
  • lower (np.ndarray) – An array of shape (n,) representing the lower bounds of the hyperrectangle.

  • upper (np.ndarray) – An array of shape (n,) representing the upper bounds of the hyperrectangle.

Returns:

A tuple containing two elements: - region_matrix: An array of shape (2*n, n) representing the matrix form of the hyperrectangle. - region_boundary: An array of shape (2*n,) representing the boundary conditions of the hyperrectangle.

Return type:

tuple[np.ndarray, np.ndarray]

vopy.utils.hyperrectangle_get_vertices(lower: numpy.ndarray, upper: numpy.ndarray) numpy.ndarray

This method takes an n-dimensional lower bound array and an n-dimensional upper bound array, and constructs the vertices of the corresponding hyperrectangle by combining these bounds.

Parameters:
  • lower (np.ndarray) – An array of shape (n,) representing the lower bounds of the hyperrectangle.

  • upper (np.ndarray) – An array of shape (n,) representing the upper bounds of the hyperrectangle.

Returns:

An array of shape (2^n, n) containing the vertices of the hyperrectangle.

Return type:

np.ndarray

vopy.utils.is_covered(vi: numpy.ndarray, vj: numpy.ndarray, eps: float, W: numpy.ndarray) bool

Check if vector vi is epsilon-covered by vector vj for a given cone matrix W.

This function determines if the vector vi can be weakly dominated by vj with an epsilon length vector chosen from the cone.

Parameters:
  • vi (np.ndarray) – A (D,) array representing the vector to be checked.

  • vj (np.ndarray) – A (D,) array representing the reference vector.

  • eps (float) – A float representing the slackness.

  • W (np.ndarray) – An (n_constraint, D) array representing the cone matrix.

Returns:

True if vi is epsilon-covered by vj under the constraints of W, False otherwise.

Return type:

bool

vopy.utils.is_pt_in_extended_polytope(pt: numpy.ndarray, polytope: numpy.ndarray, invert_extension: bool = False)

Check if pt is an element of the extended polytope with vertices represented with polytope.

This method checks if a point pt is an element of the polytope defined by the vertices in polytope and extended along to infinity along the axes. This corresponds to the Minkowski addition of a hyperrectangle with a right-angled cone. The invert_extension parameter can be used to invert the extension to negative infinity, i.e., Minkowski addition with negative of the right angle.

Parameters:
  • pt (np.ndarray) – A (D, ) array for the point to check.

  • polytope (np.ndarray) – An (N_vertices, D) array of vertices defining the polytope.

  • invert_extension (bool) – If True, the extension is inverted.

Returns:

True if the point is an element of the extended polytope, False otherwise.

Return type:

bool

vopy.utils.line_seg_pt_intersect_at_dim(P1: numpy.ndarray, P2: numpy.ndarray, target_pt: numpy.ndarray, target_dim: int) numpy.ndarray | None

Check if a line segment intersects with a point at a specific dimension.

This function determines if the line segment defined by points P1 and P2 intersects with the point target_pt when only the dimension target_dim is considered. If there is an intersection, it returns the point on the line segment where the intersection occurs. Otherwise, it returns None.

Parameters:
  • P1 (np.ndarray) – A (D, ) array for the first endpoint of the line segment.

  • P2 (np.ndarray) – A (D, ) array for the second endpoint of the line segment.

  • target_pt (np.ndarray) – A (D, ) array for the target point to check intersection.

  • target_dim (int) – The dimension to consider for the intersection check.

Returns:

The point on the line segment where the intersection occurs, or None if there is no intersection.

Return type:

Optional[np.ndarray]

vopy.utils.normalize(data: numpy.ndarray, bounds: list[tuple[float, float]]) numpy.ndarray

Normalize the data based on the provided bounds. Each column of the data array is normalized based on the corresponding bounds.

Parameters:
  • data (np.ndarray) – The data array to normalize.

  • bounds (list[tuple[float, float]]) – A list of tuples containing the lower and upper bounds for each column.

Returns:

The normalized data array.

Return type:

np.ndarray

vopy.utils.set_seed(seed: int) None

This function sets the seed for both NumPy and PyTorch random number generators.

Parameters:

seed (int) – The seed value to set for the random number generators.

vopy.utils.unnormalize(data: numpy.ndarray, bounds: list[tuple[float, float]]) numpy.ndarray

Unnormalize the data based on the provided bounds. Each column of the data array is unnormalized based on the corresponding bounds.

Parameters:
  • data (np.ndarray) – The data array to unnormalize.

  • bounds (list[tuple[float, float]]) – A list of tuples containing the lower and upper bounds for each column.

Returns:

The unnormalized data array.

Return type:

np.ndarray

Evaluation Utilities

vopy.utils.evaluate.calculate_epsilonF1_score(dataset: Dataset, order: PolyhedralConeOrder, true_indices: numpy.ndarray, pred_indices: numpy.ndarray, epsilon: float)

This method computes the epsilon-F1 score, which is a measure of the accuracy of the predicted indices compared to the true indices, considering a specified epsilon value.

Parameters:
  • dataset (Dataset) – The dataset containing the output data.

  • order (Order) – The order object containing the ordering cone.

  • true_indices (np.ndarray) – The true indices of the Pareto front.

  • pred_indices (np.ndarray) – The predicted indices of the Pareto front.

  • epsilon (float) – The epsilon value used for calculating the uncovered size and gap values.

Returns:

The calculated epsilon-F1 score.

Return type:

float

vopy.utils.evaluate.calculate_hypervolume_discrepancy_for_model(order: PolyhedralConeOrder, problem: ContinuousProblem, model: Model)

This method computes the hypervolume discrepancy between the true Pareto front and the predicted Pareto front for a given model. It uses Sobol sampling to generate input samples, evaluates the true and predicted outputs, and calculates the hypervolumes of the true and predicted Pareto fronts.

Parameters:
  • order (Order) – The order object containing the ordering cone and methods to get the Pareto set.

  • problem (ContinuousProblem) – The continuous problem to be evaluated.

  • model (Model) – The model trained on the problem, used to predict the outputs.

Returns:

The logarithm of the hypervolume discrepancy between the true and predicted Pareto fronts.

Return type:

float

Raises:

AssertionError – If the hypervolume discrepancy is less than or equal to a threshold.

Plotting Utilities

vopy.utils.plotting.plot_2d_cone(cone_membership: Callable[[numpy.ndarray], numpy.ndarray], path: str | PathLike | None = None, density: int = 50) matplotlib.pyplot.Figure

Plot the 2D cone by checking membership of the points in the cone.

This function plots a 2D cone by checking the membership of points within the cone using the provided cone_membership function. The plot is created using Matplotlib and can be saved to a specified path if provided.

Parameters:
  • cone_membership (Callable[[np.ndarray], np.ndarray]) – A callable that takes an array of points and returns a boolean array indicating whether each point is inside the cone.

  • path (Optional[Union[str, PathLike]]) – The file path where the plot will be saved. If None, the plot is not saved.

  • density (int) – The number of points to sample along each axis for plotting.

Returns:

The Matplotlib figure object containing the plot.

Return type:

plt.Figure

vopy.utils.plotting.plot_2d_theta_cone(cone_degree: float, path: str | PathLike | None = None) matplotlib.pyplot.Figure

Plot the 2D cone defined by the given cone degree, symmetric around \(y=x\).

This function plots a 2D cone based on the specified cone degree. The plot is created using Matplotlib and can be saved to a specified path if provided.

Parameters:
  • cone_degree (float) – The degree of the cone to be plotted.

  • path (Optional[Union[str, PathLike]]) – The file path where the plot will be saved. If None, the plot is not saved.

Returns:

The Matplotlib figure object containing the plot.

Return type:

plt.Figure

vopy.utils.plotting.plot_3d_cone(cone_membership: Callable[[numpy.ndarray], numpy.ndarray], path: str | PathLike | None = None, density: int = 50) matplotlib.pyplot.Figure

Plot the 3D cone by checking membership of the points in the cone.

This function plots a 3D cone by checking the membership of points within the cone using the provided cone_membership function. The plot is created using Matplotlib and can be saved to a specified path if provided.

Parameters:
  • cone_membership (Callable[[np.ndarray], np.ndarray]) – A callable that takes an array of points and returns a boolean array indicating whether each point is inside the cone.

  • path (Optional[Union[str, PathLike]]) – The file path where the plot will be saved. If None, the plot is not saved.

  • density (int) – The number of points to sample along each axis for plotting.

Returns:

The Matplotlib figure object containing the plot.

Return type:

plt.Figure

vopy.utils.plotting.plot_cells_with_centers(cells: numpy.ndarray, centers: numpy.ndarray, path: str | PathLike | None = None) matplotlib.pyplot.Figure

Plot the given cells with their corresponding centers. The plot is created using Matplotlib and can be saved to a specified path if provided.

Parameters:
  • cells (np.ndarray) – An array of shape (N, 2, 2) representing the cells to be plotted.

  • centers (np.ndarray) – An array of shape (N, 2) representing the centers of the cells.

  • path (Optional[Union[str, PathLike]]) – The file path where the plot will be saved. If None, the plot is not saved.

Returns:

The Matplotlib figure object containing the plot.

Return type:

plt.Figure

vopy.utils.plotting.plot_pareto_front(elements: numpy.ndarray, pareto_indices: numpy.ndarray, path: str | PathLike | None = None) matplotlib.pyplot.Figure

Plot the Pareto front for a given set of elements.

This function plots the Pareto front for a given set of elements in either 2D or 3D space. The elements that belong to the Pareto front are highlighted in a different color. The plot is created using Matplotlib and can be saved to a specified path if provided.

Parameters:
  • elements (np.ndarray) – An array of shape (N, dim) representing the elements to be plotted.

  • pareto_indices (np.ndarray) – An array of indices indicating which elements belong to the Pareto front.

  • path (Optional[Union[str, PathLike]]) – The file path where the plot will be saved. If None, the plot is not saved.

Returns:

The Matplotlib figure object containing the plot.

Return type:

plt.Figure

Raises:
  • AssertionError – If the elements array is not 2-dimensional.

  • AssertionError – If the dimension of the elements is not 2 or 3.