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.