Mathematical utilities (skhep.math)¶
Module for mathematical functions and utilities.
This module contains in particular:
 Vector classes.
 Geometry classes.
Mathematical functions relevant to kinematics¶

skhep.math.kinematics.
Armenteros_Podolanski_variables
(pplus_3Dvec, pminus_3Dvec)¶ Calculate the Armenteros Podolanski [APPaper] variables \((\alpha,q_T)\) for a 2body decay.
\[ \begin{align}\begin{aligned}\alpha = \frac{p_L^+  p_L^}{p_L^+ + p_L^}\\q_T = \frac{ p^ \times p^{\mathrm mother}}{p^{\mathrm mother}}\end{aligned}\end{align} \]where the longitudinal momentum along the direction of flight of the mother particle is
\[p_L^\pm = \frac{p^\pm \cdot p^{\mathrm mother}}{p^{\mathrm mother}}\]and \(q_T\) is the transverse momentum of the daughter particles with respect to the direction of flight of the mother particle.
These expressions can be simplified to
\[ \begin{align}\begin{aligned}\alpha = \frac{p^+^2  p^^2}{p^+ + p^^2}\\q_T = \frac{ p^+ \times p^ }{p^+ + p^}\end{aligned}\end{align} \]Parameters: Returns: Return type: Tuple \((\alpha,q_T)\).
References
[APPaper]  Podolanski and R. Armenteros, III. Analysis of Vevents, The London, Edinburgh, and Dublin Philosophical Magazine and Journal of Science 45 (1954) 13, http://dx.doi.org/10.1080/14786440108520416

skhep.math.kinematics.
Kallen_function
(x, y, z)¶ The Kallen function, aka triangle or lambda function, named after physicist Anders Olof Gunnar Kallen [Kallen].
\[\begin{split}\begin{eqnarray} \lambda(x,y,z) &=& x^2 + y^2 + z^2  2 x y  2 y z  2 z x \\ &=& (xyz)^2  4 y z \\ &=& [ x  (\sqrt{y}+\sqrt{z})^2 ] [ x  (\sqrt{y}\sqrt{z})^2 ] \,\,\,\mathrm{if} \,\,\,y, z > 0 \end{eqnarray}\end{split}\]Example
Calculate in the rest frame of a particle of mass M decaying to 2 particles labeled 1 and 2, \(P (M) \to p1 (m1) + p2 (m2)\), the momenta of 1 and 2 given by \(p = \mathbf{p1} = \mathbf{p2}\):
>>> from skhep.math import Kallen_function >>> from skhep.units import MeV, GeV >>> from math import sqrt >>> M = 5.279 * GeV; m1 = 493.7 * MeV; m2 = 139.6 * MeV >>> p = sqrt( Kallen_function( M**2, m1**2, m2**2 ) ) / (2*M) >>> print p / GeV # print the CMS momentum in GeV 2.61453580221
References
[Kallen] https://en.wikipedia.org/wiki/K%C3%A4ll%C3%A9n_function

skhep.math.kinematics.
lifetime_to_width
(tau)¶ Convert from a particle lifetime to a decay width.
Parameters: tau (float > 0) – Particle lifetime, typically in picoseconds (any HEP time unit is OK). Returns: Return type: Particle decay width, in the HEP standard energy unit MeV.

skhep.math.kinematics.
width_to_lifetime
(Gamma)¶ Convert from a particle decay width to a lifetime.
Parameters: Gamma (float > 0) – Particle decay width, typically in MeV (any HEP energy unit is OK). Returns: Return type: Particle lifetime, in the HEP standard time unit ns.
Vector classes¶
Two vector classes are available:
Vector3D
: a 3dimensional vector.LorentzVector
: a Lorentz vector, i.e. a 4dimensional Minkowski spacetime vector or a 4momentum vector. The metric is (1,1,1,+1).

class
skhep.math.vectors.
LorentzVector
(x=0.0, y=0.0, z=0.0, t=0.0)¶ Class representing a Lorentz vector, either a 4dimensional Minkowski spacetime vector or a 4momentum vector. The 4vector components can be seen as (x,y,z,t) or (px,py,pz,E).
 Constructors:
 __init__(x=0., y=0., z=0., t=0.) from4vector(avector) from3vector(vector3d, t)

beta
¶ Return \(\beta = v/c\).

boost
(*args)¶ Apply a Lorentz boost on the Lorentz vector.

boostvector
¶ Return the spatial component divided by the time component.

copy
()¶ Get a copy of the LorentzVector.
Example
>>> v = ... >>> v1 = v.copy()

costheta
()¶ Return the cosinus of the spherical coordinate theta.

deltaeta
(other)¶ Return the pseudorapidity difference, \(\Delta \eta\), with another Lorentz vector.

deltaphi
(other)¶ Return the phi angle difference, \(\Delta \phi\), with another Lorentz vector.

deltar
(other)¶ Return \(\Delta R\) the distance in (eta,phi) space with another Lorentz vector, defined as: \(\Delta R = \sqrt{(\Delta \eta)^2 + (\Delta \phi)^2}\)

dot
(other)¶ Dot product with another Lorentz vector.

e
¶ Return the energy/time component, aka momentum coordinate at position 3.

et
¶ Return the transverse energy.

eta
¶ Return the pseudorapidity.

classmethod
from3vector
(vector3d, t)¶ Constructor from a Vector3D and the time/energy component.

classmethod
from4vector
(other)¶ Copy constructor.

classmethod
fromiterable
(values)¶ Constructor from a suitable iterable object. Suitable means here that all entries are numbers and the length equals 4.

gamma
¶ Return \(\gamma = 1/\sqrt{1\beta^2}\).

islightlike
()¶ Check if Lorentz Vector is lightlike.

isspacelike
()¶ Check if Lorentz Vector is spacelike.

istimelike
()¶ Check if Lorentz Vector is timelike.

m
¶ Return the invariant mass.

m2
¶ Return the square of the invariant mass.

mag
¶ Magnitude, a.k.a. norm, of the Lorentz vector.

mag2
¶ Square of the magnitude, a.k.a. norm, of the Lorentz vector.

mass
¶ Return the invariant mass.

mass2
¶ Return the square of the invariant mass.

mt
¶ Return the transverse mass.

mt2
¶ Return the square of the transverse mass.

p
¶ Return the momentum, aka norm of the momentum vector.

perp
¶ Transverse component of the spatial components.

perp2
¶ Square of the transverse component, in the (x,y) plane, of the spatial components.

phi
(deg=False)¶ Return the spherical or cylindrical coordinate phi.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

pseudorapidity
¶ “Return the pseudorapidity. Alternative to eta() method.

pt
¶ Return the transverse momentum, aka transverse component of the momentum vector.

px
¶ Return the Vector3D coordinate px, aka first momentum coordinate at position 0.

py
¶ Return the Vector3D coordinate px, aka second momentum coordinate at position 1.

pz
¶ Return the Vector3D coordinate pz, aka third momentum coordinate at position 2.

rapidity
¶ Return the rapidity.

rotate
(angle, *args)¶ Rotate vector by a given angle (in radians) around a given axis.

rotatex
(angle)¶ Rotate vector by a given angle (in radians) around the x axis.

rotatey
(angle)¶ Rotate vector by a given angle (in radians) around the y axis.

rotatez
(angle)¶ Rotate vector by a given angle (in radians) around the z axis.

set
(x, y, z, t)¶ Update/set all components at once.

setptetaphie
(pt, eta, phi, e)¶ Set the transverse momentum, the pseudorapidity, the angle phi and the energy.

setptetaphim
(pt, eta, phi, m)¶ Set the transverse momentum, the pseudorapidity, the angle phi and the mass.

setpxpypze
(px, py, pz, e)¶ Set the px,py,pz components and the energy.

setpxpypzm
(px, py, pz, m)¶ Set the px,py,pz components and the mass.

t
¶ Return the time/energy component, aka coordinate at position 3.

theta
(deg=False)¶ Return the spherical coordinate theta.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

tolist
()¶ Return the LorentzVector as a list.

transversemass
¶ Return the transverse mass.

transversemass2
¶ Return the square of the transverse mass.

vector
¶ Return a copy of the vector of spatial components.

x
¶ Return the coordinate x, aka first coordinate at position 0.

y
¶ Return the coordinate x, aka second coordinate at position 1.

z
¶ Return the coordinate z, aka third coordinate at position 2.

class
skhep.math.vectors.
Vector3D
(x=0.0, y=0.0, z=0.0)¶ Vector class in 3 dimensions.
 Constructors:
 __init__(x=0., y=0., z=0.) origin() frompoint(x, y, z) fromvector(avector) fromsphericalcoords(r, theta, phi) fromcylindricalcoords(rho, phi, z) fromiterable(values)

angle
(other, deg=False)¶ Angle with respect to another vector.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

copy
()¶ Get a copy of the vector.
Example
>>> v = ... >>> v1 = v.copy()

cosdelta
(other)¶ Get cos(angle) with respect to another vector

costheta
()¶ Return the cosine of the spherical coordinate theta.

cross
(other)¶ Cross product with another vector.

dot
(other)¶ Dot product with another vector.

classmethod
fromcylindricalcoords
(rho, phi, z)¶ Constructor from a space point specified in cylindrical coordinates.
Parameters:  rho (radial distance from the zaxis (rho > 0)) –
 phi (azimuthal angle in radians (phi in [pi, pi) rad)) –
 z (height) –

classmethod
fromiterable
(values)¶ Constructor from a suitable iterable object. Suitable means here that all entries are numbers and the length equals 3.

classmethod
frompoint
(x, y, z)¶ Constructor from an explicit space point.

classmethod
fromsphericalcoords
(r, theta, phi)¶ Constructor from a space point specified in spherical coordinates.
Parameters:  r (radius, the radial distance from the origin (r > 0)) –
 theta (inclination in radians (theta in [0, pi] rad)) –
 phi (azimuthal angle in radians (phi in [0, 2pi) rad)) –

classmethod
fromvector
(other)¶ Copy constructor.

isantiparallel
(other)¶ Check if another vector is antiparallel. Two vectors are antiparallel if they have opposite direction but not necessarily the same magnitude.

iscollinear
(other)¶ Check if another vector is collinear Two vectors are collinear if they have parallel or antiparallel

isopposite
(other)¶ Two vectors are opposite if they have the same magnitude but opposite direction.

isparallel
(other)¶ Check if another vector is parallel. Two vectors are parallel if they have the same direction but not necessarily the same magnitude.

isperpendicular
(other)¶ Check if another vector is perpendicular.

mag
¶ Magnitude, a.k.a. norm, of the vector.

mag2
¶ Square of the magnitude, a.k.a. norm, of the vector.

classmethod
origin
()¶ Shortcut constuctor for the origin (x=0.,y=0.,z=0.). Equivalent to the default constructor Vector3D().

phi
(deg=False)¶ Return the spherical or cylindrical coordinate phi.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

r
¶ Return the spherical coordinate r.

rho
¶ Return the cylindrical coordinate rho.

rotate
(angle, *args)¶ Rotate vector by a given angle (in radians) around a given axis.

rotatex
(angle)¶ Rotate vector by a given angle (in radians) around the x axis.

rotatey
(angle)¶ Rotate vector by a given angle (in radians) around the y axis.

rotatez
(angle)¶ Rotate vector by a given angle (in radians) around the z axis.

set
(x, y, z)¶ Update the vector components all at once.

theta
(deg=False)¶ Return the spherical coordinate theta.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

tolist
()¶ Return the vector as a list.

unit
()¶ Return the normalized vector, i.e. the unit vector along the direction of itself.

x
¶ Return the x, aka first coordinate at position 0.

y
¶ Return the y, aka second coordinate at position 1.

z
¶ Return the z, aka third coordinate at position 2.
Geometry classes¶
Three geometry classes are available:
* Point3D
: a point in 3dimensional space
* Line3D
: a line in 3dimensional space
* Plane3D
: a plane in 3dimensional space

class
skhep.math.geometry.
Vector3D
(x=0.0, y=0.0, z=0.0)¶ Vector class in 3 dimensions.
 Constructors:
 __init__(x=0., y=0., z=0.) origin() frompoint(x, y, z) fromvector(avector) fromsphericalcoords(r, theta, phi) fromcylindricalcoords(rho, phi, z) fromiterable(values)

angle
(other, deg=False)¶ Angle with respect to another vector.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

copy
()¶ Get a copy of the vector.
Example
>>> v = ... >>> v1 = v.copy()

cosdelta
(other)¶ Get cos(angle) with respect to another vector

costheta
()¶ Return the cosine of the spherical coordinate theta.

cross
(other)¶ Cross product with another vector.

dot
(other)¶ Dot product with another vector.

classmethod
fromcylindricalcoords
(rho, phi, z)¶ Constructor from a space point specified in cylindrical coordinates.
Parameters:  rho (radial distance from the zaxis (rho > 0)) –
 phi (azimuthal angle in radians (phi in [pi, pi) rad)) –
 z (height) –

classmethod
fromiterable
(values)¶ Constructor from a suitable iterable object. Suitable means here that all entries are numbers and the length equals 3.

classmethod
frompoint
(x, y, z)¶ Constructor from an explicit space point.

classmethod
fromsphericalcoords
(r, theta, phi)¶ Constructor from a space point specified in spherical coordinates.
Parameters:  r (radius, the radial distance from the origin (r > 0)) –
 theta (inclination in radians (theta in [0, pi] rad)) –
 phi (azimuthal angle in radians (phi in [0, 2pi) rad)) –

classmethod
fromvector
(other)¶ Copy constructor.

isantiparallel
(other)¶ Check if another vector is antiparallel. Two vectors are antiparallel if they have opposite direction but not necessarily the same magnitude.

iscollinear
(other)¶ Check if another vector is collinear Two vectors are collinear if they have parallel or antiparallel

isopposite
(other)¶ Two vectors are opposite if they have the same magnitude but opposite direction.

isparallel
(other)¶ Check if another vector is parallel. Two vectors are parallel if they have the same direction but not necessarily the same magnitude.

isperpendicular
(other)¶ Check if another vector is perpendicular.

mag
¶ Magnitude, a.k.a. norm, of the vector.

mag2
¶ Square of the magnitude, a.k.a. norm, of the vector.

classmethod
origin
()¶ Shortcut constuctor for the origin (x=0.,y=0.,z=0.). Equivalent to the default constructor Vector3D().

phi
(deg=False)¶ Return the spherical or cylindrical coordinate phi.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

r
¶ Return the spherical coordinate r.

rho
¶ Return the cylindrical coordinate rho.

rotate
(angle, *args)¶ Rotate vector by a given angle (in radians) around a given axis.

rotatex
(angle)¶ Rotate vector by a given angle (in radians) around the x axis.

rotatey
(angle)¶ Rotate vector by a given angle (in radians) around the y axis.

rotatez
(angle)¶ Rotate vector by a given angle (in radians) around the z axis.

set
(x, y, z)¶ Update the vector components all at once.

theta
(deg=False)¶ Return the spherical coordinate theta.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

tolist
()¶ Return the vector as a list.

unit
()¶ Return the normalized vector, i.e. the unit vector along the direction of itself.

x
¶ Return the x, aka first coordinate at position 0.

y
¶ Return the y, aka second coordinate at position 1.

z
¶ Return the z, aka third coordinate at position 2.

class
skhep.math.geometry.
Point3D
(*args, **kwargs)¶ Point in 3D space.

copy
()¶ Make a copy of this point.

distance
(other)¶ Get ‘distance’ between point and other object.

classmethod
fromcylindricalcoords
(rho, phi, z)¶ Constructor from a space point specified in cylindrical coordinates.
Parameters:  rho (radial distance from the zaxis (rho > 0)) –
 phi (azimuthal angle in radians (phi in [pi, pi) rad)) –
 z (height) –

classmethod
fromiterable
(values)¶ Constructor from a suitable iterable object. Suitable means here that all entries are numbers and the length equals 3.

classmethod
frompoint
(x, y, z)¶ Constructor from an explicit space point.

classmethod
fromsphericalcoords
(r, theta, phi)¶ Constructor from a space point specified in spherical coordinates.
Parameters:  r (radius, the radial distance from the origin (r > 0)) –
 theta (inclination in radians (theta in [0, pi] rad)) –
 phi (azimuthal angle in radians (phi in [0, 2pi) rad)) –

classmethod
fromvector
(other)¶ Copy constructor.

mag
¶ Magnitude, a.k.a. norm, of the point.

mag2
¶ Square of the magnitude, a.k.a. norm, of the point.

on_line
(line)¶ In the point on the line?

on_plane
(plane)¶ Is the point on the plane?

classmethod
origin
()¶ Shortcut constuctor for the origin (x=0.,y=0.,z=0.). Equivalent to the default constructor Point3D().

phi
¶ Return the spherical or cylindrical coordinate phi.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

rho
¶ Return the cylindrical coordinate rho.

theta
¶ Return the spherical coordinate theta.
Parameters: deg (float, optional) – Return the angle in degrees (default is radians).

tolist
()¶ Return the vector as a list.

x
¶ Return the x, aka first coordinate at position 0.

y
¶ Return the y, aka second coordinate at position 1.

z
¶ Return the z, aka third coordinate at position 2.


class
skhep.math.geometry.
Line3D
(point=<Point3D(x=0, y=0, z=0)>, vector=<Vector3D (x=0, y=0, z=1)>)¶ Line in 3D space. Line is defined by a point on line and by the direction.

angle
(other)¶ Get the ‘angle’ between a line and other object.

closest_point
(point)¶ Get the point on line that is closest to the given point in space.
Example
>>> line = ... >>> point = ... >>> closest = line.closest_point ( point )

closest_point_param
(point)¶ Get the ‘mu’ parameter of the point on line that is closest to the given point in space.
Example
>>> line = ... >>> point = ... >>> mu = line.closest_point_param ( point )

closest_points
(line)¶ Get two points on lines that is closest to each other.
Example
>>> line1 = ... >>> line2 = ... >>> p1 , p2 = line1.closest_points ( line2 )

closest_points_params
(line)¶ Get the ‘mu’ parameters of two points on lines that is closest to each other.
Example
>>> line1 = ... >>> line2 = ... >>> mu1 , mu2 = line1.closest_points_param ( line2 )

copy
()¶ Make a copy of this line.

distance
(other)¶ Get ‘distance’ between line and other object.
Examples
>>> line = ... >>> point = ... >>> line2 = ... >>> plane = ... >>> print line.distance ( line2 ) >>> print line.distance ( point ) >>> print line.distance ( plane )

classmethod
from_line
(line)¶ Create the line from anoother line.

classmethod
from_points
(point1, point2)¶ Create the line from two points.
Parameters:  point1 (the first point on the line) –
 point2 (the second point on the line) –

intersect
(other)¶ Get the ‘intersection’ between a line and other object.

iscollinear
(other)¶ Is the line collinear to another line or vector?

on_plane
(plane)¶ Is the line on the plane?

point_on_line
(mu)¶ Get the point on line, that corresponds to parameter ‘mu’.
Example
>>> line = ... >>> p0 = line.point_on_line ( 0 ) ## should be equal to line.point >>> p1 = line.point_on_line ( 1 ) ## shodul be equal to line.point+line.vector


class
skhep.math.geometry.
Plane3D
(point=<Point3D(x=0, y=0, z=0)>, normal=<Vector3D (x=0, y=0, z=1)>)¶ Plane in 3D space, defined by a point on plane and by the normal vector.

angle
(other)¶ Get the ‘angle’ between a plane and other object.

copy
()¶ Make a copy of this plane.

distance
(other)¶ Get ‘distance’ between plane and other object.
Examples
>>> line = ... >>> point = ... >>> line2 = ... >>> plane = ... >>> print line.distance ( line2 ) >>> print line.distance ( point ) >>> print line.distance ( plane )

classmethod
from_line_and_point
(line, point)¶ Create the plane from the line and point.
Parameters:  line (the line in plane) –
 point (the point in plane) –

classmethod
from_points
(point1, point2, point3)¶ Create the plane from three points.
Parameters:  point1 (the first point on the plane) –
 point2 (the second point on the plane) –
 point3 (the third point on the plane) –

intersect
(other)¶ Get the ‘intersection’ between a line and other object

isparallel
(other)¶ Is the plane collinear to another line, vector or plane?


skhep.math.geometry.
distance
(obj1, obj2)¶ Calculate 3Ddistance between two geometry objects (points, lines, planes).
Examples
>>> line1 = ... >>> line2 = ... >>> point1 = ... >>> point2 = ... >>> plane1 = ... >>> plane2 = ... >>> for o1 in ( line1, line2 , point1 , point2 , plane1 , plane2 ) : ... for o2 in ( line1, line2 , point1 , point2 , plane1 , plane2 ) : ... print distance ( o1 , o2 )