Conventions

Conventions#

This document details the conventions used in this library. Hence, unless specified otherwise, the following conventions apply everywhere.

XYZ coordinates#

Those coordinates are absolute, and are by default expressed in the three-dimensional right-handed XYZ space, where units are meters.

Arrays expressing such coordinates are always of the type and shape Float[Array, "... 3"].

Fig. 1 shows how Cartesian coordinates are defined.

Spherical coordinates#

Those coordinates are relative to some origin, and are by default expressed in the three-dimensional \(r\theta\varphi\) space, where units are meters for \(r\), and radians for \(\theta\) and \(\varphi\). We follow the physical convention (see Fig. 2), where \(\theta\) is referred to as the polar angle, and \(\varphi\) as the azimuth angle.

Arrays expressing such coordinates are mainly of the type and shape Float[Array, "... 3"], but sometimes the radial component \(r\) is omitted which means Float[Array, "... 2"] arrays can also be used in some places, usually as a means to indicate a radial component equal to 1.

Fig. 2 shows how spherical coordinates are defined.

Coordinate transformations#

Below are descriptions of how to transform from one coordinate system to another.

Cartesian to spherical#

Spherical coordinates can be derived from Cartesian coordinates using the following relation:

\[\begin{split}\begin{bmatrix}r \\ \theta \\ \varphi \end{bmatrix} = \begin{bmatrix} \sqrt{x^2 + y^2 + z^2} \\ \arccos(z / \sqrt{x^2 + y^2 + z^2}) \\ \arctan(y / x) \end{bmatrix},\ \ \ 0 \le \theta \le \pi,\ \ \ -\pi < \varphi < \pi,\end{split}\]

and is implemented by cartesian_to_spherical.

Spherical to Cartesian#

Conversely, it is possible to derive Cartesian coordinates from spherical coordinates using:

\[\begin{split}\begin{bmatrix} x \\ y \\ z \end{bmatrix} = \begin{bmatrix} r\sin\theta\cos\varphi \\ r\sin\theta\sin\varphi \\ r\cos\theta\end{bmatrix},\end{split}\]

and is implemented by spherical_to_cartesian.