# 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.``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

  [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 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.

    deg : 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.

    Options:
      deg : 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.

    deg : 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 cosinus 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.

    deg : 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.

    deg : 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.

    deg : 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 cosinus 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.

    deg : 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.

    deg : 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.

    deg : float. Return the angle in degrees (default is radians).

  `rho`

    Return the cylindrical coordinate rho.

  `theta`

    Return the spherical coordinate theta.

    deg : float. 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.

    Example

        >>> 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 Plane is 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.

    Example

        >>> 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 )