# 4.6.14. pde.tools.spherical module¶

Module collecting functions for handling spherical geometry

The coordinate systems use the following convention for polar coordinates $$(r, \phi)$$, where $$r$$ is the radial coordinate and $$\phi$$ is the polar angle:

$\begin{split}\begin{cases} x = r \cos(\phi) &\\ y = r \sin(\phi) & \end{cases} \text{for} \; r \in [0, \infty] \; \text{and} \; \phi \in [0, 2\pi)\end{split}$

Similarly, for spherical coordinates $$(r, \theta, \phi)$$, where $$r$$ is the radial coordinate, $$\theta$$ is the azimuthal angle, and $$\phi$$ is the polar angle, we use

$\begin{split}\begin{cases} x = r \sin(\theta) \cos(\phi) &\\ y = r \sin(\theta) \sin(\phi) &\\ z = r \cos(\theta) \end{cases} \text{for} \; r \in [0, \infty], \; \theta \in [0, \pi], \; \text{and} \; \phi \in [0, 2\pi)\end{split}$

The module also provides functions for handling spherical harmonics. These spherical harmonics are described by the degree $$l$$ and the order $$m$$ or, alternatively, by the mode $$k$$. The relation between these values is

$k = l(l + 1) + m$

and

$\begin{split}l &= \text{floor}(\sqrt{k}) \\ m &= k - l(l + 1)\end{split}$

We will use these indices interchangeably, although the mode $$k$$ is preferred internally. Note that we also consider axisymmetric spherical harmonics, where the order is always zero and the degree $$l$$ and the mode $$k$$ are thus identical.

 radius_from_volume Return the radius of a sphere with a given volume volume_from_radius Return the volume of a sphere with a given radius surface_from_radius Return the surface area of a sphere with a given radius spherical_index_k returns the mode k from the degree degree and order order spherical_index_lm returns the degree l and the order m from the mode k spherical_index_count return the number of modes for all indices <= l spherical_index_count_optimal checks whether the modes captures all orders for maximal degree spherical_harmonic_symmetric axisymmetric spherical harmonics with degree degree, so m=0. spherical_harmonic_real real spherical harmonics of degree l and order m spherical_harmonic_real_k real spherical harmonics described by mode k
class PointsOnSphere(points)[source]

Bases: object

class representing points on an n-dimensional unit sphere

Parameters

points (ndarray) – The list of points on the unit sphere

get_area_weights(balance_axes: bool = True)[source]

return the weight of each point associated with the unit cell size

Parameters

balance_axes (bool) – Flag determining whether the weights should be chosen such that the weighted average of all points is the zero vector

Returns

The weight associated with each point

Return type

ndarray

get_distance_matrix()[source]

calculate the (spherical) distances between each point

Returns

the distance of each point to each other

Return type

ndarray

get_mean_separation() [source]

float: calculates the mean distance to the nearest neighbor

classmethod make_uniform(dim: int, num_points: int = None)[source]

create uniformly distributed points on a sphere

Parameters
• dim (int) – The dimension of space

• num_points (int, optional) – The number of points to generate. Note that for one-dimensional spheres (intervals), only exactly two points can be generated

write_to_xyz(path: str, comment: str = '', symbol: str = 'S')[source]

write the point coordinates to a xyz file

Parameters
• path (str) – location of the file where data is written

• comment (str, optional) – comment that is written to the second line

• symbol (str, optional) – denotes the symbol used for the atoms

get_spherical_polygon_area(vertices: numpy.ndarray, radius: float = 1) [source]

Calculate the surface area of a polygon on the surface of a sphere. Based on equation provided here: http://mathworld.wolfram.com/LHuiliersTheorem.html Decompose into triangles, calculate excess for each

Adapted from https://github.com/tylerjereddy/spherical-SA-docker-demo Licensed under MIT License (see copy in root of this project)

Parameters
• vertices (ndarray) – List of vertices (using Cartesian coordinates) that describe the corners of the polygon. The vertices need to be oriented.

• radius (float) – Radius of the sphere

haversine_distance(point1: numpy.ndarray, point2: numpy.ndarray) [source]

Calculate the haversine-based distance between two points on the surface of a sphere. Should be more accurate than the arc cosine strategy. See, for example: https://en.wikipedia.org/wiki/Haversine_formula

Adapted from https://github.com/tylerjereddy/spherical-SA-docker-demo Licensed under MIT License (see copy in root of this project)

Parameters
• point1 (ndarray) – First point(s) on the sphere (given in Cartesian coordinates)

• point2 (ndarray) – Second point on the sphere Second point(s) on the sphere (given in Cartesian coordinates)

Returns

The distances between the points

Return type

ndarray

make_radius_from_volume_compiled(dim: int) Callable[[TNumArr], TNumArr][source]

Return a function calculating the radius of a sphere with a given volume

Parameters

dim (int) – Dimension of the space

Returns

A function that takes a volume and returns the radius

Return type

function

make_surface_from_radius_compiled(dim: int) Callable[[TNumArr], TNumArr][source]

Return a function calculating the surface area of a sphere

Parameters

dim (int) – Dimension of the space

Returns

A function that takes a radius and returns the surface area

Return type

function

make_volume_from_radius_compiled(dim: int) Callable[[TNumArr], TNumArr][source]

Return a function calculating the volume of a sphere with a given radius

Parameters

dim (int) – Dimension of the space

Returns

A function that takes a radius and returns the volume

Return type

function

points_cartesian_to_spherical(points: numpy.ndarray) [source]

Convert points from Cartesian to spherical coordinates

Parameters

points (ndarray) – Points in Cartesian coordinates

Returns

Points (r, θ, φ) in spherical coordinates

Return type

ndarray

points_spherical_to_cartesian(points: numpy.ndarray) [source]

Convert points from spherical to Cartesian coordinates

Parameters

points (ndarray) – Points in spherical coordinates (r, θ, φ)

Returns

Points in Cartesian coordinates

Return type

ndarray

radius_from_surface(surface: TNumArr, dim: int) TNumArr[source]

Return the radius of a sphere with a given surface area

Parameters
Returns

Radius of the sphere

Return type

float or ndarray

radius_from_volume(volume: TNumArr, dim: int) TNumArr[source]

Return the radius of a sphere with a given volume

Parameters
Returns

Radius of the sphere

Return type

float or ndarray

spherical_harmonic_real(degree: int, order: int, θ: float, φ: float) [source]

real spherical harmonics of degree l and order m

Parameters
• degree (int) – Degree $$l$$ of the spherical harmonics

• order (int) – Order $$m$$ of the spherical harmonics

• θ (float) – Azimuthal angle (in $$[0, \pi]$$) at which the spherical harmonics is evaluated.

• φ (float) – Polar angle (in $$[0, 2\pi]$$) at which the spherical harmonics is evaluated.

Returns

The value of the spherical harmonics

Return type

float

spherical_harmonic_real_k(k: int, θ: float, φ: float) [source]

real spherical harmonics described by mode k

Parameters
• k (int) – Combined index determining the degree and order of the spherical harmonics

• θ (float) – Azimuthal angle (in $$[0, \pi]$$) at which the spherical harmonics is evaluated.

• φ (float) – Polar angle (in $$[0, 2\pi]$$) at which the spherical harmonics is evaluated.

Returns

The value of the spherical harmonics

Return type

float

spherical_harmonic_symmetric(degree: int, θ: float) [source]

axisymmetric spherical harmonics with degree degree, so m=0.

Parameters
• degree (int) – Degree of the spherical harmonics

• θ (float) – Azimuthal angle at which the spherical harmonics is evaluated (in $$[0, \pi]$$)

Returns

The value of the spherical harmonics

Return type

float

spherical_index_count(l: int) int[source]

return the number of modes for all indices <= l

The returned value is one less than the maximal mode k required.

Parameters

l (int) – Maximal degree of the spherical harmonics

Returns

The number of modes

Return type

int

spherical_index_count_optimal(k_count: int) bool[source]

checks whether the modes captures all orders for maximal degree

Parameters

k_count (int) – The number of modes considered

spherical_index_k(degree: int, order: int = 0) int[source]

returns the mode k from the degree degree and order order

Parameters
• degree (int) – Degree of the spherical harmonics

• order (int) – Order of the spherical harmonics

Raises

ValueError – if order < -degree or order > degree

Returns

a combined index k

Return type

int

spherical_index_lm(k: int) Tuple[int, int][source]

returns the degree l and the order m from the mode k

Parameters

k (int) – The combined index for the spherical harmonics

Returns

The degree l and order m of the spherical harmonics assoicated with the combined index

Return type

tuple

Return the surface area of a sphere with a given radius

Parameters
Returns

Surface area of the sphere

Return type

float or ndarray

float or ndarray