Bases: UncertaintySet
A cardinality-constrained (i.e., “gamma”) set.
- Parameters:
origin ((N,) array_like) – Origin of the set (e.g., nominal uncertain parameter values).
positive_deviation ((N,) array_like) – Upper bounds for absolute values of the positive coordinate
deviations from the origin.
gamma (numeric type) – Upper bound for the number of coordinates that can
simultaneously realize their maximal deviations from
the origin. Must be a numerical value ranging from 0
to the set dimension N.
negative_deviation ((N,) array_like, optional) – Upper bounds for absolute values of the negative coordinate
deviations from the origin.
If None is passed, then this argument is set to
an (N,) shaped array of zeros.
Notes
The \(n\)-dimensional cardinality-constrained set is defined by
\[\begin{split}\left\{ q \in \mathbb{R}^n\,\middle|
\,\exists\, \xi^+, \xi^- \in [0, 1]^n \,:\,
\left[
\begin{array}{l}
q = q^0 + \hat{q}^+ \circ \xi^+
- \hat{q}^- \circ \xi^- \\
\displaystyle \sum_{i=1}^n (\xi_i^+ + \xi_i^-)
\leq \Gamma \\
\xi_i^+ = 0 \quad\forall\,i :
\hat{q}_i^+ = 0 \\
\xi_i^- = 0 \quad\forall\,i :
\hat{q}_i^- = 0
\end{array}
\right]
\right\}\end{split}\]
in which
\(q^\text{0} \in \mathbb{R}^n\) refers to origin,
the quantity \(\hat{q}^+ \in \mathbb{R}_{+}^n\)
refers to positive_deviation,
the quantity \(\hat{q}^- \in \mathbb{R}_{+}^n\)
refers to negative_deviation,
and
\(\Gamma \in [0, n]\) refers to gamma.
Note
If \(\hat{q}^+ = \hat{q}^-\),
then this set is mathematically equal to
\[\begin{split}\left\{ q \in \mathbb{R}^n\,\middle|
\,\exists\, \delta \in [-1, 1]^n \,:\,
\left[
\begin{array}{l}
q = q^0 + \hat{q}^+ \circ \delta \\
\displaystyle \sum_{i=1}^n |\delta_i|
\leq \Gamma
\end{array}
\right]
\right\},\end{split}\]
the cardinality-constrained set implicitly defined
in the popular robust optimization work [BS04].
Examples
A 4D cardinality-constrained set:
>>> from pyomo.contrib.pyros import CardinalitySet
>>> gamma_set = CardinalitySet(
... origin=[0, 0, 0, 0],
... positive_deviation=[1.0, 2.0, 1.5, 0.0],
... gamma=1,
... negative_deviation=[0.0, 2.0, 0.0, 5.0],
... )
>>> gamma_set.origin
array([0, 0, 0, 0])
>>> gamma_set.positive_deviation
array([1. , 2. , 1.5, 0. ])
>>> gamma_set.gamma
1
>>> gamma_set.negative_deviation
array([0., 2., 0., 5.])
-
__init__(origin, positive_deviation, gamma, negative_deviation=None)[source]
Initialize self (see class docstring).
Methods
__init__(origin, positive_deviation, gamma)
|
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 cardinality-constrained 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 CardinalitySet validity. |
Attributes
dim
|
Dimension N of the cardinality-constrained set. |
gamma
|
Upper bound for the number of coordinates that can simultaneously realize their maximal deviations from the origin. |
geometry
|
Geometry of the cardinality-constrained set. |
negative_deviation
|
Upper bounds for absolute values of the negative coordinate deviations from the origin. |
origin
|
Origin of the cardinality-constrained set (e.g., nominal parameter values). |
parameter_bounds
|
Bounds in each dimension of the cardinality-constrained set. |
positive_deviation
|
Upper bounds for absolute values of the positive coordinate deviations from the origin. |
type
|
Brief description of the type of the uncertainty set. |
Member Documentation
-
compute_auxiliary_uncertain_param_vals(point, solver=None)[source]
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)[source]
Determine whether a given point lies in the
cardinality-constrained set.
- Parameters:
point ((N,) array-like) – Point (parameter value) of interest.
- Returns:
True if the point lies in the set, False otherwise.
- Return type:
bool
-
set_as_constraint(uncertain_params=None, block=None)[source]
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)[source]
Check CardinalitySet validity.
- Raises:
ValueError – If any uncertainty set attributes are not valid.
(e.g., numeric values are infinite,
self.positive_deviation has negative values,
or self.gamma is out of range).
-
property dim
Dimension N of the cardinality-constrained set.
- Type:
int
-
property gamma
Upper bound for the number of coordinates that
can simultaneously realize their maximal deviations from
the origin. Must be a numerical value ranging from 0
to the set dimension N.
Note that, mathematically, setting gamma to 0 reduces the set
to a singleton containing the point represented by
self.origin, while setting gamma to
the set dimension N makes the set mathematically equivalent
to a box set.
- Type:
numeric type
-
property geometry
Geometry of the cardinality-constrained set.
- Type:
Geometry
-
property negative_deviation
Upper bounds for absolute values of
the negative coordinate deviations from the origin.
- Type:
(N,) numpy.ndarray
-
property origin
Origin of the cardinality-constrained set
(e.g., nominal parameter values).
- Type:
(N,) numpy.ndarray
-
property parameter_bounds
Bounds in each dimension of the cardinality-constrained set.
- Returns:
List, length N, of coordinate value
(lower, upper) bound pairs.
- Return type:
list[tuple[numbers.Real, numbers.Real]]
-
property positive_deviation
Upper bounds for absolute values of
the positive coordinate deviations from the origin.
- Type:
(N,) numpy.ndarray
-
property type
Brief description of the type of the uncertainty set.
- Type:
str