Add an arithmetic_compat option to xr.set_options, which determines how non-index coordinates of the same name are compared for potential conflicts when performing binary operations.

mjwillson · mjwillson · commit 53bad2da36c6 · 2025-11-22T00:23:06.000Z
Previously the behaviour has been fixed at compat='minimal', this allows any of the compat options to be set.

For now the default is still 'minimal', but this sets up arithmetic_compat to be migrated to 'override' alongside the other defaults for compat, as part of use_new_combine_kwarg_defaults. It warns about behaviour which will change under this migration.

A couple of tests which were relying on or testing the arithmetic_compat='minimal' behaviour have been updated to avoid the warning, either by setting arithmetic_compat explicitly or by avoiding a coordinate clash.
diff --git a/doc/whats-new.rst b/doc/whats-new.rst
@@ -17,6 +17,10 @@ New Features
 - :py:func:`combine_nested` now support :py:class:`DataTree` objects
   (:pull:`10849`).
   By `Stephan Hoyer <https://github.com/shoyer>`_.
+- :py:func:`set_options` now supports an `arithmetic_compat` option which determines how non-index coordinates
+  of the same name are compared for potential conflicts when performing binary operations. The default for it is
+  `arithmetic_compat='minimal'` which matches the existing behaviour, but it is slated to change to 'override'
+  in future alongside the other defaults for `compat`, see below.
 
 Breaking Changes
 ~~~~~~~~~~~~~~~~
@@ -25,6 +29,10 @@ Breaking Changes
 Deprecations
 ~~~~~~~~~~~~
 
+- The default for the `arithmetic_compat` option will change from 'minimal' to 'override' in a future version,
+  consistent with the existing deprecation cycle which will change the default for `compat` to 'override' elsewhere.
+  We log a warning on behaviour which will change when this default changes.
+
 
 Bug Fixes
 ~~~~~~~~~
diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py
@@ -21,7 +21,7 @@
     assert_no_index_corrupted,
     create_default_index_implicit,
 )
-from xarray.core.types import DataVars, ErrorOptions, Self, T_DataArray, T_Xarray
+from xarray.core.types import CompatOptions, DataVars, ErrorOptions, Self, T_DataArray, T_Xarray
 from xarray.core.utils import (
     Frozen,
     ReprObject,
@@ -31,6 +31,7 @@
 from xarray.core.variable import Variable, as_variable, calculate_dimensions
 from xarray.structure.alignment import Aligner
 from xarray.structure.merge import merge_coordinates_without_align, merge_coords
+from xarray.util.deprecation_helpers import CombineKwargDefault
 
 if TYPE_CHECKING:
     from xarray.core.common import DataWithCoords
@@ -499,18 +500,18 @@ def _drop_coords(self, coord_names):
         # redirect to DatasetCoordinates._drop_coords
         self._data.coords._drop_coords(coord_names)
 
-    def _merge_raw(self, other, reflexive):
+    def _merge_raw(self, other, reflexive, compat: CompatOptions | CombineKwargDefault):
         """For use with binary arithmetic."""
         if other is None:
             variables = dict(self.variables)
             indexes = dict(self.xindexes)
         else:
             coord_list = [self, other] if not reflexive else [other, self]
-            variables, indexes = merge_coordinates_without_align(coord_list)
+            variables, indexes = merge_coordinates_without_align(coord_list, compat=compat)
         return variables, indexes
 
     @contextmanager
-    def _merge_inplace(self, other):
+    def _merge_inplace(self, other, compat: CompatOptions | CombineKwargDefault):
         """For use with in-place binary arithmetic."""
         if other is None:
             yield
@@ -523,12 +524,16 @@ def _merge_inplace(self, other):
                 if k not in self.xindexes
             }
             variables, indexes = merge_coordinates_without_align(
-                [self, other], prioritized
+                [self, other], prioritized, compat=compat
             )
             yield
             self._update_coords(variables, indexes)
 
-    def merge(self, other: Mapping[Any, Any] | None) -> Dataset:
+    def merge(
+        self,
+        other: Mapping[Any, Any] | None,
+        compat: CompatOptions | CombineKwargDefault = "minimal",
+        ) -> Dataset:
         """Merge two sets of coordinates to create a new Dataset
 
         The method implements the logic used for joining coordinates in the
@@ -545,6 +550,9 @@ def merge(self, other: Mapping[Any, Any] | None) -> Dataset:
         other : dict-like, optional
             A :py:class:`Coordinates` object or any mapping that can be turned
             into coordinates.
+        compat : {"identical", "equals", "broadcast_equals", "no_conflicts",
+            "override", "minimal"}, default: "minimal"
+            Compatibility checks to use between coordinate variables.
 
         Returns
         -------
@@ -559,7 +567,7 @@ def merge(self, other: Mapping[Any, Any] | None) -> Dataset:
         if not isinstance(other, Coordinates):
             other = Dataset(coords=other).coords
 
-        coords, indexes = merge_coordinates_without_align([self, other])
+        coords, indexes = merge_coordinates_without_align([self, other], compat=compat)
         coord_names = set(coords)
         return Dataset._construct_direct(
             variables=coords, coord_names=coord_names, indexes=indexes
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
@@ -4899,7 +4899,8 @@ def _binary_op(
             if not reflexive
             else f(other_variable_or_arraylike, self.variable)
         )
-        coords, indexes = self.coords._merge_raw(other_coords, reflexive)
+        coords, indexes = self.coords._merge_raw(
+            other_coords, reflexive, compat=OPTIONS["arithmetic_compat"])
         name = result_name([self, other])
 
         return self._replace(variable, coords, name, indexes=indexes)
@@ -4919,7 +4920,7 @@ def _inplace_binary_op(self, other: DaCompatible, f: Callable) -> Self:
         other_coords = getattr(other, "coords", None)
         other_variable = getattr(other, "variable", other)
         try:
-            with self.coords._merge_inplace(other_coords):
+            with self.coords._merge_inplace(other_coords, compat=OPTIONS["arithmetic_compat"]):
                 f(self.variable, other_variable)
         except MergeError as exc:
             raise MergeError(
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
@@ -7765,7 +7765,7 @@ def apply_over_both(lhs_data_vars, rhs_data_vars, lhs_vars, rhs_vars):
             return type(self)(new_data_vars)
 
         other_coords: Coordinates | None = getattr(other, "coords", None)
-        ds = self.coords.merge(other_coords)
+        ds = self.coords.merge(other_coords, compat=OPTIONS["arithmetic_compat"])
 
         if isinstance(other, Dataset):
             new_vars = apply_over_both(
diff --git a/xarray/core/options.py b/xarray/core/options.py
@@ -2,14 +2,17 @@
 
 import warnings
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Any, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, Literal, TypedDict, get_args
 
 from xarray.core.utils import FrozenDict
+from xarray.core.types import CompatOptions
+from xarray.util.deprecation_helpers import CombineKwargDefault, _ARITHMETIC_COMPAT_DEFAULT
 
 if TYPE_CHECKING:
     from matplotlib.colors import Colormap
 
     Options = Literal[
+        "arithmetic_compat",
         "arithmetic_join",
         "chunk_manager",
         "cmap_divergent",
@@ -40,6 +43,7 @@
 
     class T_Options(TypedDict):
         arithmetic_broadcast: bool
+        arithmetic_compat: CompatOptions | CombineKwargDefault
         arithmetic_join: Literal["inner", "outer", "left", "right", "exact"]
         chunk_manager: str
         cmap_divergent: str | Colormap
@@ -70,6 +74,7 @@ class T_Options(TypedDict):
 
 OPTIONS: T_Options = {
     "arithmetic_broadcast": True,
+    "arithmetic_compat": _ARITHMETIC_COMPAT_DEFAULT,
     "arithmetic_join": "inner",
     "chunk_manager": "dask",
     "cmap_divergent": "RdBu_r",
@@ -109,6 +114,7 @@ def _positive_integer(value: Any) -> bool:
 
 _VALIDATORS = {
     "arithmetic_broadcast": lambda value: isinstance(value, bool),
+    "arithmetic_compat": get_args(CompatOptions).__contains__,
     "arithmetic_join": _JOIN_OPTIONS.__contains__,
     "display_max_children": _positive_integer,
     "display_max_rows": _positive_integer,
@@ -178,18 +184,35 @@ class set_options:
 
     Parameters
     ----------
+    arithmetic_broadcast: bool, default: True
+        Whether to perform automatic broadcasting in binary operations.
+    arithmetic_compat: {"identical", "equals", "broadcast_equals", "no_conflicts",
+        "override", "minimal"}, default: "minimal"
+        How to compare non-index coordinates of the same name for potential
+        conflicts when performing binary operations. (For the alignment of index
+        coordinates in binary operations, see `arithmetic_join`.)
+
+        - "identical": all values, dimensions and attributes of the coordinates
+          must be the same.
+        - "equals": all values and dimensions of the coordinates must be the
+          same.
+        - "broadcast_equals": all values of the coordinates must be equal after
+          broadcasting to ensure common dimensions.
+        - "no_conflicts": only values which are not null in both coordinates
+          must be equal. The returned coordinate then contains the combination
+          of all non-null values.
+        - "override": skip comparing and take the coordinates from the first
+          operand.
+        - "minimal": drop conflicting coordinates.
     arithmetic_join : {"inner", "outer", "left", "right", "exact"}, default: "inner"
-        DataArray/Dataset alignment in binary operations:
+        DataArray/Dataset index alignment in binary operations:
 
         - "outer": use the union of object indexes
         - "inner": use the intersection of object indexes
         - "left": use indexes from the first object with each dimension
         - "right": use indexes from the last object with each dimension
         - "exact": instead of aligning, raise `ValueError` when indexes to be
           aligned are not equal
-        - "override": if indexes are of same size, rewrite indexes to be
-          those of the first object with that dimension. Indexes for the same
-          dimension must have the same size in all objects.
     chunk_manager : str, default: "dask"
         Chunk manager to use for chunked array computations when multiple
         options are installed.
diff --git a/xarray/structure/merge.py b/xarray/structure/merge.py
@@ -332,6 +332,18 @@ def merge_collected(
                             FutureWarning,
                         )
                 except MergeError:
+                    if isinstance(compat, CombineKwargDefault) and compat == "minimal":
+                        emit_user_level_warning(
+                            compat.warning_message(
+                                f"Here we have dropped the variable {name!r} due to either a "
+                                "failed equality test between variables of this name, or an "
+                                "inability to perform such an equality test. The default in "
+                                "future will be to retain the first instance of variable "
+                                f"{name!r} without attempting an equality check."
+                            ),
+                            FutureWarning,
+                        )
+
                     if compat != "minimal":
                         # we need more than "minimal" compatibility (for which
                         # we drop conflicting coordinates)
@@ -433,6 +445,7 @@ def merge_coordinates_without_align(
     prioritized: Mapping[Any, MergeElement] | None = None,
     exclude_dims: AbstractSet = frozenset(),
     combine_attrs: CombineAttrsOptions = "override",
+    compat: CompatOptions | CombineKwargDefault = "minimal",
 ) -> tuple[dict[Hashable, Variable], dict[Hashable, Index]]:
     """Merge variables/indexes from coordinates without automatic alignments.
 
@@ -457,7 +470,7 @@ def merge_coordinates_without_align(
     # TODO: indexes should probably be filtered in collected elements
     # before merging them
     merged_coords, merged_indexes = merge_collected(
-        filtered, prioritized, combine_attrs=combine_attrs
+        filtered, prioritized, compat=compat, combine_attrs=combine_attrs
     )
     merged_indexes = filter_indexes_from_coords(merged_indexes, set(merged_coords))
 
diff --git a/xarray/tests/test_dataarray.py b/xarray/tests/test_dataarray.py
@@ -25,6 +25,7 @@
     DataArray,
     Dataset,
     IndexVariable,
+    MergeError,
     Variable,
     align,
     broadcast,
@@ -2477,27 +2478,30 @@ def test_math_with_coords(self) -> None:
         actual = 1 + orig
         assert_identical(expected, actual)
 
-        actual = orig + orig[0, 0]
-        exp_coords = {k: v for k, v in coords.items() if k != "lat"}
-        expected = DataArray(
-            orig.values + orig.values[0, 0], exp_coords, dims=["x", "y"]
-        )
-        assert_identical(expected, actual)
+        with xr.set_options(arithmetic_compat='minimal'):
+            actual = orig + orig[0, 0]
+            exp_coords = {k: v for k, v in coords.items() if k != "lat"}
+            expected = DataArray(
+                orig.values + orig.values[0, 0], exp_coords, dims=["x", "y"]
+            )
+            assert_identical(expected, actual)
 
-        actual = orig[0, 0] + orig
-        assert_identical(expected, actual)
+            actual = orig[0, 0] + orig
+            assert_identical(expected, actual)
 
-        actual = orig[0, 0] + orig[-1, -1]
-        expected = DataArray(orig.values[0, 0] + orig.values[-1, -1], {"c": -999})
-        assert_identical(expected, actual)
+            actual = orig[0, 0] + orig[-1, -1]
+            expected = DataArray(
+                orig.values[0, 0] + orig.values[-1, -1],
+                {"c": -999})
+            assert_identical(expected, actual)
 
-        actual = orig[:, 0] + orig[0, :]
-        exp_values = orig[:, 0].values[:, None] + orig[0, :].values[None, :]
-        expected = DataArray(exp_values, exp_coords, dims=["x", "y"])
-        assert_identical(expected, actual)
+            actual = orig[:, 0] + orig[0, :]
+            exp_values = orig[:, 0].values[:, None] + orig[0, :].values[None, :]
+            expected = DataArray(exp_values, exp_coords, dims=["x", "y"])
+            assert_identical(expected, actual)
 
-        actual = orig[0, :] + orig[:, 0]
-        assert_identical(expected.transpose(transpose_coords=True), actual)
+            actual = orig[0, :] + orig[:, 0]
+            assert_identical(expected.transpose(transpose_coords=True), actual)
 
         actual = orig - orig.transpose(transpose_coords=True)
         expected = DataArray(np.zeros((2, 3)), orig.coords)
@@ -2507,14 +2511,53 @@ def test_math_with_coords(self) -> None:
         assert_identical(expected.transpose(transpose_coords=True), actual)
 
         alt = DataArray([1, 1], {"x": [-1, -2], "c": "foo", "d": 555}, "x")
-        actual = orig + alt
-        expected = orig + 1
-        expected.coords["d"] = 555
-        del expected.coords["c"]
-        assert_identical(expected, actual)
 
-        actual = alt + orig
-        assert_identical(expected, actual)
+        with xr.set_options(arithmetic_compat='minimal'):
+            actual = orig + alt
+            expected = orig + 1
+            expected.coords["d"] = 555
+            del expected.coords["c"]
+            assert_identical(expected, actual)
+
+            actual = alt + orig
+            assert_identical(expected, actual)
+
+    def test_math_with_arithmetic_compat_options(self) -> None:
+        # Setting up a clash of non-index coordinate 'foo':
+        a = xr.DataArray(
+            data=[0, 0, 0],
+            dims=["x"],
+            coords={
+                "x": [1, 2, 3],
+                "foo": (["x"], [1.0, 2.0, np.nan]),
+            }
+        )
+        b = xr.DataArray(
+            data=[0, 0, 0],
+            dims=["x"],
+            coords={
+                "x": [1, 2, 3],
+                "foo": (["x"], [np.nan, 2.0, 3.0]),
+            }
+        )
+
+        with xr.set_options(arithmetic_compat="minimal"):
+            assert_equal(a + b, a.drop_vars("foo"))
+
+        with xr.set_options(arithmetic_compat="override"):
+            assert_equal(a + b, a)
+            assert_equal(b + a, b)
+
+        with xr.set_options(arithmetic_compat="no_conflicts"):
+            expected = a.assign_coords(foo=(["x"], [1.0, 2.0, 3.0]))
+            assert_equal(a + b, expected)
+            assert_equal(b + a, expected)
+
+        with xr.set_options(arithmetic_compat="equals"):
+            with pytest.raises(MergeError):
+                a + b
+            with pytest.raises(MergeError):
+                b + a
 
     def test_index_math(self) -> None:
         orig = DataArray(range(3), dims="x", name="x")
diff --git a/xarray/tests/test_dataset.py b/xarray/tests/test_dataset.py
diff --git a/xarray/tests/test_interp.py b/xarray/tests/test_interp.py
diff --git a/xarray/util/deprecation_helpers.py b/xarray/util/deprecation_helpers.py
