credit.ensemble.spherical#

Classes#

`SphericalNoise`	Spherical harmonic-based noise generator with Matérn covariance for lat/lon grids.
`SphericalRandomField`	Gaussian Random Field generator on the sphere with Matérn covariance.

Module Contents#

class credit.ensemble.spherical.SphericalNoise(amplitude: float = 0.05, smoothness: float = 2.0, length_scale: float = 3.0, variance_scale: 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.

Parameters:

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

amplitude = 0.05#

smoothness = 2.0#

length_scale = 3.0#

variance_scale = None#

use_padding#

__call__(x: torch.Tensor) → torch.Tensor#

Generate spherical noise matching input tensor dimensions.

Parameters:: x (torch.Tensor) – Reference tensor whose shape determines the output noise dimensions. The last two dimensions must correspond to a lat/lon grid.
Returns:: Spherical noise tensor with the same shape as the input, scaled by the amplitude.
Return type:: torch.Tensor
Raises:: ValueError – If the lat/lon aspect ratio is not in N:2N or (N+1):2N format.

class credit.ensemble.spherical.SphericalRandomField(latitude_modes: int, smoothness: float = 2.0, length_scale: float = 3.0, variance_scale: float | None = None, sphere_radius: float = 1.0, grid_type: str = 'equiangular', dtype: torch.dtype = torch.float32, device: torch.device = 'cuda:0')#

Bases: 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.

Parameters:

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

latitude_modes#

longitude_modes#

inverse_sht#

forward(num_samples: int, noise_input: torch.Tensor | None = 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.

Parameters:

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

Returns:

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

Return type:

torch.Tensor