torch_harmonics.InverseRealVectorSHT#

class torch_harmonics.InverseRealVectorSHT(
nlat,
nlon,
lmax=None,
mmax=None,
grid='equiangular',
norm='ortho',
csphase=True,
)[source]#

Bases: Module

Defines a module for computing the inverse (real-valued) vector SHT. Precomputes Legendre Gauss nodes, weights and associated Legendre polynomials on these nodes.

Given spheroidal and toroidal spectral coefficients \(\hat{s}_l^m\) and \(\hat{t}_l^m\), reconstructs the tangential vector field on the sphere via Legendre synthesis with the derivatives of the associated Legendre polynomials, followed by an inverse real FFT.

See also

Spherical harmonic transforms

User guide with the full mathematical derivation of the inverse vector SHT formulas, normalization conventions, and worked examples.

Parameters:

  • nlat (int) – Number of latitude points

  • nlon (int) – Number of longitude points

  • lmax (int) – Maximum spherical harmonic degree

  • mmax (int) – Maximum spherical harmonic order

  • grid (str) – Grid type ("equiangular", "legendre-gauss", "lobatto", "equiangular-trapezoidal"), by default "equiangular"

  • norm (str) – Normalization convention ("ortho", "schmidt", "unnorm"), by default "ortho".

  • csphase (bool) – Whether to include the Condon–Shortley phase factor \((-1)^m\), by default True.

Examples

>>> import torch
>>> import torch_harmonics as th
>>> nlat, nlon = 128, 256
>>> ivsht = th.InverseRealVectorSHT(nlat, nlon).cuda()
>>> coeffs = torch.randn(1, 2, 128, 129, dtype=torch.cfloat, device="cuda")
>>> vector_field = ivsht(coeffs)   # shape (1, 2, 128, 256), real
>>> vector_field.shape
torch.Size([1, 2, 128, 256])

Note

This module uses cuFFT (via torch.fft.irfft()) to compute the longitudinal inverse Fourier transform efficiently. When running in float16 or bfloat16 precision, cuFFT requires the transformed dimension (nlon) to be a power of two. If your grid does not satisfy this constraint and the module is called inside a torch.autocast context, guard it with torch.autocast(device_type="cuda", enabled=False):

with torch.autocast(device_type="cuda", dtype=torch.float16):
    # ... other half-precision work ...
    with torch.autocast(device_type="cuda", enabled=False):
        vector_field = ivsht(coeffs.to(torch.cfloat))

Note

The inverse real FFT (C2R transform) expects the DC component (\(m = 0\)) and, when nlon is even, the Nyquist component (\(m = N_\lambda / 2\)) to be purely real. This routine zeros out the imaginary parts of these components before calling the transform.

References

[2], [3]

forward(x)[source]#

Compute the inverse (real) vector spherical harmonic transform.

Parameters:

x (torch.Tensor) – Complex vector harmonic coefficients of shape (..., 2, lmax, mmax), where the size-2 dimension holds the spheroidal and toroidal components.

Returns:

Real-valued tangential vector field of shape (..., 2, nlat, nlon), where the size-2 dimension holds the two tangential (colatitude, longitude) components.

Return type:

torch.Tensor