credit.ensemble.temporal
========================

.. py:module:: credit.ensemble.temporal


Classes
-------

.. autoapisummary::

   credit.ensemble.temporal.TemporalNoise


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

.. py:class:: TemporalNoise(noise_generator: torch.Tensor, temporal_correlation: float = 0.9, perturbation_std: Optional[Union[float, torch.Tensor]] = None, hemispheric_rescale: Optional[bool] = False, terrain_file: str = None)

   AR(1) temporal noise generator that leverages spatial noise patterns.

   Implements an autoregressive process of order 1 for temporal correlation:
   δ_t = ρ * δ_{t-1} + ε_t

   where ρ is the temporal correlation coefficient and ε_t is generated using
   a Noise instance (allowing for spatially correlated innovations).

   This creates perturbations that evolve smoothly over forecast steps while
   maintaining realistic spatial patterns at each time step.

   :param noise_generator: Noise generator instance used to create the white noise innovations (ε_t)
   :type noise_generator: Noise
   :param temporal_correlation: Temporal correlation coefficient (0-1). Higher values create smoother
                                temporal evolution, by default 0.9
   :type temporal_correlation: float, optional
   :param perturbation_std: Noise standard deviation scaling. Can be either:
                            - float: uniform scaling applied to all channels
                            - torch.Tensor: per-channel scaling with shape matching channel dimension
                            If provided, overrides the amplitude from the noise_generator, by default None
   :type perturbation_std: Union[float, torch.Tensor], optional


   .. py:attribute:: noise_generator


   .. py:attribute:: temporal_correlation
      :value: 0.9



   .. py:attribute:: perturbation_std
      :value: None



   .. py:attribute:: hemispheric_rescale


   .. py:method:: __call__(x: torch.Tensor, previous_perturbation: Optional[torch.Tensor] = None, forecast_step: int = 1) -> tuple[torch.Tensor, torch.Tensor]

      Apply temporally correlated perturbation for sequential forecasting.

      :param x: Input state tensor to perturb
      :type x: torch.Tensor
      :param previous_perturbation: Perturbation from the previous forecast step, by default None.
                                    If None or forecast_step=1, generates new initial perturbation.
      :type previous_perturbation: torch.Tensor, optional
      :param forecast_step: Current forecast step (1-indexed), by default 1
      :type forecast_step: int, optional

      :returns:

                - Perturbed state tensor (x + perturbation)
                - Current perturbation tensor (for use in next step)
      :rtype: tuple[torch.Tensor, torch.Tensor]