Overview#

Installation#

You can install Vector with pip and conda.

pip install vector

Introduction#

Vector is a Python library for 2D and 3D spatial vectors, as well as 4D space-time vectors. It is especially intended for performing geometric calculations on arrays of vectors, rather than one vector at a time in a Python for loop.

Vector is part of the Scikit-HEP project, High Energy Physics (HEP) tools in Python.

Coordinate systems#

Vectors may be expressed in any of these coordinate systems:

the azimuthal plane may be Cartesian x y or polar rho (\(\rho\)) phi (\(\phi\))
the longitudinal axis may be Cartesian z, polar theta (\(\theta\)), or pseudorapidity eta (\(\eta\))
the temporal component for space-time vectors may be Cartesian t or proper time tau (\(\tau\))

in any combination. (That is, 4D vectors have 2×3×2 = 12 distinct coordinate systems.)

Backends#

Vectors may be included in any of these data types:

vector.obj objects (pure Python)
NumPy structured arrays of vectors
Awkward Arrays of vectors (possibly within variable-length lists or nested record structures)
SymPy expressions for symbolic (non-numeric) manipulations
In Numba-compiled functions, with vector.obj objects or Awkward Arrays

Each of these “backends” provides the same suite of properties and methods, through a common “compute” library.

Integrations#

Optionally, the vector package provides integration with other libraries. Currently, this includes:

PyTree integrations using the optree package.

Geometric versus momentum#

Finally, 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, such as pt (\(p_T\), transverse momentum) for the azimuthal magnitude rho (\(\rho\)) and energy and mass for the Cartesian time t and proper time tau (\(\tau\)).

Familiar conventions#

Names and coordinate conventions were chosen to align with ROOT’s TLorentzVector and Math::LorentzVector, as well as scikit-hep/math, uproot-methods TLorentzVector, henryiii/hepvector, and coffea.nanoevents.methods.vector.

Vector follows the \((-, -, -, +)\) (x, y, z, t) metric convention for Lorentz vectors. The \((-,-,-,+)\) metric convention for Lorentz vectors corresponds to the Minkowski metric:

\[g_{\mu\nu} = \text{diag}(-1, -1, -1, +1)\]

For a Lorentz vector \(p^\mu = (p_x, p_y, p_z, E)\), the squared norm (or invariant mass squared) is given by:

\[p^\mu p_\mu = g_{\mu\nu} p^\mu p^\nu = E^2 - p_x^2 - p_y^2 - p_z^2\]

This convention is widely used in high-energy physics (HEP), including frameworks such as ROOT.

Further, the transformations and rotations (including boosts) are active, and the Euler angle conventions align with the formalisations in the GenVector package. More precisely, the implementation of rotate_euler uses the matrices defined in the wikipedia article.

Getting help#

Source code on GitHub: scikit-hep/vector
Report bugs and request features on the GitHub Issues page
Ask questions on the GitHub Discussions page
Real-time chat on Gitter: Scikit-HEP/Vector

Contributing to Vector#

If you want to contribute to Vector, pull requests are welcome!

Please install the latest version of the main branch from source or a fork:

git clone https://github.com/scikit-hep/vector.git
cd vector
pip install -e .

Refer to CONTRIBUTING.md for more.

Citing Vector#

To cite Vector, please use

@article{Chopra2025,
doi = {10.21105/joss.07791},
url = {https://doi.org/10.21105/joss.07791},
year = {2025}, publisher = {The Open Journal},
volume = {10},
number = {109},
pages = {7791},
author = {Saransh Chopra and Henry Schreiner and Eduardo Rodrigues and Jonas Eschle and Jim Pivarski},
title = {Vector: JIT-compilable mathematical manipulations of ragged Lorentz vectors},
journal = {Journal of Open Source Software}
}

Documentation#

Tutorials

Vector constructors

Vector functions

Integrations

PyTree API

More ways to learn

Papers and talks

Overview

Contents