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.
polar_coordinates	Return polar coordinates associated with grid points.
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)

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_radius_from_volume_nd_compiled()

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

Returns:

A function that calculate the radius from a volume and dimension

Return type:

function

make_surface_from_radius_compiled(dim)

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)

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

make_volume_from_radius_nd_compiled()

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

Returns:

A function that calculates the volume using a radius and dimension

Return type:

function

points_cartesian_to_spherical(points)

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)

Convert points from spherical to Cartesian coordinates.

Parameters:

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

Returns:

Points in Cartesian coordinates

Return type:

ndarray

polar_coordinates(grid: GridBase, *, origin: ndarray[tuple[int, ...], dtype[integer | floating]] | None = None, ret_angle: Literal[False] = False) → ndarray[tuple[int, ...], dtype[integer | floating]]

polar_coordinates(grid: GridBase, *, origin: ndarray[tuple[int, ...], dtype[integer | floating]] | None = None, ret_angle: Literal[True]) → tuple[ndarray[tuple[int, ...], dtype[integer | floating]], ...]

Return polar coordinates associated with grid points.

Parameters:

• grid (GridBase) – The grid whose cell coordinates are used.

• origin (ndarray, optional) – Cartesian coordinates of the origin at which polar coordinates are anchored.

• ret_angle (bool) – Determines whether angles are returned alongside the distance. If False only the distance to the origin is returned for each support point of the grid. If True, the distance and angles are returned. For a 1d system system, the angle is defined as the sign of the difference between the point and the origin, so that angles can either be 1 or -1. For 2d systems and 3d systems, polar coordinates and spherical coordinates are used, respectively.

Returns:

Coordinates values in polar coordinates

Return type:

ndarray or tuple of ndarray

radius_from_surface(surface, dim)

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, dim)

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, order, θ, φ)

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 function is evaluated.

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

Returns:

The value of the spherical harmonics

Return type:

float

spherical_harmonic_real_k(k, θ, φ)

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 function is evaluated.

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

Returns:

The value of the spherical harmonics

Return type:

float

spherical_harmonic_symmetric(degree, θ)

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

Parameters:

• degree (int) – Degree of the spherical harmonics

• θ (float) – Azimuthal angle at which function is evaluated (in \([0, \pi]\))

Returns:

The value of the spherical harmonics

Return type:

float

spherical_index_count(l)

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)

Checks whether the modes captures all orders for maximal degree.

Parameters:

k_count (int) – The number of modes considered

Returns:

indicates whether k_count is optimally chosen.

Return type:

bool

spherical_index_k(degree, order=0)

Returns the mode k from the degree degree and order order

Parameters:

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

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

Raises:

ValueError – if order < -degree or order > degree

Returns:

a combined index k

Return type:

int

spherical_index_lm(k)

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 associated with the combined index

Return type:

tuple

surface_from_radius(radius, dim)

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

volume_from_radius(radius, dim)

Return the volume of a sphere with a given radius.

Parameters:

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

• dim (int) – Dimension of the space

Returns:

Volume of the sphere

Return type:

float or ndarray