feat: unlabeled-operand pairing by size (#736)

[FBumann]

Closes #736. Stacked on #717 (feat/arithmetic-convention).

Draft: review-ready and design-final, but the diff is against #717, so it can't merge to master until #717 does. (Not gated by the #744 MultiIndex decision — this PR's size-pairing never touches MultiIndex level coords; its HELPER_DIMS usage is _term / _factor, orthogonal to how MultiIndexes are stored.)

Implements the last unimplemented rule of the v1 convention's coordinate-alignment intro: unlabeled operands pair with the linopy operand's dimensions by size.

The rule

numpy arrays, lists, and polars Series carry no dimension labels, so their axes adopt the operand's dims by size — the same rule for arithmetic operands and for add_variables / add_constraints bounds and masks (no positional carve-out for construction):

x = m.add_variables(coords=[a4, time5])     # dims (a: 4, time: 5)
(1 * x) + np.arange(5)                       # length-5 → pairs with `time`
(1 * x) @ np.arange(5)                       # matmul contracts `time`, result keeps `a`

Ambiguity raises (v1), pointing at the explicit fix:

y = m.add_variables(coords=[p4, q4])         # both dims size 4
(1 * y) + np.arange(4)
# ValueError: ... could pair with any of ['p', 'q'] — sizes alone cannot decide.
#             Wrap the array in an xarray.DataArray with explicit dims.

Case	v1	legacy
unique size match	pair by size	pair positionally (agrees → silent)
size matches a non-leading dim	pair by size	pair positionally, warn (v1 differs)
ambiguous (shared size / square)	raise	pair positionally, warn
no size match	raise	pair positionally, warn

The rule is uniform: add_variables(coords=[a:4, time:5], lower=np.arange(5)) now resolves lower to time (positional pairing errored on a); a square/ambiguous bare-numpy bound raises asking for a DataArray wrap, instead of silently guessing.

Implementation (linopy/alignment.py)

• _pair_axes_by_size + _dims_for_unlabeled_operand — the size-pairing with the legacy/v1 fork.
• as_constant — normalizes degenerate operands on entry: a Python list → numpy array (lists have no numeric operators), a 0-d array → Python scalar (takes the scalar fast-path, never pairs). ConstantLike stays numeric-only.
• _broadcast_to_coords gains unlabeled_pairing="semantic" for the arithmetic path; explicit-coords callers (add_variables) stay positional.
• Two conversion fixes the seam exposed: as_dataarray's scalar branch and the positional fallback now exclude HELPER_DIMS, so a scalar never broadcasts over _term / _factor. (HELPER_DIMS was already the global registry; _group is transient and correctly excluded.)

Why dims=self.coord_dims was dropped from the operator calls

The arithmetic operators (expressions.py _add_constant, _apply_constant_op, to_constraint; variables.py to_linexpr; both __matmul__) previously passed dims=self.coord_dims into broadcast_to_coords. That argument pinned an unlabeled array's axes to those dims by position — which is exactly the behavior #736 replaces. While it's passed, size-pairing can never run (an explicit dims means "the caller named the axes").

So every arithmetic call site drops it. This is safe because coords=self.coords already carries the same dim information, and dims only ever affected unlabeled inputs:

• DataArray / named-pandas operands ignore dims entirely (they carry their own labels) — unchanged.
• Unlabeled operands (numpy / list / polars) now reach _dims_for_unlabeled_operand and pair by size — the point of the PR.

dims=self.coord_dims did do one extra thing worth calling out: it excluded helper dims (_term, _factor) from the positional labeling. Dropping it surfaced three latent HELPER_DIMS leaks (a scalar gaining _term, etc.), now fixed in the conversion layer (as_dataarray's scalar branch and the positional fallback both exclude HELPER_DIMS). as_constant on entry and UNLABELED_TYPES as the single dispatch source complete the picture; Variable operators inherit it all via delegation.

Tests

• TestUnlabeledPairing (test_legacy_violations) — parametrized over numpy / list / polars, with @pytest.mark.legacy / @pytest.mark.v1 pairs covering pair-by-size, order-independence, ambiguity, no-match, the DataArray escape hatch, and matmul.
• The two pre-existing unlabeled-rhs constraint tests forked legacy/v1.
• benchmark_model example named its rhs axis (it used an ambiguous square-dim rhs — now demonstrates the convention).

Verification

Full suite under both semantics: 6458 passed, 548 skipped. mypy + pre-commit clean. convention.md §736 TODO resolved; legacy-removal.md updated.

🤖 Generated with Claude Code