Unify naming: rename .vars → .variables across Constraint/LinearExpression/QuadraticExpression

[FBumann]

Today the read-side uses vars but the typed mutation API uses variables:

• Constraint.vars (property + deprecated setter)
• Constraint.update(variables=...) (kwarg)
• Same split on LinearExpression.vars, QuadraticExpression.vars, and the underlying Dataset key

The kwarg was variables to avoid shadowing the vars() builtin in kwarg position — that reasoning doesn't apply to property names. Result is c.vars to read but c.update(variables=...) to mutate, which is mildly confusing.

Proposal

Rename .vars → .variables on Constraint, LinearExpression, QuadraticExpression, and the underlying Dataset key. Keep .vars as a deprecated alias for one release cycle, then remove.

Scope / cost

• Touches every internal callsite + the Dataset key.
• PyPSA reads c.vars directly in many places — needs coordination.
• Two-release deprecation: add .variables, alias .vars with DeprecationWarning, remove later.

Out of scope for #727 (typed .update() API); tracking separately.

[FabianHofmann]

I agree! would give this low prio for now

[FBumann]

Yes, will create conflicts...

[FBumann]

Closing — on reflection the rename trades a small asymmetry (c.vars read vs. c.update(variables=...) mutate) for a worse one (Python property .variables ≠ underlying xarray Dataset key "vars"). The Dataset key can't cleanly become "variables" either, since xarray.Dataset.variables is a built-in attribute that would shadow it (forcing data["variables"] and breaking the uniform data.coeffs/data.const/data.vars access pattern). If the original asymmetry is worth fixing, the cheaper move is renaming the update(variables=) kwarg back to vars=.

[FBumann]

Revisited with a cleaner A/B split that the previous discussion conflated:

Category A — rename to .variables (it's about linopy.Variable instances at the public Python API):

• Constraint.vars, LinearExpression.vars, QuadraticExpression.vars, ScalarLinearExpression.vars, CSRConstraint.vars, Objective.vars, Constraints.vars (collection)
• Constraint.update(variables=...) kwarg (already this name; stays)

Category B — keep as vars (it's the xarray Dataset key; renaming collides with xarray.Dataset.variables built-in):

• self.data.vars, data["vars"], Dataset({"vars": ...}), assign(vars=...), drop_vars(["vars"]), FILL_VALUE["vars"], pl.col("vars")

The previous close comment argued the rename trades one asymmetry for another. Under the A/B framing the new asymmetry (c.variables property ≠ data.vars storage key) is principled — public API layer vs. internal storage layer — same pattern ORMs and serializers use, not arbitrary inconsistency.

Cost is still real: ~50–100 mechanical edits, deprecation warnings noisy for downstream (PyPSA), and a false-positive class on data.sel(...).vars chains that needs care during migration. Not picking this up right now; flagging here so the framing is recorded if/when we revisit.

[FBumann]

Note

This comment was written with Claude Code.

A related angle worth deciding here, since it changes whether the rename is even worth a deprecation cycle: should .vars / .coeffs be part of the public stability contract at all?

The motivation comes out of #741 / #752. The problem with these two specifically isn't the name — it's that the value is only interpretable with internal knowledge:

expr.vars.dims      # ('i', '_term')   <- the private helper dim leaks out
expr.vars.values    # integer variable *labels*; empty slots are the -1 sentinel
expr.coeffs.dims    # ('i', '_term')   same layout

So they're "public" by the no-underscore test, but reading them safely requires knowing the _term helper dim and the -1 dead-slot sentinel — i.e. they expose the term-storage layout, not an abstraction over it. Keeping them in the contract also freezes that layout: we couldn't move expressions to a flat/polars backing without a breaking change. (.const is different — it's a plain numeric DataArray over the coord dims only, no _term, no sentinel — so that one is genuinely fine to keep.)

The legitimate reasons someone reaches for them are already covered by layout-independent public API:

Why reach for .vars / .coeffs	Public alternative
"does this slot have variables?"	has_terms (#741) / nterm
"give me the structure to inspect/export"	flat, to_polars()
"the constant term"	const
"the solution values"	solution
build the actual matrices	internal (matrices)

Once has_terms is in, I can't find a consumer need that requires the raw _term-indexed DataArray.

Proposal: demote, don't delete

Rather than rename-and-keep, I'd lean toward:

1. Keep .vars / .coeffs importable (hard removal breaks downstream, incl. PyPSA today), but
2. take them out of the stability guarantee: document as low-level / layout-not-guaranteed, point the docs at flat / to_polars / has_terms / nterm / const / solution, and
3. wrap access in the existing EvolvingAPIWarning so users get nudged off before any eventual removal.

How this interacts with the rename here

If we demote them, the cost/benefit of #730 shifts: renaming .vars → .variables and carrying a .vars deprecation alias is a fair bit of churn to invest in something we'd simultaneously be signalling as not-contract. Options to reconcile:

• (a) Do the rename anyway, but introduce .variables already marked EvolvingAPIWarning (rename + demote in one move), or
• (b) Skip the rename and just demote .vars/.coeffs as-is, keeping naming churn off the table.

Either is fine by me — the substantive ask is the demotion. On the PyPSA side the only consumer of raw .vars is the single (lhs.vars == -1).all("_term") site, which has_terms already retires (#741 / #752 §0), so PyPSA won't block whichever path you pick.