documenting how xarray.dot() interacts with coordinates

[dhruvak001]

• Closes Document how dot interacts with coordinates #10899

Description

This PR addresses issue #10899 by documenting how xarray.dot() and DataArray.dot() interact with coordinates.

Previously, the documentation did not explain:

• How coordinates behave when arrays have coordinates in different orders
• What happens when coordinate values don't overlap
• Which coordinates appear in the output array

Changes

Enhanced xarray.dot() documentation (xarray/computation/computation.py)

Added a new "Coordinate Handling" subsection to the Notes that clearly explains:

• Coordinates are aligned based on their values, not their positional order
• Uses an inner join by default (only overlapping coordinate values are included)
• Non-overlapping coordinates are excluded from the computation
• Dimensions not involved in the summation retain their coordinates in the output
• How to use xr.set_options(arithmetic_join="exact") to require exact coordinate matching and raise errors on misalignment

Added three practical examples demonstrating:

1. Coordinate alignment by value: Shows that x["a", "b"] @ y["b", "a"] correctly aligns by coordinate value
2. Non-overlapping coordinates: Shows that only overlapping coordinate values participate in the dot product
3. Preserved output coordinates: Shows that non-summed dimensions retain their coordinates

Enhanced DataArray.dot() documentation (xarray/core/dataarray.py)

Added a Notes section explaining:

• The method aligns input arrays using an inner join
• Coordinates are matched by values, not order
• Cross-reference to xarray.dot() for detailed information

Added an example demonstrating coordinate alignment behavior.

Example Usage

import xarray as xr

# Coordinates aligned by value, not order
x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
y = xr.DataArray([2, 20], coords=[("foo", ["b", "a"])])
xr.dot(x, y)  # Returns 40 (1*20 + 10*2)

# Non-overlapping coordinates
x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
y = xr.DataArray([2, 30], coords=[("foo", ["b", "c"])])
xr.dot(x, y)  # Returns 20 (only "b" overlaps: 10*2)

# Preserved 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")  # Returns array with time coordinate preserved

[max-sixty]

thanks @dhruvak001

does dot differ from other methods? if not, we should just bolster the general docs...

[dhruvak001]

sure, I will update.