Perturbations¶

def __init__(  # noqa: PLR0913
    self,
    mu: float | np.ndarray,
    sigma: float | np.ndarray | None = None,
    *,
    cov: np.ndarray | None = None,
    d: int | None = None,
    env_mean: np.ndarray | None = None,
    env_cov: np.ndarray | None = None,
    seed: int | None = None,
) -> None:
    """Initialize with Gaussian directional noise and additive noise.

    Args:
        mu (float | np.ndarray): Mean parameter of T. Scalar for shared mean,
            vector otherwise.
        sigma (float | np.ndarray | None): Standard deviation parameter of T.
            Scalar for iid noise, vector for diagonal covariance.
            Mutually exclusive with ``cov``.
        cov (np.ndarray | None): Covariance parameter of T. Can be diagonal
            ``(d,)`` or full covariance ``(d, d)``. Mutually exclusive with
            ``sigma``.
        d (int | None): Optional dimensionality of T when it cannot be
            inferred later.
        env_mean (np.ndarray | None): Mean vector m_ε of the additive noise
            (d,). If None, defaults to zero vector.
        env_cov (np.ndarray | None): Covariance matrix Σ_ε of the additive
            noise (d, d). If None, defaults to zero matrix.
        seed (int | None): Optional seed for the random number generator.
    """
    if (sigma is None) == (cov is None):
        msg = "Exactly one of 'sigma' or 'cov' must be provided."
        raise ValueError(msg)

    mu_arr = np.asarray(mu, dtype=float)
    sigma_arr = np.asarray(sigma, dtype=float) if sigma is not None else None
    cov_arr = np.asarray(cov, dtype=float) if cov is not None else None

    if sigma_arr is not None and np.any(sigma_arr < 0):
        msg = f"Standard deviation sigma cannot be negative. Got {sigma}"
        raise ValueError(msg)
    if cov_arr is not None:
        if cov_arr.ndim not in (1, 2):
            msg = f"cov must be a vector or matrix. Got shape {cov_arr.shape}"
            raise ValueError(msg)
        if cov_arr.ndim == 1 and np.any(cov_arr < 0):
            msg = "Diagonal covariance entries cannot be negative."
            raise ValueError(msg)

    self.mu = float(mu_arr) if mu_arr.ndim == 0 else mu_arr
    self.sigma = None if sigma_arr is None else (float(sigma_arr) if sigma_arr.ndim == 0 else sigma_arr)
    self.cov = cov_arr
    self.d = d
    self.env_mean = np.asarray(env_mean, dtype=float) if env_mean is not None else None
    self.env_cov = np.asarray(env_cov, dtype=float) if env_cov is not None else None
    self.seed = seed
    self._rng = np.random.default_rng(seed)

def __init__(
    self,
    mu: float | np.ndarray,
    delta: float | np.ndarray,
    *,
    d: int | None = None,
    env_mean: np.ndarray | None = None,
    env_cov: np.ndarray | None = None,
    seed: int | None = None,
) -> None:
    """Initialize with scalar noise parameters and additive noise parameters.

    Args:
        mu (float | np.ndarray): Mean of the distribution.
        delta (float | np.ndarray): Half-width of the distribution (radius).
        d (int | None): Optional dimensionality of T when it cannot be
            inferred later.
        env_mean (np.ndarray | None): Mean vector m_ε of the additive noise
            (d,). If None, defaults to zero vector.
        env_cov (np.ndarray | None): Covariance matrix Σ_ε of the additive
            noise (d, d). If None, defaults to zero matrix.
        seed (int | None): Optional seed for the random number generator.
    """
    mu_scalar = isinstance(mu, (int, float))
    delta_scalar = isinstance(delta, (int, float))
    delta_arr = np.asarray(delta, dtype=float)
    if np.any(delta_arr < 0):
        msg = f"Half-width delta cannot be negative. Got {delta}"
        raise ValueError(msg)
    scalar_mu = float(cast("float", mu)) if mu_scalar else None
    scalar_delta = float(cast("float", delta)) if delta_scalar else None
    self.mu = scalar_mu if scalar_mu is not None else np.asarray(mu, dtype=float)
    self.delta = scalar_delta if scalar_delta is not None else delta_arr
    self.d = d
    self.env_mean = np.asarray(env_mean, dtype=float) if env_mean is not None else None
    self.env_cov = np.asarray(env_cov, dtype=float) if env_cov is not None else None
    self.seed = seed
    self._rng = np.random.default_rng(seed)

def __init__(
    self,
    sample_fn: Callable[[int], np.ndarray] | Callable[[int, int], np.ndarray],
    sample_env_fn: Callable[[int, int], np.ndarray] | None = None,
    env_mean: np.ndarray | None = None,
    env_cov: np.ndarray | None = None,
    params: dict[str, Any] | None = None,
) -> None:
    """Initialize with user-provided callables.

    Args:
        sample_fn (Callable): Callable that returns an array of directional
            samples of shape (n, d).
        sample_env_fn (Callable | None): Optional callable
            (n, d) -> (n, d) array for ε samples.
        env_mean (np.ndarray | None): Mean vector m_ε of the additive noise (d,).
        env_cov (np.ndarray | None): Covariance matrix Σ_ε of the
            additive noise (d, d).
        params (dict[str, Any] | None): Optional dict of parameters
            describing the distribution.
    """
    self._sample_fn = sample_fn
    self._sample_env_fn = sample_env_fn
    self.env_mean = np.asarray(env_mean, dtype=float) if env_mean is not None else None
    self.env_cov = np.asarray(env_cov, dtype=float) if env_cov is not None else None
    self._params = params or {}