Making Awkward Arrays of vectors#

An Awkward Array of vectors is an Awkward Array containing appropriately named records, appropriately named fields, and the Vector behaviors registered in the array. Here’s a complete example for illustration:

>>> import awkward as ak
>>> import vector
>>> vector.register_awkward()
>>>
>>> vec = ak.Array([
...     [{"x": 1.1, "y": 2.2}, {"x": 3.3, "y": 4.4}],
...     [],
...     [{"x": 5.5, "y": 6.6}],
... ], with_name="Vector2D")
>>>
>>> abs(vec)
<Array [[2.46, 5.5], [], [8.59]] type='3 * var * float64'>

In the above,

vector.register_awkward() loads Vector’s vector.backends.awkward.behavior dict of functionality into the global ak.behavior
the Awkward Array contains records (inside variable-length lists) with field names "x" and "y"
those records are labeled with type name "Vector2D"

and thus the abs function computes the magnitude of each record as sqrt(x**2 + y**2), through the variable-length lists.

It is not necessary to install Vector’s behaviors globally. They could be installed in the vec array only by passing behavior=vector.backends.awkward.behavior to the ak.Array constructor.

The records can contain more fields than those that specify coordinates, which can be useful for specifying properties of a particle other than its momentum. Only the coordinate names are considered when performing vector calculations. Coordinates must be numbers (not, for instance, lists of numbers).

Field names that mean a coordinate under another name, such as rho (a synonym of pt) or energy in a record that already has mass, would silently change what a vector means, so Vector rejects them:

>>> ak.Array([{"pt": 1.1, "phi": 2.2, "eta": 3.3, "mass": 4.4, "energy": 5.5}], with_name="Momentum4D")
Traceback (most recent call last):
    ...
TypeError: MomentumArray4D with fields ['pt', 'phi', 'eta', 'mass', 'energy']: specify t= or tau=, but not more than one (got 'energy', 'mass')

This runs whenever the behaviors are attached, not only in vector.Array and vector.zip, so jets["rho"] = ... is caught too. It is the __awkward_validation__ hook of each behavior class and needs awkward>=2.8.11; older versions skip it. A rejected in-place assignment is only undone by awkward>=2.12: before that, the TypeError is raised but the array keeps the offending field. Subclassed behaviors (see Advanced: subclassing Awkward-Vector behaviors) inherit the check and can extend it by overriding __awkward_validation__ and calling super().__awkward_validation__().

The vector.Array function (vector.awk is a synonym) is an alternative to the ak.Array constructor, which installs Vector’s behavior in the new array (not globally in ak.behavior).

The vector.zip function is an alternative to the ak.zip function, which installs Vector’s behavior in the new array (not globally in ak.behavior).

Awkward Arrays can be used in Numba-compiled functions, including those that contain vectors.

vector.register_awkward() → None#

Make Vector behaviors known to Awkward Array’s ak.behavior mechanism.

If you call this function, any records named Vector2D, Vector3D, Vector4D, Momentum2D, Momentum3D, and Momentum4D will have vector properties and methods.

If you do not call this function, only arrays created with vector.Array() (or derived from such an array) have vector properties and methods.

vector.Array(*args: Any, **kwargs: Any) → Any#

Constructs an Awkward Array of vectors, whose type is determined by the fields of the record array (which may be nested within lists or other non-record structures).

All allowed signatures for ak.Array can be used in this function.

The array must contain records with the following combinations of field names:

(2D) x, y
(2D) rho, phi
(3D) x, y, z
(3D) x, y, theta
(3D) x, y, eta
(3D) rho, phi, z
(3D) rho, phi, theta
(3D) rho, phi, eta
(4D) x, y, z, t
(4D) x, y, z, tau`
(4D) x, y, theta, t`
(4D) x, y, theta, tau`
(4D) x, y, eta, t`
(4D) x, y, eta, tau`
(4D) rho, phi, z, t`
(4D) rho, phi, z, tau`
(4D) rho, phi, theta, t`
(4D) rho, phi, theta, tau`
(4D) rho, phi, eta, t`
(4D) rho, phi, eta, tau`

in which

px may be substituted for x
py may be substituted for y
pt may be substituted for rho
pz may be substituted for z
E may be substituted for t
e may be substituted for t
energy may be substituted for t
M may be substituted for tau
m may be substituted for tau
mass may be substituted for tau

to make the vector a momentum vector.

A coordinate may be given only once, whether by its generic name or through a momentum-alias, and the names must form exactly one of the combinations above; anything else raises a TypeError. Names that are not coordinates become extra fields of the records.

No constraints are placed on the types of the vector fields, though if they are not numbers, mathematical operations will fail. Usually, you want them to be integers or floating-point numbers.

vector.zip(arrays: dict[str, Any], depth_limit: int | None = None) → Any#

Constructs an Awkward Array of vectors, whose type is determined by the fields of the record array (which may be nested within lists or other non-record structures).

This function accepts a subset of ak.zip’s arguments.

Parameters:

arrays (dict of str to array-like) – Arrays, lists, etc. to zip together. Unlike ak.zip, this must be a dict with string keys to determine the coordinate system of the arrays; it may not be a tuple.
depth_limit (None or int) – If None, attempt to fully broadcast the array to all levels. If an int, limit the number of dimensions that get broadcasted. The minimum value is 1, for no broadcasting.

The array must contain records with the following combinations of field names:

(2D) x, y
(2D) rho, phi
(3D) x, y, z
(3D) x, y, theta
(3D) x, y, eta
(3D) rho, phi, z
(3D) rho, phi, theta
(3D) rho, phi, eta
(4D) x, y, z, t
(4D) x, y, z, tau`
(4D) x, y, theta, t`
(4D) x, y, theta, tau`
(4D) x, y, eta, t`
(4D) x, y, eta, tau`
(4D) rho, phi, z, t`
(4D) rho, phi, z, tau`
(4D) rho, phi, theta, t`
(4D) rho, phi, theta, tau`
(4D) rho, phi, eta, t`
(4D) rho, phi, eta, tau`

in which

px may be substituted for x
py may be substituted for y
pt may be substituted for rho
pz may be substituted for z
E may be substituted for t
e may be substituted for t
energy may be substituted for t
M may be substituted for tau
m may be substituted for tau
mass may be substituted for tau

to make the vector a momentum vector.

Making Awkward Arrays of vectors

Contents

Making Awkward Arrays of vectors#