# 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 2-body 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: pplus_3Dvec (Vector3D) – 3D-momentum vector of the positively-charged daughter particle. pminus_3Dvec (Vector3D) – 3D-momentum vector of the negatively-charged daughter particle. Tuple $$(\alpha,q_T)$$.

References

 [APPaper] Podolanski and R. Armenteros, III. Analysis of V-events, 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 \\ &=& (x-y-z)^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

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). 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). Particle lifetime, in the HEP standard time unit ns.

## Vector classes¶

Two vector classes are available:

• Vector3D : a 3-dimensional vector.
• LorentzVector: a Lorentz vector, i.e. a 4-dimensional Minkowski space-time vector
or a 4-momentum 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 4-dimensional Minkowski space-time vector or a 4-momentum vector. The 4-vector 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 light-like.

isspacelike()

Check if Lorentz Vector is space-like.

istimelike()

Check if Lorentz Vector is time-like.

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 z-axis (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 3-dimensional space * Line3D : a line in 3-dimensional space * Plane3D : a plane in 3-dimensional 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 z-axis (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 z-axis (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 3D-distance 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 )