Skip to content

sphharm

SphericalHarmonics

Bases: SphericalHarmonicsBase

Spherical harmonics.

m instance-attribute 

m: int

Order of the harmonic (int); must have abs(m) <= n.

n instance-attribute 

n: int

Degree of the harmonic (int); must have n >= 0. This is often denoted by l (lower case L) in descriptions of spherical harmonics.

__call__ 

__call__(
    theta: float | ndarray, phi: float | ndarray
) -> complex | ndarray[complex]

Evaluate the spherical harmonics function in complex form.

__init__ 

__init__(n: int, m: int)

Initialize the spherical harmonics function.

PARAMETER DESCRIPTION
n

Degree of the harmonic (int); must have n >= 0. This is often denoted by l (lower case L) in descriptions of spherical harmonics.

TYPE: float

m

Order of the harmonic (int); must have abs(m) <= n.

TYPE: float

plot 

plot(**kwargs) -> Tuple['Figure', 'Axes3D']

Plot the spherical harmonics function.

PARAMETER DESCRIPTION
kwargs

Keyword arguments passed to 🇵🇾meth:.SphericalHarmonicsBase.plot_spherical_harmonics method.

DEFAULT: {}

RETURNS DESCRIPTION
Tuple[Figure, Axes3D]

Figure and axes objects containing the plot.

SphericalHarmonicsBase

Base class for spherical harmonics [1] [2] [3] [4] [5] [6] [7] [8].

References

.. [1] Ken-Ichi, K. (1984). Distribution of directional data and fabric tensors. International journal of engineering science, 22(2), 149-164. .. [2] Green, R. (2003, March). Spherical harmonic lighting: The gritty details. In Archives of the game developers conference (Vol. 56, p. 4). .. [3] https://en.wikipedia.org/wiki/Spherical_harmonics .. [4] https://en.wikipedia.org/wiki/Table_of_spherical_harmonics .. [5] https://en.wikipedia.org/wiki/Legendre_polynomials .. [6] https://en.wikipedia.org/wiki/Associated_Legendre_polynomials .. [7] https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.sph_harm.html .. [8] https://zhuanlan.zhihu.com/p/466774017

basis classmethod 

basis(
    n: int, m: int, theta: float | ndarray, phi: float | ndarray
) -> complex | ndarray

Spherical harmonics basis in complex form. The spherical harmonics function in complex form is defined as

\[ Y_n^m(\theta, \phi) := \sqrt{\frac{(2n+1)(n-m)!}{4\pi(n+m)!}} \exp(i m \theta) \mathrm{P}_n^m\left(\cos(\phi)\right) \]

where :math:P_n^m are the associated Legendre functions.

basis_real classmethod 

basis_real(
    n: int, m: int, theta: float | ndarray, phi: float | ndarray
) -> float | ndarray

Spherical harmonics basis in real form. The spherical harmonics function in real form is defined as

\[ Z_n^m(\theta, \phi) := \begin{cases} \frac{Y_n^m(\theta, \phi) + \overline{Y_n^m(\theta, \phi)}}{\sqrt{2}} & m > 0 \\ Y_n^m(\theta, \phi) & m = 0 \\ \frac{Y_n^m(\theta, \phi) - \overline{Y_n^m(\theta, \phi)}}{\sqrt{2}/i} & m < 0 \\ \end{cases} \]

which gives in simplified form

\[ Z_n^m(\theta, \phi) = \begin{cases} \frac{Y_n^m(\theta, \phi) + (-1)^m Y_n^{-m}(\theta, \phi)}{\sqrt{2}} \\ Y_n^m(\theta, \phi) \\ \frac{Y_n^m(\theta, \phi) - (-1)^m Y_n^{-m}(\theta, \phi)}{\sqrt{2}/i} \\ \end{cases} \\ = \sqrt{\frac{(2 n+1)}{4 \pi} \frac{(n-|m|) !}{(n+|m|) !}} \begin{cases} \sqrt{2} \cos (m \theta) & P_n^m(\cos \phi) & m>0 \\ & P_n^m(\cos \phi) & m=0 \\ \sqrt{2} \sin (|m|\theta) & P_n^{|m|}(\cos \phi) & m<0 \end{cases} \]

evalf classmethod 

evalf(func: Callable, *args, vectorize_kwargs: dict | None = None, **kwargs)

Evaluate a function with given arguments, vectorize it if necessary.

PARAMETER DESCRIPTION
func

Function that takes theta and phi as arguments and returns the function value.

TYPE: callable

args

Positional arguments passed to func.

DEFAULT: ()

vectorize_kwargs

Keyword arguments passed to 🇵🇾func:~numpy.vectorize, by default None

TYPE: dict DEFAULT: None

kwargs

Keyword arguments passed to func.

DEFAULT: {}

expand classmethod 

expand(
    func: (
        Callable[[float, float], float] | Callable[[ndarray, ndarray], ndarray]
    ),
    deg: int,
    *,
    n_sample: int = N_SAMPLE_DEFAULT,
    n_theta: int = N_THETA_DEFAULT,
    n_phi: int = N_PHI_DEFAULT
) -> Tuple[ndarray, ndarray, ndarray, ndarray, Dict[int, ndarray]]

Expand a function in the spherical harmonics basis.

PARAMETER DESCRIPTION
deg

Degree of the spherical harmonics basis.

TYPE: int

func

Function that takes theta and phi as arguments and returns the function value.

TYPE: callable

n_sample

Number of samples, by default 1000.

TYPE: int DEFAULT: N_SAMPLE_DEFAULT

n_theta

Number of points to use for the theta (azimuthal, 0-2*pi) coordinate, by default 101

TYPE: int DEFAULT: N_THETA_DEFAULT

n_phi

Number of points to use for the phi (polar, 0-pi) coordinate, by default 101

TYPE: int DEFAULT: N_PHI_DEFAULT

RETURNS DESCRIPTION
Tuple[ndarray, ndarray, ndarray, ndarray, Dict[int, ndarray]]

A tuple of coefs, theta, phi, fevals, and fprojs_degrees, where fprojs_degrees is a dictionary of the projected function for each degree.

plot_basis classmethod 

plot_basis(
    n: int,
    m: int,
    *,
    n_theta: int = N_THETA_DEFAULT,
    n_phi: int = N_PHI_DEFAULT,
    positive_color: str = "green",
    negative_color: str = "red",
    ax: Union["Axes3D", None] = None,
    subplot_kwargs: dict | None = None,
    **kwargs
) -> Tuple["Figure", "Axes3D"]

Plot the spherical harmonics function.

PARAMETER DESCRIPTION
n

Degree of the harmonic (int); must have n >= 0. This is often denoted by l (lower case L) in descriptions of spherical harmonics.

TYPE: float

m

Order of the harmonic (int); must have abs(m) <= n.

TYPE: float

n_theta

Number of points to use for the theta (azimuthal, 0-2*pi) coordinate, by default 101

TYPE: int DEFAULT: N_THETA_DEFAULT

n_phi

Number of points to use for the phi (polar, 0-pi) coordinate, by default 101

TYPE: int DEFAULT: N_PHI_DEFAULT

positive_color

Color to use for positive values, by default "green"

TYPE: str DEFAULT: 'green'

negative_color

Color to use for negative values, by default "red"

TYPE: str DEFAULT: 'red'

ax

Axes to plot on, by default None.

TYPE: Union['Axes3D', None] DEFAULT: None

subplot_kwargs

Keyword arguments passed to 🇵🇾func:~micromechanical.plotting.subplots for creating the subplot, by default None

TYPE: dict DEFAULT: None

kwargs

Keyword arguments passed to 🇵🇾func:~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_surface.

DEFAULT: {}

RETURNS DESCRIPTION
Tuple[Figure, Axes3D]

Figure and axes objects containing the plot.

 
plot_gallery(
    deg: int,
    *,
    subplot_kwargs: dict | None = None,
    clear_empty_axis: bool = True,
    clear_axis: bool = False,
    **kwargs
) -> Tuple["Figure", List[List["Axes3D"]]]

Plot a gallery of spherical harmonics functions.

PARAMETER DESCRIPTION
deg

Degree of the spherical harmonics basis.

TYPE: int

subplot_kwargs

Keyword arguments passed to 🇵🇾func:~micromechanical.plotting.subplots for creating the subplot, by default None

TYPE: dict DEFAULT: None

clear_empty_axis

Whether to clear the axis if there is no plot, by default True

TYPE: bool DEFAULT: True

clear_axis

Whether to clear the axis of all plots, by default False

TYPE: bool DEFAULT: False

kwargs

Keyword arguments passed to 🇵🇾meth:.SphericalHarmonicsBase.plot_ method.

DEFAULT: {}

RETURNS DESCRIPTION
Tuple[Figure, List[List[Axes3D]]]

Figure and list of lists of axes objects containing the plots.

plot_projection classmethod 

plot_projection(
    func: (
        Callable[[float, float], float] | Callable[[ndarray, ndarray], ndarray]
    ),
    deg: int,
    *,
    n_sample: int = N_SAMPLE_DEFAULT,
    n_theta: int = N_THETA_DEFAULT,
    n_phi: int = N_PHI_DEFAULT,
    positive_color: str = "green",
    negative_color: str = "red",
    ax: Union["Axes3D", None] = None,
    subplot_kwargs: dict | None = None,
    **kwargs
) -> Tuple["Figure", "Axes3D"]

Plot the projected function onto the spherical harmonics basis.

PARAMETER DESCRIPTION
func

Function that takes theta and phi as arguments and returns the function value.

TYPE: callable

deg

Degree of the spherical harmonics basis.

TYPE: int

n_sample

Number of samples, by default 1000.

TYPE: int DEFAULT: N_SAMPLE_DEFAULT

n_theta

Number of points to use for the theta (azimuthal, 0-2*pi) coordinate, by default 101

TYPE: int DEFAULT: N_THETA_DEFAULT

n_phi

Number of points to use for the phi (polar, 0-pi) coordinate, by default 101

TYPE: int DEFAULT: N_PHI_DEFAULT

positive_color

Color to use for positive values, by default "green"

TYPE: str DEFAULT: 'green'

negative_color

Color to use for negative values, by default "red"

TYPE: str DEFAULT: 'red'

ax

Axes to plot on, by default None.

TYPE: Union['Axes3D', None] DEFAULT: None

subplot_kwargs

Keyword arguments passed to 🇵🇾func:~micromechanical.plotting.subplots for creating the subplot, by default None

TYPE: dict DEFAULT: None

kwargs

Keyword arguments passed to 🇵🇾func:~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_surface.

DEFAULT: {}

RETURNS DESCRIPTION
Tuple[Figure, List[Axes3D]]

Figure and list of two axes objects containing the plots.

 
plot_projections_gallery(
    func: (
        Callable[[float, float], float] | Callable[[ndarray, ndarray], ndarray]
    ),
    deg: int,
    *,
    n_sample: int = N_SAMPLE_DEFAULT,
    n_theta: int = N_THETA_DEFAULT,
    n_phi: int = N_PHI_DEFAULT,
    positive_color: str = "green",
    negative_color: str = "red",
    subplot_kwargs: dict | None = None,
    real_kwargs: dict | None = None,
    proj_kwargs: dict | None = None,
    clear_empty_axis: bool = True,
    clear_axis: bool = False,
    **kwargs
) -> Tuple["Figure", List[List["Axes3D"]]]

project classmethod 

project(
    func: (
        Callable[[float, float], float] | Callable[[ndarray, ndarray], ndarray]
    ),
    deg: int,
    n_sample: int = N_SAMPLE_DEFAULT,
) -> ndarray

Project a spherical function onto the spherical harmonics basis.

The coefficients of the spherical harmonics basis are given by

\[ c_n^m = \int_{\Omega} f(\theta, \phi) \overline{Y_n^m(\theta, \phi)} d\Omega \]
PARAMETER DESCRIPTION
deg

Degree of the spherical harmonics basis.

TYPE: int

func

Function that takes theta and phi as arguments and returns the function value.

TYPE: callable

n_sample

Number of samples, by default 1000.

TYPE: int DEFAULT: N_SAMPLE_DEFAULT

RETURNS DESCRIPTION
ndarray

An array of shape (deg+1, 2*deg+1) containing the coefficients of the spherical harmonics basis, i.e.::

c(0,0)  nan     nan    nan    nan
c(1,-1) c(1,0)  c(1,1) nan    nan
c(2,-2) c(2,-1) c(2,0) c(2,1) c(2,2)