Bases: UncertaintySet
A cardinality-constrained (i.e., “gamma”) set.
- Parameters:
origin ((N,) array_like) – Origin of the set (e.g., nominal uncertain parameter values).
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.
positive_deviation ((N,) array_like) – Maximal absolute deviation from the origin in the
positive coordinate direction.
negative_deviation ((N,) array_like, optional) – Maximal absolute deviation from the origin in the
negative coordinate direction.
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 by Bertsimas and Sim
[BS04].
Examples
A 4D cardinality-constrained set:
>>> from pyomo.contrib.pyros import CardinalitySet
>>> gamma_set = CardinalitySet(
... origin=[0, 0, 0, 0],
... gamma=1,
... positive_deviation=[1.0, 2.0, 1.5, 0.0],
... negative_deviation=[0.0, 2.0, 0.0, 5.0],
... )
>>> gamma_set.origin
array([0, 0, 0, 0])
>>> gamma_set.gamma
1
>>> gamma_set.positive_deviation
array([1. , 2. , 1.5, 0. ])
>>> gamma_set.negative_deviation
array([0., 2., 0., 5.])
-
__init__(origin, gamma, positive_deviation, negative_deviation=None)[source]
Initialize self (see class docstring).
Methods
__init__(origin, gamma, positive_deviation)
|
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
|
Maximal absolute deviation from the origin in the negative coordinate direction. |
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
|
Maximal absolute deviation from the origin in the positive coordinate direction. |
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
Maximal absolute deviation from
the origin in the negative coordinate direction.
- 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
Maximal absolute deviation from
the origin in the positive coordinate direction.
- Type:
(N,) numpy.ndarray
-
property type
Brief description of the type of the uncertainty set.
- Type:
str