From 24152021835389d731ea5422754f4ae57abffd02 Mon Sep 17 00:00:00 2001 From: DHRUVA KUMAR KAUSHAL Date: Sat, 29 Nov 2025 07:34:30 +0530 Subject: [PATCH 1/3] documenting how xarray.dot() interacts with coordinates --- xarray/computation/computation.py | 46 +++++++++++++++++++++++++++++++ xarray/core/dataarray.py | 15 ++++++++++ 2 files changed, 61 insertions(+) diff --git a/xarray/computation/computation.py b/xarray/computation/computation.py index b2b53bb9350..679177df3d2 100644 --- a/xarray/computation/computation.py +++ b/xarray/computation/computation.py @@ -515,6 +515,21 @@ 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** + + This function aligns input arrays along their coordinates using an inner join by default. + This means: + + - Coordinates are aligned based on their **values**, not their order in the arrays + - Only **overlapping coordinate values** are included in the computation + - Non-overlapping coordinates are excluded (treated as if entries don't exist) + - Dimensions that are not summed over retain their coordinates in the output + + With the default ``arithmetic_join="inner"`` option, ``dot(a, b)`` is mathematically + equivalent to ``(a * b).sum()`` over the specified dimensions. To require exact + coordinate matching, use ``xr.set_options(arithmetic_join="exact")``, which will + raise an error if coordinates don't match exactly. + Examples -------- >>> da_a = xr.DataArray(np.arange(3 * 2).reshape(3, 2), dims=["a", "b"]) @@ -572,6 +587,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..fb5380f57fe 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -5163,6 +5163,13 @@ def dot( dot numpy.tensordot + Notes + ----- + This method aligns the input arrays along their coordinates using an inner join. + Coordinates are matched by their **values**, not their order. Only overlapping + coordinate values are included in the computation. See :py:func:`xarray.dot` for + more details on coordinate handling. + Examples -------- >>> da_vals = np.arange(6 * 5 * 4).reshape((6, 5, 4)) @@ -5180,6 +5187,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( From 461ec9ef58e918bbb547233558dc1a4785bbef9f Mon Sep 17 00:00:00 2001 From: DHRUVA KUMAR KAUSHAL Date: Sat, 29 Nov 2025 07:55:12 +0530 Subject: [PATCH 2/3] minor fixes --- xarray/computation/computation.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xarray/computation/computation.py b/xarray/computation/computation.py index 679177df3d2..f748f591d77 100644 --- a/xarray/computation/computation.py +++ b/xarray/computation/computation.py @@ -615,7 +615,7 @@ def dot( >>> y = xr.DataArray([10, 20], coords=[("space", ["IA", "IL"])]) >>> xr.dot(x, y, dim="space") # time coordinates are preserved Size: 16B - array([50, 110]) + array([ 50, 110]) Coordinates: * time (time) int64 16B 0 1 """ From 494cb2b25dd55018370d8ece3888a5939ec89ec7 Mon Sep 17 00:00:00 2001 From: DHRUVA KUMAR KAUSHAL Date: Sun, 30 Nov 2025 10:50:59 +0530 Subject: [PATCH 3/3] simplifying --- xarray/computation/computation.py | 17 +++++------------ xarray/core/dataarray.py | 6 ++---- 2 files changed, 7 insertions(+), 16 deletions(-) diff --git a/xarray/computation/computation.py b/xarray/computation/computation.py index f748f591d77..eac27531a05 100644 --- a/xarray/computation/computation.py +++ b/xarray/computation/computation.py @@ -517,18 +517,11 @@ def dot( **Coordinate Handling** - This function aligns input arrays along their coordinates using an inner join by default. - This means: - - - Coordinates are aligned based on their **values**, not their order in the arrays - - Only **overlapping coordinate values** are included in the computation - - Non-overlapping coordinates are excluded (treated as if entries don't exist) - - Dimensions that are not summed over retain their coordinates in the output - - With the default ``arithmetic_join="inner"`` option, ``dot(a, b)`` is mathematically - equivalent to ``(a * b).sum()`` over the specified dimensions. To require exact - coordinate matching, use ``xr.set_options(arithmetic_join="exact")``, which will - raise an error if coordinates don't match exactly. + 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 -------- diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index fb5380f57fe..7ebf3f5c81f 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -5165,10 +5165,8 @@ def dot( Notes ----- - This method aligns the input arrays along their coordinates using an inner join. - Coordinates are matched by their **values**, not their order. Only overlapping - coordinate values are included in the computation. See :py:func:`xarray.dot` for - more details on coordinate handling. + 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 --------