<a id="skfolio-uncertainty-set-uncertaintyset"></a>

# skfolio.uncertainty_set.UncertaintySet

<a id="skfolio.uncertainty_set.UncertaintySet"></a>

### *class* skfolio.uncertainty_set.UncertaintySet(radius, geometry, norm)

Norm-ball uncertainty set.

A norm-ball uncertainty set represents deviations of a parameter vector $z$
from an estimate $\hat{z}$ as

$$
z - \hat{z} = L u,
\quad
\lVert u \rVert_p \le \kappa.
$$

Equivalently, the uncertainty set is

$$
\mathcal{U}
=
\left\{
    \hat{z} + L u :
    \lVert u \rVert_p \le \kappa
\right\}.
$$

All common uncertainty sets, including ellipsoidal, box and diamond sets, can be
represented by choosing the radius $\kappa$, the norm $p$ and the
linear map $L$.

The radius $\kappa$ controls the size of the normalized uncertainty ball.
The norm $p$ selects its canonical shape:

* $p = 2$: Euclidean ball
* $p = \infty$: Box
* $p = 1$: Diamond / Cross-polytope

The `geometry` parameter stores the linear geometry map $L$. It maps the
normalized ball into parameter space by scaling and mixing uncertainty directions to
form deviations of $z$ from $\hat{z}$. The estimator precomputes this
map so the optimizer can work directly with $L$, which may be low-rank
$(n \times r)$ with $r \ll n$.

For a linear exposure vector $e$, the worst-case deviation over
$\mathcal{U}$ is

$$
\sup_{z \in \mathcal{U}}
e^\top(z - \hat{z})
=
\kappa \,
\lVert L^\top e \rVert_q,
$$

where $q$ is the dual norm of $p$.

Downstream optimizers use this support-function as the uncertainty penalty.
For expected-return uncertainty, $z$ is $\mu$ and $e$ is the
portfolio weight vector. For covariance uncertainty, $z$ is
$\operatorname{vec}(\Sigma)$ (the vector obtained by stacking the columns of
$\Sigma$) and $e$ has the same vectorized shape.

Standard choices are:

* **Ellipsoidal set:** Use `norm=2`. For a full-rank shape matrix $S$, set
  `geometry` to a square-root factor $L$ satisfying $S = L L^\top$. This
  gives $(z - \hat{z})^\top S^{-1} (z - \hat{z}) \le \kappa^2$. For a low-rank
  representation $S = G \Lambda G^\top$, set `geometry` to $G \Lambda^{1/2}$.
* **Box set:** Use `norm=np.inf`. With axis widths $\delta_i$, set `geometry`
  to $\operatorname{diag}(\delta)$. This gives
  $|z_i - \hat{z}_i| \le \kappa \delta_i$ for each coordinate and the dual
  norm is $1$.
* **Diamond set:** Use `norm=1`. With axis scales $\delta_i$, set `geometry`
  to $\operatorname{diag}(\delta)$. This gives
  $\sum_i |z_i - \hat{z}_i| / \delta_i \le \kappa$ and the dual norm is
  $\infty$.

* **Parameters:**
  **radius** *float*
  : Radius $\kappa$ of the normalized uncertainty ball
    $\lVert u \rVert_p \le \kappa$.

  **geometry** *ndarray of shape (n_parameters, n_uncertainties)*
  : Linear geometry map $L$ mapping normalized uncertainty coordinates into
    deviations from $\hat{z}$:
    $$
    z - \hat{z} = L u.
    $$
    <br/>
    For ellipsoidal uncertainty with shape matrix $S$, `geometry` is a
    square-root factor $L$ satisfying $S = L L^\top$.
    <br/>
    For axis-aligned box or diamond uncertainty with widths `delta`, `geometry` is
    typically $\operatorname{diag}(\delta)$.

  **norm** *float or int, default=2*
  : Norm $p$ defining the normalized uncertainty ball. Must be greater than or
    equal to 1. Common choices are `2` for ellipsoidal uncertainty, `np.inf` for box
    uncertainty, and `1` for diamond uncertainty.
* **Attributes:**
  [`dual_norm`](#skfolio.uncertainty_set.UncertaintySet.dual_norm) *float*
  : Dual norm associated with `norm`.

<a id="skfolio.uncertainty_set.UncertaintySet.dual_norm"></a>

#### *property* dual_norm

Dual norm associated with `norm`.