BudgetSet

(class from pyomo.contrib.pyros.uncertainty_sets)

class pyomo.contrib.pyros.uncertainty_sets.BudgetSet(budget_membership_mat, rhs_vec, origin=None)

Bases: UncertaintySet

A budget set.

Parameters:

• budget_membership_mat ((L, N) array_like) – Incidence matrix of the budget constraints. Each row corresponds to a single budget constraint, and defines which uncertain parameters (which dimensions) participate in that row’s constraint. All entries should be of value 0 or 1.

• rhs_vec ((L,) array_like) – Budget limits (upper bounds) with respect to the origin of the set.

• origin ((N,) array_like or None, optional) – Origin of the budget set. If None is provided, then the origin is set to the zero vector.

Notes

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

\[\begin{split}\left\{ q \in \mathbb{R}^n\,\middle| \begin{pmatrix} B \\ -I \end{pmatrix} q \leq \begin{pmatrix} b + Bq^0 \\ -q^0 \end{pmatrix} \right\}\end{split}\]

in which \(B \in \{0, 1\}^{\ell \times n}\) refers to budget_membership_mat, the quantity \(I\) denotes the \(n \times n\) identity matrix, the quantity \(b \in \mathbb{R}_{+}^\ell\) refers to rhs_vec, and \(q^0 \in \mathbb{R}^n\) refers to origin.

Examples

3D budget set with one budget constraint and no origin chosen (hence origin defaults to 3D zero vector):

>>> from pyomo.contrib.pyros import BudgetSet
>>> budget_set = BudgetSet(
...     budget_membership_mat=[[1, 1, 1]],
...     rhs_vec=[2],
... )
>>> budget_set.budget_membership_mat
array([[1, 1, 1]])
>>> budget_set.budget_rhs_vec
array([2])
>>> budget_set.origin
array([0., 0., 0.])

3D budget set with two budget constraints and custom origin:

>>> budget_custom = BudgetSet(
...     budget_membership_mat=[[1, 0, 1], [0, 1, 0]],
...     rhs_vec=[1, 1],
...     origin=[2, 2, 2],
... )
>>> budget_custom.budget_membership_mat
array([[1, 0, 1],
       [0, 1, 0]])
>>> budget_custom.budget_rhs_vec
array([1, 1])
>>> budget_custom.origin
array([2, 2, 2])

__init__(budget_membership_mat, rhs_vec, origin=None)

Initialize self (see class docstring).

Methods

__init__(budget_membership_mat, rhs_vec[, ...])	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(**kwargs)	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 BudgetSet validity.

Attributes

budget_membership_mat	Incidence matrix of the budget constraints.
budget_rhs_vec	Budget limits (upper bounds) with respect to the origin.
coefficients_mat	Coefficient matrix of all polyhedral constraints defining the budget set.
dim	Dimension N of the budget set.
geometry	Geometry of the budget set.
origin	Origin of the budget set.
parameter_bounds	Bounds in each dimension of the budget set.
rhs_vec	Right-hand side vector for polyhedral constraints defining the budget set.
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(**kwargs)

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 BudgetSet validity.

Raises:

ValueError – If any uncertainty set attributes are not valid. (e.g., numeric values are infinite, self.budget_membership_mat contains a full column or row of zeros, or self.budget_rhs_vec has negative values).

property budget_membership_mat

Incidence matrix of the budget constraints. Each row corresponds to a single budget constraint and defines which uncertain parameters participate in that row’s constraint. All entries should be of value 0 or 1.

Type:

(L, N) numpy.ndarray

property budget_rhs_vec

Budget limits (upper bounds) with respect to the origin.

Type:

(L,) numpy.ndarray

property coefficients_mat

Coefficient matrix of all polyhedral constraints defining the budget set. Composed from the incidence matrix used for defining the budget constraints and a coefficient matrix for individual uncertain parameter nonnegativity constraints.

This attribute cannot be set. The budget constraint incidence matrix may be altered through the budget_membership_mat attribute.

Type:

(L + N, N) numpy.ndarray

property dim

Dimension N of the budget set.

Type:

int

property geometry

Geometry of the budget set.

Type:

Geometry

property origin

Origin of the budget set.

Type:

(N,) numpy.ndarray

property parameter_bounds

Bounds in each dimension of the budget set.

Returns:

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

Return type:

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

property rhs_vec

Right-hand side vector for polyhedral constraints defining the budget set. This also includes entries for nonnegativity constraints on the uncertain parameters.

This attribute cannot be set, and is automatically determined given other attributes.

Type:

(L + N,) numpy.ndarray

property type

Brief description of the type of the uncertainty set.

Type:

str