Package structure

pysofft.soft

Classes:

Name	Description
Soft	Python wrapper arround fortran class, that handles all transforms.
CoeffSO3	Numpy ndarray subclass adding easy access to individual Wigner coefficients \(f^l_{n,k}\) via self.lmn[].
CoeffIndexer

Soft [source]

Python wrapper arround fortran class, that handles all transforms.

Attributes:

Name	Type	Description
recurrence_types	namedtuple	Contains all available Wigner recurrence types (currently kostelec and risbo)
bw	int	Bandwidth of the SO(3) Fourier transforn defining the SO(3) sampling.

Methods:

Name	Description
__init__	Create a transform instance.
get_coeff	Create SO(3) coefficients array.
get_so3func	Create SO(3) function array.
enforce_real_symmetry	Enforces the Wigner symmetry \(f^l_{m,n} = f^l_{-m,-n} (-1)^{m+n}\) that occurs if they belong to a real
soft	Computes forward complex valued Fourier transform over SO(3)
isoft	Computes inverse complex valued Fourier transform over SO(3)
rsoft	Computes forward real valued Fourier transform over SO(3)
irsoft	Computes inverse real valued Fourier transform over SO(3)
soft_many	Computes forward complex valued Fourier transform over SO(3) for many functions at once.
isoft_many	Computes inverse complex valued Fourier transform over SO(3) for many coefficient arrays at once.
rsoft_many	Computes forward real valued Fourier transform over SO(3) for many functions at once.
irsoft_many	Computes inverse real valued Fourier transform over SO(3) for many coefficient arrays at once.
integrate_over_so3	Nummerically integrate a function over SO(3)
cross_correlation_ylm_cmplx	Computes the rotational cross-correlation between two complex functions \(f,g: S^2 \rightarrow \mathbb{C}\) over the 2-sphere given by their spherical harmonic coefficients.
cross_correlation_ylm_real	Computes the rotational cross-correlation between two real functions \(f,g: S^2 \rightarrow \mathbb{R}\) over the 2-sphere given by their spherical harmonic coefficients.
cross_correlation_ylm_cmplx_3d	Computes the rotational cross-correlation between two complex functions \(f,g: \mathbb{R}^3 \rightarrow \mathbb{C}\) defined in spherical coordinates given by n sets of spherical harmonic coefficients, where n is the number or radial grid points
cross_correlation_ylm_real_3d	Computes the rotational cross-correlation between two real functions \(f,g: \mathbb{R}^3 \rightarrow \mathbb{R}\) defined in spherical coordinates given by n sets of spherical harmonic coefficients, where n is the number or radial grid points
rotate_ylm_cmplx	Rotates an array of spherical harmonic coefficients of a complex function
rotate_ylm_real	Terribly inefficient conveniece function.

__init__(bw, lmax=None, precompute_wigners=False, recurrence_type=None, init_ffts=False, fftw_flags=0, use_fftw_wisdom=False) [source]

Create a transform instance.

Parameters:

Name	Type	Description	Default
bw	int64	Bandwidth of the SO(3) Fourier transform defining the SO(3) sampling.	required
lmax	int | None	Maximum considered Wigner degree \(l\). lmax has to satisfy 0<=lmax<bw.	None
precompute_wigners	bool	Whether or not to precompute and store the \(O(\mathrm{bw}^4)\) small Wigner-d matrix values \(d^l_{m,n}(\\beta)\).	False
recurrence_type	int | None	Selects the recurrence that is used to compute the \(d^l_{m,n}(\\beta)\).	None
init_ffts	bool	Whether to allocate memory and create fft plans during initialization rather than lacy on the first call to a transform.	False

get_coeff(real=False, random=False, seed=12345, raw=False, howmany=0) [source]

Create SO(3) coefficients array.

Parameters:

Name	Type	Description	Default
real	bool	Whether to generate a coefficient array for real or complex functions over SO(3).	False
random	bool	If True fill with random numbers, if False fill with zeros.	False
seed	int	Seed for the random number generator	12345
raw	bool	If True returns the pure numpy array without wrapping it in the CoeffSO3 class.	False
howmany	int	If grater than 0, create array of shape (howmany,n_coefficients) that is compatible with the *_many transforms.	0

Returns:

Name	Type	Description
coeff	ndarray	((4*bw^3-bw)/3,)|(howmany,(4*bw^3-bw)/3,) complex: Wigner coefficient array.

Examples:

from pysofft import Soft
s = Soft(16)
s.get_coeff(random=True)

get_so3func(real=False, random=False, seed=12345, howmany=0) [source]

Create SO(3) function array.

Parameters:

Name	Type	Description	Default
real		Whether to generate a function array for real or complex functions over SO(3).	False
random		If True fill with random numbers, if False fill with zeros.	False
seed		Seed for the random number generator	12345
howmany		If grater than 0, create array of shape (howmany,2bw,2bw,2*bw) that is compatible with the *_many transforms.	0

Returns:

Name	Type	Description
so3func	ndarray	(2*bw,2*bw,2*bw)|(howmany,2*bw,2*bw,2*bw) complex|real: Array representing a function over SO(3) sampled on self.euler_angles.

Examples:

from pysofft import Soft
s = Soft(16)
s.get_so3func(random=True)

enforce_real_symmetry(coeff) [source]

Enforces the Wigner symmetry \(f^l_{m,n} = f^l_{-m,-n} (-1)^{m+n}\) that occurs if they belong to a real valued function over SO(3).

Parameters:

Name	Type	Description	Default
coeff		((4*bw**3-bw)/3,) complex: Wigner coefficient array.	required

Examples:

from pysofft import Soft
import numpy as np
s = Soft(16)
flmn = s.get_coeff(random=True)
f = s.isoft(flmn)
print(f'Max complex magnitude of f is = {np.max(np.abs(f.imag))}')
flmn_real = flmn.copy()
s.enforce_real_symmetry(flmn_real)
f_real = s.isoft(flmn_real)
print(f'Max complex magnitude of f_real is = {np.max(np.abs(f_real.imag))}')

soft(so3func, out=None, use_mp=False) [source]

Computes forward complex valued Fourier transform over SO(3)

Parameters:

Name	Type	Description	Default
so3func	ndarray	(2*bw,2*bw,2*bw) complex: SO(3) function sampled at the eulerangles in self.euler_angles.	required
out	ndarray | None	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	((4*bw^3-bw)/3,) complex: Computed Wigner coefficients.

Examples:

from pysofft import Soft
s = Soft(16)
so3func = s.get_so3func(random=True)
s.soft(so3func)

isoft(coeff, out=None, use_mp=False) [source]

Computes inverse complex valued Fourier transform over SO(3)

Parameters:

Name	Type	Description	Default
coeff	ndarray	((4*bw^3-bw)/3,) complex: Wigner coefficients.	required
out	ndarray | None	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(2*bw,2*bw,2*bw) complex: Computed SO(3) function.

Examples:

from pysofft import Soft
s = Soft(16)
coeff = s.get_coeff(random=True)
s.isoft(coeff)

rsoft(so3func, out=None, use_mp=False) [source]

Computes forward real valued Fourier transform over SO(3)

Parameters:

Name	Type	Description	Default
so3func	ndarray	(2*bw,2*bw,2*bw) float: SO(3) function sampled at the eulerangles in self.euler_angles.	required
out	ndarray | None	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	((4*bw^3-bw)/3) complex: Computed Wigner coefficients.

Examples:

from pysofft import Soft
s = Soft(16)
so3func = s.get_so3func(random=True,real=True)
s.rsoft(so3func)

irsoft(coeff, out=None, use_mp=False) [source]

Computes inverse real valued Fourier transform over SO(3)

Parameters:

Name	Type	Description	Default
coeff	ndarray	((4*bw^3-bw)/3,) complex: Wigner coefficients.	required
out	ndarray | None	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(2*bw,2*bw,2*bw) float: Computed SO(3) function.

Examples:

from pysofft import Soft
s = Soft(16)
coeff = s.get_coeff(random=True,real=True)
s.irsoft(coeff)

soft_many(so3funcs, out=None, use_mp=False) [source]

Computes forward complex valued Fourier transform over SO(3) for many functions at once.
Parallel processing is done over the individual function arrays if enabled.

Parameters:

Name	Type	Description	Default
so3func		(n,2*bw,2*bw,2*bw) complex: containing n separate functions over SO(3).	required
out	ndarray | None	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(n,(4*bw**3-bw)/3) complex, Wigner coefficient arrays.

Examples:

from pysofft import Soft
s = Soft(16)
so3func = s.get_so3func(random=True,howmany=100)
s.soft_many(so3func)

isoft_many(coeffs, out=None, use_mp=False) [source]

Computes inverse complex valued Fourier transform over SO(3) for many coefficient arrays at once.
Parallel processing is done over the individual coefficient arrays if enabled.

Parameters:

Name	Type	Description	Default
so3func		(n,(4*bw^3-bw)/3) complex: containing n separate Wiegner coefficient arrays.	required
out		If provided the transform result is written to this array.	None
use_mp		Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(n,2*bw,2*bw,2*bw) complex: Computed SO(3) functions.

Examples:

from pysofft import Soft
s = Soft(16)
coeff = s.get_coeff(random=True,howmany=100)
s.isoft_many(coeff)

rsoft_many(so3funcs, out=None, use_mp=False) [source]

Computes forward real valued Fourier transform over SO(3) for many functions at once.
Parallel processing is done over the individual function arrays if enabled.

Parameters:

Name	Type	Description	Default
so3func		(n,2*bw,2*bw,2*bw) float storing n separate SO(3) functions.	required
out	None | ndarray	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(n,(4*bw^3-bw)/3) complex: Wigner coefficient arrays.

Examples:

from pysofft import Soft
s = Soft(16)
so3func = s.get_so3func(random=True,howmany=100,real=True)
s.rsoft_many(so3func)

irsoft_many(coeffs, out=None, use_mp=False) [source]

Computes inverse real valued Fourier transform over SO(3) for many coefficient arrays at once.
Parallel processing is done over the individual coefficient arrays if enabled.

Parameters:

Name	Type	Description	Default
so3func		(n,(4*bw^3-bw)/3) complex: storing n separate Wigner coefficient arrays.	required
out	None | ndarray	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Type	Description
`(n,2*bw,2*bw,2*bw) float`: computed SO(3) functions.

Examples:

from pysofft import Soft
s = Soft(16)
coeff = s.get_coeff(random=True,howmany=100,real=True)
s.irsoft_many(coeff)

integrate_over_so3(f) [source]

Nummerically integrate a function over SO(3)

Parameters:

Name	Type	Description	Default
f	ndarray	´(2bw,2bw,2*bw) complex|float`: SO(3) function to be integrated	required

Returns:

Type	Description
complex | float	Numerical íntegral of f

Examples:

from pysofft import Soft
import numpy as np
s = Soft(16)
func = s.get_so3func()
func[...] = 1
vol_SO3 = s.integrate_over_so3(func)
np.isclose(vol_SO3,8*np.pi**2)

cross_correlation_ylm_cmplx(f_lm, g_lm, out=None, use_mp=False) [source]

Computes the rotational cross-correlation between two complex functions \(f,g: S^2 \rightarrow \mathbb{C}\) over the 2-sphere given by their spherical harmonic coefficients. That is, it computes

\[C(\omega) = \int_{S^2} dx f(x) g(R_\omega x)^* \]

where \(\omega\) are elements of SO(3), \(x\) are points on the 2-sphere and \(R_\omega x\) describes the action of \(\omega\) on a point \(x\).

Parameters:

Name	Type	Description	Default
f_lm	ndarray	(bw**2,) complex: Spherical harmonic coefficients of \(f\). (\(|m|\leq l\) and \(f^l_m\) is stored at index l*(l+1)+m)	required
g_lm	ndarray	(bw**2,) complex: Spherical harmonic coefficients of \(g\). (\(|m|\leq l\) and \(g^l_m\) is stored at index l*(l+1)+m)	required
out	None | ndarray	If provided the transform result is written to this array.	None
use_mp	bool	Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(2*bw,2*bw,2*bw) complex Cross-correlation between.

Examples:

For an example see rotational cross-correlation.

cross_correlation_ylm_real(f_lm, g_lm, out=None, use_mp=False) [source]

Computes the rotational cross-correlation between two real functions \(f,g: S^2 \rightarrow \mathbb{R}\) over the 2-sphere given by their spherical harmonic coefficients. That is, it computes

\[C(\omega) = \int_{S^2} dx f(x) g(R_\omega x)^* \]

where \(\omega\) are elements of SO(3), \(x\) are points on the 2-sphere and \(R_\omega x\) describes the action of \(\omega\) on a point \(x\).

Parameters:

Name	Type	Description	Default
f_lm		(bw**2,) complex: Spherical harmonic coefficients of \(f\). (\(0\leq m\leq l\) and \(f^l_m\) is stored at index (m*(2*bw-1-m))/2+l)	required
g_lm		(bw**2,) complex: Spherical harmonic coefficients of \(g\). (\(0\leq m\leq l\) and \(g^l_m\) is stored at index (m*(2*bw-1-m))/2+l)	required
out		If provided the transform result is written to this array.	None
use_mp		Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(2*bw,2*bw,2*bw) real Cross-correlation between.

Examples:

For an example see rotational cross-correlation.

cross_correlation_ylm_cmplx_3d(f_lms, g_lms, out=None, radial_sampling_points=None, radial_limits=None, use_mp=False) [source]

Computes the rotational cross-correlation between two complex functions \(f,g: \mathbb{R}^3 \rightarrow \mathbb{C}\) defined in spherical coordinates given by n sets of spherical harmonic coefficients, where n is the number or radial grid points That is, it computes

\[C(\omega) = \int_{r} dr r^2 \int_{S^2} dx f(r,x) g(r,R_\omega x)^* \]

where \(\omega\) are elements of SO(3), \(x\) are points on the 2-sphere, \(r\) is the radial coordinate and \(R_\omega x\) describes the action of \(\omega\) on a point \(x\). (Written in azimutal and polar angels we have \(x=(\theta,\phi)\) and \(dx=d\theta d\phi sin(\theta)\).)

Parameters:

Name	Type	Description	Default
f_lms		(n,bw**2,) complex: Spherical harmonic coefficients of \(f\). (\(|m|\leq l\) and \(f^l_m\) is stored at index l*(l+1)+m)	required
g_lms		(n,bw**2,) complex: Spherical harmonic coefficients of \(g\). (\(|m|\leq l\) and \(g^l_m\) is stored at index l*(l+1)+m)	required
out		If provided the transform result is written to this array.	None
use_mp		Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(2*bw,2*bw,2*bw) complex Cross-correlation between.

Examples:

For an example see rotational cross-correlation.

cross_correlation_ylm_real_3d(f_lms, g_lms, out=None, radial_sampling_points=None, radial_limits=None, use_mp=False) [source]

Computes the rotational cross-correlation between two real functions \(f,g: \mathbb{R}^3 \rightarrow \mathbb{R}\) defined in spherical coordinates given by n sets of spherical harmonic coefficients, where n is the number or radial grid points That is, it computes

\[C(\omega) = \int_{r} dr r^2 \int_{S^2} dx f(r,x) g(r,R_\omega x)^* \]

where \(\omega\) are elements of SO(3), \(x\) are points on the 2-sphere, \(r\) is the radial coordinate and \(R_\omega x\) describes the action of \(\omega\) on a point \(x\). (Written in azimutal and polar angels we have \(x=(\theta,\phi)\) and \(dx=d\theta d\phi sin(\theta)\).)

Parameters:

Name	Type	Description	Default
f_lm		(n,bw**2,) complex: Spherical harmonic coefficients of \(f\). (\(0\leq m\leq l\) and \(f^l_m\) is stored at index (m*(2*bw-1-m))/2+l)	required
g_lm		(n,bw**2,) complex: Spherical harmonic coefficients of \(g\). (\(0\leq m\leq l\) and \(g^l_m\) is stored at index (m*(2*bw-1-m))/2+l)	required
out		If provided the transform result is written to this array.	None
use_mp		Whether to allow parallel execution using OpenMP.	False

Returns:

Name	Type	Description
out	ndarray	(n,2*bw,2*bw,2*bw) real Cross-correlation between.

Examples:

For an example see rotational cross-correlation.

rotate_ylm_cmplx(ylms, euler_angles) [source] staticmethod

Rotates an array of spherical harmonic coefficients of a complex function by an array of rotations given as ZXZ euler angles.

Input ylms : (n_ylmns,spherical_harmonic_coefficients) : (n,(2bw-1)*2) : complex euler_angles : (m_rotations,euler_angles) : (m,3) : int

Output ylns_rot : (m_rotations,n_ylms,harmonic_coefficients) : (m,n,(2bw-1)*2) : complex

rotate_ylm_real(ymls, euler_angles) [source] staticmethod

Terribly inefficient conveniece function. Rotates an array of spherical harmonic coefficients of a complex function by an array of rotations given as ZXZ euler angles. Works by converting to complex representation and apply rotate_ylm_cmplx.

Parameters:

Name	Type	Description	Default
ylms		(n,(bw*(bw+1))/2) complex: set of spherical harmonic coefficients. (bw here is not the bw of of Soft object but of the input coefficient array)	required
euler_angles		(m,3) float Array of euler angels.	required

Returns:

Name	Type	Description
ylns_rot	ndarray	(m,n,(bw*(bw+1))/2) complex Rotated spherical harmonic coefficients.

CoeffSO3 [source]

Bases: ndarray

Numpy ndarray subclass adding easy access to individual Wigner coefficients \(f^l_{n,k}\) via self.lmn[].

Attributes:

Name	Type	Description
bw	int	Bandwidth of the distribution.
lmn	CoeffView	allows to acces \(f^l_{m,n}\) by its indices \(l,n,k\).

CoeffIndexer [source]