Meta: predictable arithmetic — coordinate alignment and NaN handling

[FBumann]

Tracking issue for the known problems with linopy's arithmetic — coordinate alignment and NaN handling — and the v1 convention that fixes them.

linopy aligns coordinates with size-based heuristics. When operands don't line up it guesses, and the guesses are sometimes silently wrong — no exception, the solver returns Optimal, the objective looks plausible. PyPSA/PyPSA#1677 shipped a workaround for one such case (a capacity-expansion result 47% too cheap).

Bugs — silent wrong answers

• Operators align coordinates inconsistently — Operators align coordinates inconsistently (* by label, + - / by position) #708 (root cause), x - a <= 0 and x <= a build different constraints #707, bug when adding two linopy expressions/variables that share dimension names but have disjoint label coordinates of same size #670
• Subset constants break associativity — Subset constants break associativity: a + factor + b ≠ a + b + factor #711
• An absent variable is indistinguishable from a zero variable — An absent variable is indistinguishable from a zero variable #712
• Non-dimension coordinates leak into expressions — a conflicting auxiliary coordinate is silently kept, not raised — Auxiliary non-dimension coordinates leak into expressions and break alignment #295

Opinionated behaviour — silent, debatable choices

• NaN in user-supplied data is silently filled — NaN in user-supplied data is silently filled instead of surfaced #713
• Multiplying by a subset constant silently drops variables — Inconsistent behavior when multiplying with subset coordinates #570

Already fixed in v0.7.0

• Inconsistent multiplication behavior: Variable vs LinearExpression with subset coordinates #569 — subset-multiplication crash / Variable-vs-Expression inconsistency — closeable.

Out of scope

Predictability issues, but not arithmetic-alignment bugs:

• add_variables mishandles bounds with missing dimensions — add_variables: DataArray bounds with missing dimensions yield wrong dimension order #706 (DataArray bounds → wrong dimension order), add_variables: pandas Series/DataFrame bounds with missing dimensions silently drop the dimension #709 (Series/DataFrame bounds → dimension dropped). Inconsistent creation of dimensions in add_variables #450 is the original report, only partially fixed by fix: add_variables ignoring coords for DataArray bounds #614.
• Groupby of expression by dataarray leads to non-xarray like behavior #351 — groupby by a DataArray; Slicing selection not aligned on "Python standards" #308 — .loc endpoint inclusivity.

#703 (xarray method coverage) consumes the convention rather than constraining it.

The fix

A strict v1 arithmetic convention behind linopy.options["arithmetic_convention"] — align by label, raise on a mismatch, NaN means "absent term". It ships opt-in, becomes the default, and legacy is removed at linopy 1.0. One PR carries the design goals, the spec, tests and code; docs follow. Implementation: #591. Milestone: Predictable Arithmetics.

[FBumann]

Note

AI-written note (Claude Code, prompted by @FBumann) — leaving this here so we can pick it up later.

#732 / #737 raised the question how v1 should treat MultiIndex-level operands, MI coverage gaps, and user NaNs (which the legacy projection can't tell apart from gaps). Checking #717: all three already raise under existing rules — §11 (aux-coord conflict), §8 (exact match on shared dims), §5 (user NaN). No new convention language needed; the ambiguity only exists because legacy fills instead of raising.

Remaining (small, legacy-side):

1. Add an §8/§11 example to convention.md: a level-indexed operand is an aux-coord conflict — no implicit projection under v1. Legacy (since refactor: unify coords-as-truth handling in add_variables/add_constraints #732) silently projects and PyPSA multi-investment relies on it, so the migration guide must name this difference.
2. NaN in user-supplied data is silently filled instead of surfaced #713: warn at the fillna sites in _add_constant / _apply_constant_op via feat: v1 semantic convention #717's warn_legacy().
3. Merge the two warning channels — EvolvingAPIWarning (refactor: unify coords-as-truth handling in add_variables/add_constraints #732) and LinopySemanticsWarning (feat: v1 semantic convention #717) — before v1 ships.