diff --git a/xarray/computation/computation.py b/xarray/computation/computation.py index b2b53bb9350..eac27531a05 100644 --- a/xarray/computation/computation.py +++ b/xarray/computation/computation.py @@ -515,6 +515,14 @@ def dot( We recommend installing the optional ``opt_einsum`` package, or alternatively passing ``optimize=True``, which is passed through to ``np.einsum``, and works for most array backends. + **Coordinate Handling** + + Like all xarray operations, ``dot`` automatically aligns array coordinates. + Coordinates are aligned by their **values**, not their order. By default, xarray uses + an inner join, so only overlapping coordinate values are included. With the default + ``arithmetic_join="inner"``, ``dot(a, b)`` is mathematically equivalent to ``(a * b).sum()`` + over the specified dimensions. See :ref:`math automatic alignment` for more details. + Examples -------- >>> da_a = xr.DataArray(np.arange(3 * 2).reshape(3, 2), dims=["a", "b"]) @@ -572,6 +580,37 @@ def dot( >>> xr.dot(da_a, da_b, dim=...) Size: 8B array(235) + + **Coordinate alignment examples:** + + Coordinates are aligned by their values, not their order: + + >>> x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])]) + >>> y = xr.DataArray([2, 20], coords=[("foo", ["b", "a"])]) + >>> xr.dot(x, y) + Size: 8B + array(40) + + Non-overlapping coordinates are excluded from the computation: + + >>> x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])]) + >>> y = xr.DataArray([2, 30], coords=[("foo", ["b", "c"])]) + >>> xr.dot(x, y) # only 'b' overlaps: 10 * 2 = 20 + Size: 8B + array(20) + + Dimensions not involved in the dot product keep their coordinates: + + >>> x = xr.DataArray( + ... [[1, 2], [3, 4]], + ... coords=[("time", [0, 1]), ("space", ["IA", "IL"])], + ... ) + >>> y = xr.DataArray([10, 20], coords=[("space", ["IA", "IL"])]) + >>> xr.dot(x, y, dim="space") # time coordinates are preserved + Size: 16B + array([ 50, 110]) + Coordinates: + * time (time) int64 16B 0 1 """ from xarray.core.dataarray import DataArray diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 6c8d0617038..7ebf3f5c81f 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -5163,6 +5163,11 @@ def dot( dot numpy.tensordot + Notes + ----- + This method automatically aligns coordinates by their values (not their order). + See :ref:`math automatic alignment` and :py:func:`xarray.dot` for more details. + Examples -------- >>> da_vals = np.arange(6 * 5 * 4).reshape((6, 5, 4)) @@ -5180,6 +5185,14 @@ def dot( >>> dot_result.dims ('x', 'y') + Coordinates are aligned by their values: + + >>> x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])]) + >>> y = xr.DataArray([2, 20], coords=[("foo", ["b", "a"])]) + >>> x.dot(y) + Size: 8B + array(40) + """ if isinstance(other, Dataset): raise NotImplementedError(