credit.ensemble.spherical
=========================

.. py:module:: credit.ensemble.spherical


Classes
-------

.. autoapisummary::

   credit.ensemble.spherical.SphericalNoise
   credit.ensemble.spherical.SphericalRandomField


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

.. py:class:: SphericalNoise(amplitude: float = 0.05, smoothness: float = 2.0, length_scale: float = 3.0, variance_scale: Union[float, None] = None, padding_conf: dict = None)

   Spherical harmonic-based noise generator with Matérn covariance for lat/lon grids.

   Generates spatially correlated noise on the sphere using spherical harmonics and a
   Matérn covariance structure. This method produces realistic geophysical noise
   patterns that respect the spherical geometry of Earth.

   The generated noise has Matérn covariance:

       C = σ² (-Δ + τ²I)^(-α)

   where:
   * Δ is the spherical Laplacian operator.
   * I is the identity operator.
   * σ, τ, α are scalar parameters controlling the covariance structure.

   .. warning::

      For grids that don't naturally fit spherical harmonic constraints (N:2N or (N+1):2N),
      this method generates noise at a larger valid grid size and symmetrically crops to
      the target dimensions. This preserves most correlation properties but may introduce
      minor boundary effects.

   :param amplitude: Overall scaling factor for the generated noise.
                     Defaults to 0.05.
   :type amplitude: float, optional
   :param smoothness: Regularity/smoothness parameter (α). Higher values
                      produce smoother fields. Must be > 1.0 for well-defined covariance. Defaults to 2.0.
   :type smoothness: float, optional
   :param length_scale: Characteristic length scale parameter (τ). Higher
                        values include more spatial scales in the noise. Defaults to 3.0.
   :type length_scale: float, optional
   :param variance_scale: Variance scaling parameter (σ). If None,
                          computed as τ^(0.5*(2*α - 2)). Defaults to None.
   :type variance_scale: float | None, optional


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



   .. py:attribute:: smoothness
      :value: 2.0



   .. py:attribute:: length_scale
      :value: 3.0



   .. py:attribute:: variance_scale
      :value: None



   .. py:attribute:: use_padding


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

      Generate spherical noise matching input tensor dimensions.

      :param x: Reference tensor whose shape determines the output noise
                dimensions. The last two dimensions must correspond to a lat/lon grid.
      :type x: torch.Tensor

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

      :raises ValueError: If the lat/lon aspect ratio is not in N:2N or (N+1):2N format.



.. py:class:: SphericalRandomField(latitude_modes: int, smoothness: float = 2.0, length_scale: float = 3.0, variance_scale: Union[float, None] = None, sphere_radius: float = 1.0, grid_type: str = 'equiangular', dtype: torch.dtype = torch.float32, device: torch.device = 'cuda:0')

   Bases: :py:obj:`torch.nn.Module`


   Gaussian Random Field generator on the sphere with Matérn covariance.

   Implements a mean-zero Gaussian Random Field on the sphere using spherical
   harmonics with Matérn covariance structure:

       C = σ² (-Δ + τ²I)^(-α)

   where:
   - Δ is the spherical Laplacian operator.
   - I is the identity operator.
   - σ² controls overall variance (variance_scale²).
   - τ² controls characteristic length scale (length_scale²).
   - α controls smoothness/regularity (smoothness).

   The covariance is trace-class (well-defined) if and only if α > 1.

   :param latitude_modes: Number of spherical harmonic modes in the latitude
                          direction. Longitude modes are automatically set to 2 * latitude_modes.
   :type latitude_modes: int
   :param smoothness: Regularity parameter (α). Higher values produce
                      smoother fields. Must be > 1.0. Defaults to 2.0.
   :type smoothness: float, optional
   :param length_scale: Characteristic length scale parameter (τ).
                        Defaults to 3.0.
   :type length_scale: float, optional
   :param variance_scale: Variance parameter (σ). If
                          None, computed automatically as τ^(0.5*(2*α - 2)). Defaults to None.
   :type variance_scale: Union[float, None], optional
   :param sphere_radius: Radius of the sphere for scaling. Defaults
                         to 1.0.
   :type sphere_radius: float, optional
   :param grid_type: Grid type for spherical harmonics. Options are
                     "equiangular" or "legendre-gauss". Defaults to "equiangular".
   :type grid_type: str, optional
   :param dtype: Numerical precision for calculations. Defaults
                 to torch.float32.
   :type dtype: torch.dtype, optional
   :param device: PyTorch device for computations. Defaults
                  to "cuda:0".
   :type device: torch.device, optional


   .. py:attribute:: latitude_modes


   .. py:attribute:: longitude_modes


   .. py:attribute:: inverse_sht


   .. py:method:: forward(num_samples: int, noise_input: Optional[torch.Tensor] = None) -> torch.Tensor

      Generate random field samples on the sphere.

      Uses Karhunen-Loève expansion to generate correlated random fields:
      1. Sample independent Gaussian noise in spherical harmonic space.
      2. Scale by the square root of covariance eigenvalues.
      3. Transform back to physical space via inverse spherical harmonics.

      :param num_samples: Number of independent random field realizations to generate.
      :type num_samples: int
      :param noise_input: Pre-generated complex Gaussian noise
                          with shape (num_samples, latitude_modes, latitude_modes+1). If None,
                          new noise is sampled automatically. Defaults to None.
      :type noise_input: torch.Tensor, optional

      :returns:

                Random field samples with shape
                    (num_samples, latitude_modes, longitude_modes) on an equiangular grid
                    covering the sphere.
      :rtype: torch.Tensor