credit.ensemble.color
=====================

.. py:module:: credit.ensemble.color


Classes
-------

.. autoapisummary::

   credit.ensemble.color.ColorNoise


Functions
---------

.. autoapisummary::

   credit.ensemble.color.apply_noise_perturbation_step


Module Contents
---------------

.. py:class:: ColorNoise(amplitude: float = 0.05, reddening: int = 2)

   2D spatially correlated noise generator for lat/lon grids.

   Generates colored noise with controllable spatial correlation using power-law
   scaling in the frequency domain. The noise characteristics are determined by
   the reddening parameter:

   * reddening = 0: White noise (uncorrelated, flat power spectrum)
   * reddening = 1: Pink noise (1/f power spectrum)
   * reddening = 2: Brown/Brownian/Red noise (1/f² power spectrum)
   * reddening > 2: Higher-order red noise (1/f^n power spectrum)

   Higher reddening values produce smoother, more spatially coherent patterns,
   which are often more realistic for geophysical applications.

   :param amplitude: Scaling factor for the generated noise.
                     Defaults to 0.05.
   :type amplitude: float, optional
   :param reddening: Power-law exponent controlling spatial
                     correlation. Higher values create smoother, more correlated noise
                     patterns. Defaults to 2 (Brown noise).
   :type reddening: int, optional


   .. py:attribute:: amplitude
      :value: 0.05



   .. py:attribute:: reddening
      :value: 2



   .. py:method:: __call__(x: torch.Tensor) -> torch.Tensor

      Generate spatially correlated noise matching input tensor dimensions.

      :param x: Reference tensor whose shape determines the output noise
                dimensions. The last two dimensions are treated as the spatial lat/lon
                grid.
      :type x: torch.Tensor

      :returns: Spatially correlated noise tensor with the same shape as the
                input, scaled by the amplitude parameter.
      :rtype: torch.Tensor



   .. py:method:: _create_correlated_noise(shape: tuple[int, Ellipsis], device: torch.device) -> torch.Tensor

      Generate spatially correlated noise using frequency domain filtering.

      Creates colored noise by:
      1. Starting with white noise (uniform power spectrum).
      2. Transforming to frequency domain.
      3. Applying power-law scaling (1/f^reddening).
      4. Transforming back to spatial domain.

      :param shape: Shape of the output noise tensor.
      :type shape: tuple[int, ...]
      :param device: Device to generate tensors on.
      :type device: torch.device

      :returns: Spatially correlated noise with unit variance (before
                amplitude scaling).
      :rtype: torch.Tensor



   .. py:method:: __repr__() -> str


.. py:function:: apply_noise_perturbation_step(x: torch.Tensor, delta_prev: Optional[torch.Tensor], forecast_step: int, rho: float = 0.9, perturbation_std: Union[float, torch.Tensor] = 0.05) -> Tuple[torch.Tensor, torch.Tensor]

   Red noise perturbation in physical units, with per-channel control.