refactor(remote): OETC/SSH as standalone transports (closes #683)

[FBumann]

Stacked on top of #690 (rebase target after that lands on master).

Closes #683 — with a different design than the issue proposed.

Why standalone, not Solver subclass

The issue framed OETC as a Solver subclass so Model.solve could fold the remote= branch into the unified Solver pipeline. Trying that, the fit was wrong:

• Remote handlers aren't solvers — they ship a netcdf elsewhere and let someone else solve.
• Forcing them through Solver required workarounds: a non-colliding inner_solver field, property-vs-field collisions on solver_name, SolverName enum entries for things that aren't algorithms.
• Solver's feature-flag plumbing is about local solver capabilities; for remotes we want to validate the inner solver's flags.

So Oetc and SSH are standalone classes in linopy/remote/, parallel to Solver, not subclasses of it.

What's new

m.solve("gurobi", remote=OetcSettings(email=..., password=..., name=..., ...), Method=2)
m.solve("highs", remote=SshSettings(hostname=..., setup_commands=["conda activate linopy-env"]))

• solver_name and **solver_options are the same axes as for local solves; remote= selects where to run.
• New model.remote attribute mirrors model.solver for post-solve introspection.
• Oetc.upload(model) / submit() / collect(model) exposed for async-style workflows (drive the seam manually).
• SshSettings.setup_commands: list[str] runs shell commands on the remote before the inner solver — replaces the old "build a RemoteHandler and call .execute(...)" pattern.
• Pip extra remote → ssh (matches what it installs: paramiko). OETC has its own linopy[oetc] extra; both are now symmetric. linopy[remote] is dropped (not aliased) — see Breaking Changes in the release notes.

API surface — what the new transport classes do (and don't) cover

Oetc and SSH are intentionally narrower than the deprecated Handler classes. They cover solving a model on a remote machine. They don't try to be a general remote-shell wrapper.

	Old RemoteHandler	New SSH	Replacement
Solve a model	solve_on_remote(m)	solve(m)	direct rename
Env activation before solve	handler.execute("conda activate …")	—	SshSettings.setup_commands=[…]
Reuse connection across multiple solves	implicit (long-lived handler)	implicit (SSH._handler is cached)	works the same
Arbitrary remote shell commands between solves	handler.execute(any cmd)	—	drop to RemoteHandler (deprecated) or use paramiko directly
Custom file transfer	write_model_on_remote etc.	—	drop to RemoteHandler (deprecated) or paramiko/SFTP directly

Asymmetry with Oetc: Oetc exposes upload / submit / collect because OETC has a genuine async seam (submit a job, walk away, collect hours later). SSH doesn't — the shell session is held open and the solve is synchronous, so there's no useful split.

The narrowing is intentional: the old RemoteHandler blurred two concerns — be a paramiko shell wrapper and solve linopy models on a remote. The new SSH is just the second. If you want the first, paramiko itself is a perfectly good API.

Deprecations

• OetcHandler(...) / RemoteHandler(...) construction emits DeprecationWarning. Their solve_on_oetc / solve_on_remote return contracts are unchanged during deprecation; solve_on_oetc now internally delegates to Oetc.solve.
• Model.solve(remote=<Handler>) is deprecated — pass the settings dataclass instead.
• OetcCredentials is deprecated — pass email= and password= directly to OetcSettings. The OetcSettings(credentials=OetcCredentials(...)) shape still works during the deprecation period.

Other designs considered (rejected)

Remote returns Model instead of Result. Tried in a separate commit (f049999, since reverted): Oetc.solve / SSH.solve would return the round-tripped solved Model, with a new Model._assign_from_solved_model(solved) helper for in-place writeback. The pitch: remote workers natively produce inflated Models, so the Result shape forces an xarray → flat → xarray round-trip via _scatter_solution_from_solved_model. Rejected in favor of uniformity: every solve path (local Solver or Remote) returns a Result and goes through Model.assign_result. One assign-path, one mental model. Cost: the scatter pass — ~few ms + ~32 MB transient per 1M model variables, dominated by the network round-trip in practice.

Keep OetcCredentials as a separate class long-term. Considered keeping it (cloud-SDK convention, visual flag for secrets in code review) and adding OetcCredentials.from_env() for symmetry with OetcSettings.from_env(). Folded instead because:

• The auth shape is uniform (always email + password), so the wrapper adds no structural payoff.
• SshSettings already takes username / password inline.
• Every existing OETC user is already on a deprecation cycle for OetcHandler, so the extra one-line migration (credentials=OetcCredentials(email=..., password=...) → email=..., password=...) is essentially free.

Follow-ups (not in this PR)

• Remove OetcHandler / RemoteHandler. Their private transport methods (_upload_file_to_gcp, _submit_job_to_compute_service, wait_and_get_job_data, _download_file_from_gcp, __sign_in, paramiko shell management) still live on the Handler classes; Oetc / SSH reach into self._handler._upload_file_to_gcp(...) to use them. A follow-up PR will migrate that code into Oetc / SSH and port the ~50 OETC tests that exercise the handler internals.
• Remove OetcCredentials. After one release cycle of deprecation warnings.
• Phase 5 tests for the new standalone classes (Oetc.solve(mocked OetcHandler), SSH.solve(mocked RemoteHandler), deprecation-warning assertions, upload/submit/collect separability).

Test plan

• pytest test/remote/ test/test_sos_reformulation.py test/test_oetc_settings.py — 166 pass.
• pytest --ignore=test/remote — full broader suite (3495 passed, 29 skipped).
• ruff check, ruff format — clean.

🤖 Generated with Claude Code

@FabianHofmann:

• if you'd prefer to keep OetcCredentials as a long-term, top-level class im fine. I went with fold because the deprecation cost happens to be near-free given the Handler is also deprecated, and .from_env() handles the credentials issue cleanly.
• Im not fully satisifed with "remote". Its more a transport, or offload technically... Its now or never on the rename maybe, but its probably not worth it anyway.

[FabianHofmann]

@FBumann I think the concept makes sense. I would like to make sure that it is flexible enough for interfaces like gurobi instant cloud. could you take that into consideration?

[FBumann]

@FabianHofmann Yes, I already did think about it. But i can sketch it out a bit more, maybe even create a Remote parent class...
I also didnt add the tests yet, and some cleanupy might also be possible. And the latest context manager from #690 isnt used yet

[FBumann]

@FBumann I think the concept makes sense. I would like to make sure that it is flexible enough for interfaces like gurobi instant cloud. could you take that into consideration?

It fits well for async instant cloud. For the sync instan cloud it doesnt fit as cleanly. But I think it can be wired in without adjusting public api. Probably just refactor some internal helpers for collection

[FabianHofmann]

@FBumann I think the concept makes sense. I would like to make sure that it is flexible enough for interfaces like gurobi instant cloud. could you take that into consideration?

It fits well for async instant cloud. For the sync instan cloud it doesnt fit as cleanly. But I think it can be wired in without adjusting public api. Probably just refactor some internal helpers for collection

I guess async is the most important one

[FBumann]

@FBumann I think the concept makes sense. I would like to make sure that it is flexible enough for interfaces like gurobi instant cloud. could you take that into consideration?

It fits well for async instant cloud. For the sync instan cloud it doesnt fit as cleanly. But I think it can be wired in without adjusting public api. Probably just refactor some internal helpers for collection

I guess async is the most important one

I thin the regular gurobi cloud can be used by just using the regular gurobi solver anyway...? It fully dispatches to gurobipy, and gets a gurobipy solution back, right? SO no extra class needed...

[FBumann]

@FabianHofmann
Here is some advice from CLaude after some back and forth:

## Generality check — Gurobi & other clouds

- Gurobi Instant Cloud / Compute Server sync → already works via m.solve("gurobi", env=cloud_env). Belongs as GurobiSolver config, not a remote class. A GurobiInstantCloud remote class would be a fake — construct an Env and dispatch back into the regular Solver path.
- Gurobi batch solve / detached submit-now-collect-later → genuine fit for the remote handler shape.
- Friction for any future handler: solver_name is mandatory and means inner solver (redundant for solver-specific clouds); _scatter_solution_from_solved_model assumes a netcdf round-trip with a linopy Model on the other side.

## Naming clarity

"Remote" is defensible as user-facing vocabulary but mislabels the technical category, and "async" is the wrong axis entirely:

- The actual invariant shared by Oetc and SSH is a second linopy instance does the solve (local linopy serializes → remote linopy deserializes → .solve() → result back). Gurobi Cloud is also remote geographically, but only one linopy instance is involved — gurobipy talks to a remote engine too.
- "Async" misclassifies SSH (fully synchronous, no job seam) and overpromises on Oetc (.solve() blocks; the seam is optional). True async (blocking=False returning a handle) is orthogonal — it could apply to a local callback-driven Gurobi solve too.

SO the new architecture should cover all cases. THe only issue i see is thst "remote" isnt a precise name. "worker" or "offload" might be better. But thats not as important for now i think

[FBumann]

@FabianHofmann I argue that the final form of API would be removing OetcHandler.
The High level api would be OetcSettings passed to Model.solve(). The low level API is using Oetc.from_model() like a Solver.

OetcHandler delegates for backwards compat, but is deprecated.

This reflects the 2-level state of regular solvers: Pass name + options in Model.solve(), or directly invoke with the Solver class, which holds the logic/validation for the solver.

Do you agree?

[FBumann]

@FabianHofmann Ready for a review