Interface for 3D vectors

Contents

Interface for 3D vectors#

3D vectors of all backends have the following attributes, properties, and methods.

For the momentum synonyms, see Interface for 3D momentum.

class vector._methods.VectorProtocolSpatial#
property longitudinal: Longitudinal#

Container of longitudinal coordinates, for use in dispatching to compute functions or to identify coordinate system with isinstance.

property z: Any#

The Cartesian \(z\) coordinate of the vector or every vector in the array.

property theta: Any#

The spherical \(\theta\) coordinate (polar angle) of the vector or every vector in the array (in radians, always between \(0\) (\(+z\)) and \(\pi\) (\(-z\))).

property eta: Any#

The pseudorapidity \(\eta\) coordinate of the vector or every vector in the array (in radians, always between \(0\) (\(+z\)) and \(\pi\) (\(-z\))).

property costheta: Any#

The \(\cos\theta\) coordinate of the vector or every vector in the array (has the same sign as \(z\)).

property cottheta: Any#

The \(\cot\theta\) coordinate of the vector or every vector in the array (has the same sign as \(z\)).

property mag: Any#

The magnitude of the vector(s) in 3D (not including any temporal parts).

property mag2: Any#

The magnitude-squared of the vector(s) in 3D (not including any temporal parts).

scale3D(factor: Any) → SameVectorType#

Returns vector(s) with the 3D part scaled by a factor, not affecting any longitudinal or temporal parts.

property neg3D: SameVectorType#

Returns vector(s) with the 3D part negated, not affecting any longitudinal or temporal parts.

cross(other: VectorProtocolSpatial) → VectorProtocolSpatial#

The 3D cross-product of self with other.

Even if self or other is 4D, the resulting vector(s) is/are 3D.

deltaangle(other: VectorProtocolSpatial | VectorProtocolLorentz) → Any#

Angle in 3D space between self and other, which is always positive, between \(0\) and \(\pi\).

deltaeta(other: VectorProtocolSpatial | VectorProtocolLorentz) → Any#

Signed difference in \(\eta\) of self minus other.

deltaR(other: VectorProtocolSpatial | VectorProtocolLorentz) → Any#

Sum in quadrature of vector._methods.VectorProtocolPlanar.deltaphi() and vector._methods.VectorProtocolSpatial.deltaeta():

\[\Delta R = \sqrt{\Delta\phi^2 + \Delta\eta^2}\]

deltaR2(other: VectorProtocolSpatial | VectorProtocolLorentz) → Any#

Square of the sum in quadrature of vector._methods.VectorProtocolPlanar.deltaphi() and vector._methods.VectorProtocolSpatial.deltaeta():

\[\Delta R^2 = \Delta\phi^2 + \Delta\eta^2\]

rotateX(angle: Any) → SameVectorType#

Rotates the vector(s) by a given angle (in radians) around the \(x\) axis.

Note that the angle can be an array with the same length as the vectors, if the vectors are in an array.

rotateY(angle: Any) → SameVectorType#

Rotates the vector(s) by a given angle (in radians) around the \(y\) axis.

Note that the angle can be an array with the same length as the vectors, if the vectors are in an array.

rotate_axis(axis: VectorProtocolSpatial, angle: Any) → SameVectorType#

Rotates the vector(s) by a given angle (in radians) around the axis indicated by another vector, axis. The magnitude of axis is ignored.

Note that the axis and angle can be arrays with the same length as the vectors, if the vectors are in an array.

rotate_euler(phi: Any, theta: Any, psi: Any, order: str = 'zxz') → SameVectorType#

Rotates the vector(s) by three given angles: phi, theta, and psi (in radians). The order string determines which axis each rotation is applied around:

The names phi, theta, and psi agree with Wikipedia’s terminology, and both the names and order agree with ROOT’s Math::EulerAngles. The default order = "zxz" is also ROOT’s convention.

Note that the angles can be arrays with the same lengths as the vectors, if the vectors are in an array.

rotate_nautical(yaw: Any, pitch: Any, roll: Any) → SameVectorType#

Rotates the vector(s) by three given angles: yaw, pitch, and roll (in radians). These are Tait-Bryan angles often used for boats and planes (see this lesson and this lesson).

This function is entirely equivalent to

rotate_euler(roll, pitch, yaw, order="zyx")

Note that the angles can be arrays with the same lengths as the vectors, if the vectors are in an array.

rotate_quaternion(u: Any, i: Any, j: Any, k: Any) → SameVectorType#

Rotates the vector(s) by four angles as quaternion coefficients (in radians). Four angles are sometimes preferred over three because the latter has a pathology known as “gimbal lock.”

This function follows the same conventions as ROOT’s Math::Quaternion.

Note that the angles can be arrays with the same lengths as the vectors, if the vectors are in an array.

transform3D(obj: TransformProtocol3D) → SameVectorType#

Arbitrarily transforms the vector(s) by

obj["xx"] obj["xy"] obj["xz"]
obj["yx"] obj["yy"] obj["yz"]
obj["zx"] obj["zy"] obj["zz"]

leaving any temporal coordinate unchanged. There is no restriction on the type of obj; it just has to provide those components (which can be arrays if the vectors are in an array).

is_parallel(other: VectorProtocol, tolerance: Any = 1e-05) → Any#

Returns True if self and other are pointing in the same direction (i.e. not “antiparallel”; dot product is nearly abs(self) * abs(other)).

The tolerance is measured in units of \(\cos(\Delta\alpha)\) where \(\Delta\alpha\) is self.deltaangle(other).

is_antiparallel(other: VectorProtocol, tolerance: Any = 1e-05) → Any#

Returns True if self and other are pointing in opposite directions (i.e. dot product is nearly -abs(self) * abs(other)).

The tolerance is measured in units of \(\cos(\Delta\alpha)\) where \(\Delta\alpha\) is self.deltaangle(other).

is_perpendicular(other: VectorProtocol, tolerance: Any = 1e-05) → Any#

Returns True if self and other are pointing in perpendicular directions (i.e. dot product is nearly 0).

The tolerance is measured in units of \(\cos(\Delta\alpha)\) where \(\Delta\alpha\) is self.deltaangle(other).

add(other: VectorProtocol) → VectorProtocol#

Sum of self and other.

This method is equivalent to the + operator.

property azimuthal: Azimuthal#

Container of azimuthal coordinates, for use in dispatching to compute functions or to identify coordinate system with isinstance.

deltaphi(other: VectorProtocol) → Any#

Signed difference in \(\phi\) of self minus other (in radians).

dot(other: VectorProtocol) → Any#

Vector dot product of self with other.

This method is equivalent to the @ operator.

equal(other: VectorProtocol) → Any#

Returns True if self is exactly equal to other (possibly for arrays of vectors), False otherwise.

This method is equivalent to the == operator.

Typically, you’ll want to check vector._methods.VectorProtocol.isclose() to allow for numerical errors.

isclose(other: VectorProtocol, rtol: Any = 1e-05, atol: Any = 1e-08, equal_nan: Any = False) → Any#

Returns True if self is approximately equal to other (possibly for arrays of vectors), False otherwise.

The relative tolerance (rtol) and absolute tolerance (atol) are interpreted as in np.isclose:

close_enough = abs(self - other) <= atol + rtol * abs(other)
like(other: VectorProtocol) → VectorProtocol#

Projects the vector into the geometric coordinates of the other vector.

Value(s) of \(0\) is/are imputed while transforming vector from a lower geometric dimension to a higher geometric dimension.

vec_4d + vec_3d.like(vec_4d)

For more flexibility (passing new coordinate values), see vector._methods.Vector2D.to_Vector3D(), vector._methods.Vector2D.to_Vector4D(), and vector._methods.Vector3D.to_Vector4D(), which can be used as:

vec_2d.to_Vector3D(z=3.0)
vec_2d.to_Vector4D(z=3.0, t=4.0)
vec_3d.to_Vector4D(t=4.0)
property neg2D: SameVectorType#

Returns vector(s) with the 2D part negated, not affecting any longitudinal or temporal parts.

not_equal(other: VectorProtocol) → Any#

Returns False if self is exactly equal to other (possibly for arrays of vectors), True otherwise.

This method is equivalent to the != operator.

Typically, you’ll want to check vector._methods.VectorProtocol.isclose() to allow for numerical errors.

property phi: Any#

The polar \(\phi\) coordinate of the vector or every vector in the array (in radians, always between \(-\pi\) and \(\pi\)).

property rho: Any#

The polar \(\rho\) coordinate of the vector or every vector in the array.

This is also the magnitude of the 2D azimuthal part of the vector (not including any longitudinal or temporal parts).

property rho2: Any#

The polar \(\rho\) coordinate squared of the vector or every vector in the array.

rotateZ(angle: Any) → SameVectorType#

Rotates the vector(s) by a given angle (in radians) around the longitudinal axis.

Note that the angle can be an array with the same length as the vectors, if the vectors are in an array.

scale(factor: Any) → SameVectorType#

Returns vector(s) scaled by a factor, changing the length(s) but not the direction(s).

This method is equivalent to the * operator.

scale2D(factor: Any) → SameVectorType#

Returns vector(s) with the 2D part scaled by a factor, not affecting any longitudinal or temporal parts.

subtract(other: VectorProtocol) → VectorProtocol#

Difference of self minus other.

This method is equivalent to the - operator.

to_2D() → VectorProtocolPlanar#

Projects this vector/these vectors onto azimuthal coordinates only.

Alias for vector._methods.VectorProtocol.to_Vector2D().

to_3D() → VectorProtocolSpatial#

Projects this vector/these vectors onto azimuthal and longitudinal coordinates only.

If 2D, a default \(z\) component of \(0\) is imputed.

The longitudinal coordinate can be passed as a named argument.

Alias for vector._methods.VectorProtocol.to_Vector3D().

to_4D() → VectorProtocolLorentz#

Projects this vector/these vectors onto azimuthal, longitudinal, and temporal coordinates.

If 3D, a default \(t\) component of \(0\) is imputed.

If 2D, a \(z\) component of \(0\) is imputed along with a default \(t\) component of \(0\).

The longitudinal and temporal coordinates can be passed as named arguments.

Alias for vector._methods.VectorProtocol.to_Vector4D().

to_Vector2D() → VectorProtocolPlanar#

Projects this vector/these vectors onto azimuthal coordinates only.

to_Vector3D() → VectorProtocolSpatial#

Projects this vector/these vectors onto azimuthal and longitudinal coordinates only.

If 2D, a default \(z\) component of \(0\) is imputed.

The longitudinal coordinate can be passed as a named argument.

to_Vector4D() → VectorProtocolLorentz#

Projects this vector/these vectors onto azimuthal, longitudinal, and temporal coordinates.

If 3D, a default \(t\) component of \(0\) is imputed.

If 2D, a \(z\) component of \(0\) is imputed along with a default \(t\) component of \(0\).

The longitudinal and temporal coordinates can be passed as named arguments.

to_ptphi() → VectorProtocolPlanar#

Converts to \(pt\)-\(\phi\) coordinates, possibly eliminating dimensions with a projection.

to_ptphieta() → VectorProtocolSpatial#

Converts to \(pt\)-\(\phi\)-\(\eta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(eta\) coordinate can be passed as a named argument.

to_ptphietaenergy() → VectorProtocolLorentz#

Converts to \(pt\)-\(\phi\)-\(\eta\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(energy\) coordinates can be passed as a named argument.

to_ptphietamass() → VectorProtocolLorentz#

Converts to \(pt\)-\(\phi\)-\(\theta\)-\(mass\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(mass\) coordinates can be passed as a named argument.

to_ptphipz() → VectorProtocolSpatial#

Converts to \(pt\)-\(\phi\)-\(pz\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(pz\) coordinate can be passed as a named argument.

to_ptphipzenergy() → VectorProtocolLorentz#

Converts to \(pt\)-\(\phi\)-\(pz\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(pz\) and \(energy\) coordinates can be passed as a named argument.

to_ptphipzmass() → VectorProtocolLorentz#

Converts to \(pt\)-\(\phi\)-\(pz\)-\(mass\) coordinates, possibly imputing dimensions with a projection.

The \(pz\) and \(mass\) coordinates can be passed as a named argument.

to_ptphitheta() → VectorProtocolSpatial#

Converts to \(pt\)-\(\phi\)-\(\theta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(theta\) coordinate can be passed as a named argument.

to_ptphithetaenergy() → VectorProtocolLorentz#

Converts to \(pt\)-\(\phi\)-\(\theta\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(energy\) coordinates can be passed as a named argument.

to_ptphithetamass() → VectorProtocolLorentz#

Converts to \(pt\)-\(\phi\)-\(\theta\)-\(mass\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(mass\) coordinates can be passed as a named argument.

to_pxpy() → VectorProtocolPlanar#

Converts to \(px\)-\(py\) coordinates, possibly eliminating dimensions with a projection.

to_pxpyeta() → VectorProtocolSpatial#

Converts to \(px\)-\(py\)-\(\eta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(eta\) coordinate can be passed as a named argument.

to_pxpyetaenergy() → VectorProtocolLorentz#

Converts to \(px\)-\(py\)-\(\eta\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(energy\) coordinates can be passed as a named argument.

to_pxpyetamass() → VectorProtocolLorentz#

Converts to \(px\)-\(py\)-\(\eta\)-\(mass\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(mass\) coordinates can be passed as a named argument.

to_pxpypz() → VectorProtocolSpatial#

Converts to \(px\)-\(py\)-\(pz\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(pz\) coordinate can be passed as a named argument.

to_pxpypzenergy() → VectorProtocolLorentz#

Converts to \(px\)-\(py\)-\(pz\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(pz\) and \(energy\) coordinates can be passed as a named argument.

to_pxpypzmass() → VectorProtocolLorentz#

Converts to \(px\)-\(py\)-\(pz\)-\(mass\) coordinates, possibly imputing dimensions with a projection.

The \(pz\) and \(mass\) coordinates can be passed as a named argument.

to_pxpytheta() → VectorProtocolSpatial#

Converts to \(px\)-\(py\)-\(\theta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(theta\) coordinate can be passed as a named argument.

to_pxpythetaenergy() → VectorProtocolLorentz#

Converts to \(px\)-\(py\)-\(\theta\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(energy\) coordinates can be passed as a named argument.

to_pxpythetamass() → VectorProtocolLorentz#

Converts to \(px\)-\(py\)-\(\theta\)-\(energy\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(mass\) coordinates can be passed as a named argument.

to_rhophi() → VectorProtocolPlanar#

Converts to \(\rho\)-\(\phi\) coordinates, possibly eliminating dimensions with a projection.

to_rhophieta() → VectorProtocolSpatial#

Converts to \(\rho\)-\(\phi\)-\(\eta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(eta\) coordinate can be passed as a named argument.

to_rhophietat() → VectorProtocolLorentz#

Converts to \(\rho\)-\(\phi\)-\(\eta\)-\(t\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(t\) coordinates can be passed as a named argument.

to_rhophietatau() → VectorProtocolLorentz#

Converts to \(\rho\)-\(\phi\)-\(\eta\)-\(\tau\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(tau\) coordinates can be passed as a named argument.

to_rhophitheta() → VectorProtocolSpatial#

Converts to \(\rho\)-\(\phi\)-\(\theta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(theta\) coordinate can be passed as a named argument.

to_rhophithetat() → VectorProtocolLorentz#

Converts to \(\rho\)-\(\phi\)-\(\theta\)-\(t\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(t\) coordinates can be passed as a named argument.

to_rhophithetatau() → VectorProtocolLorentz#

Converts to \(\rho\)-\(\phi\)-\(\theta\)-\(\tau\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(tau\) coordinates can be passed as a named argument.

to_rhophiz() → VectorProtocolSpatial#

Converts to \(\rho\)-\(\phi\)-\(z\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(z\) coordinate can be passed as a named argument.

to_rhophizt() → VectorProtocolLorentz#

Converts to \(\rho\)-\(\phi\)-\(z\)-\(t\) coordinates, possibly imputing dimensions with a projection.

The \(z\) and \(t\) coordinates can be passed as a named argument.

to_rhophiztau() → VectorProtocolLorentz#

Converts to \(\rho\)-\(\phi\)-\(z\)-\(\tau\) coordinates, possibly imputing dimensions with a projection.

The \(z\) and \(tau\) coordinates can be passed as a named argument.

to_xy() → VectorProtocolPlanar#

Converts to \(x\)-\(y\) coordinates, possibly eliminating dimensions with a projection.

to_xyeta() → VectorProtocolSpatial#

Converts to \(x\)-\(y\)-\(\eta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(eta\) coordinate can be passed as a named argument.

to_xyetat() → VectorProtocolLorentz#

Converts to \(x\)-\(y\)-\(\eta\)-\(t\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(t\) coordinates can be passed as a named argument.

to_xyetatau() → VectorProtocolLorentz#

Converts to \(x\)-\(y\)-\(\eta\)-\(\tau\) coordinates, possibly imputing dimensions with a projection.

The \(eta\) and \(tau\) coordinates can be passed as a named argument.

to_xytheta() → VectorProtocolSpatial#

Converts to \(x\)-\(y\)-\(\theta\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(theta\) coordinate can be passed as a named argument.

to_xythetat() → VectorProtocolLorentz#

Converts to \(x\)-\(y\)-\(\theta\)-\(t\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(t\) coordinates can be passed as a named argument.

to_xythetatau() → VectorProtocolLorentz#

Converts to \(x\)-\(y\)-\(\theta\)-\(\tau\) coordinates, possibly imputing dimensions with a projection.

The \(theta\) and \(tau\) coordinates can be passed as a named argument.

to_xyz() → VectorProtocolSpatial#

Converts to \(x\)-\(y\)-\(z\) coordinates, possibly eliminating or imputing dimensions with a projection.

The \(z\) coordinate can be passed as a named argument.

to_xyzt() → VectorProtocolLorentz#

Converts to \(x\)-\(y\)-\(z\)-\(t\) coordinates, possibly imputing dimensions with a projection.

The \(z\) and \(t\) coordinates can be passed as a named argument.

to_xyztau() → VectorProtocolLorentz#

Converts to \(x\)-\(y\)-\(z\)-\(\tau\) coordinates, possibly imputing dimensions with a projection.

The \(z\) and \(tau\) coordinates can be passed as a named argument.

transform2D(obj: TransformProtocol2D) → SameVectorType#

Arbitrarily transforms the vector(s) by

obj["xx"] obj["xy"]
obj["yx"] obj["yy"]

leaving any longitudinal or temporal coordinates unchanged. There is no restriction on the type of obj; it just has to provide those components (which can be arrays if the vectors are in an array).

unit() → SameVectorType#

Returns vector(s) normalized to unit length, which is rho == 1 for 2D vectors, mag == 1 for 3D vectors, and tau == 1 for 4D vectors.

property x: Any#

The Cartesian \(x\) coordinate of the vector or every vector in the array.

property y: Any#

The Cartesian \(y\) coordinate of the vector or every vector in the array.

Contents