Variable.update() / Constraint.update() as canonical mutation API

[FBumann]

Stacked on #718. Exploratory branch for the API discussion (#718 review thread).

Adds typed .update() methods on Variable and Constraint so every mutation goes through one validated entry point. The existing 7 setters survive as one-line shims that forward to .update(), so no user-visible breakage — but _coef_dirty, broadcasting, sign normalisation, and the rhs-rearrange-to-lhs logic all live in one method.

API

Variable.update(*, lower=None, upper=None) -> Variable

Constraint.update(
    constraint=None,   # positional: a complete ConstraintLike, e.g. x + 5 <= 3
    *,
    lhs=None,          # replace whole expression
    rhs=None,          # set rhs (Variable/Expression rearranged onto lhs, like add_constraints)
    sign=None,         # set sign
    coeffs=None,       # partial: coefficient values
    variables=None,    # partial: variable labels
) -> Constraint

Two call shapes for Constraint, mirroring add_constraints:

c.update(x + 5 <= 3)               # complete replacement via a comparison
c.update(lhs=x, sign="<=", rhs=-2) # partial / explicit

Composition rules:

• lhs= replaces the whole expression first; rhs= rearrangement then sees the new lhs.
• lhs= is mutually exclusive with coeffs= / variables= (whole vs partial).
• Positional constraint is mutually exclusive with all keyword arguments.
• sign= applied last so it composes cleanly.
• Returns self for chaining.

Setter shims

Forwarders, no other behaviour:

setter	forwards to
var.lower = x	var.update(lower=x)
var.upper = x	var.update(upper=x)
c.lhs = expr	c.update(lhs=expr)
c.rhs = …	c.update(rhs=…)
c.sign = s	c.update(sign=s)
c.coeffs = x	c.update(coeffs=x)
c.vars = v	c.update(variables=v)

Closes the #718 review A1 residual

Last commit (70dbed4) flips ModelDiff.from_snapshot(same_model=…) default from True to False. The flag-trust path (skip_coef_compare = same_model and not coef_dirty) is now precise through Constraint.update() — it sets the flag in one place; setters forward there. But c.coeffs.values[...] = ... still bypasses _coef_dirty, and with the old default, that bypass silently produced wrong diffs.

The only production caller (Solver._update_locked) passes same_model explicitly, so it's unaffected. Same-model warm-update paths now value-diff the CSR data instead of trusting the flag — small perf cost (50–200 ms at Mayk-scale per his bench), correct by default. Solver-aware callers who own the mutation contract can opt back into the optimization with same_model=True.

What's NOT in this branch

• Variable.update(type=…) for binary/integer/continuous switching (would need new validation logic).
• Objective.update(...) (separate container; the persistent-solver diff already tracks obj_linear / obj_sense).
• Setter removal. We chose to keep shims for back-compat; some setters predate feat(persistent): in-place solver updates (Solver framework + HiGHS/Gurobi/Xpress/Mosek) #718 by ~4 years and removal is a bigger break worth its own PR.
• Migration of internal setter call sites (sanitize_zeros and friends). Setters are pure shims so the migration would be cosmetic; postpone until / unless setters get actually removed.
• Batching the multiple assign_multiindex_safe calls a multi-attr update makes.

Warts (inherited, not introduced)

• variables= kwarg shadows the .vars attribute spelling — picked the unambiguous name to dodge Python's vars() builtin shadow; .vars (read) stays as the attribute.
• rhs=Variable/Expression silently rearranges onto lhs (kept for symmetry with add_constraints; documented).
• lhs= xor coeffs= / variables= is a runtime check, not a type-system constraint.
• Mixing positional + keyword is a runtime check too.

Test plan

• test_variable.py, test_constraint.py, test_constraints.py, test_constraint_coef_dirty.py, test_model.py, test_variables.py — 280 pass (266 existing + 14 new for .update() directly, incl. the positional ConstraintLike form).
• PR feat(persistent): in-place solver updates (Solver framework + HiGHS/Gurobi/Xpress/Mosek) #718's persistent-solver suite: test_persistent_snapshot_diff.py, test_persistent_snapshot_buffers.py, test_persistent_solver_extras.py, test_persistent_solver_orchestrator.py, test_persistent_apply_update.py — 112 tests pass on this branch with the same_model=False default.
• Pre-commit clean.

🤖 Generated with Claude Code

[odow]

This is much closer to how JuMP does things. We have set_ functions instead of modify, but same thing.

• https://jump.dev/JuMP.jl/dev/api/JuMP/#set_normalized_rhs
• https://jump.dev/JuMP.jl/dev/api/JuMP/#set_normalized_coefficient
• https://jump.dev/JuMP.jl/dev/api/JuMP/#set_objective_coefficient
• https://jump.dev/JuMP.jl/dev/api/JuMP/#set_objective_sense
• https://jump.dev/JuMP.jl/dev/api/JuMP/#set_integer

In MathOptInterface we have a CachingOptimizer which controls the "pass to solver OR rebuild" logic:

• https://github.com/jump-dev/MathOptInterface.jl/blob/master/src/Utilities/cachingoptimizer.jl
• Here's the "delete a variable if supported" logic: https://github.com/jump-dev/MathOptInterface.jl/blob/f0e9fef21118bc85b78717e134acc05a1798ec10/src/Utilities/cachingoptimizer.jl#L698-L724

I tried to cover the caching optimizer in my MOI talk, but I don't really like it. It was too brief and I did things in the wrong order: https://youtu.be/M31xoZGyj9w?si=NTQHUsnq7o9Lg770&t=2211

[FBumann]

Follow-up: what .update() should grow to cover

Mapping against the per-backend apply_update calls in #718 — the backends all expose more than this PR exposes today. Concrete TODO:

Next milestones (additive, don't change existing shape):

• Variable.update(type=…) — switch between "continuous" / "integer" / "binary" / "semi_continuous". All four backends expose it (changeColsIntegrality / setAttr(VType) / chgcoltype / putvartypelist). Validation: binary → bounds in {0,1}, semi_continuous → positive lower.
• model.objective.update(expression=, sense=) (or Model.update_objective(...)) — backends expose changeColsCost / setAttr(Obj) / chgobj / putclist for linear coefficients and changeObjectiveSense / ModelSense / chgobjsense / putobjsense for sense. The persistent-solver snapshot already tracks obj_linear and obj_sense — only the user-facing mutation API is missing.

Later, if a workflow surfaces:

• Per-cell coefficient shortcut (c.update(coefficient={x: 2.0}) or c.update_coefficient(x, 2.0)). Maps to changeCoeff / chgCoeff / chgmcoef. Today coeffs= replaces the whole array.
• Variable.update(cost=…) shortcut for setting objective linear coefficients per variable. Canonical location is the objective; this would just be sugar.

Intentionally out of scope — solvers don't support, so neither should .update():

• Coefficient sparsity change → already a rebuild trigger; lhs= flips it implicitly.
• Quadratic objective in place → rebuild.
• Variable / constraint add / remove → use add_variables / remove_variables.
• Mask flip → rebuild per feat(persistent): in-place solver updates (Solver framework + HiGHS/Gurobi/Xpress/Mosek) #718.

Each item is additive — won't reshape the current .update() signature.

[FBumann]

API surface from a user perspective

Tying this back to the _coef_dirty / same_model discussion on #718: if Variable.update() / Constraint.update() become the canonical mutation path, the dirty flag becomes a reliable invariant and the leaky same_model=True parameter on ModelDiff.from_snapshot can go away.

Two follow-ups worth committing to here:

1. Auto-detect identity in the diff — store a weakref to the source model on ModelSnapshot. from_snapshot consults _coef_dirty only when identity matches. Users get one safe signature, no flags.

2. Split Solver.update(model, apply=True) into diff(model) and apply(diff) (per earlier discussion). update doing both is fine as sugar but the primitives should be separate — easier to reason about, easier to test, and removes the need to expose ModelDiff.from_snapshot / from_models publicly at all (their only legitimate caller becomes Solver.diff).

End state: users call var.update(...) to mutate, solver.diff(model) to inspect, solver.apply(diff) to push. No dirty flags, no same_model, no from_snapshot in the public surface.