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). Be careful about field names that coincide with coordinates, such as rho (azimuthal magnitude) and tau (proper time).

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.

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#