Add Gaussian confidence level attribute to PyROS EllipsoidalSet

[shermanjasonaf]

Summary/Motivation:

Motivated by recent user feedback, this PR adds a new PyROS EllipsoidalSet attribute and constructor argument gaussian_conf_lvl that specifies, as an alternative to the the squared semi-axis scaling factor attribute and constructor argument scale, the level of the (ellipsoidal) confidence region of the multivariate Gaussian distribution with mean center and covariance shape_matrix. Mathematically, the PyROS ellipsoidal set with center $q^0 \in \mathbb{R}^n$, positive definite shape matrix $P \in \mathbb{S}_{++}^n$, and squared semi-axis scale factor $s \geq 0$ is defined by

$$ \{ q \in \mathbb{R}^n \mid (q - q^0)^\top P^{-1} (q - q^0) \leq s \}. $$

For confidence level $p \in [0, 1)$, the $100p$% multivariate Gaussian confidence region is obtained by setting $s = \chi_{n,p}^2$, where $\chi_{n,\cdot}^2$ is the (invertible) lower-tail quantile function of the chi-squared distribution with $n$ degrees of freedom. Thus, we ensure that setting gaussian_conf_lvl triggers, through the invertible mapping between the squared scaling factor $s$ and confidence level $p$, an update of scale, and vice-versa.

Changes proposed in this PR:

• Add new settable attribute and constructor argument gaussian_conf_lvl to PyROS EllipsoidalSet.

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

1. I agree my contributions are submitted under the BSD license.
2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

[jsiirola]

Two ignorable minor comments, but otherwise looks good.

[jsiirola]

You don't need to change this, but would it be more clear to have this be:

if (scale is None) ^ (gaussian_conf_lvl is None):
    self.scale = scale
    self.gaussian_conf_lvl = gaussian_conf_lvl
else:
    raise ValueError(
        "Exactly one of `scale` and `gaussian_conf_lvl` should be "
        f"None (got {scale=}, {gaussian_conf_lvl=})"
    )

And then have the setters just "do nothing" if the incoming value is None?

[shermanjasonaf]

I agree this would clarify the code, but are we sure we want each of those setters to leave the state unchanged if None is passed (without at least noting this behavior in the property docstrings)? Currently, each of the other EllipsoidalSet attribute setters (and more broadly, attribute setters for other concrete UncertaintySet subclasses) raises an exception if None is passed and not an acceptable value/type/shape for the attribute. I am wondering whether this new behavior for scale and gaussian_conf_lvl might not be clear to users attempting to set either attribute to None post construction.

[mrmundt]

Suggestion: I won't have this hold up the PR, but it might be worth making this message into its own class-level var so you don't have to potentially change the error message in a bunch of places if you decide to modify the language or the error message someday.

[mrmundt]

I am fine with this PR as-is, but I did have one suggestion for better maintainability within the tests.