vopy.order

class vopy.order.Order

Abstract base class for defining an ordering relation between points in a space. Any deriving class must implement the dominates() that induces the preorder.

class vopy.order.PolyhedralConeOrder(ordering_cone: OrderingCone)

Base class for defining an ordering relation using a specified polyhedral ordering cone.

Parameters:

ordering_cone (OrderingCone) – An instance of OrderingCone that defines the ordering relation.

dominates(a: numpy.ndarray, b: numpy.ndarray) → bool

Determines if point a dominates point b according to the ordering cone.

Parameters:

• a (np.ndarray) – The vector representing the point to check for dominance.

• b (np.ndarray) – The vector representing the point to check if dominated.

Returns:

True if a dominates b according to the order; otherwise, False.

Return type:

bool

get_pareto_set(elements: numpy.ndarray) → numpy.ndarray

Computes the Pareto set from a set of elements, retaining only non-dominated points. See: https://stackoverflow.com/a/40239615

Parameters:

elements (np.ndarray) – An array of shape (N, dim), where N is the number of elements and dim is the dimension of the elements and the ordering cone.

Returns:

Indices of the elements that belong to the Pareto set.

Return type:

np.ndarray

Raises:

ValueError – If elements is not a 2D array.

get_pareto_set_naive(elements: numpy.ndarray) → numpy.ndarray

Computes the Pareto set using a naive method by iterating over each element and checking if it is dominated by any other.

Parameters:

elements (np.ndarray) – An array of shape (N, dim), where N is the number of elements and dim is the dimension of the elements and the ordering cone.

Returns:

Indices of the elements that belong to the Pareto set.

Return type:

np.ndarray

Raises:

ValueError – If elements is not a 2D array.

plot_pareto_set(elements: numpy.ndarray, path: str | PathLike | None = None) → matplotlib.pyplot.Figure

Plots the Pareto front of the provided elements if the dimension is 2D or 3D.

Parameters:

• elements (np.ndarray) – An array of shape (N, dim), where N is the number of elements and dim is the dimension of the elements and the ordering cone.

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

Returns:

The matplotlib figure containing the plot.

Return type:

plt.Figure

Raises:

ValueError – If elements is not a 2D array or has a dimension other than 2 or 3.

Useful Orders

class vopy.order.ComponentwiseOrder(dim: int)

Component-wise ordering class that defines an ordering relation where each dimension is considered independently. Vector optimization with this order corresponds to the multi-objective optimization.

Parameters:

dim (int) – The dimension of the space in which the ordering relation is defined.

class vopy.order.ConeTheta2DOrder(cone_degree)

Defines an ordering relation in 2D using a cone with a specified opening angle. The ordering cone is an instance of vopy.ordering_cone.ConeTheta2D.

Parameters:

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

class vopy.order.ConeOrder3D(cone_type: str)

Defines a 3D ordering relation using a specified cone type. The class supports three predefined cone types—‘acute’, ‘right’, and ‘obtuse’—each with its unique constraint matrix, as used in [Karagozlu2024].

Parameters:

cone_type (str) – The type of cone to use for ordering. Must be one of ‘acute’, ‘right’, or ‘obtuse’.

Raises:

ValueError – If cone_type is not one of the allowed values.

References:

[Karagozlu2024]

Karagözlü, Yıldırım, Ararat, Tekin. Learning the Pareto Set Under Incomplete Preferences: Pure Exploration in Vector Bandits. Artificial Intelligence and Statistics (AISTATS), 2024.

class vopy.order.ConeOrder3DIceCream(cone_degree: float, num_halfspace: int)

Defines a 3D ordering relation approximating the shape of an ice cream cone with opening defined by cone_angle. The ordering cone is constructed with equally rotated half-spaces based on the specified number of half-spaces.

Parameters:

• cone_degree (float) – The opening angle of the cone in degrees.

• num_halfspace (int) – The number of half-spaces used to approximate the cone.

compute_ice_cream_cone(K: int, theta: float) → numpy.ndarray

Computes the constraint matrix W for the ice cream cone approximation. The cone is constructed by rotating half-spaces around a central axis.

Parameters:

• K (int) – The number of half-spaces used to approximate the cone.

• theta (float) – The opening angle of the cone in degrees.

Returns:

A 2D array representing the normal vectors for each half-space, i.e., a cone matrix \(\mathbf{W}\) that approximates the ice cream cone.

Return type:

np.ndarray