vector 1.6.0__tar.gz → 1.6.2__tar.gz

{vector-1.6.0 → vector-1.6.2}/.github/workflows/cd.yml

@@ -37,7 +37,7 @@ jobs:
         run: ls -l dist/
 
       - name: Generate artifact attestation for sdist and wheel
-        uses: actions/attest-build-provenance@7668571508540a607bdfd90a87a560489fe372eb # v2.1.0
+        uses: actions/attest-build-provenance@c074443f1aee8d4aeeae555aebba3282517141b2 # v2.2.3
         with:
           subject-path: "dist/vector-*"
 

{vector-1.6.0 → vector-1.6.2}/.github/workflows/ci.yml

@@ -93,7 +93,7 @@ jobs:
         run: nox -s coverage-${{ matrix.python-version }} --verbose
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v5.1.2
+        uses: codecov/codecov-action@v5.4.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 

{vector-1.6.0 → vector-1.6.2}/.pre-commit-config.yaml

@@ -19,14 +19,14 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.9.1"
+    rev: "v0.11.6"
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.14.1
+    rev: v1.15.0
     hooks:
       - id: mypy
         files: src
@@ -37,13 +37,14 @@ repos:
           - sympy
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
       - id: codespell
+        args: ["-LHEP"]
         exclude: ^docs/usage/intro.ipynb$
 
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: "v3.4.2"
+    rev: "v3.5.3"
     hooks:
       - id: prettier
         types_or: [yaml, markdown, html, css, scss, javascript, json]

{vector-1.6.0 → vector-1.6.2}/CITATION.cff

@@ -15,7 +15,7 @@ authors:
 - family-names: "Chopra"
   given-names: "Saransh"
   orcid: "https://orcid.org/0000-0003-3046-7675"
-  affiliation: "University of Delhi"
+  affiliation: "University College London"
 doi: 10.5281/zenodo.5942082
 repository-code: "https://github.com/scikit-hep/vector"
 url: "https://vector.readthedocs.io/"

{vector-1.6.0 → vector-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vector
-Version: 1.6.0
+Version: 1.6.2
 Summary: Vector classes and utilities
 Project-URL: Bug Tracker, https://github.com/scikit-hep/vector/issues
 Project-URL: Changelog, https://vector.readthedocs.io/en/latest/changelog.html

{vector-1.6.0 → vector-1.6.2}/docs/index.md

@@ -65,6 +65,22 @@ Finally, vectors come in two flavors:
 
 Names and coordinate conventions were chosen to align with [ROOT](https://root.cern/)'s [TLorentzVector](https://root.cern.ch/doc/master/classTLorentzVector.html) and [Math::LorentzVector](https://root.cern.ch/doc/master/classROOT_1_1Math_1_1LorentzVector.html), as well as [scikit-hep/math](https://github.com/scikit-hep/scikit-hep/tree/master/skhep/math), [uproot-methods TLorentzVector](https://github.com/scikit-hep/uproot3-methods/blob/master/uproot3_methods/classes/TLorentzVector.py), [henryiii/hepvector](https://github.com/henryiii/hepvector), and [coffea.nanoevents.methods.vector](https://coffea-hep.readthedocs.io/en/latest/modules/coffea.nanoevents.methods.vector.html).
 
+Vector follows the $(-, -, -, +)$ (`x, y, z, t`) metric convention for Lorentz vectors. The $(-,-,-,+)$ metric convention for Lorentz vectors corresponds to the Minkowski metric:
+
+```{math}
+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:
+
+```{math}
+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](https://root.cern/topical/GenVector.pdf). More precisely, the implementation of `rotate_euler` uses the matrices defined in the [wikipedia article](https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix).
+
 ## Getting help
 
 - Source code on GitHub: [scikit-hep/vector](https://github.com/scikit-hep/vector)

vector-1.6.2/docs/src/numba.ipynb

@@ -0,0 +1,336 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1af51709-6860-4e5c-96c9-6a437eaed606",
+   "metadata": {},
+   "source": [
+    "# Compiling functions on vectors with Numba"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "03064225-ea6b-4f6b-a5bf-08a47b62350e",
+   "metadata": {},
+   "source": [
+    "First, [install](../index.md#installation) and import Vector and [Numba](https://numba.pydata.org/)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "df8bea35-cf3c-4f87-8e3d-8ffe06264811",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import vector\n",
+    "import numba as nb\n",
+    "import numpy as np"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7fff9620-227b-4e5e-a211-4daf1fb96298",
+   "metadata": {},
+   "source": [
+    "Numba is a just-in-time (JIT) compiler for a mathematically relevant subset of NumPy and Python. It allows you to write fast code without leaving the Python environment. The drawback of Numba is that it can only compile code blocks involving objects and functions that it recognizes.\n",
+    "\n",
+    "The Vector library includes extensions to inform Numba about [vector objects](object.md), [arrays of vectors](numpy.md), and [arrays of Awkward Arrays](awkward.md). At the time of writing, the implementation of vector NumPy arrays is incomplete (see issue [#43](https://github.com/scikit-hep/vector/issues/43)).\n",
+    "\n",
+    "Consider the following function:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "0e7f7c5c-2ce3-4f55-9159-363910fac6b9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def compute_mass(v1, v2):\n",
+    "    return (v1 + v2).mass"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "16d0fe04-fc8d-4d1f-bb68-0f869c1d2bdb",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "18.3 μs ± 144 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit compute_mass(vector.obj(px=1, py=2, pz=3, E=4), vector.obj(px=-1, py=-2, pz=-3, E=4))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "22516614-48eb-47de-96a9-12781fdeb66f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@nb.njit\n",
+    "def compute_mass(v1, v2):\n",
+    "    return (v1 + v2).mass"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "293e83fa-d059-4f14-a70f-3c4d91de8f9b",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The slowest run took 27658.64 times longer than the fastest. This could mean that an intermediate result is being cached.\n",
+      "93 ms ± 227 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit -n 1 compute_mass(vector.obj(px=1, py=2, pz=3, E=4), vector.obj(px=-1, py=-2, pz=-3, E=4))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "69c36f6d-3b54-4db8-9890-9245d64fefe7",
+   "metadata": {},
+   "source": [
+    "When the two `MomentumObject4D` objects are passed as arguments, Numba recognizes them and replaces the Python objects with low-level structs. When it compiles the function, it recognizes `+` as the 4D `add` function and recognizes `.mass` as the `tau` component of the result.\n",
+    "\n",
+    "Although this demonstrates that Numba can manipulate vector objects, there is no performance advantage (and a likely disadvantage) to compiling a calculation on just a few vectors. The `@nb.njit` result showcases this behavior, where the run (the actual just-in-time compilation + the run) takes much longer to run that the non-JIT version.\n",
+    "\n",
+    "Once the function has been JIT-compiled, the subsequent runs are comparable to the non-JIT version, but is no performance advantage on just a few vectors."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "d0fb0559-b944-43d1-b44e-1b959c1bbbd4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "24.1 μs ± 116 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit compute_mass(vector.obj(px=1, py=2, pz=3, E=4), vector.obj(px=-1, py=-2, pz=-3, E=4))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0bb7c5d1-2310-4a9a-8fdb-176179e3f84f",
+   "metadata": {},
+   "source": [
+    "However, the real advantage comes when many vectors are involved, in arrays."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "63f614a2-969d-465d-8d74-a44f6f77eab4",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<pre>[[{x: -1.47, y: -0.254, z: 1.44, t: 11}, ..., {x: -0.96, y: -0.5, z: ..., ...}],\n",
+       " [{x: 0.46, y: -1.97, z: -0.815, t: 9.54}, ..., {x: 0.399, y: 1.36, ...}],\n",
+       " [],\n",
+       " [{x: -0.484, y: 1.29, z: -0.875, t: 9.92}, {x: 1.05, y: -1.39, ...}],\n",
+       " [{x: -0.441, y: -0.38, z: -1.99, t: 10.2}],\n",
+       " [{x: -0.974, y: -0.324, z: 0.0935, t: 8.76}, {x: 0.989, y: 0.577, ...}],\n",
+       " [{x: -2.34, y: 0.919, z: 2.36, t: 10.6}],\n",
+       " [{x: 0.109, y: 0.589, z: -0.555, t: 11.3}, ..., {x: 0.681, y: -0.827, ...}],\n",
+       " [{x: 0.716, y: 0.122, z: 0.21, t: 10}, ..., {x: -1.41, y: -1.53, z: ..., ...}],\n",
+       " [],\n",
+       " ...,\n",
+       " [{x: 1.51, y: -1.67, z: 0.00979, t: 10.5}, ..., {x: -0.347, y: -0.968, ...}],\n",
+       " [{x: 0.765, y: -0.107, z: 0.0998, t: 10.2}],\n",
+       " [{x: 1.96, y: -0.0284, z: -0.204, t: 8.2}, {x: 0.411, y: -1.67, ...}],\n",
+       " [{x: 0.398, y: 0.242, z: -0.609, t: 8.86}],\n",
+       " [{x: -0.429, y: 1.23, z: 1.44, t: 10.1}],\n",
+       " [{x: -0.52, y: -0.614, z: 0.586, t: 10.6}, ..., {x: -0.732, y: 0.394, ...}],\n",
+       " [{x: -0.21, y: -0.225, z: 0.503, t: 11.6}],\n",
+       " [],\n",
+       " [{x: -1.63, y: 0.324, z: 0.701, t: 9.05}, {x: -0.000179, y: -0.59, ...}]]\n",
+       "---------------------------------------------------------------------------------------------\n",
+       "backend: cpu\n",
+       "nbytes: 3.0 kB\n",
+       "type: 50 * var * Momentum4D[\n",
+       "    x: float64,\n",
+       "    y: float64,\n",
+       "    z: float64,\n",
+       "    t: float64\n",
+       "]</pre>"
+      ],
+      "text/plain": [
+       "<MomentumArray4D [[{x: -1.47, y: -0.254, ...}, ...], ...] type='50 * var * ...'>"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# This is still not a large number. You want millions.\n",
+    "array = vector.Array(\n",
+    "    [\n",
+    "        [\n",
+    "            dict(\n",
+    "                {x: np.random.normal(0, 1) for x in (\"px\", \"py\", \"pz\")},\n",
+    "                E=np.random.normal(10, 1),\n",
+    "            )\n",
+    "            for inner in range(np.random.poisson(1.5))\n",
+    "        ]\n",
+    "        for outer in range(50)\n",
+    "    ]\n",
+    ")\n",
+    "array"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "f6edd6c9-a423-4662-bcae-c685686633c8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def compute_masses(array):\n",
+    "    out = np.empty(len(array), np.float64)\n",
+    "    for i, event in enumerate(array):\n",
+    "        total = vector.obj(px=0.0, py=0.0, pz=0.0, E=0.0)\n",
+    "        for vec in event:\n",
+    "            total = total + vec\n",
+    "        out[i] = total.mass\n",
+    "    return out"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "fa854373-aeba-4274-8ab8-c1c85d5a931b",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "98.5 ms ± 305 μs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit compute_masses(array)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "a6ca1a20-3f5f-485b-8cc0-663cdbf70ec6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@nb.njit\n",
+    "def compute_masses(array):\n",
+    "    out = np.empty(len(array), np.float64)\n",
+    "    for i, event in enumerate(array):\n",
+    "        total = vector.obj(px=0.0, py=0.0, pz=0.0, E=0.0)\n",
+    "        for vec in event:\n",
+    "            total = total + vec\n",
+    "        out[i] = total.mass\n",
+    "    return out"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "c9bbfba4-1000-4d86-9804-340f8494076d",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The slowest run took 2514.01 times longer than the fastest. This could mean that an intermediate result is being cached.\n",
+      "69.1 ms ± 169 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit -n 1 compute_masses(array)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "48d33ad4-a1ad-47f5-ac19-d8d2359265cb",
+   "metadata": {},
+   "source": [
+    "This time, given that the function operates on a large array, the subsequent runs are much faster (by a considerable factor) than the non-JIT version runs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "56f6f10d-ee09-47c8-81da-a639a27a9645",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "194 μs ± 2.57 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit compute_masses(array)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "950f1c48-956b-436b-8b8e-9a2b65fe45d8",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{vector-1.6.0 → vector-1.6.2}/pyproject.toml

@@ -137,7 +137,7 @@ isort.required-imports = [
   "T20",
 ]
 "docs/src/*.ipynb" = [
-  "T20", "I001", "I002"
+  "T20", "I001", "I002", "F811"
 ]
 "src/vector/backends/_numba_object.py" = [
   "PGH003",

{vector-1.6.0 → vector-1.6.2}/src/vector/_methods.py

@@ -4400,7 +4400,7 @@ def _lib_of(*objects: VectorProtocol) -> Module:  # NumPy-like module
         if isinstance(obj, Vector):
             if lib is None:
                 lib = obj.lib
-            elif lib is not obj.lib:
+            elif lib != obj.lib:
                 raise TypeError(
                     f"cannot use {lib} and {obj.lib} in the same calculation"
                 )

{vector-1.6.0 → vector-1.6.2}/src/vector/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.6.0'
-__version_tuple__ = version_tuple = (1, 6, 0)
+__version__ = version = '1.6.2'
+__version_tuple__ = version_tuple = (1, 6, 2)

{vector-1.6.0 → vector-1.6.2}/src/vector/backends/awkward.py

@@ -622,10 +622,38 @@ class AwkwardProtocol(Protocol):
     def __getitem__(self, where: typing.Any) -> float | ak.Array | ak.Record | None: ...
 
 
+class _lib(typing.NamedTuple):
+    """a wrapper that respects the numpy-like interface of awkward-array and the module interface of numpy"""
+
+    module: types.ModuleType
+    nplike: ak._nplikes.numpy_like.NumpyLike
+
+    def __eq__(self, other: typing.Any) -> bool:
+        if isinstance(other, _lib):
+            return self.module is other.module and self.nplike is other.nplike
+        else:
+            return self.module is other
+
+    def __ne__(self, other: typing.Any) -> bool:
+        return not self.__eq__(other)
+
+    def __getattr__(self, name: str) -> typing.Any:
+        if fun := getattr(self.nplike, name, False):
+            return fun
+        else:
+            return getattr(self.module, name)
+
+
 class VectorAwkward:
     """Mixin class for Awkward vectors."""
 
-    lib: types.ModuleType = numpy
+    @property
+    def lib(self):  # type:ignore[no-untyped-def]
+        if (
+            nplike := self.layout.backend.nplike  # type:ignore[attr-defined]
+        ) is ak._nplikes.typetracer.TypeTracer.instance():
+            return _lib(module=numpy, nplike=nplike)
+        return numpy
 
     def _wrap_result(
         self: AwkwardProtocol,