Redesign as_dataarray: strict public API + internal ensure_dataarray helper

[FBumann]

Summary

Redesigns as_dataarray() by splitting it into two functions with clear responsibilities:

• as_dataarray(arr, coords?, dims?) — Public API. When coords is provided: converts to DataArray, validates shared dim coords match exactly, rejects extra dims, broadcasts missing dims via expand_dims. When coords is None: pure type conversion only.
• ensure_dataarray(arr, coords?, dims?) — Internal helper. Pure type conversion (scalar, numpy, pandas, polars, list → DataArray). No validation, no expand_dims. Coords are used only as construction hints. Callers handle alignment themselves (xarray broadcasting, reindex_like, etc.).

Both share a common _type_dispatch function for the actual type conversion logic.

Motivation

Previously as_dataarray() mixed two conflicting roles:

1. Strict validation for add_variables where user-provided bounds must match coords exactly
2. Lenient conversion in expression arithmetic where xarray alignment handles coord reconciliation

This led to bugs where DataArray inputs to add_variables had their coords silently ignored, and attempts to fix it broke expression arithmetic.

How variable coordinates are determined

Scenario	Behavior
coords provided, bounds are scalars/numpy/pandas	coords defines the variable's coordinate space; inputs are converted using coords
coords provided, bounds are DataArrays	coords defines the variable's coordinate space; bounds are validated against coords (shared dims must match, extra dims raise ValueError, missing dims are broadcast)
coords is None, bounds are DataArrays	Coordinates are inferred from the DataArray bounds directly
coords is None, bounds are scalars	Scalar (dimensionless) variable is created

Changes

File	Change
linopy/common.py	Extract _type_dispatch (shared conversion), _expand_missing_dims, _validate_dataarray_coords (strict, no allow_extra_dims flag). Add ensure_dataarray. Refactor as_dataarray to delegate to ensure_dataarray when no coords, or validate+expand when coords provided.
linopy/expressions.py	Switch all call sites to ensure_dataarray (arithmetic, constants, constraint comparisons, dot)
linopy/variables.py	Switch Variable.to_linexpr to ensure_dataarray
linopy/model.py	add_variables lower/upper use as_dataarray (strict). Masks, sign, rhs use ensure_dataarray (lenient).
test/test_common.py	Tests for _validate_dataarray_coords, ensure_dataarray (no expand, allows extra dims, no coord validation), and add_variables integration.
doc/release_notes.rst	Release note entry.

Mask handling

The mask parameter uses ensure_dataarray (no validation). The existing broadcast_mask function handles misaligned mask coords by filling with False. A TODO is left for a future deprecation path toward stricter validation (see #591).

Examples

# Mismatched coords → ValueError
lower = xr.DataArray([0, 0, 0], dims=["time"], coords={"time": [0, 1, 2]})
m.add_variables(lower=lower, coords=[pd.RangeIndex(5, name="time")], name="x")
# ValueError: Coordinates for dimension 'time' do not match

# Extra dims → ValueError
lower = xr.DataArray([[1, 2], [3, 4]], dims=["x", "y"])
m.add_variables(lower=lower, coords={"x": [0, 1]}, name="x")
# ValueError: DataArray has extra dimensions not in coords: {'y'}

# Subset dims → broadcast
lower = xr.DataArray([0, 0], dims=["x"], coords={"x": [0, 1]})
m.add_variables(lower=lower, coords={"x": [0, 1], "y": [0, 1, 2]}, name="x")
# works, lower broadcast to shape (2, 3)

# No coords → pass through unchanged
m.add_variables(lower=lower, name="x")

# Internal arithmetic uses ensure_dataarray (lenient)
expr = m.variables["x"] + np.array([1, 2])  # xarray handles alignment

Checklist

• Code changes are sufficiently documented
• Unit tests pass
• A note for the release notes
• I consent to the release of this PR's code under the MIT license

[FBumann]

Maybe remove explicit broadcast from masking added in a prior patch

[FBumann]

SHould be merged before #591

[FBumann]

Adjust mask validation in #591

[FBumann]

@FabianHofmann I think merging this would be a great addition in UX

[FBumann]

Fixed #450

[FBumann]

Closed in favor of #614