Spherical samples#

s2fft.sampling.s2_samples.elm2ind(el: int, m: int) → int#

Convert from spherical harmonic 2D indexing of \((\ell,m)\) to 1D index.

1D index is defined by el**2 + el + m.

Warning

Note that 1D storage of spherical harmonic coefficients is not the default.

Parameters:

el (int) – Harmonic degree \(\ell\).
m (int) – Harmonic order \(m\).

Returns:

Corresponding 1D index value.

Return type:

int

s2fft.sampling.s2_samples.f_shape(L: int | None = None, sampling: str = 'mw', nside: int | None = None) → Tuple[int]#

Shape of spherical signal.

Parameters:

L (int, optional) – Harmonic band-limit.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”, “dh”, “gl”, “healpix”}. Defaults to “mw”.
nside (int, optional) – HEALPix Nside resolution parameter. Only required if sampling=”healpix”. Defaults to None.

Returns:

Pixel-space array dimensions with shape \([n_{\theta}, n_{\phi}]\). Note that “healpix” is instead indexed by a 1D array, with standard conventions.

Return type:

Tuple[int]

s2fft.sampling.s2_samples.flm_1d_to_2d(flm_1d: ndarray, L: int) → ndarray#

Convert from 1D indexed harmnonic coefficients to 2D indexed coefficients.

Note

Storage conventions for harmonic coefficients \(flm_{(\ell,m)}\), for e.g. \(L = 3\), are as follows.

\[\begin{split}\text{ 2D data format}: \begin{bmatrix} 0 & 0 & flm_{(0,0)} & 0 & 0 \\ 0 & flm_{(1,-1)} & flm_{(1,0)} & flm_{(1,1)} & 0 \\ flm_{(2,-2)} & flm_{(2,-1)} & flm_{(2,0)} & flm_{(2,1)} & flm_{(2,2)} \end{bmatrix}\end{split}\]

\[\text{1D data format}: [flm_{0,0}, flm_{1,-1}, flm_{1,0}, flm_{1,1}, \dots]\]

Parameters:

flm_1d (np.ndarray) – 1D indexed harmonic coefficients.
L (int) – Harmonic band-limit.

Returns:

2D indexed harmonic coefficients.

Return type:

np.ndarray

s2fft.sampling.s2_samples.flm_2d_to_1d(flm_2d: ndarray, L: int) → ndarray#

Convert from 2D indexed harmonic coefficients to 1D indexed coefficients.

Note

Storage conventions for harmonic coefficients \(flm_{(\ell,m)}\), for e.g. \(L = 3\), are as follows.

\[\text{1D data format}: [flm_{0,0}, flm_{1,-1}, flm_{1,0}, flm_{1,1}, \dots]\]

Parameters:

flm_2d (np.ndarray) – 2D indexed harmonic coefficients.
L (int) – Harmonic band-limit.

Returns:

1D indexed harmonic coefficients.

Return type:

np.ndarray

s2fft.sampling.s2_samples.flm_2d_to_hp(flm_2d: ndarray, L: int) → ndarray#

Converts from 2D indexed harmonic coefficients to HEALPix (healpy) indexed coefficients.

Note

HEALPix implicitly assumes conjugate symmetry and thus only stores positive m coefficients. So this function discards the negative m values. This process is NOT invertible! See the healpy api docs for details on healpy indexing and lengths.

Note

Storage conventions for harmonic coefficients \(f_{(\ell,m)}\), for e.g. \(L = 3\), are as follows.

\[\text{HEALPix}: [flm_{(0,0)}, \dots, flm_{(2,0)}, flm_{(1,1)}, \dots, flm_{(L-1,1)}, \dots]\]

Warning

Returns harmonic coefficients of an explicitly real signal.

Warning

Note that the harmonic band-limit L differs to the HEALPix lmax convention, where L = lmax + 1.

Parameters:

flm_2d (np.ndarray) – 2D indexed harmonic coefficients.
L (int) – Harmonic band-limit.

Returns:

HEALPix indexed harmonic coefficients.

Return type:

np.ndarray

s2fft.sampling.s2_samples.flm_hp_to_2d(flm_hp: ndarray, L: int) → ndarray#

Converts from HEALPix (healpy) indexed harmonic coefficients to 2D indexed coefficients.

Notes

HEALPix implicitly assumes conjugate symmetry and thus only stores positive m coefficients. Here we unpack that into harmonic coefficients of an explicitly real signal.

Warning

Note that the harmonic band-limit L differs to the HEALPix lmax convention, where L = lmax + 1.

Note

Storage conventions for harmonic coefficients \(f_{(\ell,m)}\), for e.g. \(L = 3\), are as follows.

\[\text{HEALPix}: [flm_{(0,0)}, \dots, flm_{(2,0)}, flm_{(1,1)}, \dots, flm_{(L-1,1)}, \dots]\]

Note

Returns harmonic coefficients of an explicitly real signal.

Parameters:

flm_hp (np.ndarray) – HEALPix indexed harmonic coefficients.
L (int) – Harmonic band-limit.

Returns:

2D indexed harmonic coefficients.

Return type:

np.ndarray

s2fft.sampling.s2_samples.flm_shape(L: int) → Tuple[int, int]#

Standard shape of harmonic coefficients.

Parameters:: L (int, optional) – Harmonic band-limit.
Returns:: Sampling array shape, with indexing \([\ell, m]\).
Return type:: Tuple[int]

s2fft.sampling.s2_samples.ftm_shape(L: int, sampling: str = 'mw', nside: int | None = None) → Tuple[int, int]#

Shape of intermediate array, before/after latitudinal step.

Parameters:

L (int) – Harmonic band-limit.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”, “dh”, “gl”, “healpix”}. Defaults to “mw”.
nside (int, optional) – HEALPix Nside resolution parameter.

Raises:

ValueError – Unknown sampling scheme.

Returns:

Shape of ftm array, i.e. \([n_{\theta}, n_{\phi}]\). Note that here “healpix” defaults to \(2L = 4nside\) phi samples for ftm.

Return type:

Tuple[int,int]

s2fft.sampling.s2_samples.hp_ang2pix(nside: int, theta: float, phi: float) → int#

Convert angles to HEALPix index for HEALPix ring ordering scheme.

Parameters:

nside (int) – HEALPix Nside resolution parameter.
theta (float) – Spherical \(\theta\) angle.
phi (float) – Spherical \(\phi\) angle.

Returns:

HEALPix map index for ring ordering scheme.

Return type:

int

s2fft.sampling.s2_samples.hp_getidx(L: int, el: int, m: int) → int#

Compute HEALPix harmonic index.

Warning

Note that the harmonic band-limit L differs to the HEALPix :math`ell_{text{max}}` convention, where \(L = \ell_{\text{max}} + 1\).

Parameters:

L (int) – Harmonic band-limit.
el (int) – Harmonic degree \(\ell\).
m (int) – Harmonic order \(m\).

Returns:

Corresponding index for RING ordered HEALPix.

Return type:

int

s2fft.sampling.s2_samples.ind2elm(ind: int) → tuple#

Convert from 1D spherical harmonic index to 2D index of \((\ell,m)\).

Warning

Note that 1D storage of spherical harmonic coefficients is not the default.

Parameters:: ind (int) – 1D spherical harmonic index.
Returns:: (el,m) defining spherical harmonic degree and order.
Return type:: tuple

s2fft.sampling.s2_samples.lm2lm_hp(flm: ndarray, L: int) → ndarray#

Converts from 1D indexed harmonic coefficients to HEALPix (healpy) indexed coefficients.

Note

Storage conventions for harmonic coefficients \(f_{(\ell,m)}\), for e.g. \(L = 3\), are as follows.

\[\text{1D data format}: [flm_{0,0}, flm_{1,-1}, flm_{1,0}, flm_{1,1}, \dots]\]

\[\text{HEALPix}: [flm_{(0,0)}, \dots, flm_{(2,0)}, flm_{(1,1)}, \dots, flm_{(L-1,1)}, \dots]\]

Warning

Returns harmonic coefficients of an explicitly real signal.

Warning

Note that the harmonic band-limit L differs to the HEALPix :math`ell_{text{max}}` convention, where \(L = \ell_{\text{max}} + 1\).

Parameters:

flm (np.ndarray) – 1D indexed harmonic coefficients.
L (int) – Harmonic band-limit.

Returns:

HEALPix indexed harmonic coefficients.

Return type:

np.ndarray

s2fft.sampling.s2_samples.ncoeff(L: int) → int#

Number of spherical harmonic coefficients for given band-limit L.

Parameters:: L (int, optional) – Harmonic band-limit.
Returns:: Number of spherical harmonic coefficients.
Return type:: int

s2fft.sampling.s2_samples.nphi_equiang(L: int, sampling: str = 'mw') → int#

Number of \(\phi\) samples for equiangular sampling scheme at specified resolution.

Number of samples is independent of \(\theta\) since equiangular sampling scheme.

Parameters:

L (int) – Harmonic band-limit.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”, “dh”, “gl”}. Defaults to “mw”.

Raises:

ValueError – HEALPix sampling scheme.
ValueError – Unknown sampling scheme.

Returns:

Number of \(\phi\) samples.

Return type:

int

s2fft.sampling.s2_samples.nphi_equitorial_band(nside: int) → int#

Number of \(\phi\) samples within the equitorial band for HEALPix sampling scheme.

Parameters:: nside (int, optional) – HEALPix Nside resolution parameter.
Returns:: Number of \(\phi\) samples.
Return type:: int

s2fft.sampling.s2_samples.nphi_ring(t: int, nside: int | None = None) → int#

Number of \(\phi\) samples for HEALPix sampling on given \(\theta\) ring.

Parameters:

t (int) – Index of HEALPix \(\theta\) ring.
nside (int, optional) – HEALPix Nside resolution parameter.

Raises:

ValueError – Invalid ring index given nside.

Returns:

Number of \(\phi\) samples on given \(\theta\) ring.

Return type:

int

s2fft.sampling.s2_samples.ntheta(L: int | None = None, sampling: str = 'mw', nside: int | None = None) → int#

Number of \(\theta\) samples for sampling scheme at specified resolution.

Parameters:

L (int, optional) – Harmonic band-limit. Required if sampling not healpix. Defaults to None.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”, “dh”, “gl”, “healpix”}. Defaults to “mw”.
nside (int, optional) – HEALPix Nside resolution parameter. Only required if sampling=”healpix”. Defaults to None.

Raises:

ValueError – L not specified when sampling not healpix.
ValueError – HEALPix sampling set but nside not specified.
ValueError – Sampling scheme not supported.

Returns:

Number of \(\theta\) samples of sampling scheme at given resolution.

Return type:

int

s2fft.sampling.s2_samples.ntheta_extension(L: int, sampling: str = 'mw') → int#

Number of \(\theta\) samples for MW/MWSS sampling when extended to \(2\pi\).

Parameters:

L (int) – Harmonic band-limit.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”}. Defaults to “mw”.

Raises:

ValueError – Sampling scheme other than MW/MWSS.

Returns:

Number of \(\theta\) samples when extended to \(2\pi\).

Return type:

int

s2fft.sampling.s2_samples.p2phi_equiang(L: int, p: int, sampling: str = 'mw') → ndarray#

Convert index to \(\phi\) angle for sampling scheme.

Parameters:

L (int, optional) – Harmonic band-limit.
p (int) – \(\phi\) index.
sampling (str, optional) – Sampling scheme. Supported equiangular sampling schemes include {“mw”, “mwss”, “dh”, “gl”}. Defaults to “mw”.

Raises:

ValueError – HEALPix sampling not support (only equiangular schemes supported).
ValueError – Unknown sampling scheme.

Returns:

\(\phi\) sample(s) for given sampling scheme.

Return type:

np.ndarray

s2fft.sampling.s2_samples.p2phi_ring(t: int, p: int, nside: int) → ndarray#

Convert index to \(\phi\) angle for HEALPix for given \(\theta\) ring.

Parameters:

t (int) – \(\theta\) index of ring.
p (int) – \(\phi\) index within ring.
nside (int) – HEALPix Nside resolution parameter.

Returns:

\(\phi\) angle.

Return type:

np.ndarray

s2fft.sampling.s2_samples.phis_equiang(L: int, sampling: str = 'mw') → ndarray#

Compute \(\phi\) samples for equiangular sampling scheme.

Parameters:

L (int, optional) – Harmonic band-limit.
sampling (str, optional) – Sampling scheme. Supported equiangular sampling schemes include {“mw”, “mwss”, “dh”, “gl”}. Defaults to “mw”.

Returns:

Array of \(\phi\) samples for given sampling scheme.

Return type:

np.ndarray

s2fft.sampling.s2_samples.phis_ring(t: int, nside: int) → ndarray#

Compute \(\phi\) samples for given \(\theta\) HEALPix ring.

Parameters:

t (int) – \(\theta\) index.
nside (int) – HEALPix Nside resolution parameter.

Returns:

\(\phi\) angles.

Return type:

np.ndarray

s2fft.sampling.s2_samples.ring_phase_shift_hp(L: int, t: int, nside: int, forward: bool = False, reality: bool = False) → ndarray#

Generates a phase shift vector for HEALPix for a given \(\theta\) ring.

Parameters:

L (int, optional) – Harmonic band-limit.
t (int) – \(\theta\) index of ring.
nside (int) – HEALPix Nside resolution parameter.
forward (bool, optional) – Whether to provide forward or inverse shift. Defaults to False.
reality (bool, optional) – Whether the signal on the sphere is real. If so, conjugate symmetry is exploited to reduce computational costs. Defaults to False.

Returns:

Vector of phase shifts with shape \([2L-1]\).

Return type:

np.ndarray

s2fft.sampling.s2_samples.t2theta(t: int, L: int | None = None, sampling: str = 'mw', nside: int | None = None) → ndarray#

Convert index to \(\theta\) angle for sampling scheme.

Parameters:

t (int) – \(\theta\) index.
L (int, optional) – Harmonic band-limit. Required if sampling not healpix. Defaults to None.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”, “dh”, “gl”, “healpix”}. Defaults to “mw”.
nside (int, optional) – HEALPix Nside resolution parameter. Only required if sampling=”healpix”. Defaults to None.

Raises:

ValueError – L not specified when sampling not healpix.
ValueError – HEALPix sampling set but nside not specified.
ValueError – Sampling scheme not supported.

Returns:

\(\theta\) angle(s) for passed index or indices.

Return type:

np.ndarray

s2fft.sampling.s2_samples.thetas(L: int | None = None, sampling: str = 'mw', nside: int | None = None) → ndarray#

Compute \(\theta\) samples for given sampling scheme.

Parameters:

L (int, optional) – Harmonic band-limit. Required if sampling not healpix. Defaults to None.
sampling (str, optional) – Sampling scheme. Supported sampling schemes include {“mw”, “mwss”, “dh”, “gl”, “healpix”}. Defaults to “mw”.
nside (int, optional) – HEALPix Nside resolution parameter. Only required if sampling=”healpix”. Defaults to None.

Returns:

Array of \(\theta\) samples for given sampling scheme.

Return type:

np.ndarray