# Vector objects First, [install](../index.html.md#installation) and import Vector. ```none [1]: ``` ## Making a vector If you only need a few vectors or performance is not a concern, you can make vectors as Python objects. The basic constructor for that is [vector.obj](make_object.html.md), and the type of vector (2D/3D/4D, coordinate system, geometric or momentum) depends on the pattern of keyword arguments provided. Below is a 2D, Cartesian, geometric vector: ```none [2]: ``` ```none [2]: ``` Below is a 3D, Cartesian, momentum vector: ```none [3]: ``` ```none [3]: ``` Below is a 4D geometric vector that has Cartesian azimuthal components (`x` and `y`), the longitudinal component is expressed in [pseudorapidity](https://en.wikipedia.org/wiki/Pseudorapidity), and the temporal component is expressed using proper time: ```none [4]: ``` ```none [4]: ``` The allowed keyword arguments for 2D vectors are: - `x` and `y` for Cartesian azimuthal coordinates, - `px` ($p_x$) and `py` ($p_y$) for momentum, - `rho` ($\rho$) and `phi` ($\phi$) for polar azimuthal coordinates, - `pt` ($p_T$) and `phi` ($\phi$) for momentum. For 3D vectors, you need the above and: - `z` for the Cartesian longitudinal coordinate, - `pz` ($p_z$) for momentum, - `theta` ($\theta$) for the spherical polar angle (from $0$ to $\pi$, inclusive), - `eta` ($\eta$) for [pseudorapidity](https://en.wikipedia.org/wiki/Pseudorapidity), which is a kind of spherical polar angle: $\eta = -\ln \left[ \tan \left( \frac{\theta}{2} \right) \right]$. For 4D vectors, you need the above and: - `t` for the Cartesian temporal coordinate, - `e`, `E`, or `energy` to get four-momentum, - `tau` ($\tau$) for the “proper time” (temporal coordinate in the vector’s rest coordinate system), - `m`, `M`, or `mass` to get four-momentum. Since momentum vectors have momentum-synonyms in addition to the geometrical names, any momentum-synonym will make the whole vector a momentum vector. The meanings of the geometric components are illustrated below: ![a0bfe85ef710469d8591d6b67ff4b985](_images/coordinate-systems.svg) This one constructor, [vector.obj](make_object.html.md), can output a variety of data types. If you want to control the type more explicitly, you can use [vector.VectorObject2D](make_object.html.md#vector.VectorObject2D), [vector.MomentumObject2D](make_object.html.md#vector.MomentumObject2D), [vector.VectorObject3D](make_object.html.md#vector.VectorObject3D), [vector.MomentumObject3D](make_object.html.md#vector.MomentumObject3D), [vector.VectorObject4D](make_object.html.md#vector.VectorObject4D), and [vector.MomentumObject4D](make_object.html.md#vector.MomentumObject4D) to construct or check the type explicitly. These classes also have `from_*` methods to construct vectors from positional arguments, rather than keyword arguments. ## Using a vector Vector objects have a suite of properties and methods appropriate to their type (2D/3D/4D, geometric or momentum). For example, to compute the cross-product of two vectors, you would use [cross](vector3d.html.md#vector._methods.VectorProtocolSpatial.cross): ```none [5]: ``` ```none [5]: ``` or to compute the angle between them, you would use [deltaangle](vector3d.html.md#vector._methods.VectorProtocolSpatial.deltaangle): ```none [6]: ``` ```none [6]: ``` or to compute their sum, you would use `+`: ```none [7]: ``` ```none [7]: ``` In this last example, the `+` operator overloads the [add](common.html.md#vector._methods.VectorProtocol.add) method. Similarly, multiplication between a vector and a scalar number overloads [scale](common.html.md#vector._methods.VectorProtocol.scale), etc. Since they overload standard operators, vectors can be used in Python built-in functions like [sum](https://docs.python.org/3/library/functions.html#sum), as long as you provide a `start`: ```none [8]: ``` ```none [8]: ``` The same applies to [abs](https://docs.python.org/3/library/functions.html#abs) for the vector’s magnitude, but note that this depends on the number of dimensions: ```none [9]: ``` ```none [9]: ``` ```none [10]: ``` ```none [10]: ``` ```none [11]: ``` ```none [11]: ``` Equality ([equal](common.html.md#vector._methods.VectorProtocol.equal)) and inequality ([not_equal](common.html.md#vector._methods.VectorProtocol.not_equal)) are defined: ```none [12]: ``` ```none [12]: ``` But you’ll probably want to use [isclose](common.html.md#vector._methods.VectorProtocol.isclose) (and possibly specify tolerances): ```none [13]: ``` ```none [13]: ``` ```none [14]: ``` ```none [14]: ``` The full set of properties and methods available to each type of vector (2D/3D/4D, geometric or momentum) is described in - [Interface for all vectors](common.html.md) - [Interface for 2D vectors](vector2d.html.md) - [Interface for 3D vectors](vector3d.html.md) - [Interface for 4D vectors](vector4d.html.md) - [Interface for 2D momentum](momentum2d.html.md) - [Interface for 3D momentum](momentum3d.html.md) - [Interface for 4D momentum](momentum4d.html.md) ## Using coordinate systems A vector can be constructed using any combination of coordinate systems and computations will be performed using whatever coordinate system it has. Thus, after creating vectors, you can write code that does not depend on the coordinate system—it becomes a hidden implementation detail. ```none [15]: ``` ```none [15]: ``` Some of the properties of a vector are coordinates, so you can use Vector to convert coordinates. ```none [16]: ``` ```none [16]: ``` Since the way that you access the original coordinates is the same as the way that you access converted coordinates, ```none [17]: ``` ```none [17]: ``` these conversions are part of the coordinate-abstraction. For reasons of numerical precision, you might want to open this black box and explicitly change the coordinate system. These methods start with `to_*`: ```none [18]: ``` ```none [18]: ``` ```none [19]: ``` ```none [19]: ``` ## Geometric versus momentum vectors Vectors come in two flavors: - geometric: only one name for each property or method - momentum: same property or method can be accessed with several synonyms (which assume that the vector is a [momentum](https://en.wikipedia.org/wiki/Momentum) vector). ```none [20]: ``` ```none [20]: ``` ```none [21]: ``` ```none [21]: ``` Calculations are the same in both cases: ```none [22]: ``` ```none [22]: ``` ```none [23]: ``` ```none [23]: ``` but there are more ways to express some operations: ```none [24]: ``` ```none [24]: ``` ```none [25]: ``` ```none [25]: ``` ```none [26]: ``` ```none [26]: ``` The geometric vector satisfies the [Zen of Python](https://en.wikipedia.org/wiki/Zen_of_Python) stipulation that > There should be one– and preferably only one –obvious way to do it. and code that uses, for example, “`pt`” to specify “distance from the beamline” is obfuscated code. However, the most common use for these vectors in High Energy Physics (HEP) is to represent the momentum of particles. For that purpose, using “`rho`” for $p_T$ is not self-documenting. Momentum vectors have all of the same properties and methods as geometric vectors *as well as* momentum synonyms. In some cases, there are multiple momentum synonyms for adherence to different conventions. For example, energy and mass (the [temporal component of momentum](https://en.wikipedia.org/wiki/Four-momentum), as Cartesian and proper time, respectively) have four different spellings: | energy spelling | mass spelling | rationale | |-------------------|-----------------|-------------------------------------------------------------------------------| | `t` | `tau` | geometric coordinates; $\tau$ for proper time is conventional | | `energy` | `mass` | full names are more self-documenting in the code | | `e` | `m` | all other coordinates are lower-case single letters (sometimes Greek letters) | | `E` | `M` | capital E and M (only!) are used in other HEP vector libraries | If any momentum components are used to construct a vector (or if [vector.MomentumObject2D](make_object.html.md#vector.MomentumObject2D), [vector.MomentumObject3D](make_object.html.md#vector.MomentumObject3D), or [vector.MomentumObject4D](make_object.html.md#vector.MomentumObject4D) are used explicitly), then the vector is momentum and all synonyms become available. ## Numeric data types and numerical error Vector does not require any specific numeric data type, such as `np.float32` or `np.float64`, it only requires that vector components are some kind of number, including integers. ```none [27]: ``` ```none [28]: ``` ```none [28]: ``` ```none [29]: ``` ```none [29]: ``` ```none [30]: ``` ```none [31]: ``` ```none [32]: ``` ```none [32]: ``` ```none [33]: ``` ```none [33]: ``` The same formulas are applied, regardless of the numeric type, so if the numerical error is larger than you expect it to be, check your types (and coordinate systems). ## Application to other backends Everything stated above about vector objects (except their methods of construction) apply equally to all other backends. Arrays of vectors and symbolic vector expressions in SymPy have the same properties and methods as vector objects, they can hide choice of coordinate system as an abstraction, and the set of synonyms can be minimal for geometric vectors and maximal for momentum vectors. Therefore, it can be convenient to use vector objects as a quick way to debug issues in large arrays. However, note that different backends can use different libraries for computations, and results might differ in numerical error. In particular, note that SymPy vector expressions have a different sign convention for operations on space-like and negative time-like 4D vectors. For all other backends, Vector’s conventions were chosen to agree with popular HEP libraries, particularly [ROOT](https://root.cern), but for the SymPy backend, those conventions would insert piecewise if-then branches, which would complicate symbolic expressions.