What's new with Vector?

Henry Schreiner (Princeton University)
Jim Pivarski (Princeton University)
Saransh Chopra (University of Delhi) 🙋🏻‍♂️

PyHEP 2023

Quick recap!

Create and manipulate 2D, 3D, and Lorentz vectors -

pip install vector
conda install -c conda-forge vector
  • Pure Python objects (numba-object)
  • NumPy arrays of vectors
  • Awkward Arrays of vectors (numpy-awkward)

Pure Python vectors

In [1]: v1 = vector.obj(x=3, y=4, z=-2, t=10)

In [2]: v2 = vector.obj(rho=5, phi=0.9273, eta=-0.39, t=10)

In [3]: v1 + v2
Out[3]: VectorObject4D(x=5.999980871972148, y=8.000014345949428, z=-3.999809798461195, t=20)

In [4]: v1.x + v2.rho
Out[4]: 8

NumPy vectors

In [1]: v1 = vector.arr(
   ...:     {
   ...:         "x": [1.0, 2.0, 3.0, 4.0, 5.0],
   ...:         "y": [1.1, 2.2, 3.3, 4.4, 5.5],
   ...:         "z": [0.1, 0.2, 0.3, 0.4, 0.5],
   ...:     }
   ...: )

In [2]: v2 = vector.arr(
   ...:     {
   ...:         "px": [1.0, 2.0, 3.0, 4.0, 5.0],
   ...:         "py": [1.1, 2.2, 3.3, 4.4, 5.5],
   ...:         "pz": [0.1, 0.2, 0.3, 0.4, 0.5],
   ...:     }
   ...: )

In [3]: v1 + v2
Out[3]: 
VectorNumpy3D([( 2.,  2.2, 0.2), ( 4.,  4.4, 0.4), ( 6.,  6.6, 0.6),
               ( 8.,  8.8, 0.8), (10., 11. , 1. )],
              dtype=[('x', '<f8'), ('y', '<f8'), ('z', '<f8')])

In [4]: v1.x + v2.px
Out[4]: array([ 2.,  4.,  6.,  8., 10.])
In [1]: v1 = vector.awk(
   ...:     [
   ...:         [{"x": 1, "y": 1.1, "z": 0.1}, {"x": 2, "y": 2.2, "z": 0.2}],
   ...:         [],
   ...:         [{"x": 3, "y": 3.3, "z": 0.3}],
   ...:         [{"x": 4, "y": 4.4, "z": 0.4}, {"x": 5, "y": 5.5, "z": 0.5}],
   ...:     ]
   ...: )

In [2]: v2 = vector.awk(
   ...:     [
   ...:         [{"rho": 1, "phi": 1.1, "pz": 0.1}, {"rho": 2, "phi": 2.2, "pz": 0.2}],
   ...:         [],
   ...:         [{"rho": 3, "phi": 3.3, "pz": 0.3}],
   ...:         [{"rho": 4, "phi": 4.4, "pz": 0.4}, {"rho": 5, "phi": 5.5, "pz": 0.5}],
   ...:     ]
   ...: )

In [3]: v1 + v2
Out[3]: <VectorArray3D [[{x: 1.45, y: 1.99, ... z: 1}]] type='4 * var * Vector3D["x": fl...'>

In [4]: v1.x + v2.rho
Out[4]: <Array [[2, 4], [], [6], [8, 10]] type='4 * var * int64'>

Awkward vectors

JIT compiled vectors

In [1]: @numba.njit
   ...: def compute_mass(v1, v2):
   ...:     return (v1 + v2).mass

In [2]: compute_mass(
   ...:     vector.obj(px=1, py=2, pz=3, E=4),
   ...:     vector.obj(px=-1, py=-2, pz=-3, E=4)
   ...: )
Out[2]: 8.0
In [1]: array = vector.awk(
   ...:     [
   ...:         [
   ...:             dict(
   ...:                 {
   ...:                     x: numpy.random.normal(0, 1)
   ...:                     for x in ("px", "py", "pz")
   ...:                 },
   ...:                 E=numpy.random.normal(10, 1),
   ...:             )
   ...:             for inner in range(numpy.random.poisson(1.5))
   ...:         ]
   ...:         for outer in range(50)
   ...:     ]
   ...: )

In [2]: @numba.njit
   ...: def compute_masses(array):
   ...:     out = numpy.empty(len(array), numpy.float64)
   ...:     for i, event in enumerate(array):
   ...:         total = vector.obj(px=0.0, py=0.0, pz=0.0, E=0.0)
   ...:         for vec in event:
   ...:             total = total + vec
   ...:         out[i] = total.mass
   ...:     return out
   ...: 

In [3]: compute_masses(array)
Out[3]: 
array([ 0.        , 10.36167953,  0.        ,  9.15367049, 28.62136726,
        9.54993212,  0.        ,  9.00308428, 20.04212849, 10.06963788,
       19.8551194 ,  0.        , 30.6957947 ,  0.        , 23.24512715,
       19.88520087, 18.98248046,  0.        , 30.44632714, 10.2959194 ,
        9.26368332, 10.03039074, 21.56346856,  8.75170183,  8.80118952,
       18.05519623, 59.30509616, 11.4278945 , 47.78437373, 18.26799481,
        8.88103215,  0.        ,  0.        , 30.78770864, 38.00767698,
       21.21591576, 19.53493617,  0.        , 28.8201169 , 29.29564491,
        0.        ,  0.        , 10.85570784,  0.        ,  7.66535582,
       19.03323138, 38.85245788, 10.13798577,  9.30661898,  0.        ])

Detailed resources

  • PyHEP 2022 talk:                               Saransh-cpp/Constructing-HEP-vector-
                                                                     and- analyzing-HEP-data-using-Vector 
  • Vector's README:                     scikit-hep/vector
  • Vector's Documentation:                 vector.readthedocs.io

  • Vector's CHANGELOG:                      scikit-hep/vector/docs/changelog.md

  • All talks - linked in README:            README.md#talks-about-vector

But, what's new?

New constructors

In [1]: vector.VectorObject2D(x=2, y=3)
Out[1]: VectorObject2D(x=2, y=3)
  
In [2]: vector.MomentumObject2D(pt=2, phi=3)
Out[2]: MomentumObject2D(pt=2, phi=3)

In [3]: vector.VectorObject3D.from_xyz(2, 3, 4)
Out[3]: VectorObject3D(x=2, y=3, z=4)
  
In [4]: vector.MomentumObject2D.from_rhophi(2, 3)
Out[4]: MomentumObject2D(pt=2, phi=3)

In [5]: from vector.backends.object import AzimuthalObjectXY, LongitudinalObjec
   ...: tZ, TemporalObjectT

In [6]: vector.VectorObject2D(azimuthal=AzimuthalObjectXY(2, 3), longitudinal=L
   ...: ongitudinalObjectZ(4), temporal=TemporalObjectT(5))
Out[6]: VectorObject4D(x=2, y=3, z=4, t=5)
  
In [7]: vector.MomentumObject4D(azimuthal=AzimuthalObjectXY(2, 3), longitudinal
  ...: =LongitudinalObjectZ(4), temporal=TemporalObjectT(5))
Out[7]: MomentumObject4D(px=2, py=3, pz=4, E=5)
In [1]: vector.VectorNumpy2D([(1.1, 2.1), (1.2, 2.2), (1.3, 2.3), (1.4, 2.4), (
  ...: 1.5, 2.5)], dtype=[('x', float), ('y', float)])
Out[1]: 
VectorNumpy2D([(1.1, 2.1), (1.2, 2.2), (1.3, 2.3), (1.4, 2.4), (1.5, 2.5)],
              dtype=[('x', '<f8'), ('y', '<f8')])

In [2]: vector.MomentumNumpy3D([(1.1, 2.1, 3.1), (1.2, 2.2, 3.2), (1.3, 2.3, 3.
  ...: 3), (1.4, 2.4, 3.4), (1.5, 2.5, 3.5)], dtype=[('px', float), ('py', flo
  ...: at), ('pz', float)])
Out[2]: 
MomentumNumpy3D([(1.1, 2.1, 3.1), (1.2, 2.2, 3.2), (1.3, 2.3, 3.3), (1.4, 2.4, 3.4),
                 (1.5, 2.5, 3.5)], dtype=[('x', '<f8'), ('y', '<f8'), ('z', '<f8')])

In [1]: vector.Array(
  ...:     [
  ...:         [{"x": 1, "y": 1.1, "z": 0.1}],
  ...:         [],
  ...:         [{"x": 3, "y": 3.3, "z": 0.3}],
  ...:         [
  ...:             {"x": 4, "y": 4.4, "z": 0.4},
  ...:             {"x": 5, "y": 5.5, "z": 0.5},
  ...:             {"x": 6, "y": 6.6, "z": 0.6},
  ...:         ],
  ...:     ]
  ...: )
Out[1]: <VectorArray3D [[{x: 1, y: 1.1, z: 0.1, ... z: 0.6}]] type='4 * var * Vector3D["...'>

In [2]: vector.Array(
  ...:     [
  ...:         [{"px": 1, "py": 1.1, "pz": 0.1}],
  ...:         [],
  ...:         [{"px": 3, "py": 3.3, "pz": 0.3}],
  ...:         [
  ...:             {"px": 4, "py": 4.4, "pz": 0.4},
  ...:             {"px": 5, "py": 5.5, "pz": 0.5},
  ...:             {"px": 6, "py": 6.6, "pz": 0.6},
  ...:         ],
  ...:     ]
  ...: )
Out[2]: <MomentumArray3D [[{x: 1, y: 1.1, z: 0.1, ... z: 0.6}]] type='4 * var * Momentum...'>

Awkward v2 support

Still using awkward v1? Still works with awkward v1!

No extra "vector" overhead for switching between awkward v1 to v2, everything is handled automatically

New features

User experience:        Better reprs, better error messages, better
                                      private-public API segregation, ...

Methods:                     to_Vector*D, sum, count, count_nonzero,
                                      deltaRapidityPhi, deltaRapidityPhi2, ...

Support:                       Python 3.11 and 3.12 support

Less annoying bugs

Checks:                               Type checks in constructors

Constructors:                     Bug fixes in old constructors

Properties and methods: numpy.sum, high coordinate values, ...

Revamped documentation

The documentation is now targeted towards users and not the developers of vector

A nice way to get involved!

  • better layout for content
  • more docstrings
  • updated and tested examples
  • doctests for public API
  • better contributing guide
  • and much more...

Where is vector now?

A stable place with v1.0.0 out

Development is being spearheaded by bug reports and feature requests, no specific development targets

Mostly voluntary development, participating in hacktoberfest!

Future plans (2024)

Possibility of making Vector differentiable using Jax

Ties up with making the AGC differentiable (AD)

@software{Schreiner_vector,
author = {Schreiner, Henry and Pivarski, Jim and Chopra, Saransh},
doi = {10.5281/zenodo.5942082},
license = {BSD-3-Clause},
title = {{vector}},
url = {https://github.com/scikit-hep/vector}
}

Thank you!

saransh-cpp.github.io