Add legacy/v1 arithmetic convention with deprecation transition (#607)

* Add legacy arithmetic join mode with deprecation warning for transition

- Add `options["arithmetic_join"]` setting (default: "legacy") to control
  coordinate alignment in arithmetic operations, merge, and constraints
- Legacy mode reproduces old behavior: override when shapes match, outer
  otherwise for merge; reindex_like for constants; inner for align()
- All legacy codepaths emit FutureWarning guiding users to opt in to "exact"
- Move shared test fixtures (m, x, y, z, v, u) to conftest.py
- Exact-behavior tests use autouse fixture to set arithmetic_join="exact"
- Legacy test files (test_*_legacy.py) validate old behavior is preserved
- All 2736 tests pass

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Simplify global setting to 'legacy'/'v1', add LinopyDeprecationWarning

- Restrict options["arithmetic_join"] to {"legacy", "v1"} instead of
  exposing all xarray join values (explicit join= parameter still accepts any)
- "v1" maps to "exact" join internally
- Add LinopyDeprecationWarning class (subclass of FutureWarning) with
  centralized message including how to silence
- Export LinopyDeprecationWarning from linopy.__init__

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Rename arithmetic_join to arithmetic_convention, mention v1 removal

- Rename setting from 'arithmetic_join' to 'arithmetic_convention'
- Update deprecation message: "will be removed in linopy v1"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Rename test fixtures from exact_join to v1_convention

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update legacy tests

* Merge harmonize-linopy-operations-mixed, restore NaN filling and align function

- Resolve merge conflicts keeping transition layer logic
- Restore NaN fillna(0) in _add_constant and _apply_constant_op
- Restore simple finisher-based align() function (fixes MultiIndex)
- Use check_common_keys_values in merge legacy path
- Update legacy test files to match origin/harmonize-linopy-operations

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Clean up obsolete code and fix convention-awareness in arithmetic

- Remove dead check_common_keys_values function from common.py
- Remove redundant default_join parameter from _align_constant, use
  options["arithmetic_convention"] directly
- Gate fillna(0) calls in _add_constant and _apply_constant_op behind
  legacy convention check so NaN values propagate correctly under v1
- Fix legacy to_constraint path to compute constraint RHS directly
  instead of routing through sub() which re-applies fillna
- Restore Variable.__mul__ scalar fast path via to_linexpr(other)
- Restore Variable.__div__ explicit TypeError for non-linear division
- Update v1 tests to expect ValueError on mismatched coords and test
  explicit join= escape hatches

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix mypy errors and pytest importmode for CI

- Add return type annotations (Generator) to all v1_convention fixtures
- Add importmode = "importlib" to pytest config to fix import mismatch
  when linopy is installed from wheel and source dir is also present
- Use tuple literal in loop to fix arg-type error

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix CI: move import linopy to lazy in conftest.py

Top-level `import linopy` in conftest.py caused pytest to import the
package from site-packages before collecting doctests from the source
directory, triggering import file mismatch errors on all platforms.

Move the import inside fixture functions where it's actually needed.
Also revert the unnecessary test.yml and importmode changes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: FBumann

.gitignore

@@ -50,4 +50,3 @@ benchmark/scripts/leftovers/
 # direnv
 .envrc
 AGENTS.md
-coverage.xml

linopy/__init__.py

@@ -13,7 +13,7 @@
 # we need to extend their __mul__ functions with a quick special case
 import linopy.monkey_patch_xarray  # noqa: F401
 from linopy.common import align
-from linopy.config import options
+from linopy.config import LinopyDeprecationWarning, options
 from linopy.constants import EQUAL, GREATER_EQUAL, LESS_EQUAL
 from linopy.constraints import Constraint, Constraints
 from linopy.expressions import LinearExpression, QuadraticExpression, merge
@@ -34,6 +34,7 @@
     "EQUAL",
     "GREATER_EQUAL",
     "LESS_EQUAL",
+    "LinopyDeprecationWarning",
     "LinearExpression",
     "Model",
     "Objective",

linopy/common.py

@@ -10,7 +10,7 @@
 import operator
 import os
 from collections.abc import Callable, Generator, Hashable, Iterable, Sequence
-from functools import reduce, wraps
+from functools import partial, reduce, wraps
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload
 from warnings import warn
@@ -1205,7 +1205,7 @@ def check_common_keys_values(list_of_dicts: list[dict[str, Any]]) -> bool:
 
 def align(
     *objects: LinearExpression | QuadraticExpression | Variable | T_Alignable,
-    join: JoinOptions = "exact",
+    join: JoinOptions | None = None,
     copy: bool = True,
     indexes: Any = None,
     exclude: str | Iterable[Hashable] = frozenset(),
@@ -1265,41 +1265,56 @@ def align(
 
 
     """
+    from linopy.config import options
     from linopy.expressions import LinearExpression, QuadraticExpression
     from linopy.variables import Variable
 
-    # Extract underlying Datasets for index computation.
+    if join is None:
+        join = options["arithmetic_convention"]
+
+    if join == "legacy":
+        from linopy.config import LEGACY_DEPRECATION_MESSAGE, LinopyDeprecationWarning
+
+        warn(
+            LEGACY_DEPRECATION_MESSAGE,
+            LinopyDeprecationWarning,
+            stacklevel=2,
+        )
+        join = "inner"
+
+    elif join == "v1":
+        join = "exact"
+
+    finisher: list[partial[Any] | Callable[[Any], Any]] = []
     das: list[Any] = []
     for obj in objects:
-        if isinstance(obj, LinearExpression | QuadraticExpression | Variable):
+        if isinstance(obj, LinearExpression | QuadraticExpression):
+            finisher.append(partial(obj.__class__, model=obj.model))
+            das.append(obj.data)
+        elif isinstance(obj, Variable):
+            finisher.append(
+                partial(
+                    obj.__class__,
+                    model=obj.model,
+                    name=obj.data.attrs["name"],
+                    skip_broadcast=True,
+                )
+            )
             das.append(obj.data)
         else:
+            finisher.append(lambda x: x)
             das.append(obj)
 
     exclude = frozenset(exclude).union(HELPER_DIMS)
-
-    # Compute target indexes.
-    target_aligned = xr_align(
-        *das, join=join, copy=False, indexes=indexes, exclude=exclude
+    aligned = xr_align(
+        *das,
+        join=join,
+        copy=copy,
+        indexes=indexes,
+        exclude=exclude,
+        fill_value=fill_value,
     )
-
-    # Reindex each object to target indexes.
-    reindex_kwargs: dict[str, Any] = {}
-    if fill_value is not dtypes.NA:
-        reindex_kwargs["fill_value"] = fill_value
-    results: list[Any] = []
-    for obj, target in zip(objects, target_aligned):
-        indexers = {
-            dim: target.indexes[dim]
-            for dim in target.dims
-            if dim not in exclude and dim in target.indexes
-        }
-        # Variable.reindex has no fill_value — it always uses sentinels
-        if isinstance(obj, Variable):
-            results.append(obj.reindex(indexers))
-        else:
-            results.append(obj.reindex(indexers, **reindex_kwargs))  # type: ignore[union-attr]
-    return tuple(results)
+    return tuple([f(da) for f, da in zip(finisher, aligned)])
 
 
 LocT = TypeVar(

linopy/config.py

@@ -9,28 +9,46 @@
 
 from typing import Any
 
+VALID_ARITHMETIC_JOINS = {"legacy", "v1"}
+
+LEGACY_DEPRECATION_MESSAGE = (
+    "The 'legacy' arithmetic convention is deprecated and will be removed in "
+    "linopy v1. Set linopy.options['arithmetic_convention'] = 'v1' to opt in "
+    "to the new behavior, or filter this warning with:\n"
+    "  import warnings; warnings.filterwarnings('ignore', category=LinopyDeprecationWarning)"
+)
+
+
+class LinopyDeprecationWarning(FutureWarning):
+    """Warning for deprecated linopy features scheduled for removal."""
+
 
 class OptionSettings:
-    def __init__(self, **kwargs: int) -> None:
+    def __init__(self, **kwargs: Any) -> None:
         self._defaults = kwargs
         self._current_values = kwargs.copy()
 
-    def __call__(self, **kwargs: int) -> None:
+    def __call__(self, **kwargs: Any) -> None:
         self.set_value(**kwargs)
 
-    def __getitem__(self, key: str) -> int:
+    def __getitem__(self, key: str) -> Any:
         return self.get_value(key)
 
-    def __setitem__(self, key: str, value: int) -> None:
+    def __setitem__(self, key: str, value: Any) -> None:
         return self.set_value(**{key: value})
 
-    def set_value(self, **kwargs: int) -> None:
+    def set_value(self, **kwargs: Any) -> None:
         for k, v in kwargs.items():
             if k not in self._defaults:
                 raise KeyError(f"{k} is not a valid setting.")
+            if k == "arithmetic_convention" and v not in VALID_ARITHMETIC_JOINS:
+                raise ValueError(
+                    f"Invalid arithmetic_convention: {v!r}. "
+                    f"Must be one of {VALID_ARITHMETIC_JOINS}."
+                )
             self._current_values[k] = v
 
-    def get_value(self, name: str) -> int:
+    def get_value(self, name: str) -> Any:
         if name in self._defaults:
             return self._current_values[name]
         else:
@@ -57,4 +75,8 @@ def __repr__(self) -> str:
         return f"OptionSettings:\n {settings}"
 
 
-options = OptionSettings(display_max_rows=14, display_max_terms=6)
+options = OptionSettings(
+    display_max_rows=14,
+    display_max_terms=6,
+    arithmetic_convention="legacy",
+)