hikari.utility.math_tools

This file contains constants and functions containing purely mathematical information / methods used in the package.

Functions

`angle2rad`(value)	Interpret a unit of given angle value and return this value in radians.
`cart2sph`(x, y, z)	Convert Cartesian coordinates x, y, z
`sph2cart`(r, p, a)	Convert conventional spherical coordinates r, p, a
`det3x3`(matrix)	Calculate a determinant of a 3x3 matrix. Should be usually substituted
`fibonacci_sphere`([samples, seed])	Return a 3D cartesian coordinates of samples number of points
`euler_rodrigues_matrix`(a, b, c, d)	Return a rotation matrix based on a Euler-Rodrigues parametrisation. For
`rotation_from`(from_, to)	Return matrix associated with rotation of vector from_ onto to.
`rotation_around`(axis, by)	Return matrix associated with counterclockwise rotation about axis through
`weighted_quantile`(values, quantiles[, weights])	A function to approximate quantiles based on many weighted points. Quantiles

Module Contents

hikari.utility.math_tools.angle2rad(value)[source]

Interpret a unit of given angle value and return this value in radians. Values in range between -3.15 and 3.15 are interpreted as given in radians. Values outside this range are interpreted as given in degrees.

The function can be used to dynamically interpret and accept both radian and degrees and return the value in angles. Should you not need this functionality, please use numpy’s rad2deg and deg2rad instead.

Example:

>>> angle2rad(np.pi)
3.141592653589793
>>> angle2rad(180)
3.141592653589793
>>> angle2rad(2*np.pi)
0.1096622711232151

Please mind that in the last case the value given in radians was treated as given in degrees and wrongly recalculated to radians again.

Parameters:: value (float) – Angle value given in angles or radians
Returns:: Angle value expressed in radians
Return type:: float

hikari.utility.math_tools.cart2sph(x, y, z)[source]

Convert Cartesian coordinates x, y, z to conventional spherical coordinates r, p, a

Parameters:

x (float or np.ndarray) – Cartesian coordinate or vector x
y (float or np.ndarray) – Cartesian coordinate or vector y
z (float or np.ndarray) – Cartesian coordinates or vector z

Returns:

Spherical coordinates: radius, polar angle, and azimuth angle

Return type:

np.ndarray

hikari.utility.math_tools.sph2cart(r, p, a)[source]

Convert conventional spherical coordinates r, p, a to Cartesian coordinates x, y, z

Parameters:

r (float or np.ndarray) – Spherical coordinate or vector radius
p (float or np.ndarray) – Spherical coordinate or vector polar angle
a (float or np.ndarray) – Spherical coordinate or vector azimuth angle

Returns:

Cartesian coordinates: x, y, and z

Return type:

np.ndarray

hikari.utility.math_tools.det3x3(matrix)[source]

Calculate a determinant of a 3x3 matrix. Should be usually substituted by numpy.linalg.det, but is indispensable for matrices with uncertainties.

Parameters:: matrix (numpy.ndarray or uncertainties.unumpy.matrix) – 3x3 array/matrix which allows for 2d indexing
Returns:: Determinant of the matrix
Return type:: int or float or uncertainties.core.Variable

hikari.utility.math_tools.fibonacci_sphere(samples=1, seed=1337)[source]

Return a 3D cartesian coordinates of samples number of points evenly distributed on a surface of a unit sphere at (0, 0, 0).

The algorithm utilised in this function gives a uniform distribution on the sphere. Contrary to an uniform distribution on coordinates, this algorithm does not favour points close to poles. For more details see this article.

The function is written so that it does always return the same set of points in order to ensure reproducibility of other methods. A list of other points can be obtained by changing (or even randomising) the value of a seed.

Example:

>>> fibonacci_sphere(4)
array([[ 0.62069, -0.75, -0.22857],
       [-0.44395, -0.25,  0.86047],
       [ 0.41275,  0.25,  0.87587],
       [-0.61208,  0.75, -0.25072]])
>>> fibonacci_sphere(4)
array([[ 0.62069, -0.75, -0.22857],
       [-0.44395, -0.25,  0.86047],
       [ 0.41275,  0.25,  0.87587],
       [-0.61208,  0.75, -0.25072]])
>>> fibonacci_sphere(4, seed=420)
array([[ 0.64040, -0.75,  0.16550],
       [-0.85489, -0.25,  0.45460],
       [ 0.32329,  0.25, -0.91268],
       [ 0.25831,  0.75,  0.60892]])

Parameters:

samples (int) – Number of points to be generated.
seed (any) – A seed value used once to slightly randomise point position.

Returns:

(x,y,z) arrays representing points’ cartesian coordinates.

Return type:

np.array

hikari.utility.math_tools.euler_rodrigues_matrix(a, b, c, d)[source]

Return a rotation matrix based on a Euler-Rodrigues parametrisation. For details, see https://en.wikipedia.org/wiki/Euler%E2%80%93Rodrigues_formula.

Parameters:

a (Union[int, float, uncertainties.UFloat]) – Euler-Rodrigues parameter a
b (Union[int, float, uncertainties.UFloat]) – Euler-Rodrigues parameter b
c (Union[int, float, uncertainties.UFloat]) – Euler-Rodrigues parameter c
d (Union[int, float, uncertainties.UFloat]) – Euler-Rodrigues parameter d

Returns:

3x3 matrix describing rotation

Return type:

numpy.ndarray

hikari.utility.math_tools.rotation_from(from_, to)[source]

Return matrix associated with rotation of vector from_ onto to.

Parameters:

from (np.ndarray) – A 3D vector which will have been rotated onto to.
to (np.ndarray) – A 3D vector onto which from will have been rotated.

Returns:

Matrix associated with rotation of from onto to.

Return type:

np.ndarray

hikari.utility.math_tools.rotation_around(axis, by)[source]

Return matrix associated with counterclockwise rotation about axis through by radians. See Euler-Rodrigues form.,https://stackoverflow.com/q/6802577/

Parameters:

axis (np.ndarray) – A 3D vector about which rotation is performed
by (float) – Angle of rotation in radians

Returns:

Matrix associated with rotation around axis through by.

Return type:

np.ndarray

hikari.utility.math_tools.weighted_quantile(values, quantiles, weights=None)[source]

A function to approximate quantiles based on many weighted points. Quantiles are derived exactly using method 7 of H&F from an unweighted distribution, otherwise they are approximated by comparing two opposing interpolations.

Let A: {1, 2, 2, 2, 3} and B: {1, 2(x3), 3} be seemingly equivalent sets where (x3) denotes triple weight of the “2”. Let q[n] denote quantiles. For set A, q[1/4](A) = q[3/4](A) = 2. However, for set B we need to extrapolate and read quantile from PDF, obtained via linear interpolation. As a result, q[1/4](B) = 4/3 < q[3/4](B) = 2 since f(0) = 1 and f(3/4) = 2 at f(1/4) and the results are always underestimated.

To combat this effect, we can repeat the process for -B: {-3, -2(x3), -1}. Here, q[1/4](-B) = -8/3 and q[3/4](-B) = -2. As a result, the quantile q[n](A) is described a bit better using formula (q[n](B) - q[1-n](-B)) / 2.

Parameters:

values (tuple or list or np.ndarray) – data to be evaluated
quantiles (tuple or list or np.ndarray) – iterable containing desired quartiles between 0 and 1
weights (tuple or list or np.ndarray) – weights of data in the same order

Returns:

array containing approximated quartiles

Return type:

np.ndarray