polars.Expr.arr.dot#

Expr.arr.dot(other: IntoExpr | Sequence[Any]) → Expr[source]#

Compute row-wise dot product with another Array expression.

engine:In MemoryStreamingDistributed

Both inputs must contain equal-width arrays. Their inner data types are cast to a common supertype, which must be an integer, Float32, or Float64. An input with one row is broadcast against the other input. If either input Array is null for a row, the result for that row is null.

Parameters:
other

Array expression or query vector to compute dot product with. A Python sequence or one-dimensional NumPy array is treated as a one-row Array query. A one-row Series is also broadcast.

Notes

Elements are paired by position.

Pairs where either element is null do not contribute to the sum. If a non-null row has no pairs where both elements are valid, the result is zero.

Integer operations use wrapping arithmetic. Each pair is multiplied in the common inner data type before the product is converted to the arr.sum accumulator type. Therefore, an Int64 output does not prevent multiplication from overflowing in Int8, UInt8, Int16, or UInt16. Accumulation may also wrap in the output type. To avoid wrapping, cast both Array inputs to a type that can represent each product and the final sum before calling dot.

NaN and infinity follow floating-point multiplication and addition semantics. Floating-point results are not guaranteed to be bitwise identical to mathematically equivalent expressions that use a different reduction path.

Examples

>>> df = pl.DataFrame(
...     {
...         "a": [[1.0, 2.0], [3.0, 4.0]],
...         "b": [[5.0, 6.0], [7.0, 8.0]],
...     },
...     schema={
...         "a": pl.Array(pl.Float64, 2),
...         "b": pl.Array(pl.Float64, 2),
...     },
... )
>>> df.select(pl.col("a").arr.dot("b"))
shape: (2, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 17.0 │
│ 53.0 │
└──────┘

A Python sequence can be used as a broadcast query.

>>> query = [2.0, 3.0]
>>> df.select(pl.col("a").arr.dot(query))
shape: (2, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 8.0  │
│ 18.0 │
└──────┘

Integer multiplication can wrap before accumulator promotion.

>>> a = pl.Series("a", [[100, 100]], dtype=pl.Array(pl.Int8, 2))
>>> b = pl.Series("b", [[2, 2]], dtype=pl.Array(pl.Int8, 2))
>>> a.arr.dot(b)
shape: (1,)
Series: 'a' [i64]
[
    -112
]

Cast both inputs before dot to perform multiplication and accumulation in a type that can represent the result.

>>> wide = pl.Array(pl.Int64, 2)
>>> a.cast(wide).arr.dot(b.cast(wide))
shape: (1,)
Series: 'a' [i64]
[
    400
]
On this page