droplets.tools package

droplets.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

radius_from_surface

Return the radius of a sphere with a given surface area

make_radius_from_volume_compiled

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

make_volume_from_radius_compiled

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

make_surface_from_radius_compiled

Return a function calculating the surface area of a sphere

points_cartesian_to_spherical

Convert points from Cartesian to spherical coordinates

points_spherical_to_cartesian

Convert points from spherical to Cartesian coordinates

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

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: ndarray) 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: ndarray) 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
  • surface (float or ndarray) – Surface area of the sphere

  • dim (int) – Dimension of the space

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
  • volume (float or ndarray) – Volume of the sphere

  • dim (int) – Dimension of the space

Returns

Radius of the sphere

Return type

float or ndarray

spherical_harmonic_real(degree: int, order: int, θ: float, φ: 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) 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) 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

surface_from_radius(radius: TNumArr, dim: int) TNumArr[source]

Return the surface area of a sphere with a given radius

Parameters
  • radius (float or ndarray) – Radius of the sphere

  • dim (int) – Dimension of the space

Returns

Surface area of the sphere

Return type

float or ndarray