New alignment option: join='strict'

.gitignore

@@ -79,3 +79,6 @@ doc/team-panel.txt
 doc/external-examples-gallery.txt
 doc/notebooks-examples-gallery.txt
 doc/videos-gallery.txt
+
+# MyPy Report
+mypy_report/

doc/user-guide/options.rst

@@ -16,7 +16,7 @@ Xarray offers a small number of configuration options through :py:func:`set_opti
    - ``display_max_rows``
    - ``display_style``
 
-2. Control behaviour during operations: ``arithmetic_join``, ``keep_attrs``, ``use_bottleneck``.
+2. Control behaviour during operations: ``arithmetic_broadcast``, ``arithmetic_join``, ``keep_attrs``, ``use_bottleneck``.
 3. Control colormaps for plots:``cmap_divergent``, ``cmap_sequential``.
 4. Aspects of file reading: ``file_cache_maxsize``, ``warn_on_unclosed_files``.
 

doc/whats-new.rst

@@ -64,6 +64,9 @@ Mathias Hauser, Matt Savoie, Maximilian Roos, Rambaud Pierrick, Tom Nicholas
 New Features
 ~~~~~~~~~~~~
 
+- Added the ability to control broadcasting for alignment, and new gloal option ``arithmetic_broadcast``
+  (:issue:`6806`, :pull:`8698`).
+  By `Etienne Schalk <https://github.com/etienneschalk>`_.
 - Added a simple ``nbytes`` representation in DataArrays and Dataset ``repr``.
   (:issue:`8690`, :pull:`8702`).
   By `Etienne Schalk <https://github.com/etienneschalk>`_.

xarray/core/alignment.py

@@ -5,7 +5,17 @@
 from collections import defaultdict
 from collections.abc import Hashable, Iterable, Mapping
 from contextlib import suppress
-from typing import TYPE_CHECKING, Any, Callable, Final, Generic, TypeVar, cast, overload
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Final,
+    Generic,
+    TypeVar,
+    cast,
+    get_args,
+    overload,
+)
 
 import numpy as np
 import pandas as pd
@@ -19,7 +29,7 @@
     indexes_all_equal,
     safe_cast_to_index,
 )
-from xarray.core.types import T_Alignable
+from xarray.core.types import JoinOptions, T_Alignable
 from xarray.core.utils import is_dict_like, is_full_slice
 from xarray.core.variable import Variable, as_compatible_data, calculate_dimensions
 
@@ -28,7 +38,6 @@
     from xarray.core.dataset import Dataset
     from xarray.core.types import (
         Alignable,
-        JoinOptions,
         T_DataArray,
         T_Dataset,
         T_DuckArray,
@@ -113,6 +122,7 @@ class Aligner(Generic[T_Alignable]):
     results: tuple[T_Alignable, ...]
     objects_matching_indexes: tuple[dict[MatchingIndexKey, Index], ...]
     join: str
+    broadcast: bool
     exclude_dims: frozenset[Hashable]
     exclude_vars: frozenset[Hashable]
     copy: bool
@@ -133,6 +143,7 @@ def __init__(
         self,
         objects: Iterable[T_Alignable],
         join: str = "inner",
+        broadcast: bool = True,
         indexes: Mapping[Any, Any] | None = None,
         exclude_dims: str | Iterable[Hashable] = frozenset(),
         exclude_vars: Iterable[Hashable] = frozenset(),
@@ -145,9 +156,10 @@ def __init__(
         self.objects = tuple(objects)
         self.objects_matching_indexes = ()
 
-        if join not in ["inner", "outer", "override", "exact", "left", "right"]:
+        if join not in get_args(JoinOptions):
             raise ValueError(f"invalid value for join: {join}")
         self.join = join
+        self.broadcast = broadcast
 
         self.copy = copy
         self.fill_value = fill_value
@@ -264,13 +276,19 @@ def find_matching_indexes(self) -> None:
         self.all_indexes = all_indexes
         self.all_index_vars = all_index_vars
 
-        if self.join == "override":
+        if self.join == "override" or not self.broadcast:
             for dim_sizes in all_indexes_dim_sizes.values():
                 for dim, sizes in dim_sizes.items():
                     if len(sizes) > 1:
+                        message = (
+                            "join='override'"
+                            if self.join == "override"
+                            else "broadcast=False"
+                        )
                         raise ValueError(
-                            "cannot align objects with join='override' with matching indexes "
-                            f"along dimension {dim!r} that don't have the same size"
+                            f"cannot align objects with indexes "
+                            f"along dimension {dim!r} that don't have the same size "
+                            f"({sizes!r}) when {message}"
                         )
 
     def find_matching_unindexed_dims(self) -> None:
@@ -478,6 +496,20 @@ def assert_unindexed_dim_sizes_equal(self) -> None:
                     f"because of conflicting dimension sizes: {sizes!r}" + add_err_msg
                 )
 
+    def assert_equal_dimension_names(self) -> None:
+        # When broadcasting is disabled, only allows objects having the exact same dimensions' names.
+        if self.broadcast:
+            return
+
+        unique_dims = set(tuple(o.dims) for o in self.objects)
+        all_objects_have_same_dims = len(unique_dims) == 1
+        if not all_objects_have_same_dims:
+            raise ValueError(
+                f"cannot align objects with broadcast=False "
+                f"because given objects do not share the same dimension names "
+                f"({[tuple(o.dims) for o in self.objects]!r})."
+            )
+
     def override_indexes(self) -> None:
         objects = list(self.objects)
 
@@ -568,6 +600,7 @@ def align(self) -> None:
             self.results = (obj.copy(deep=self.copy),)
             return
 
+        self.assert_equal_dimension_names()
         self.find_matching_indexes()
         self.find_matching_unindexed_dims()
         self.assert_no_index_conflict()
@@ -595,6 +628,7 @@ def align(
     /,
     *,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -609,6 +643,7 @@ def align(
     /,
     *,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -624,6 +659,7 @@ def align(
     /,
     *,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -640,6 +676,7 @@ def align(
     /,
     *,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -657,6 +694,7 @@ def align(
     /,
     *,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -668,6 +706,7 @@ def align(
 def align(
     *objects: T_Alignable,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -678,6 +717,7 @@ def align(
 def align(
     *objects: T_Alignable,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -710,7 +750,9 @@ def align(
         - "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.
-
+    broadcast : bool, optional
+        Disallow automatic broadcasting of all objects along dimensions that are present in some but not all objects.
+        If False, this will raise an error when all objects do *not* have the same dimensions.
     copy : bool, default: True
         If ``copy=True``, data in the return values is always copied. If
         ``copy=False`` and reindexing is unnecessary, or can be performed with
@@ -874,6 +916,7 @@ def align(
     aligner = Aligner(
         objects,
         join=join,
+        broadcast=broadcast,
         copy=copy,
         indexes=indexes,
         exclude_dims=exclude,
@@ -886,6 +929,7 @@ def align(
 def deep_align(
     objects: Iterable[Any],
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -946,6 +990,7 @@ def is_alignable(obj):
     aligned = align(
         *targets,
         join=join,
+        broadcast=broadcast,
         copy=copy,
         indexes=indexes,
         exclude=exclude,

xarray/core/arithmetic.py

@@ -78,6 +78,7 @@ def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
                 "`.values`)."
             )
 
+        broadcast = OPTIONS["arithmetic_broadcast"]
         join = dataset_join = OPTIONS["arithmetic_join"]
 
         return apply_ufunc(
@@ -86,6 +87,7 @@ def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
             input_core_dims=((),) * ufunc.nin,
             output_core_dims=((),) * ufunc.nout,
             join=join,
+            broadcast=broadcast,
             dataset_join=dataset_join,
             dataset_fill_value=np.nan,
             kwargs=kwargs,

xarray/core/computation.py

@@ -282,6 +282,7 @@ def apply_dataarray_vfunc(
     *args,
     signature: _UFuncSignature,
     join: JoinOptions = "inner",
+    broadcast: bool = True,
     exclude_dims=frozenset(),
     keep_attrs="override",
 ) -> tuple[DataArray, ...] | DataArray:
@@ -295,6 +296,7 @@ def apply_dataarray_vfunc(
             deep_align(
                 args,
                 join=join,
+                broadcast=broadcast,
                 copy=False,
                 exclude=exclude_dims,
                 raise_on_invalid=False,
@@ -494,6 +496,7 @@ def apply_dataset_vfunc(
     signature: _UFuncSignature,
     join="inner",
     dataset_join="exact",
+    broadcast: bool = True,
     fill_value=_NO_FILL_VALUE,
     exclude_dims=frozenset(),
     keep_attrs="override",
@@ -518,6 +521,7 @@ def apply_dataset_vfunc(
             deep_align(
                 args,
                 join=join,
+                broadcast=broadcast,
                 copy=False,
                 exclude=exclude_dims,
                 raise_on_invalid=False,
@@ -1906,6 +1910,7 @@ def dot(
     subscripts = ",".join(subscripts_list)
     subscripts += "->..." + "".join(dim_map[d] for d in output_core_dims[0])
 
+    broadcast = OPTIONS["arithmetic_broadcast"]
     join = OPTIONS["arithmetic_join"]
     # using "inner" emulates `(a * b).sum()` for all joins (except "exact")
     if join != "exact":
@@ -1920,6 +1925,7 @@ def dot(
         input_core_dims=input_core_dims,
         output_core_dims=output_core_dims,
         join=join,
+        broadcast=broadcast,
         dask="allowed",
     )
     return result.transpose(*all_dims, missing_dims="ignore")

xarray/core/concat.py

@@ -146,6 +146,7 @@ def concat(
         - "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.
+
     combine_attrs : {"drop", "identical", "no_conflicts", "drop_conflicts", \
                      "override"} or callable, default: "override"
         A callable or a string indicating how to combine attrs of the objects being

xarray/core/dataarray.py

@@ -4671,8 +4671,11 @@ def _binary_op(
         if isinstance(other, (Dataset, GroupBy)):
             return NotImplemented
         if isinstance(other, DataArray):
+            broadcast = OPTIONS["arithmetic_broadcast"]
             align_type = OPTIONS["arithmetic_join"]
-            self, other = align(self, other, join=align_type, copy=False)
+            self, other = align(
+                self, other, join=align_type, broadcast=broadcast, copy=False
+            )
         other_variable_or_arraylike: DaCompatible = getattr(other, "variable", other)
         other_coords = getattr(other, "coords", None)
 

xarray/core/dataset.py

@@ -7584,8 +7584,11 @@ def _binary_op(self, other, f, reflexive=False, join=None) -> Dataset:
         if isinstance(other, GroupBy):
             return NotImplemented
         align_type = OPTIONS["arithmetic_join"] if join is None else join
+        broadcast = OPTIONS["arithmetic_broadcast"]
         if isinstance(other, (DataArray, Dataset)):
-            self, other = align(self, other, join=align_type, copy=False)
+            self, other = align(
+                self, other, join=align_type, broadcast=broadcast, copy=False
+            )
         g = f if not reflexive else lambda x, y: f(y, x)
         ds = self._calculate_binary_op(g, other, join=align_type)
         keep_attrs = _get_keep_attrs(default=False)

xarray/core/merge.py

@@ -541,6 +541,7 @@ def merge_coords(
     objects: Iterable[CoercibleMapping],
     compat: CompatOptions = "minimal",
     join: JoinOptions = "outer",
+    broadcast: bool = True,
     priority_arg: int | None = None,
     indexes: Mapping[Any, Index] | None = None,
     fill_value: object = dtypes.NA,
@@ -554,7 +555,12 @@ def merge_coords(
     _assert_compat_valid(compat)
     coerced = coerce_pandas_values(objects)
     aligned = deep_align(
-        coerced, join=join, copy=False, indexes=indexes, fill_value=fill_value
+        coerced,
+        join=join,
+        broadcast=broadcast,
+        copy=False,
+        indexes=indexes,
+        fill_value=fill_value,
     )
     collected = collect_variables_and_indexes(aligned, indexes=indexes)
     prioritized = _get_priority_vars_and_indexes(aligned, priority_arg, compat=compat)
@@ -647,6 +653,7 @@ def merge_core(
     objects: Iterable[CoercibleMapping],
     compat: CompatOptions = "broadcast_equals",
     join: JoinOptions = "outer",
+    broadcast: bool = True,
     combine_attrs: CombineAttrsOptions = "override",
     priority_arg: int | None = None,
     explicit_coords: Iterable[Hashable] | None = None,
@@ -709,7 +716,12 @@ def merge_core(
 
     coerced = coerce_pandas_values(objects)
     aligned = deep_align(
-        coerced, join=join, copy=False, indexes=indexes, fill_value=fill_value
+        coerced,
+        join=join,
+        broadcast=broadcast,
+        copy=False,
+        indexes=indexes,
+        fill_value=fill_value,
     )
 
     for pos, obj in skip_align_objs: