EllipsoidalSet

(class from pyomo.contrib.pyros.uncertainty_sets)

class pyomo.contrib.pyros.uncertainty_sets.EllipsoidalSet(center, shape_matrix, scale=1, gaussian_conf_lvl=None)

Bases: UncertaintySet

A general ellipsoidal region.

Parameters:

• center ((N,) array-like) – Center of the ellipsoid.

• shape_matrix ((N, N) array-like) – A symmetric positive definite matrix characterizing the shape and orientation of the ellipsoid.

• scale (numeric type, optional) – Square of the factor by which to scale the semi-axes of the ellipsoid (i.e. the eigenvectors of the shape matrix). The default is 1.

• gaussian_conf_lvl (numeric type, optional) – (Fractional) confidence level of the multivariate normal distribution with mean center and covariance matrix shape_matrix. Exactly one of scale and gaussian_conf_lvl should be None; otherwise, an exception is raised.

See also

AxisAlignedEllipsoidalSet

An axis-aligned ellipsoidal region.

Notes

The \(n\)-dimensional ellipsoidal set is defined by

\[\left\{ q \in \mathbb{R}^n\,| \,(q - q^0)^\intercal \Sigma^{-1}(q - q^0) \leq s \right\}\]

in which \(q^0 \in \mathbb{R}^n\) refers to center, the quantity \(\Sigma \in \mathbb{R}^{n \times n}\) refers to shape_matrix, and \(s \geq 0\) refers to scale.

The quantity \(s\) is related to the Gaussian confidence level (gaussian_conf_lvl) \(p \in [0, 1)\) by \(s = \chi_{n}^2(p)\), in which \(\chi_{n}^2(\cdot)\) is the quantile function of the chi-squared distribution with \(n\) degrees of freedom.

Examples

A 3D origin-centered unit ball:

>>> from pyomo.contrib.pyros import EllipsoidalSet
>>> import numpy as np
>>> ball = EllipsoidalSet(
...     center=[0, 0, 0],
...     shape_matrix=np.eye(3),
...     scale=1,
... )
>>> ball.center
array([0, 0, 0])
>>> ball.shape_matrix
array([[1., 0., 0.],
       [0., 1., 0.],
       [0., 0., 1.]])
>>> ball.scale
1

A 2D ellipsoidal region with custom rotation and scaling:

>>> rotated_ellipsoid = EllipsoidalSet(
...     center=[1, 1],
...     shape_matrix=[[4, 2], [2, 4]],
...     scale=0.5,
... )
>>> rotated_ellipsoid.center
array([1, 1])
>>> rotated_ellipsoid.shape_matrix
array([[4, 2],
       [2, 4]])
>>> rotated_ellipsoid.scale
0.5

A 4D 95% confidence ellipsoidal region:

>>> conf_ellipsoid = EllipsoidalSet(
...     center=np.zeros(4),
...     shape_matrix=np.diag(range(1, 5)),
...     scale=None,
...     gaussian_conf_lvl=0.95,
... )
>>> conf_ellipsoid.center
array([0., 0., 0., 0.])
>>> conf_ellipsoid.shape_matrix
array([[1, 0, 0, 0],
       [0, 2, 0, 0],
       [0, 0, 3, 0],
       [0, 0, 0, 4]])
>>> conf_ellipsoid.scale

...9.4877...
>>> conf_ellipsoid.gaussian_conf_lvl
0.95

__init__(center, shape_matrix, scale=1, gaussian_conf_lvl=None)

Initialize self (see class docstring).

Methods

__init__(center, shape_matrix[, scale, ...])	Initialize self (see class docstring).
compute_auxiliary_uncertain_param_vals(point)	Compute auxiliary uncertain parameter values for a given point.
is_bounded(config)	Determine whether the uncertainty set is bounded.
is_nonempty(config)	Determine whether the uncertainty set is nonempty.
point_in_set(point)	Determine whether a given point lies in the uncertainty set.
set_as_constraint([uncertain_params, block])	Construct a block of Pyomo constraint(s) defining the uncertainty set on variables representing the uncertain parameters, for use in a two-stage robust optimization problem or subproblem (such as a PyROS separation subproblem).
validate(config)	Check EllipsoidalSet validity.

Attributes

center	Center of the ellipsoid.
dim	Dimension N of the ellipsoidal set.
gaussian_conf_lvl	(Fractional) confidence level of the multivariate Gaussian distribution with mean self.origin and covariance self.shape_matrix for ellipsoidal region with square magnification factor self.scale.
geometry	Geometry of the ellipsoidal set.
parameter_bounds	Bounds in each dimension of the ellipsoidal set.
scale	Square of the factor by which to scale the semi-axes of the ellipsoid (i.e. the eigenvectors of the shape matrix).
shape_matrix	A positive definite matrix characterizing the shape and orientation of the ellipsoid.
type	Brief description of the type of the uncertainty set.

Member Documentation

compute_auxiliary_uncertain_param_vals(point, solver=None)

Compute auxiliary uncertain parameter values for a given point. The point need not be in the uncertainty set.

Parameters:

• point ((N,) array-like) – Point of interest.

• solver (Pyomo solver, optional) – If needed, a Pyomo solver with which to compute the auxiliary values.

Returns:

aux_space_pt – Computed auxiliary uncertain parameter values.

Return type:

numpy.ndarray

is_bounded(config)

Determine whether the uncertainty set is bounded.

Parameters:

config (ConfigDict) – PyROS solver configuration.

Returns:

True if the uncertainty set is certified to be bounded, and False otherwise.

Return type:

bool

Notes

This check is carried out by checking if all parameter bounds are finite.

If no parameter bounds are available, the following processes are run to perform the check: (i) feasibility-based bounds tightening is used to obtain parameter bounds, and if not all bound are found, (ii) solving a sequence of maximization and minimization problems (in which the objective for each problem is the value of a single uncertain parameter). If any of the optimization models cannot be solved successfully to optimality, then False is returned.

This method is invoked by self.validate().

is_nonempty(config)

Determine whether the uncertainty set is nonempty.

Parameters:

config (ConfigDict) – PyROS solver configuration.

Returns:

True if the uncertainty set is nonempty, and False otherwise.

Return type:

bool

point_in_set(point)

Determine whether a given point lies in the uncertainty set.

Parameters:

point ((N,) array-like) – Point (parameter value) of interest.

Returns:

True if the point lies in the uncertainty set, False otherwise.

Return type:

bool

Notes

This method is invoked at the outset of a PyROS solver call to determine whether a user-specified nominal parameter realization lies in the uncertainty set.

set_as_constraint(uncertain_params=None, block=None)

Construct a block of Pyomo constraint(s) defining the uncertainty set on variables representing the uncertain parameters, for use in a two-stage robust optimization problem or subproblem (such as a PyROS separation subproblem).

Parameters:

• uncertain_params (None, Var, or list of Var, optional) – Variable objects representing the (main) uncertain parameters. If None is passed, then new variable objects are constructed.

• block (BlockData or None, optional) – Block on which to declare the constraints and any new variable objects. If None is passed, then a new block is constructed.

Returns:

A collection of the components added or addressed.

Return type:

UncertaintyQuantification

validate(config)

Check EllipsoidalSet validity.

Raises:

ValueError – If any uncertainty set attributes are not valid. (e.g., numeric values are infinite, self.shape_matrix is not positive semidefinite, or self.scale is negative).

property center

Center of the ellipsoid.

Type:

(N,) numpy.ndarray

property dim

Dimension N of the ellipsoidal set.

Type:

int

property gaussian_conf_lvl

(Fractional) confidence level of the multivariate Gaussian distribution with mean self.origin and covariance self.shape_matrix for ellipsoidal region with square magnification factor self.scale.

Type:

numeric type

property geometry

Geometry of the ellipsoidal set.

Type:

Geometry

property parameter_bounds

Bounds in each dimension of the ellipsoidal set.

Returns:

List, length N, of coordinate value (lower, upper) bound pairs.

Return type:

list[tuple[numbers.Real, numbers.Real]]

property scale

Square of the factor by which to scale the semi-axes of the ellipsoid (i.e. the eigenvectors of the shape matrix).

Type:

numeric type

property shape_matrix

A positive definite matrix characterizing the shape and orientation of the ellipsoid.

Type:

(N, N) numpy.ndarray

property type

Brief description of the type of the uncertainty set.

Type:

str