LVec

Lorentz vectors for particle physics with NumPy and Awkward Array.

Reconstruct invariant masses, select particles, transform reference frames, and calculate decay angles on scalars, dense arrays, or jagged event data. LVec also provides two- and three-dimensional spatial vectors.

Install

Requires Python 3.10 or later and NumPy 2.2.4 or later. Jagged collections additionally require Awkward 2.7.4 or later.

python -m pip install lvec
python -m pip install "lvec[awkward]"  # for jagged event data

Reconstruct a two-particle system

Use consistent energy and momentum units, with c=1 and metric (+,-,-,-).

from lvec import LVec

daughter1 = LVec(px=3., py=0., pz=0., E=5.)
daughter2 = LVec(px=0., py=4., pz=0., E=5.)
parent = daughter1 + daughter2

print(f"Pair mass: {parent.mass:.3f}")  # Pair mass: 8.660
daughter1_cm = daughter1.boost_to_rest(parent)

The same operations act elementwise on arrays. Components are independent, read-only float64 snapshots, so editing an input array cannot change a vector. Use validate=True when constructing physical particle momenta. For event samples, start with jagged events and reductions.

Documentation

The LVec manual provides searchable tutorials, physics conventions, and API reference pages. Sources can also be read here:

Start here	Contents
Tutorials	Scalars, NumPy arrays, jagged events, particle combinations, and rest frames
Physics guide	Coordinates, invariant mass, event selections, rest frames, decay angles, and numerical conventions
API reference	Complete 2D, 3D, 4D, and frame interfaces, including aliases and coordinate conversions
Migrating from vector	Familiar interfaces and scientific differences to check
Benchmarks	Representative measurements, ownership boundaries, and reproduction
Contributing	Testing, numerical bug reports, and releases

Citation

Please cite LVec using CITATION.cff.

Licence

LVec is licensed under the GNU General Public License v3.