km3pipe.math

Maths, Geometry, coordinates.

Module Contents

Classes

Polygon	A polygon, to implement containment conditions.
IrregularPrism	Like a cylinder, but the top is an irregular Polygon.
SparseCone	A Cone, represented by sparse samples.

Functions

neutrino_to_source_direction(phi, theta[, radian])	Flip the direction.
source_to_neutrino_direction(azimuth, zenith[, radian])	Flip the direction.
theta(v)	Neutrino direction in polar coordinates.
theta_separg(dir_z)
phi(v)	Neutrino direction in polar coordinates.
phi_separg(dir_x, dir_y)
zenith(v)	Return the zenith angle in radians.
azimuth(v)	Return the azimuth angle in radians.
cartesian(phi, theta[, radius])
angle(v1, v2[, normalized])	Compute the unsigned angle between two vectors. For a stacked input, the
magnitude(v)	Calculates the magnitude of a vector or array of vectors.
angle_between(v1, v2[, axis])	Returns the angle in radians between vectors 'v1' and 'v2'.
unit_vector(vector, **kwargs)	Returns the unit vector of the vector.
pld3(pos, line_vertex, line_dir)	Calculate the point-line-distance for given point and line.
lpnorm(x[, p])
dist(x1, x2[, axis])	Return the distance between two points.
com(points[, masses])	Calculate center of mass for given points.
circ_permutation(items)	Calculate the circular permutation for a given list of items.
hsin(theta)	haversine
space_angle(phi1, theta1, phi2, theta2)	Also called Great-circle-distance --
rotation_matrix(axis, theta)	The Euler–Rodrigues formula.
spherecutmask(center, rmin, rmax, items)	Returns a mask to select items, within a certain radius around a given center.
spherecut(center, rmin, rmax, items)	Select items within a certain radius around a given center.
inertia(x, y, z[, weight])	Inertia tensor, stolen of thomas
g_parameter(time_residual)	stolen from thomas
gold_parameter(time_residual)	stolen from thomas
log_b(arg, base)	Logarithm to any base
qrot(vector, quaternion)	Rotate a 3D vector using quaternion algebra.
qeuler(yaw, pitch, roll)	Convert Euler angle to quaternion.
qrot_yaw(vector, heading)	Rotate vectors using quaternion algebra.
intersect_3d(p1, p2)	Find the closes point for a given set of lines in 3D.

Attributes

log

km3pipe.math.log

km3pipe.math.neutrino_to_source_direction(phi, theta, radian=True)

Flip the direction.

Parameters:

phi, theta: neutrino direction

radian: bool [default=True]

receive + return angles in radian? (if false, use degree)

km3pipe.math.source_to_neutrino_direction(azimuth, zenith, radian=True)

Flip the direction.

Parameters:

zenithfloat

neutrino origin

azimuth: float

neutrino origin

radian: bool [default=True]

receive + return angles in radian? (if false, use degree)

km3pipe.math.theta(v)

Neutrino direction in polar coordinates.

Parameters:

varray (x, y, z)

Notes

Downgoing event: theta = 180deg Horizont: 90deg Upgoing: theta = 0

Angles in radians.

km3pipe.math.theta_separg(dir_z)

km3pipe.math.phi(v)

Neutrino direction in polar coordinates.

Parameters:

varray (x, y, z)

Notes

phi, theta is the opposite of zenith, azimuth.

Angles in radians.

km3pipe.math.phi_separg(dir_x, dir_y)

km3pipe.math.zenith(v)

Return the zenith angle in radians.

Parameters:

varray (x, y, z)

Notes

Defined as ‘Angle respective to downgoing’. Downgoing event: zenith = 0 Horizont: 90deg Upgoing: zenith = 180deg

km3pipe.math.azimuth(v)

Return the azimuth angle in radians.

Parameters:

varray (x, y, z)

Notes

phi, theta is the opposite of zenith, azimuth.

This is the ‘normal’ azimuth definition – beware of how you define your coordinates. KM3NeT defines azimuth differently than e.g. SLALIB, astropy, the AAS.org

km3pipe.math.cartesian(phi, theta, radius=1)

km3pipe.math.angle(v1, v2, normalized=False)

Compute the unsigned angle between two vectors. For a stacked input, the angle is computed pairwise. Inspired by the “vg” Python package.

Parameters:

v1np.array

With shape (3,) or a kx3 stack of vectors.

v2np.array

A vector or stack of vectors with the same shape as v1.

normalizedbool

By default, the vectors will be normalised unless normalized is True.

Returns:

A float or a vector of floats with the angle in radians.

km3pipe.math.magnitude(v)

Calculates the magnitude of a vector or array of vectors.

Parameters:

vnp.array

With shape (3,) or kx3 stack of vectors.

Returns:

A float or a vector of floats with the magnitudes.

km3pipe.math.angle_between(v1, v2, axis=0)

Returns the angle in radians between vectors ‘v1’ and ‘v2’.

If axis=1 it evaluates the angle between arrays of vectors.

Examples

>>> angle_between((1, 0, 0), (0, 1, 0))
1.5707963267948966
>>> angle_between((1, 0, 0), (1, 0, 0))
0.0
>>> angle_between((1, 0, 0), (-1, 0, 0))
3.141592653589793
>>> v1 = np.array([[1, 0, 0], [1, 0, 0]])
>>> v2 = np.array([[0, 1, 0], [-1, 0, 0]])
>>> angle_between(v1, v2, axis=1)
array([1.57079633, 3.14159265])

km3pipe.math.unit_vector(vector, **kwargs)

Returns the unit vector of the vector.

km3pipe.math.pld3(pos, line_vertex, line_dir)

Calculate the point-line-distance for given point and line.

km3pipe.math.lpnorm(x, p=2)

km3pipe.math.dist(x1, x2, axis=0)

Return the distance between two points.

Set axis=1 if x1 is a vector and x2 a matrix to get a vector of distances.

km3pipe.math.com(points, masses=None)

Calculate center of mass for given points. If masses is not set, assume equal masses.

km3pipe.math.circ_permutation(items)

Calculate the circular permutation for a given list of items.

km3pipe.math.hsin(theta)

haversine

km3pipe.math.space_angle(phi1, theta1, phi2, theta2)

Also called Great-circle-distance –

use long-ass formula from wikipedia (last in section): https://en.wikipedia.org/wiki/Great-circle_distance#Computational_formulas

Space angle only makes sense in lon-lat, so convert zenith -> latitude.

km3pipe.math.rotation_matrix(axis, theta)

The Euler–Rodrigues formula.

Return the rotation matrix associated with counterclockwise rotation about the given axis by theta radians.

Parameters:

axis: vector to rotate around

theta: rotation angle [rad]

km3pipe.math.spherecutmask(center, rmin, rmax, items)

Returns a mask to select items, within a certain radius around a given center.

Parameters:

center: array of shape(3,)

central point of the sphere

rmin: float

minimum radius of the sphere selection

rmax: float

maximum radius of the sphere selection

items: array of shape (n, 3) or iterable with pos_[xyz]-attributed items

the items to cut on

Returns:

mask of the array of shape (n, 3) or iterable with pos_[xyz]-attributed items.

km3pipe.math.spherecut(center, rmin, rmax, items)

Select items within a certain radius around a given center. This function calls spherecutmask() to create the selection mask and returns the selected items.

Parameters:

center: array of shape(3,)

central point of the sphere

rmin: float

minimum radius of the sphere selection

rmax: float

maximum radius of the sphere selection

items: array of shape (n, 3) or iterable with pos_[xyz]-attributed items

the items to cut on

Returns:

array of shape (k, 3) or iterable with pos_[xyz]-attributed items

items which survived the cut.

class km3pipe.math.Polygon(vertices)

A polygon, to implement containment conditions.

contains(points)

contains_xy(x, y)

class km3pipe.math.IrregularPrism(xy_vertices, z_min, z_max)

Like a cylinder, but the top is an irregular Polygon.

contains(points)

contains_xyz(x, y, z)

class km3pipe.math.SparseCone(spike_pos, bottom_center_pos, opening_angle)

A Cone, represented by sparse samples.

This samples evenly spaced points from the base circle.

Parameters:

spike_poscoordinates of the top

bottom_center_poscenter of the bottom circle

opening_anglecone opening angle, in rad

theta, axis to mantle, not mantle-mantle. So this is the angle to the axis, and mantle-to-mantle (aperture) is 2 theta.

property sample_axis

sample_circle(n_angles=4)

sample(n_circle=4)

km3pipe.math.inertia(x, y, z, weight=None)

Inertia tensor, stolen of thomas

km3pipe.math.g_parameter(time_residual)

stolen from thomas

km3pipe.math.gold_parameter(time_residual)

stolen from thomas

km3pipe.math.log_b(arg, base)

Logarithm to any base

km3pipe.math.qrot(vector, quaternion)

Rotate a 3D vector using quaternion algebra.

Implemented by Vladimir Kulikovskiy.

Parameters:

vectornp.array

quaternionnp.array

Returns:

np.array

km3pipe.math.qeuler(yaw, pitch, roll)

Convert Euler angle to quaternion.

Parameters:

yawnumber

pitchnumber

rollnumber

Returns:

np.array

km3pipe.math.qrot_yaw(vector, heading)

Rotate vectors using quaternion algebra.

Parameters:

vectornp.array or list-like (3 elements)

headingthe heading to rotate to [deg]

Returns:

np.array

km3pipe.math.intersect_3d(p1, p2)

Find the closes point for a given set of lines in 3D.

Parameters:

p1(M, N) array_like

Starting points

p2(M, N) array_like

End points.

Returns:

x(N,) ndarray

Least-squares solution - the closest point of the intersections.

Raises:

numpy.linalg.LinAlgError

If computation does not converge.