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
|
Compute the angle between vectors. |
|
Convert Cartesian cordinates to spherical coordinates. |
|
A decorator that turn functions into accepting row vectors. |
|
Convert spherical coordinates to Cartesian coordinates. |
Classes
|
- 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. Ifv1is a 2D numpy array, the length must also be consistent with the length ofv2.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. Ifv2is a 2D numpy array, the length must also be consistent with the length ofv1.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
v1orv2contains 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’, aRunTimeErrorwill 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