Function Documentation

Transforms

Fast methods for forward and inverse spin-weighted spherical harmonic transforms.

An extension of the methods presented in McEwen and Wiaux (2011) [MW], the transforms here use FFTs and numba-acceleration to rapidly compute the spin-weighted spherical harmonic decomposition of a discretely-sampled function on a sphere, or invert the decomposition back to sampled values. The only requirement is that the sphere be sampled with evenly-spaced samples in azimuth (phi) at each colatitude (theta).

Non-uniform sampling in theta will be supported in the future.

pyspherical.transforms.forward_transform(dat, phis, thetas, lmax, lmin=0, spin=0)

Transform sampled data to spin-weighted spherical harmonics.

Parameters

• dat (ndarray of float or complex) –

  Sampled data array. Shape can be:

  • dat.shape = (phis.size, thetas.size)

  • dat.shape = (thetas.size, phis.size)

  • dat.shape = phis.shape = theta.shape

  In the first two cases, it is assumed that the same sampling in phi is done at all co-latitudes.

• phis (ndarray of float) – Sample azimuths in radians.

• thetas (ndarray of float) – Sample co-latitudes in radians.

• lmax (int) – Maximum multipole mode.

• lmin (int) – Minimum multipole mode to compute. (Optional, default 0)

• spin (int) – Spin of the transform.

Returns

flm – Spherical-harmonic components, shape ((lmax-1)**2) Modes with el < spin will be set to zero.

Return type

ndarray of complex

pyspherical.transforms.inverse_transform(flm, phis=None, thetas=None, lmax=None, lmin=0, spin=0, Nt=None, Nf=None)

Evaluate spin-weighted spherical harmonic components to a sphere.

Without any optional parameters, this assumes the sampling described in McEwan and Wiaux (2011).

Parameters

• flm (ndarray of complex) – Spherical harmonic components in the ordering returned by forward_transform.

• phis (ndarray of float) – Sample azimuths in radians. Overrides Nf keyword. (Optional) Defaults to Nf uniform samples in [0, 2 pi).

• thetas (ndarray of float) – Sample co-latitudes in radians. Overrides Nt keyword. (Optional) Defaults to Nt uniform samples in [dth, pi], where dth = pi/(2 * Nt - 1)

• lmax (int) – Maximum multipole mode. (Optional) Defaults to sqrt(len(flm)).

• lmin (int) – Minimum multipole mode to compute. (Optional, default 0)

• spin (int) – Spin of the transform.

• Nt (int) – Number of samples in theta. (Optional, defaults to lmax)

• Nf (int) – Number of samples in phi for all colatitudes (Optional, defaults to (2 * lmax - 1))

Returns

dat – Evaluation of the spherical harmonic components to the sample positions.

Return type

ndarray of complex

Notes

The sampling given through phi/theta can either be the axes of a grid (i.e., identical phi sampling for all thetas) or specify the individual phi/theta positions for each sample. In the first case, dat.shape = (phi.size, theta.size). In the latter case, dat.shape = phi.shape = theta.shape.

This function cannot be used to evaluate the spherical harmonic components to arbitrary positions on the sphere. For that, the function spin_spherical_harmonic() is provided.

Evaluation

Evaluation of Wigner-d functions and spin-weighted spherical harmonic functions.

pyspherical.wigner.spin_spharm_goldberg(spin, el, em, theta, phi)

Spin-s spherical harmonic function from Goldberg et al. (1967).

Parameters

• spin (int) – Spin of the function.

• el (ints) – Spherical harmonic mode.

• em (ints) – Spherical harmonic mode.

• theta (array_like or float) – Colatitude(s) to evaluate to, in radians.

• phi (array_like or float) – Azimuths to evaluate to, in radians.

Returns

Values of the sYlm spin-weighted spherical harmonic function at spherical positions theta, phi.

Return type

complex or ndarray of complex

Notes

If theta/phi are arrays, they must have the same shape.

For nonzero spin, this function is unstable when theta/2 is close to a multiple of pi.

Also at risk of an integer overflow for el > 10.

pyspherical.wigner.spin_spherical_harmonic(spin, el, em, theta, phi, lmin=None, lmax=None, double_prec=None)

Evaluate the spin-weighted spherical harmonic.

Obeys the standard numpy broadcasting for theta and phi.

Parameters

• spin (int) – Spin of the function.

• el (ints) – Spherical harmonic mode.

• em (ints) – Spherical harmonic mode.

• theta (ndarray or float) – Colatitude(s) to evaluate to, in radians.

• phi (ndarray or float) – Azimuths to evaluate to, in radians.

• lmin (int) – Precompute the cached DeltaMatrix from some minimum el. (Optional. See notes on wigner_d.)

• lmax (int) – Precompute the cached Delta matrix up to some maximum el. (Optional. See notes on wigner_d.)

• double_prec (bool or None) – Compute the DeltaMatrix using doubles instead of singles. (See docstring for wigner_d for details). Default None

Returns

Values of the sYlm spin-weighted spherical harmonic function at spherical positions theta, phi.

Return type

complex or ndarray of complex

Notes

Uses eqns (2) and (7) of McEwan and Wiaux (2011). If theta/phi are arrays, they must have the same shape.

Utilities

Utility functions.

pyspherical.utils.get_grid_sampling(lmax=None, Nt=None, Nf=None)

Get sample positions for “grid”, compatible with the MW transform methods.

Parameters

• lmax (int) – Maximum multipole moment (Optional if Nt/Nf are set.)

• Nt (int) – Number of samples in theta. (Optional, defaults to lmax)

• Nf (int) – Number of samples in phi for all colatitudes (Optional, defaults to (2 * lmax - 1))

Returns

• thetas (ndarray) – Colatitudes in radians.

• phis (ndarray) – Azimuths in radians.

pyspherical.utils.ravel_lm(ind)

Get (el, em) from index.

pyspherical.utils.resize_axis(arr, size, mode='zero', axis=0)

Resize an axis of the array, either truncating or zero-padding.

The “mode” keyword determines how this is done.

Parameters

• arr (ndarray) – Array to resize

• size (int) – New size for the axis.

• mode (str) –

  If the new array is zero-padded, where to put the old data:

  • ’zero’ : Put zeros in the middle of the axis (center data on zero)

  • ’start’ : Put zeros at the end of the axis.

  • ’center’: Evenly fill data on both sides.

  Defaults to “zero”.

• axis (int) – Which axis to resize

Returns

arr – Input array with the specified axis padded or truncated.

Return type

ndarray

Notes

The ‘zero’ mode can be used to zero-pad an FFT-transformed array before applying an inverse transform.

pyspherical.utils.tri_ravel(l, m1, m2)

Ravel indices for the ‘stack of triangles’ ordering.

pyspherical.utils.unravel_lm(el, m)

Get index from (el, em).

Caching

The methods used to calculate spherical harmonic transforms and Wigner-D functions use an array of pre-computed values of the Wigner-d functions at θ = π / 2, called a DeltaMatrix. This matrix is computed for a particular range of \(l\) values, respecting a fixed limit of memory usage. These functions control this caching behavior.

Evaluation of Wigner-d functions and spin-weighted spherical harmonic functions.

pyspherical.wigner.clear_cached_dmat()

Delete cached DeltaMatrix.

pyspherical.wigner.get_cache_details()

Details of the cached DeltaMatrix.

Returns

A dictionary containing:

• cache_mem_limit

  Limit in MiB of the cached DeltaMatrix

• maximum_el

  Maximum el mode that can be supported by itself in the cached DeltaMatrix, under the current limit.

  This is not the same as lmax. Each el mode “block” in the matrix consists of (el + 1) * (el + 2) / 2 floats. This is the maximum el whose block can fit in the memory limit.

The following will be included only if a DeltaMatrix is cached:

• lmin

  Minimum el mode in the cached DeltaMatrix

• lmax

  Maximum el mode in the cached DeltaMatrix

• size

  Number of floats in the cached DeltaMatrix

Return type

dict

pyspherical.wigner.get_cached_dmat()

Return currently cached DeltaMatrix.

pyspherical.wigner.set_cache_mem_limit(maxmem)

Set the memory limit for cached DeltaMatrix values.

Defaults to 200 MiB.

Also estimates the maximum el that can be contained in this limit by itself.

Parameters

maxmem (float) – Memory usage limit in MiB for cached DeltaMatrix array. Defaults to 200, corresponding with about lmax ~ 540 for lmin = 0.