vopy.ordering_cone

class vopy.ordering_cone.OrderingCone(W: numpy.ndarray)

Represents a polyhedral ordering cone in the form \(C := \{ x | \mathbf{W}x \geq 0 \}\), where \(\mathbf{W}\) is a matrix defining the cone’s boundaries. The ordering cone is used to check if points lie within the cone by testing if they satisfy the inequality.

Parameters:

W (np.ndarray) – A 2D array (matrix) that defines the ordering cone. The shape of W should be number of constraints by number of dimensions.

Attr W:

The matrix defining the ordering cone.

Attr dim:

The number of dimensions of the ordering cone.

Attr alpha:

The alpha vector of the ordering cone.

Examples:
>>> import numpy as np
>>> W = np.array([[1, 0], [0, 1]])
>>> cone = OrderingCone(W)
>>> x = np.array([0.5, 0.5])
>>> cone.is_inside(x)
array([ True])
>>> x_outside = np.array([-1, 0.5])
>>> cone.is_inside(x_outside)
array([False])
is_inside(x: numpy.ndarray) numpy.ndarray

Determines if a point is or an array of points are inside the ordering cone.

Parameters:

x (np.ndarray) – A point or an array of points to test. The points should have the same dimension as the cone’s \(\mathbf{W}\) matrix.

Returns:

A boolean array where True indicates that the point is within the cone.

Return type:

np.ndarray

plot(path: str | PathLike | None = None, **kwargs) matplotlib.pyplot.Figure

Generate a plot of the ordering cone if the cone is 2D or 3D.

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

  • kwargs (dict) – Additional keyword arguments to pass to the plotting function.

Returns:

The matplotlib figure containing the plot.

Return type:

plt.Figure

Raises:

ValueError – If the dimension of the ordering cone is not 2 or 3.

class vopy.ordering_cone.ConeTheta2D(cone_degree: float)

Represents a 2D ordering cone defined by a specified degree.

This class is a specific type of OrderingCone and it constructs the W matrix based on the given cone degree. The ordering cone corresponds to a symmetric cone with its height overlapping \(y=x\). This class also defines a \(\beta\) attribute that is given in [Ararat2023] as ordering complexity of the ordering cone.

Parameters:

cone_degree (float) – The degree of the cone in degrees. The cone is symmetric about the line \(y=x\) and the degree specifies the angle of the cone.

Attr cone_degree:

The degree of the cone.

Attr beta:

The \(\beta\) parameter of the cone.

Example:
>>> cone = ConeTheta2D(45)
>>> x = np.array([1, 1])
>>> cone.is_inside(x)
array([ True])
>>> cone.beta
1.4142135623730951
References:
[Ararat2023]

Ararat, Tekin. Vector Optimization with Stochastic Bandit Feedback. Artificial Intelligence and Statistics (AISTATS), 2023.

property beta: float

Calculate the ordering complexity \(\beta\) based on the cone’s angle in degrees.

Returns:

The ordering complexity of the cone.

Return type:

float

plot(path: str | PathLike | None = None)

Plots the 2D ordering cone based on the specified cone degree.

Parameters:

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

Returns:

The matplotlib figure containing the plot.

Return type:

plt.Figure