e15190.utilities.geometry

A submodule that deals with 2D and 3D geometry.

Surprisingly, by the time of this writing, there does not seem to be any libraries that can do several common geometrical manipulations well, in the sense that they are pythonic, vectorized, and match the convention in physics.

Hence, this submodule is written.

Functions

angle_between(v1, v2[, directional, zero_vector])

Compute the angle between vectors.

cartesian_to_spherical(*args)

Convert Cartesian cordinates to spherical coordinates.

deco_to_2darray(func)

A decorator that turn functions into accepting row vectors.

spherical_to_cartesian(*args)

Convert spherical coordinates to Cartesian coordinates.

Classes

CoordinateConversion()

RectangularBar(vertices[, ...])

e15190.utilities.geometry.deco_to_2darray(func)

A decorator that turn functions into accepting row vectors.

The argument func is assumed to be a function that does the following mapping:

\[f: \mathbb{R}^k \rightarrow \mathbb{R}^k \ , (x_1, x_2, ..., x_k) \mapsto (y_1, y_2, ..., y_k)\]

This decorator will turn the function into accepting 2D array of shape (n_vectors, k). The result is equivalent to looping over the rows of the array and calling the undecorated function.

e15190.utilities.geometry.spherical_to_cartesian(*args)

Convert spherical coordinates to Cartesian coordinates.

Parameters

args (3-tuple of scalars, 3-tuple of 1D numpy arrays or a 2D numpy array) –

If the input is a 3-tuple of scalars or a 3-tuple of 1D numpy arrays, they will be interpreted as \((r, \theta, \phi)\).

If the input is a 2D numpy array of shape (n_vectors, 3), it will be interpreted as an array of row vectors \((r, \theta, \phi)\).

\(r\) is the distance from the origin. Accepts any real numbers. Negative radius is simply interpreted as the opposite direction, e.g. \((1, 2, 3)\) becomes \((-1, -2, -3)\).

\(\theta\) is the polar angle of the point in radians. Accepts any real numbers, but expect identical result for any theta with the same \(\mathrm{mod}(\theta, 2\pi)\) value.

\(\phi\) is the azimuthal angle of the point in radians. Accepts any real numbers, but expect identical result for any phi with the same \(\mathrm{mod}(\phi, 2\pi)\) value.

Returns

cartesian_coordinates – Cartesian coordinates of the inputs.

Return type

same as args

e15190.utilities.geometry.cartesian_to_spherical(*args)

Convert Cartesian cordinates to spherical coordinates.

Parameters

args (tuple of scalars, tuple of 1D numpy arrays or a 2D numpy array) –

If the input is a tuple of scalars or a tuple of 1D numpy arrays, they will be interpreted as \((x, y, z)\).

If the input is a 2D numpy array of shape (n_vectors, 3), it will be interpreted as an array of row vectors \((x, y, z)\).

Returns

spherical_coordinates – The returned ranges are \(r \in [0, \infty)\) for radius, \(\theta \in [0, \pi]\) for polar angle and \(\phi \in (-\pi, \pi]\) for azimuthal angle.

Return type

same as args

e15190.utilities.geometry.angle_between(v1, v2, directional=False, zero_vector=None)

Compute the angle between vectors.

Parameters
  • v1 (1D array-like or 2D numpy array of shape (n_vectors, n_dim)) – The first vector or vectors. The dimension of vectors must be consistent with v2. If v1 is a 2D numpy array, the length must also be consistent with the length of v2.

  • v2 (1D array-like or 2D numpy array of shape (n_vectors, n_dim)) – The second vector or vectors. The dimension of vectors must be consistent with v1. If v2 is a 2D numpy array, the length must also be consistent with the length of v1.

  • directional (bool) – Whether to return the directional angle. Only support for vectors of two-dimension, otherwise it will be ignored. If True, the angle will be in the range \((-\pi, \pi]\). If False, the angle will be in the range \([0, \pi]\).

  • zero_vector (None, 'raise' or scalar) – To specify what to do when v1 or v2 contains zero vectors, i.e. vectors with zero norms. If None, nothing will be done. Whatever warnings or errors show up during the calculation will be shown unless otherwise being suppressed. If ‘raise’, a RunTimeError will be raised. If a scalar, the value will be assigned as the angle. The last option is sometimes useful for later identifying zero vectors.

Returns

angles – The angle(s) between the two vectors in radians.

Return type

float or 1D array-like