flextool 4.0.0__py3-none-any.whl

flextool/engine_polars/_subprocess_solve.py

@@ -0,0 +1,1838 @@
+"""Subprocess solver driver — the only cold-solve path in FlexTool.
+
+After the in-process cold-solve retirement, this module is the *single*
+entry point for any solve that isn't going through the warm-active
+HiGHS path:
+
+* HiGHS with ``--save-memory`` (or with ``warm=False`` and the
+  soft-promote rule fired in ``_orchestration.py``) — written via
+  :meth:`polar_high.Problem.write_mps`, solved by
+  :mod:`flextool.cli.cmd_solve_mps`.
+* Non-HiGHS solvers (``gurobi`` / ``cplex`` / ``xpress`` / ``copt``) —
+  written via the same :meth:`Problem.write_mps`, solved by the
+  solver's CLI binary discovered on ``$PATH`` (with a small set of
+  conventional install dirs as fallback).
+
+The default HiGHS path in ``_orchestration.py`` (warm-active
+:class:`polar_high.WarmProblem`) does **not** call this module.
+
+**Non-HiGHS contract**: commercial solvers (Gurobi/CPLEX/Xpress/COPT)
+*always* go through subprocess regardless of ``--save-memory``.  This
+keeps every cold solve at the bound peak-memory footprint
+:meth:`Problem.write_mps` was designed to deliver (~2-3 GB on a 9.9 M
+row LP vs ~45 GB for HiGHS' own ``writeModel``).  The corollary: there
+is no in-process Gurobi/CPLEX/Xpress/COPT dispatch in FlexTool at all.
+
+The child process has a clean address space — none of FlexTool's
+~7-11 GB of polars frames, no glibc fragmentation from upstream
+preprocessing.  When it finishes, the parent reads the solution back:
+
+* HiGHS path parses the subprocess-written .sol directly
+  (:func:`_parse_highs_sol`) — the file already carries names + primal
+  + duals.
+* Commercial path writes the MPS with GENERIC ``C…``/``R…`` names
+  (``emit_names=False``) so real entity names — which routinely contain
+  spaces, illegal in whitespace-delimited free-format MPS — never
+  corrupt the file.  It parses the solver-native .sol with the parsers
+  imported from polar-high's ``_mps_fallback`` (copied verbatim so the
+  parsers stay free of the ``LpView`` materialisation polar-high uses
+  upstream of them), then maps the generic-named primal/dual back by
+  *index* onto the real names rebuilt from the Problem's surviving
+  ``_vars`` (:func:`_col_names_from_vars`) and pre-release ``_cstrs``
+  (:func:`_row_names_from_cstrs`).
+
+Neither path re-reads the MPS through :meth:`highspy.Highs.readModel`
+in the parent: that used to spike tens of GB of RSS on large LPs, and
+hard-failed on FlexTool's own free-format MPS whenever an entity name
+contained a space.  Instead both wrap the parsed arrays in a
+:class:`_SolHighsShim`, giving downstream output writers a uniform
+``Solution.highs`` shape — they keep doing
+``h.allVariableNames() + h.getSolution()`` regardless of which solver
+produced the result.
+
+Loses warm-LP reuse for the cascade — ``write_mps(release=True)``
+puts the Problem in ``_released`` state and it can't be resolved.
+Already documented on the ``--save-memory`` flag.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from polar_high import Problem, Solution
+
+
+# Warm-start first-transfer A/B margin.  A supplied basis disables HiGHS'
+# presolve, so a *far* / stale seed can make the warm solve SLOWER than a
+# cold (presolve-on) solve (Landmine B).  On a family's first warm
+# transfer we time a cold reference run and only keep injecting the basis
+# when the warm run's wall time is within ``(1 + _WARM_AB_MARGIN)`` of the
+# cold time; otherwise the fingerprint is marked ``.nowarm`` and future
+# solves go cold.  Env-tunable; a NEGATIVE value forces a regression
+# verdict (used by tests to exercise the disable path deterministically).
+_WARM_AB_MARGIN = float(os.environ.get("FLEXTOOL_WARM_AB_MARGIN", "0.10"))
+
+
+def _warm_ab_margin() -> float:
+    """Effective A/B margin, re-read from the environment at decision time.
+
+    Falls back to the import-time :data:`_WARM_AB_MARGIN` default when the
+    env var is unset or unparseable.  Read at runtime (not once at import)
+    so ``FLEXTOOL_WARM_AB_MARGIN`` stays tunable within a live process —
+    the gate fires at most once per fingerprint, so the cost is trivial.
+    """
+    try:
+        return float(
+            os.environ.get("FLEXTOOL_WARM_AB_MARGIN", str(_WARM_AB_MARGIN))
+        )
+    except (TypeError, ValueError):
+        return _WARM_AB_MARGIN
+
+
+def _touch_marker(path: Path, logger: logging.Logger | None) -> None:
+    """Best-effort create an empty warm-start decision marker file.
+
+    Markers (``<fp>.nowarm`` / ``<fp>.abtested``) live in the persistent
+    basis cache dir and record the first-transfer A/B verdict.  A write
+    failure is logged and non-fatal — the gate degrades to re-probing on
+    the next solve, never breaking the solve itself.
+    """
+    try:
+        path.write_text("")
+    except OSError as exc:
+        if logger is not None:
+            logger.warning(
+                "save_memory: warm-start marker write failed for %s (%s)",
+                path, exc,
+            )
+
+
+def _run_cold_probe(
+    *,
+    mps_path: Path,
+    opts_path: Path,
+    probe_sol: Path,
+    probe_stats: Path,
+    logger: logging.Logger | None,
+) -> float | None:
+    """Spawn a throwaway COLD child solve purely to measure its wall time.
+
+    Used by the first-transfer A/B gate (see :data:`_WARM_AB_MARGIN`).
+    The child runs with the SAME ``--mps`` / ``--options`` but a throwaway
+    ``--solution`` and ``--stats`` and NO ``--warm-basis`` — a pure cold
+    reference solve.  Its solution is discarded; only ``run_time`` matters.
+
+    Returns the cold ``run_time`` in seconds, or ``None`` when the probe
+    could not run or produced no usable time (caller then skips gating).
+    Fully defensive — never raises.
+    """
+    try:
+        probe_cmd = [
+            sys.executable, "-m", "flextool.cli.cmd_solve_mps",
+            "--mps", str(mps_path),
+            "--solution", str(probe_sol),
+            "--options", str(opts_path),
+            "--stats", str(probe_stats),
+        ]
+        subprocess.run(probe_cmd)
+        if not probe_stats.exists():
+            return None
+        pstats = json.loads(probe_stats.read_text())
+        rt = pstats.get("run_time")
+        if rt is None:
+            return None
+        return float(rt)
+    except Exception as exc:  # noqa: BLE001 - probe is measurement-only
+        if logger is not None:
+            logger.debug("save_memory: cold A/B probe failed (%s)", exc)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# HiGHS .opt formatting / .sol parsing helpers (existing)
+# ---------------------------------------------------------------------------
+
+
+def _format_opt_value(v: object) -> str:
+    """Render *v* in HiGHS .opt file syntax (``key=value`` per line)."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return str(v)
+
+
+def _read_objective_from_sol(sol_path: Path) -> float:
+    """Parse the ``Objective <value>`` line from a HiGHS style=0 sol file.
+
+    ``highspy.Highs.getObjectiveValue()`` only reflects the most recent
+    ``run()`` and is zero after a bare ``readModel + readSolution``, so
+    we read the value the subprocess wrote directly.  Returns ``0.0``
+    when the line is absent (caller should treat as non-optimal).
+    """
+    try:
+        with open(sol_path) as f:
+            for line in f:
+                if line.startswith("Objective "):
+                    return float(line.split(None, 1)[1])
+    except (OSError, ValueError):
+        pass
+    return 0.0
+
+
+# ---------------------------------------------------------------------------
+# HiGHS .sol direct parser + lightweight Highs-shim
+# ---------------------------------------------------------------------------
+#
+# The cold (``--save-memory``) path used to re-load the *entire* MPS via
+# ``highspy.Highs.readModel`` in the parent process — purely to satisfy
+# downstream writers that call ``h.allVariableNames()`` / ``h.getSolution()``
+# / ``h.getLp().row_names_``.  On large LPs (DES: ~10 M rows, 7 M cols)
+# that ``readModel`` accounts for the +33 GB RSS spike at the per-solve
+# ``Solver`` checkpoint — and immediately gets thrown away after the
+# writers finish.  We sidestep it: parse the HiGHS style=0 .sol file
+# directly (it already carries column / row names + primal + dual values)
+# and wrap the arrays in a duck-typed shim that exposes exactly the API
+# surface the writers use.  No 33 GB sidecar Highs instance.
+
+def _parse_mps_row_names(mps_path: Path) -> list[str]:
+    """Return constraint row names (in MPS ROWS order, objective excluded).
+
+    HiGHS' ``writeSolution`` periodically rewrites row names to
+    ``r0, r1, ...`` (warning: ``Row names are not present, or contain
+    duplicates: using names with prefix "r"``) when the LP's row name
+    array survives ``readModel`` in a degraded state — observed with
+    free-format MPS row names that contain bracket / comma characters
+    (``nodeBalance_eq[battery,p2020,t0001]``).  The MPS file itself
+    carries the canonical names; this helper recovers them so the
+    downstream output writers' name-based row lookups (``row_dual``
+    for ``nodeBalance_eq`` / ``reserveBalance_*_eq`` / ``co2_max_*``)
+    keep working through the subprocess-MPS path.
+
+    The objective row (``N  cost`` in the polar-high MPS) is excluded
+    so the returned list aligns with HiGHS' ``row_dual`` array, which
+    only covers constraint rows (objective dual is meaningless).
+
+    Parser: a tiny state machine over the ROWS section.  Lines look
+    like ``" E  nodeBalance_eq[...]"`` — leading whitespace + 1-char
+    sense + whitespace + name.  Anything else terminates the section.
+    """
+    names: list[str] = []
+    try:
+        with open(mps_path) as fh:
+            in_rows = False
+            for raw in fh:
+                line = raw.rstrip("\n")
+                if not in_rows:
+                    if line.strip().upper() == "ROWS":
+                        in_rows = True
+                    continue
+                # Detect end of ROWS section (next header line: COLUMNS,
+                # RHS, RANGES, BOUNDS, ENDATA, ...).  Header lines are
+                # left-flush; data lines start with whitespace.
+                if line and not line[0].isspace():
+                    break
+                parts = line.split()
+                if len(parts) < 2:
+                    continue
+                sense = parts[0].upper()
+                name = parts[1]
+                # Skip the objective row — ``row_dual`` covers
+                # constraints only.
+                if sense == "N":
+                    continue
+                if sense in ("E", "L", "G"):
+                    names.append(name)
+    except OSError:
+        pass
+    return names
+
+
+def _col_names_from_vars(problem: "Problem") -> list[str]:
+    """Rebuild the dense, ``col_id``-indexed column-name list from a
+    (possibly released) :class:`polar_high.Problem`.
+
+    ``Problem.write_mps(release=True)`` keeps ``self._vars`` alive
+    precisely so an external solver's solution can be mapped back to
+    user-space names.  This helper reproduces the *exact* naming
+    polar-high itself emits for ``Solution.col_names`` —
+    ``"<family>[<d0>,<d1>,…]"`` for dimensioned variables, the bare
+    family name for scalar ones — from those surviving
+    ``Var.frame['col_id']`` columns (mirrors the canonical-matrix name
+    pass in ``polar_high.engine.Problem._canonicalise``).
+
+    Preferred over re-reading the MPS through
+    ``highspy.Highs.readModel`` on the commercial-solver path: the result
+    is **complete** (columns the MPS COLUMNS section elides because they
+    carry no objective / matrix entry are still present here),
+    ``col_id``-aligned by construction, and immune to the free-format-MPS
+    whitespace fragility a text round-trip suffers when an entity name
+    contains a space.
+    """
+    import polars as pl
+
+    vars_map = getattr(problem, "_vars", {}) or {}
+    # Every column is created by exactly one ``add_var`` and lands in that
+    # variable's frame, so the max ``col_id`` across all frames + 1 is the
+    # exact dense column count — no dependence on the internal counter
+    # (which differs between ``Problem`` and ``WarmProblem``).
+    max_cid = -1
+    for v in vars_map.values():
+        ids = v.frame["col_id"].to_numpy()
+        if ids.size:
+            max_cid = max(max_cid, int(ids.max()))
+    n_cols = max_cid + 1
+
+    col_names: list[str] = [""] * n_cols
+    for v in vars_map.values():
+        ids = v.frame["col_id"].to_numpy()
+        if v.dims:
+            tagged = v.frame.select(
+                pl.format(
+                    "{}[{}]",
+                    pl.lit(v.name),
+                    pl.concat_str(
+                        [pl.col(d).cast(pl.String) for d in v.dims],
+                        separator=",",
+                    ),
+                ).alias("__name")
+            )["__name"].to_list()
+            for cid, nm in zip(ids.tolist(), tagged):
+                col_names[cid] = nm
+        elif ids.size:
+            col_names[int(ids[0])] = v.name
+    return col_names
+
+
+def _row_names_from_cstrs(problem: "Problem") -> list[str]:
+    """Rebuild the ``row_id``-ordered constraint-name list from a Problem's
+    ``_cstrs`` families — the row analogue of :func:`_col_names_from_vars`.
+
+    Same ``"<family>[<d0>,<d1>,…]"`` format polar-high emits for
+    ``Solution.row_names`` (bare family name for a scalar constraint),
+    walking ``_cstrs`` in declaration order — which is the exact order the
+    canonical matrix assigns row ids (mirrors
+    ``polar_high.engine.Problem._canonicalise``'s row-name pass).
+
+    Unlike ``_vars``, ``_cstrs`` is **dropped** by
+    ``write_mps(release=True)``, so callers that need the real constraint
+    names (to map a solver's ``.sol`` duals back by name) must call this
+    *before* releasing.  Only the dual-returning commercial parsers
+    (:data:`_DUAL_CAPABLE_SOLVERS`) need it; Gurobi / COPT / Xpress ``.sol``
+    files carry no duals, so their path skips this entirely.
+    """
+    import polars as pl
+
+    names: list[str] = []
+    for cname, _proto, over in getattr(problem, "_cstrs", []) or []:
+        if over is None:
+            names.append(cname)
+            continue
+        axis_cols = list(over.columns)
+        names.extend(
+            over.select(
+                pl.format(
+                    "{}[{}]",
+                    pl.lit(cname),
+                    pl.concat_str(
+                        [pl.col(d).cast(pl.String) for d in axis_cols],
+                        separator=",",
+                    ),
+                ).alias("__rn")
+            )["__rn"].to_list()
+        )
+    return names
+
+
+# polar-high's ``write_mps(emit_names=False)`` emits generic, whitespace-safe
+# column / row names in strict id order: column ``col_id=j`` → ``f"C{j+1:07d}"``
+# and constraint ``row_id=i`` → ``f"R{i+2:07d}"`` (the objective row is the
+# reserved name ``cost`` and never appears in a solver ``.sol``'s variable or
+# dual list).  These regexes recover the id from such a name; the ``0*`` +
+# open ``[0-9]+`` tolerates the field widening past 7 digits on >10 M-col LPs.
+_GENERIC_COL_RE = re.compile(r"^C0*([0-9]+)$")
+_GENERIC_ROW_RE = re.compile(r"^R0*([0-9]+)$")
+
+
+def _generic_col_id(name: str) -> int | None:
+    """``"C0000001"`` → ``0``; ``None`` when *name* isn't a generic col id."""
+    m = _GENERIC_COL_RE.match(name)
+    return int(m.group(1)) - 1 if m else None
+
+
+def _generic_row_id(name: str) -> int | None:
+    """``"R0000002"`` → ``0``; ``None`` when *name* isn't a generic row id."""
+    m = _GENERIC_ROW_RE.match(name)
+    return int(m.group(1)) - 2 if m else None
+
+
+# Commercial ``.sol`` parsers that can return constraint duals.  Only these
+# pay the cost of rebuilding real row names before ``write_mps`` releases;
+# Gurobi / COPT / Xpress ResultFiles carry primal values only.
+_DUAL_CAPABLE_SOLVERS = frozenset({"cplex"})
+
+
+def _parse_highs_sol(
+    sol_path: Path,
+) -> tuple[
+    list[str], list[str],
+    np.ndarray, np.ndarray, np.ndarray,
+]:
+    """Parse a HiGHS style=0 ``.sol`` file into the writer-facing arrays.
+
+    Returns ``(col_names, row_names, col_value, col_dual, row_dual)``.
+    All five live in-process at numpy / list scale — typically a few
+    hundred MB even on the DES-scale LP, vs the +33 GB the equivalent
+    ``Highs.readModel(mps)`` parent re-read used to cost.
+
+    The HiGHS style=0 file format (see ``Highs::writeSolution``):
+
+        Model status
+        <status>
+
+        # Primal solution values
+        Feasible | Infeasible
+        Objective <value>
+        # Columns <N>
+        <name> <value>
+        ...
+        # Rows <M>
+        <name> <value>
+        ...
+
+        # Dual solution values
+        Feasible | Infeasible
+        # Columns <N>
+        <name> <dual>
+        ...
+        # Rows <M>
+        <name> <dual>
+        ...
+
+        # Basis ...   (ignored — basis statuses are not needed by the
+                       parent-side output writers)
+
+    Each ``<name> <value>`` line splits on whitespace; names with
+    embedded spaces are not produced by HiGHS so the simple split is
+    safe.
+    """
+    col_names: list[str] = []
+    row_names: list[str] = []
+    col_value_list: list[float] = []
+    col_dual_list: list[float] = []
+    row_value_list: list[float] = []   # not actually exposed; parse but discard
+    row_dual_list: list[float] = []
+
+    # Three-state parser:
+    #   section   ∈ {"primal", "dual", None}
+    #   bucket    ∈ {"col", "row", None}
+    section: str | None = None
+    bucket: str | None = None
+
+    with open(sol_path) as fh:
+        for raw in fh:
+            line = raw.rstrip("\n")
+            if not line.strip():
+                continue
+            if line.startswith("# Primal solution"):
+                section, bucket = "primal", None
+                continue
+            if line.startswith("# Dual solution"):
+                section, bucket = "dual", None
+                continue
+            if line.startswith("# Basis"):
+                # Basis section ends the data we care about.
+                break
+            if line.startswith("# Columns"):
+                bucket = "col"
+                continue
+            if line.startswith("# Rows"):
+                bucket = "row"
+                continue
+            if line.startswith("#"):
+                # Unrecognised comment header — keep current state.
+                continue
+            if (
+                line.startswith("Model status")
+                or line.startswith("Objective ")
+                or line in ("Feasible", "Infeasible", "Unknown")
+                or line.startswith("HiGHS_basis_file")
+                or line in ("Valid", "None")
+            ):
+                continue
+            # Data row: "<name> <value>"
+            sp = line.rsplit(None, 1)
+            if len(sp) != 2:
+                continue
+            name, val_s = sp
+            try:
+                val = float(val_s)
+            except ValueError:
+                continue
+            if section == "primal" and bucket == "col":
+                col_names.append(name)
+                col_value_list.append(val)
+            elif section == "primal" and bucket == "row":
+                row_names.append(name)
+                row_value_list.append(val)
+            elif section == "dual" and bucket == "col":
+                col_dual_list.append(val)
+            elif section == "dual" and bucket == "row":
+                row_dual_list.append(val)
+
+    col_value = np.asarray(col_value_list, dtype=np.float64)
+    col_dual = (
+        np.asarray(col_dual_list, dtype=np.float64)
+        if col_dual_list else np.zeros(len(col_value), dtype=np.float64)
+    )
+    row_dual = (
+        np.asarray(row_dual_list, dtype=np.float64)
+        if row_dual_list else np.zeros(len(row_names), dtype=np.float64)
+    )
+    return col_names, row_names, col_value, col_dual, row_dual
+
+
+class _SolHighsShim:
+    """Duck-typed stand-in for ``highspy.Highs`` for the cold-path writers.
+
+    The flextool writers under ``process_outputs/`` consume the solver
+    instance via a small, stable surface:
+
+    * ``allVariableNames()`` — list[str] of column names.
+    * ``getSolution()`` — object with ``col_value`` / ``col_dual``
+      / ``row_dual`` attributes (numpy arrays).
+    * ``getLp().row_names_`` — list[str] of constraint names.
+    * ``passColName(cid, name)`` — in-place rename of a column.
+
+    This shim wraps the arrays parsed from the subprocess ``.sol`` file
+    and exposes exactly those four entry points.  Sidesteps the parent-
+    side ``highspy.Highs.readModel`` whose +33 GB RSS bump used to spike
+    at the per-solve ``Solver`` checkpoint on large LPs.
+
+    Memory cost: O(n_cols + n_rows) Python strings + the four numpy
+    arrays — typically a few hundred MB on a 10 M-cell LP vs the tens
+    of GB the full Highs sidecar took.
+    """
+
+    __slots__ = ("_col_names", "_row_names", "_solution", "_lp", "_obj")
+
+    class _SolutionView:
+        __slots__ = ("col_value", "col_dual", "row_dual")
+
+        def __init__(
+            self,
+            col_value: np.ndarray,
+            col_dual: np.ndarray,
+            row_dual: np.ndarray,
+        ):
+            self.col_value = col_value
+            self.col_dual = col_dual
+            self.row_dual = row_dual
+
+    class _LpView:
+        __slots__ = ("row_names_",)
+
+        def __init__(self, row_names: list[str]):
+            self.row_names_ = row_names
+
+    def __init__(
+        self,
+        *,
+        col_names: list[str],
+        row_names: list[str],
+        col_value: np.ndarray,
+        col_dual: np.ndarray,
+        row_dual: np.ndarray,
+        objective: float = 0.0,
+    ):
+        self._col_names = col_names
+        self._row_names = row_names
+        self._solution = self._SolutionView(col_value, col_dual, row_dual)
+        self._lp = self._LpView(row_names)
+        self._obj = objective
+
+    # --- writer-facing API ------------------------------------------------
+
+    def allVariableNames(self) -> list[str]:
+        return self._col_names
+
+    def getSolution(self) -> "_SolHighsShim._SolutionView":
+        return self._solution
+
+    def getLp(self) -> "_SolHighsShim._LpView":
+        return self._lp
+
+    def passColName(self, col_id: int, new_name: str) -> None:
+        # Mirror highspy's in-place rename onto the shim's name array.
+        self._col_names[col_id] = new_name
+
+    def getNumCol(self) -> int:
+        return len(self._col_names)
+
+    def getNumRow(self) -> int:
+        return len(self._row_names)
+
+    def getObjectiveValue(self) -> float:
+        # Used by ``write_v_obj`` (scaled value, the writer un-scales).
+        # Backed by the value we parsed from the ``Objective`` line in
+        # the .sol file.
+        return self._obj
+
+    # Silence / status helpers a few code paths invoke defensively.
+    def silent(self) -> None:  # pragma: no cover - trivial
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Per-solver CLI dispatch (copied from polar-high's _mps_fallback.py)
+# ---------------------------------------------------------------------------
+# Source: ``polar-high-opt/src/polar_high/solvers/_mps_fallback.py``.
+# We copy verbatim (with imports adapted) rather than reuse the upstream
+# ``run_via_file`` because that entry point materialises an ``LpView`` —
+# the memory-greedy path we spent days bounding via ``Problem.write_mps``.
+# The duplication keeps both repos independent of each other on this
+# memory-critical code path.
+
+_BINARY_NAMES: dict[str, str] = {
+    "gurobi": "gurobi_cl",
+    "cplex": "cplex",
+    "xpress": "optimizer",
+    "copt": "copt_cmd",
+}
+
+_POSIX_INSTALL_DIRS: dict[str, list[str]] = {
+    "gurobi": [
+        "/opt/gurobi/bin",
+        "/opt/gurobi/linux64/bin",
+        "/Library/gurobi/bin",
+        os.path.expanduser("~/gurobi/bin"),
+    ],
+    "cplex": [
+        "/opt/ibm/ILOG/CPLEX_Studio/cplex/bin/x86-64_linux",
+        "/opt/ibm/ILOG/CPLEX_Studio/cplex/bin",
+        "/opt/cplex/bin",
+        os.path.expanduser("~/cplex/bin"),
+    ],
+    "xpress": [
+        "/opt/xpressmp/bin",
+        "/opt/fico/xpress/bin",
+        os.path.expanduser("~/xpressmp/bin"),
+    ],
+    "copt": [
+        "/opt/copt/bin",
+        "/opt/copt71/bin",
+        os.path.expanduser("~/copt/bin"),
+    ],
+}
+
+
+def _find_solver_binary(solver_name: str) -> Path | None:
+    """Return the absolute path to the solver's CLI binary, or ``None``.
+
+    Lookup order: ``$PATH`` via :func:`shutil.which`, then a small set
+    of conventional POSIX install dirs.  Returns ``None`` on miss; the
+    caller raises a user-actionable error.
+    """
+    bin_name = _BINARY_NAMES.get(solver_name)
+    if bin_name is None:
+        return None
+    found = shutil.which(bin_name)
+    if found is not None:
+        return Path(found)
+    if os.name == "posix":
+        for d in _POSIX_INSTALL_DIRS.get(solver_name, []):
+            candidate = Path(d) / bin_name
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                return candidate
+    return None
+
+
+def _gurobi_script(
+    binary: Path, mps_path: Path, sol_path: Path, opt_path: Path | None,
+) -> tuple[list[str], str | None]:
+    """``gurobi_cl [ReadParams=<opt>] ResultFile=<sol> <mps>``.
+
+    When *opt_path* is given, Gurobi's native ``ReadParams=<file>`` slot
+    loads our merged baseline+overlay parameters before the solve.
+    """
+    argv: list[str] = [str(binary)]
+    if opt_path is not None:
+        argv.append(f"ReadParams={opt_path}")
+    argv.append(f"ResultFile={sol_path}")
+    argv.append(str(mps_path))
+    return argv, None
+
+
+def _cplex_script(
+    binary: Path, mps_path: Path, sol_path: Path, opt_path: Path | None,
+) -> tuple[list[str], str]:
+    """CPLEX interactive optimizer: pipe commands on stdin.
+
+    When *opt_path* is given, each non-comment line is translated to
+    ``set <name> <value>`` and emitted *before* the ``read``/``optimize``
+    pair so parameter values are in effect when the model loads.
+    """
+    pre: list[str] = []
+    if opt_path is not None:
+        for name, value in _parse_native_opt_file(opt_path).items():
+            pre.append(f"set {name} {value}")
+    cmds = "\n".join(
+        pre
+        + [
+            f"read {mps_path}",
+            "optimize",
+            f"write {sol_path} sol",
+            "quit",
+            "",
+        ]
+    )
+    return [str(binary)], cmds
+
+
+def _xpress_script(
+    binary: Path, mps_path: Path, sol_path: Path, opt_path: Path | None,
+) -> tuple[list[str], str]:
+    """Xpress optimizer console script via stdin.
+
+    When *opt_path* is given, each non-comment line is translated to
+    ``setControl <NAME> <value>`` and emitted *before* ``readprob``/
+    ``lpoptimize`` so controls are in effect for the solve.
+    """
+    pre: list[str] = []
+    if opt_path is not None:
+        for name, value in _parse_native_opt_file(opt_path).items():
+            pre.append(f"setControl {name} {value}")
+    cmds = "\n".join(
+        pre
+        + [
+            f"readprob {mps_path}",
+            "lpoptimize",
+            # Force the MPS-like **SLX** solution (name-based, whitespace-
+            # safe) for the primal — Xpress' default ``writesol`` emits an
+            # index-based ``.asc``/``.hdr`` CSV pair with no usable
+            # name→value mapping.  ``writeprtsol`` carries the objective
+            # value SLX omits.  Xpress appends ``.slx`` / ``.prt`` to the
+            # base path; :func:`_parse_xpress_sol` looks for those.
+            f"writeslxsol {sol_path}",
+            f"writeprtsol {sol_path}",
+            "quit",
+            "",
+        ]
+    )
+    return [str(binary)], cmds
+
+
+def _copt_script(
+    binary: Path, mps_path: Path, sol_path: Path, opt_path: Path | None,
+) -> tuple[list[str], str]:
+    """COPT's ``copt_cmd`` script via stdin.
+
+    When *opt_path* is given, each non-comment line is translated to
+    ``set <ParamName> <value>`` and emitted *before* ``read``/``optimize``.
+    """
+    pre: list[str] = []
+    if opt_path is not None:
+        for name, value in _parse_native_opt_file(opt_path).items():
+            pre.append(f"set {name} {value}")
+    cmds = "\n".join(
+        pre
+        + [
+            f"read {mps_path}",
+            "optimize",
+            f"write {sol_path}",
+            "quit",
+            "",
+        ]
+    )
+    return [str(binary)], cmds
+
+
+_SCRIPTS = {
+    "gurobi": _gurobi_script,
+    "cplex": _cplex_script,
+    "xpress": _xpress_script,
+    "copt": _copt_script,
+}
+
+
+# ---------------------------------------------------------------------------
+# Per-solver baseline option-file handling
+# ---------------------------------------------------------------------------
+# Each commercial solver gets a baseline ``solver_config/<solver>.opt``
+# (shipped with the FlexTool repo, user-editable).  The file is written
+# in the *solver's own* parameter-file syntax — see the comment header
+# in each baseline file for the exact format.  The scenario's
+# ``solver_options`` dict (already keyed by native parameter names by
+# ``build_solver_options`` in ``_solver_dispatch.py``) is then overlaid
+# on top, taking precedence per key.  The merged dict is materialised
+# to a temp file next to the MPS in the per-solver native format and
+# fed to the CLI via the per-solver mechanism (Gurobi: ReadParams=
+# argv slot; CPLEX/Xpress/COPT: inline set/setControl commands piped
+# on stdin).  Format helpers below.
+
+
+def _resolve_solver_config_dir() -> Path:
+    """Resolve the directory holding ``<solver>.opt`` baseline files.
+
+    Lookup order:
+
+    1. ``$FLEXTOOL_SOLVER_CONFIG_DIR`` environment variable (matches the
+       override hook used by the existing ``highs.opt`` resolution path
+       in tests / CI).
+    2. ``<cwd>/solver_config`` — the same default that
+       :func:`flextool.engine_polars._orchestration.run_chain_from_db`
+       uses for ``highs.opt``.
+
+    Returns the resolved :class:`Path` regardless of whether it exists;
+    callers check ``.is_file()`` on the specific solver file before
+    parsing.
+    """
+    env = os.environ.get("FLEXTOOL_SOLVER_CONFIG_DIR")
+    if env:
+        return Path(env)
+    return Path.cwd() / "solver_config"
+
+
+def _parse_native_opt_file(path: Path) -> dict[str, str]:
+    """Parse a native solver ``.opt`` file into a name → value dict.
+
+    Format (shared across all four commercial baselines):
+
+    * ``#`` introduces a comment line; blank lines are ignored.
+    * Every other line is split on the *first* whitespace run into a
+      ``(name, value)`` pair.  The name may contain a single internal
+      space when needed (CPLEX uses dotted-or-spaced names like
+      ``mip tolerances mipgap``) — the parser uses :func:`str.rsplit`
+      with ``maxsplit=1`` so the **last** whitespace-separated token is
+      the value and everything before is the name.
+
+    Returns an empty dict when the file is missing or unreadable.
+    """
+    out: dict[str, str] = {}
+    if not path.is_file():
+        return out
+    try:
+        with path.open("r") as fh:
+            for raw in fh:
+                line = raw.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if " " not in line and "\t" not in line:
+                    continue
+                name, value = line.rsplit(maxsplit=1)
+                out[name.strip()] = value.strip()
+    except OSError:
+        return {}
+    return out
+
+
+def _format_native_opt_value(v: object) -> str:
+    """Render *v* for a native solver opt-file line.
+
+    Booleans become ``1`` / ``0`` (Gurobi/COPT accept either word or
+    int; the int form is portable across CPLEX/Xpress too).
+    """
+    if isinstance(v, bool):
+        return "1" if v else "0"
+    return str(v)
+
+
+def _format_gurobi_opt(merged: dict[str, str]) -> str:
+    """Format *merged* as a Gurobi ``.prm`` file body.
+
+    One ``<ParamName> <value>`` per line.  Same syntax produced by
+    ``gurobi_cl`` 's own ``-w`` parameter dump.
+    """
+    return "".join(
+        f"{name} {_format_native_opt_value(value)}\n"
+        for name, value in merged.items()
+    )
+
+
+def _format_cplex_opt(merged: dict[str, str]) -> str:
+    """Format *merged* as our CPLEX baseline body.
+
+    Same layout as the input file: ``<name> <value>`` per line, where
+    ``<name>`` uses CPLEX' interactive ``set`` syntax (e.g.
+    ``mip tolerances mipgap``).  The per-solver script builder translates
+    each line into ``set <name> <value>`` for piping on stdin.
+    """
+    return "".join(
+        f"{name} {_format_native_opt_value(value)}\n"
+        for name, value in merged.items()
+    )
+
+
+def _format_xpress_opt(merged: dict[str, str]) -> str:
+    """Format *merged* as our Xpress controls baseline body."""
+    return "".join(
+        f"{name} {_format_native_opt_value(value)}\n"
+        for name, value in merged.items()
+    )
+
+
+def _format_copt_opt(merged: dict[str, str]) -> str:
+    """Format *merged* as our COPT baseline body."""
+    return "".join(
+        f"{name} {_format_native_opt_value(value)}\n"
+        for name, value in merged.items()
+    )
+
+
+_OPT_FORMATTERS = {
+    "gurobi": _format_gurobi_opt,
+    "cplex": _format_cplex_opt,
+    "xpress": _format_xpress_opt,
+    "copt": _format_copt_opt,
+}
+
+
+def _build_commercial_opt_file(
+    solver_name: str,
+    options: dict[str, Any] | None,
+    out_path: Path,
+    *,
+    config_dir: Path | None = None,
+) -> Path | None:
+    """Merge baseline ``<solver>.opt`` with scenario *options* and write
+    the result to *out_path*.
+
+    Returns the path to the merged file when it has at least one entry,
+    or ``None`` when both the baseline file is missing and the scenario
+    *options* dict is empty (caller skips the per-solver opt-file slot
+    entirely so the CLI doesn't get a ``ReadParams=`` to a no-op file).
+    """
+    config_dir = config_dir or _resolve_solver_config_dir()
+    baseline_path = config_dir / f"{solver_name}.opt"
+    merged: dict[str, str] = {
+        k: str(v) for k, v in _parse_native_opt_file(baseline_path).items()
+    }
+    if options:
+        for key, value in options.items():
+            # Skip the FlexTool-internal ``time_limit`` knob — that's
+            # forwarded as the subprocess timeout, not as a solver
+            # parameter (Gurobi accepts ``TimeLimit`` which IS in the
+            # native-name overlay; the friendly ``time_limit`` key never
+            # appears here for the commercial path because
+            # ``build_solver_options`` translates it first).
+            if value is None:
+                continue
+            merged[str(key)] = _format_native_opt_value(value)
+    if not merged:
+        return None
+    formatter = _OPT_FORMATTERS[solver_name]
+    out_path.write_text(formatter(merged))
+    return out_path
+
+
+def _parse_gurobi_sol(
+    path: Path,
+) -> tuple[str, float | None, dict[str, float] | None, dict[str, float] | None]:
+    """Parse a Gurobi ``.sol`` (key=value text).
+
+    Returns ``(status_str, objective, primal_dict, dual_dict)`` where
+    ``status_str`` is one of ``"OPTIMAL"`` / ``"OTHER"``.
+    """
+    if not path.is_file():
+        return "OTHER", None, None, None
+    objective: float | None = None
+    primal: dict[str, float] = {}
+    with path.open("r") as fh:
+        for raw in fh:
+            line = raw.strip()
+            if not line:
+                continue
+            if line.startswith("#"):
+                # Gurobi writes ``# Objective value = <v>``; COPT writes
+                # ``# Objective value <v>`` (no ``=``) — accept either.
+                m = re.search(r"[Oo]bjective\s+value\s*=?\s*([-\d.eE+inf]+)", line)
+                if m:
+                    try:
+                        objective = float(m.group(1))
+                    except ValueError:
+                        objective = None
+                continue
+            parts = line.split()
+            if len(parts) >= 2:
+                try:
+                    primal[parts[0]] = float(parts[1])
+                except ValueError:
+                    continue
+    status = "OPTIMAL" if primal else "OTHER"
+    return status, objective, (primal or None), None
+
+
+def _parse_copt_sol(path: Path):
+    """COPT's ``.sol`` matches Gurobi's key=value layout."""
+    return _parse_gurobi_sol(path)
+
+
+def _parse_cplex_sol(
+    path: Path,
+) -> tuple[str, float | None, dict[str, float] | None, dict[str, float] | None]:
+    """Parse CPLEX XML ``.sol`` via :mod:`xml.etree.ElementTree`."""
+    if not path.is_file():
+        return "OTHER", None, None, None
+    try:
+        tree = ET.parse(path)
+    except ET.ParseError:
+        return "OTHER", None, None, None
+    root = tree.getroot()
+    if root.tag == "CPLEXSolutions":
+        children = list(root)
+        if not children:
+            return "OTHER", None, None, None
+        root = children[0]
+    objective: float | None = None
+    status = "OTHER"
+    header = root.find("header")
+    if header is not None:
+        obj_str = header.get("objectiveValue")
+        if obj_str is not None:
+            try:
+                objective = float(obj_str)
+            except ValueError:
+                pass
+        status_str = (header.get("solutionStatusString") or "").lower()
+        if "optimal" in status_str:
+            status = "OPTIMAL"
+        elif "infeasible" in status_str:
+            status = "INFEASIBLE"
+        elif "unbounded" in status_str:
+            status = "UNBOUNDED"
+        elif "time" in status_str:
+            status = "TIME_LIMIT"
+    primal: dict[str, float] = {}
+    vars_el = root.find("variables")
+    if vars_el is not None:
+        for v in vars_el.findall("variable"):
+            name = v.get("name")
+            val_str = v.get("value")
+            if name is None or val_str is None:
+                continue
+            try:
+                primal[name] = float(val_str)
+            except ValueError:
+                continue
+    dual: dict[str, float] = {}
+    cons_el = root.find("linearConstraints")
+    if cons_el is not None:
+        for c in cons_el.findall("constraint"):
+            name = c.get("name")
+            dual_str = c.get("dual")
+            if name is None or dual_str is None:
+                continue
+            try:
+                dual[name] = float(dual_str)
+            except ValueError:
+                continue
+    if status == "OTHER" and primal:
+        status = "OPTIMAL"
+    return status, objective, (primal or None), (dual or None)
+
+
+def _parse_xpress_sol(
+    path: Path,
+) -> tuple[str, float | None, dict[str, float] | None, dict[str, float] | None]:
+    """Parse the Xpress solution written by :func:`_xpress_script`.
+
+    We force Xpress to emit the MPS-like **SLX** solution (name-based,
+    whitespace-safe) for the primal plus the **print** solution for the
+    objective — rather than the default ``writesol`` output, which is an
+    index-based ``.asc``/``.hdr`` CSV pair carrying no usable name→value
+    mapping.  Xpress appends ``.slx`` / ``.prt`` to the base path passed
+    to ``writeslxsol`` / ``writeprtsol``, so look for those next to
+    *path* (with a couple of fallbacks for console-version differences).
+
+    SLX body lines look like ``  C C0000001   10`` (indicator, name,
+    value); the print solution carries one
+    ``Objective function value is <v>`` line.
+    """
+    def _first_existing(cands: list[Path]) -> Path | None:
+        for c in cands:
+            if c.is_file():
+                return c
+        return None
+
+    primal: dict[str, float] = {}
+    slx = _first_existing(
+        [Path(str(path) + ".slx"), path, path.with_suffix(".slx")]
+    )
+    if slx is not None:
+        for raw in slx.read_text().splitlines():
+            parts = raw.split()
+            # Data rows carry a trailing numeric value and a name just
+            # before it; header lines (NAME/ENDATA/OBJSENSE) fail the
+            # float() and are skipped.  ``_generic_col_id`` downstream
+            # keeps only the ``C…`` column names.
+            if len(parts) < 2:
+                continue
+            try:
+                val = float(parts[-1])
+            except ValueError:
+                continue
+            primal[parts[-2]] = val
+
+    objective: float | None = None
+    prt = _first_existing(
+        [Path(str(path) + ".prt"), path.with_suffix(".prt")]
+    )
+    if prt is not None:
+        m = re.search(
+            r"[Oo]bjective\s+function\s+value\s+is\s+([-\d.eE+]+)",
+            prt.read_text(),
+        )
+        if m:
+            try:
+                objective = float(m.group(1))
+            except ValueError:
+                objective = None
+
+    status = "OPTIMAL" if primal else "OTHER"
+    return status, objective, (primal or None), None
+
+
+_PARSERS = {
+    "gurobi": _parse_gurobi_sol,
+    "cplex": _parse_cplex_sol,
+    "xpress": _parse_xpress_sol,
+    "copt": _parse_copt_sol,
+}
+
+
+_LICENSE_HINTS = (
+    "license",
+    "licence",
+    "no token",
+    "token server",
+    "wls",
+)
+
+
+def _looks_like_license_error(*texts: str) -> bool:
+    blob = "\n".join(t for t in texts if t).lower()
+    return any(h in blob for h in _LICENSE_HINTS)
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def solve_via_subprocess(
+    problem: "Problem",
+    solver_name: str,
+    options: dict[str, Any] | None,
+    *,
+    solve_name: str,
+    logger: logging.Logger | None = None,
+    work_folder: Path | None = None,
+) -> "Solution":
+    """Solve *problem* via the appropriate CLI subprocess; return a Solution.
+
+    Parameters
+    ----------
+    problem
+        The :class:`polar_high.Problem` to solve.  Its LP source is
+        written to MPS via :meth:`Problem.write_mps(release=True)`,
+        leaving the Problem in ``_released`` state.
+    solver_name
+        ``"highs"`` for HiGHS (routes to ``flextool.cli.cmd_solve_mps``)
+        or one of ``"gurobi"`` / ``"cplex"`` / ``"xpress"`` / ``"copt"``
+        for the commercial CLIs.
+    options
+        Effective solver options.  For HiGHS, written as a HiGHS ``.opt``
+        file ingested by the subprocess.  For commercial solvers,
+        overlaid on top of the per-solver baseline at
+        ``solver_config/<solver>.opt`` and fed to the CLI via the
+        per-solver mechanism (see
+        :func:`_build_commercial_opt_file`).  Raw options win on key
+        collision.  ``time_limit`` is additionally honoured as the
+        subprocess timeout.
+    solve_name
+        Used to name the MPS / .opt / .sol files.
+    logger
+        Optional :class:`logging.Logger`.
+    work_folder
+        When given, intermediate files live under
+        ``<work_folder>/solve_data/subprocess/`` for post-mortem.
+        ``None`` uses a self-cleaning temp dir.
+
+    Returns
+    -------
+    polar_high.Solution
+        Carries a :class:`_SolHighsShim` bound to the parsed
+        primal/dual arrays and the recovered column/row names.
+        Downstream writers see a uniform ``sol.highs`` shape regardless
+        of which solver actually ran.
+    """
+    if solver_name == "highs":
+        return _solve_highs_subprocess(
+            problem, options, solve_name=solve_name, logger=logger,
+            work_folder=work_folder,
+        )
+    if solver_name in _SCRIPTS:
+        return _solve_commercial_subprocess(
+            problem, solver_name, options, solve_name=solve_name,
+            logger=logger, work_folder=work_folder,
+        )
+    raise ValueError(
+        f"solve_via_subprocess: unknown solver_name={solver_name!r}; "
+        f"expected 'highs' or one of {sorted(_SCRIPTS)}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# HiGHS subprocess path (the original ``solve_via_subprocess`` body)
+# ---------------------------------------------------------------------------
+
+
+def _solve_highs_subprocess(
+    problem: "Problem",
+    options: dict[str, Any] | None,
+    *,
+    solve_name: str,
+    logger: logging.Logger | None,
+    work_folder: Path | None,
+) -> "Solution":
+    """HiGHS-specific subprocess path (unchanged contract).
+
+    Writes MPS via :meth:`Problem.write_mps`, spawns
+    :mod:`flextool.cli.cmd_solve_mps`, parses the .sol back via
+    :func:`_parse_highs_sol` + :class:`_SolHighsShim` — no parent-side
+    ``highspy.Highs.readModel`` (which used to dominate cold-path RSS).
+
+    **Warm-start arm** (opt-in, active only when the save-memory
+    subprocess path runs *and* ``FLEXTOOL_WARM_START == "1"``): a native
+    HiGHS ``.bas`` basis is cached in a persistent directory that
+    survives the per-solve ``out_dir`` cleanup, keyed by the MPS
+    structural fingerprint (``problem._last_mps_fingerprint``).  On a
+    subsequent solve of the same structural model the cached basis is
+    injected via the child's ``--warm-basis`` (readBasis); every
+    warm-start run also captures a fresh basis (``--basis`` to a unique
+    tmp, atomically published via ``os.replace`` on success) and a stats
+    sidecar (``--stats``) for later measurement.  Every step is
+    defensive: a missing fingerprint, a rejected/garbage basis, or any
+    exception falls back to a correct cold solve.  Warm-start never
+    breaks a solve.  This ``.bas`` cache is a separate branch from the
+    in-memory ``WarmProblem`` reuse gate in ``_orchestration.py``.
+
+    **First-transfer A/B gate** (Landmine B): a supplied basis disables
+    HiGHS' presolve, so a stale/far seed can make the warm solve SLOWER
+    than a cold (presolve-on) one.  On a fingerprint's FIRST warm
+    transfer (cache hit, no verdict marker yet) we run one extra cold
+    timing PROBE child (throwaway ``.probe.sol`` / ``.probe.stats.json``,
+    no ``--warm-basis``) alongside the normal warm main run, then compare
+    wall times (``run_time`` from each stats sidecar).  Two marker files
+    in the cache dir record the verdict: ``<fp>.abtested`` (warm within
+    ``(1 + _WARM_AB_MARGIN)`` of cold → keep injecting, never re-probe)
+    or ``<fp>.nowarm`` (warm regressed → solve cold from now on, still
+    refreshing the captured basis).  If the probe can't produce a time we
+    write ``.abtested`` and proceed warm (no perpetual re-probing).  The
+    main run's Solution is always returned unchanged — the probe only
+    informs the decision, so the returned result is correct regardless of
+    the timing verdict.  Marker writes are best-effort and non-fatal.
+    """
+    from polar_high import Solution
+
+    cleanup = work_folder is None
+    if work_folder is not None:
+        out_dir = Path(work_folder) / "solve_data" / "subprocess"
+        out_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        out_dir = Path(tempfile.mkdtemp(prefix="flextool_subprocess_"))
+
+    safe_name = solve_name.replace("/", "_").replace(" ", "_") or "solve"
+    mps_path = out_dir / f"{safe_name}.mps"
+    sol_path = out_dir / f"{safe_name}.sol"
+    opts_path = out_dir / f"{safe_name}.opt"
+
+    # Warm-start basis-cache slots (populated only under FLEXTOOL_WARM_START;
+    # declared here so the ``finally`` cleanup can reference them safely).
+    warm_cached: Path | None = None
+    warm_tmp_bas: Path | None = None
+    warm_stats_path: Path | None = None
+    # First-transfer A/B gate slots.
+    warm_probe_sol: Path | None = None
+    warm_probe_stats: Path | None = None
+    warm_nowarm_marker: Path | None = None
+    warm_abtested_marker: Path | None = None
+    warm_first_transfer = False
+    warm_cold_time: float | None = None
+    warm_run_time: float | None = None
+
+    try:
+        opts = options or {}
+        with open(opts_path, "w") as f:
+            for k, v in opts.items():
+                f.write(f"{k}={_format_opt_value(v)}\n")
+
+        if logger is not None:
+            logger.info(
+                "save_memory: building LP for %r, writing MPS to %s",
+                solve_name, mps_path,
+            )
+
+        problem.write_mps(str(mps_path), release=True)
+
+        cmd = [
+            sys.executable, "-m", "flextool.cli.cmd_solve_mps",
+            "--mps", str(mps_path),
+            "--solution", str(sol_path),
+            "--options", str(opts_path),
+        ]
+
+        # --- Warm-start arm (opt-in) ------------------------------------
+        # Keyed by the MPS structural fingerprint.  Everything here is
+        # defensive: on any hiccup we drop the warm slots and solve cold.
+        if os.environ.get("FLEXTOOL_WARM_START") == "1":
+            try:
+                fp = getattr(problem, "_last_mps_fingerprint", None)
+                if fp is None:
+                    if logger is not None:
+                        logger.debug(
+                            "save_memory: no MPS fingerprint — warm-start "
+                            "skipped for %r", solve_name,
+                        )
+                else:
+                    cache_env = os.environ.get("FLEXTOOL_BASIS_CACHE_DIR")
+                    if cache_env:
+                        cache_dir = Path(cache_env)
+                    elif work_folder is not None:
+                        cache_dir = Path(work_folder) / "basis_cache"
+                    else:
+                        cache_dir = (
+                            Path(tempfile.gettempdir())
+                            / "flextool_basis_cache"
+                        )
+                    cache_dir.mkdir(parents=True, exist_ok=True)
+                    warm_cached = cache_dir / f"{fp}.bas"
+                    warm_nowarm_marker = cache_dir / f"{fp}.nowarm"
+                    warm_abtested_marker = cache_dir / f"{fp}.abtested"
+                    warm_stats_path = out_dir / f"{safe_name}.stats.json"
+
+                    if warm_cached.exists():
+                        if warm_nowarm_marker.exists():
+                            # This family regressed on its first A/B —
+                            # never inject the basis (solve cold); still
+                            # refresh the captured basis below.
+                            if logger is not None:
+                                logger.info(
+                                    "save_memory: warm-start disabled "
+                                    "(.nowarm) for %s — solving cold", fp,
+                                )
+                        elif warm_abtested_marker.exists():
+                            # Verdict already recorded as beneficial —
+                            # trust it, inject warm, no A/B probe.
+                            cmd += ["--warm-basis", str(warm_cached)]
+                            if logger is not None:
+                                logger.info(
+                                    "save_memory: warm-basis cache hit %s "
+                                    "(.abtested — trusting warm)", fp,
+                                )
+                        else:
+                            # FIRST warm transfer for this fingerprint: run
+                            # a cold timing probe now, then inject warm for
+                            # the main run and decide the verdict afterwards.
+                            warm_first_transfer = True
+                            warm_probe_sol = (
+                                out_dir / f"{safe_name}.probe.sol"
+                            )
+                            warm_probe_stats = (
+                                out_dir / f"{safe_name}.probe.stats.json"
+                            )
+                            warm_cold_time = _run_cold_probe(
+                                mps_path=mps_path,
+                                opts_path=opts_path,
+                                probe_sol=warm_probe_sol,
+                                probe_stats=warm_probe_stats,
+                                logger=logger,
+                            )
+                            cmd += ["--warm-basis", str(warm_cached)]
+                            if logger is not None:
+                                logger.info(
+                                    "save_memory: warm-basis cache hit %s "
+                                    "(first transfer — A/B probing, "
+                                    "cold_time=%s)", fp, warm_cold_time,
+                                )
+                    # Always refresh the cache this run: capture a fresh
+                    # basis to a per-process tmp (atomic publish on success),
+                    # plus a stats sidecar for later measurement.
+                    warm_tmp_bas = cache_dir / f"{fp}.bas.tmp.{os.getpid()}"
+                    cmd += [
+                        "--basis", str(warm_tmp_bas),
+                        "--stats", str(warm_stats_path),
+                    ]
+            except Exception as exc:  # noqa: BLE001 - fail safe to cold
+                if logger is not None:
+                    logger.warning(
+                        "save_memory: warm-start setup failed (%s) — "
+                        "solving cold", exc,
+                    )
+                warm_cached = warm_tmp_bas = warm_stats_path = None
+                warm_probe_sol = warm_probe_stats = None
+                warm_first_transfer = False
+
+        if logger is not None:
+            logger.info(
+                "save_memory: spawning subprocess HiGHS for %r", solve_name,
+            )
+        cp = subprocess.run(cmd)
+        optimal = cp.returncode == 0
+
+        # --- Warm-start publish + measurement ---------------------------
+        if warm_tmp_bas is not None:
+            try:
+                if cp.returncode == 0 and warm_tmp_bas.exists():
+                    # Atomic publish (write-tmp-then-rename); tmp and cache
+                    # share a directory so this is a same-FS rename.
+                    os.replace(str(warm_tmp_bas), str(warm_cached))
+                    if logger is not None:
+                        logger.info(
+                            "save_memory: published warm-basis cache %s",
+                            warm_cached.name,
+                        )
+                else:
+                    # Failed/partial solve — never publish; drop the tmp.
+                    if warm_tmp_bas.exists():
+                        warm_tmp_bas.unlink()
+            except Exception as exc:  # noqa: BLE001 - non-fatal
+                if logger is not None:
+                    logger.warning(
+                        "save_memory: warm-basis publish failed (%s) — "
+                        "cache not updated", exc,
+                    )
+                try:
+                    if warm_tmp_bas.exists():
+                        warm_tmp_bas.unlink()
+                except OSError:
+                    pass
+        if warm_stats_path is not None:
+            try:
+                if warm_stats_path.exists():
+                    stats = json.loads(warm_stats_path.read_text())
+                    rt = stats.get("run_time")
+                    warm_run_time = float(rt) if rt is not None else None
+                    if logger is not None:
+                        logger.info(
+                            "save_memory: warm-start stats for %r — "
+                            "simplex_iters=%s warm_basis_used=%s run_time=%s",
+                            solve_name,
+                            stats.get("simplex_iteration_count"),
+                            stats.get("warm_basis_used"),
+                            warm_run_time,
+                        )
+            except Exception as exc:  # noqa: BLE001 - measurement only
+                if logger is not None:
+                    logger.warning(
+                        "save_memory: warm-start stats parse failed (%s)",
+                        exc,
+                    )
+
+        # --- First-transfer A/B verdict ---------------------------------
+        # Decide whether warm-start helped this family.  A supplied basis
+        # disables presolve, so compare wall times: keep injecting only
+        # when warm is within (1 + margin) of cold, else mark ``.nowarm``.
+        # No usable timing → trust warm and stop re-probing (``.abtested``).
+        if warm_first_transfer:
+            try:
+                cold_t = warm_cold_time
+                warm_t = warm_run_time
+                if (
+                    cold_t is not None and cold_t >= 0.0
+                    and warm_t is not None and warm_t >= 0.0
+                ):
+                    if warm_t > cold_t * (1.0 + _warm_ab_margin()):
+                        _touch_marker(warm_nowarm_marker, logger)
+                        if logger is not None:
+                            logger.info(
+                                "warm-start regressed for %s "
+                                "(warm=%ss vs cold=%ss) — disabling future "
+                                "injection", fp, warm_t, cold_t,
+                            )
+                    else:
+                        _touch_marker(warm_abtested_marker, logger)
+                        if logger is not None:
+                            logger.info(
+                                "save_memory: warm-start confirmed "
+                                "beneficial for %s (warm=%ss vs cold=%ss)",
+                                fp, warm_t, cold_t,
+                            )
+                else:
+                    # Probe gave no usable time — trust warm, don't re-probe.
+                    _touch_marker(warm_abtested_marker, logger)
+                    if logger is not None:
+                        logger.debug(
+                            "save_memory: A/B probe produced no usable time "
+                            "for %s — trusting warm (.abtested)", fp,
+                        )
+            except Exception as exc:  # noqa: BLE001 - gating is best-effort
+                if logger is not None:
+                    logger.warning(
+                        "save_memory: warm-start A/B gating failed (%s) — "
+                        "no verdict recorded", exc,
+                    )
+        if cp.returncode > 1:
+            raise RuntimeError(
+                f"subprocess HiGHS for solve {solve_name!r} failed with "
+                f"exit code {cp.returncode}; MPS+options preserved at "
+                f"{out_dir} for inspection"
+            )
+        if logger is not None:
+            logger.info(
+                "save_memory: subprocess complete (exit=%d, optimal=%s); "
+                "reading solution from %s",
+                cp.returncode, optimal, sol_path,
+            )
+
+        # Parse the .sol directly — no parent-side ``Highs.readModel``.
+        # On large LPs the old path's ``readModel(mps)`` spiked +33 GB
+        # of RSS purely to satisfy ``allVariableNames()`` / ``getSolution()``
+        # on downstream writers; the .sol file already carries names +
+        # primal + duals, and the writers see the same shape via the
+        # ``_SolHighsShim`` wrapper.
+        col_names, row_names, col_value, col_dual, row_dual = (
+            _parse_highs_sol(sol_path)
+        )
+        n_cols = len(col_value)
+        if col_dual.size == 0:
+            col_dual = np.zeros(n_cols, dtype=np.float64)
+
+        # HiGHS' ``writeSolution`` may emit synthesized row names
+        # (``r0, r1, ...``) when the LP carried duplicate or otherwise
+        # un-preservable names through ``readModel`` — the warning
+        # "Row names are not present, or contain duplicates: using
+        # names with prefix 'r'" flags this on the subprocess stderr.
+        # The MPS file written by polar-high carries the canonical
+        # constraint names (e.g. ``nodeBalance_eq[n, d, t]``); recover
+        # them so the row-dual output writers' name-based lookups keep
+        # working.  Detect by checking whether every name matches the
+        # ``r<int>`` pattern AND the count equals the MPS' constraint
+        # row count.
+        if row_names and all(
+            n.startswith("r") and n[1:].isdigit() for n in row_names
+        ):
+            mps_row_names = _parse_mps_row_names(mps_path)
+            if len(mps_row_names) == len(row_names):
+                row_names = mps_row_names
+                if logger is not None:
+                    logger.debug(
+                        "save_memory: recovered %d row names from MPS "
+                        "(HiGHS writeSolution emitted synthesized 'r*' "
+                        "names for solve %r)",
+                        len(row_names), solve_name,
+                    )
+        obj = _read_objective_from_sol(sol_path)
+        h = _SolHighsShim(
+            col_names=col_names,
+            row_names=row_names,
+            col_value=col_value,
+            col_dual=col_dual,
+            row_dual=row_dual,
+            objective=obj,
+        )
+
+        return Solution(
+            optimal=optimal,
+            obj=obj,
+            col_value=col_value,
+            row_dual=row_dual,
+            col_dual=col_dual,
+            col_names=col_names,
+            row_names=row_names,
+            vars=dict(problem._vars),
+            highs=h,
+        )
+    finally:
+        if cleanup:
+            paths = [mps_path, sol_path, opts_path]
+            # The warm-start stats sidecar and A/B probe throwaways live
+            # inside ``out_dir`` — sweep them too so the ``rmdir`` below
+            # succeeds.  The cache itself (``warm_cached`` / ``warm_tmp_bas``)
+            # and the verdict markers live OUTSIDE ``out_dir`` and survive.
+            if warm_stats_path is not None:
+                paths.append(warm_stats_path)
+            if warm_probe_sol is not None:
+                paths.append(warm_probe_sol)
+            if warm_probe_stats is not None:
+                paths.append(warm_probe_stats)
+            for p in paths:
+                try:
+                    if p.exists():
+                        p.unlink()
+                except OSError:
+                    pass
+            try:
+                out_dir.rmdir()
+            except OSError:
+                pass
+
+
+# ---------------------------------------------------------------------------
+# Commercial-solver subprocess path (new)
+# ---------------------------------------------------------------------------
+
+
+def _solve_commercial_subprocess(
+    problem: "Problem",
+    solver_name: str,
+    options: dict[str, Any] | None,
+    *,
+    solve_name: str,
+    logger: logging.Logger | None,
+    work_folder: Path | None,
+) -> "Solution":
+    """Solve via a commercial solver's CLI binary.
+
+    1. ``problem.write_mps(release=True, emit_names=False)`` produces the
+       MPS via the cheap polars writer (peak ~2-3 GB on a 9.9 M-row LP),
+       using GENERIC ``C0000001`` / ``R0000002`` names.  Free-format MPS
+       is whitespace-delimited with no portable quoting, so real
+       FlexTool entity names — which routinely contain spaces (e.g.
+       ``Battery Farm``) — cannot go in the file without corrupting it.
+       We keep the real names in memory instead and map back by index.
+    2. Locate ``gurobi_cl`` / ``cplex`` / ``optimizer`` / ``copt_cmd``
+       via :func:`_find_solver_binary`.
+    3. Spawn the binary with the per-solver argv + stdin script
+       (copied verbatim from polar-high's ``_mps_fallback``).
+    4. Parse the .sol with the per-solver parser; map its generic-named
+       primal (and duals, for :data:`_DUAL_CAPABLE_SOLVERS`) back by
+       *index* onto the real ``col_id`` / ``row_id`` names rebuilt from
+       ``problem._vars`` (:func:`_col_names_from_vars`) and the pre-release
+       ``_cstrs`` snapshot (:func:`_row_names_from_cstrs`).
+    5. Wrap as a :class:`polar_high.Solution` backed by a
+       :class:`_SolHighsShim` so the existing output writer paths Just
+       Work — no parent-side ``highspy.Highs.readModel`` (which used to
+       OOM on large LPs and hard-fail on entity names containing spaces).
+
+    ``options`` is fed to the solver via a per-solver native opt-file
+    materialised next to the MPS in the per-solve temp dir.  The file
+    starts from the user-editable baseline at
+    ``solver_config/<solver>.opt`` (shipped in the FlexTool repo) and
+    overlays the scenario's *options* dict line-by-line (raw entries
+    win on key collision — same semantics as
+    :func:`build_solver_options`).  Each per-solver script builder then
+    references the merged file in the cleanest native form
+    (Gurobi: ``gurobi_cl ReadParams=<file> ...``; CPLEX/Xpress/COPT:
+    inline ``set``/``setControl`` lines piped on stdin before the
+    ``read``/``optimize`` pair).  ``time_limit`` is *also* honoured as
+    the subprocess timeout when present in *options*.
+    """
+    from polar_high import Solution
+
+    binary = _find_solver_binary(solver_name)
+    if binary is None:
+        raise RuntimeError(
+            f"{solver_name!r} CLI binary "
+            f"({_BINARY_NAMES.get(solver_name)!r}) was not found on $PATH "
+            f"or in the conventional install directories. Install the "
+            f"solver and ensure its 'bin' directory is on $PATH."
+        )
+
+    cleanup = work_folder is None
+    if work_folder is not None:
+        out_dir = Path(work_folder) / "solve_data" / "subprocess"
+        out_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        out_dir = Path(tempfile.mkdtemp(prefix=f"flextool_{solver_name}_"))
+
+    safe_name = solve_name.replace("/", "_").replace(" ", "_") or "solve"
+    mps_path = out_dir / f"{safe_name}.mps"
+    sol_path = out_dir / f"{safe_name}.sol"
+    opt_path = out_dir / f"{safe_name}.opt"
+
+    # Pull a time_limit out of options if the caller forwarded one.
+    time_limit: float | None = None
+    if options:
+        for key in ("time_limit", "TimeLimit", "timelimit", "maxtime"):
+            v = options.get(key)
+            if v is not None:
+                try:
+                    time_limit = float(v)
+                    break
+                except (TypeError, ValueError):
+                    pass
+
+    try:
+        if logger is not None:
+            logger.info(
+                "subprocess[%s]: building LP for %r, writing MPS to %s",
+                solver_name, solve_name, mps_path,
+            )
+        # Capture the real constraint names BEFORE releasing.  Only the
+        # dual-returning parsers need them (Gurobi/COPT/Xpress ResultFiles
+        # carry primal values only), and ``write_mps(release=True)`` drops
+        # ``_cstrs``.  Real *column* names survive release via ``_vars`` and
+        # are rebuilt after the solve.
+        real_row_names: list[str] = (
+            _row_names_from_cstrs(problem)
+            if solver_name in _DUAL_CAPABLE_SOLVERS else []
+        )
+        # Emit GENERIC, whitespace-safe names (``C0000001`` / ``R0000002`` …)
+        # rather than the real entity-bearing names.  Free-format MPS is
+        # whitespace-delimited with no portable quoting, so a real name
+        # containing a space — common in FlexTool entity names, e.g. a node
+        # inside ``v_flow[Battery Farm,…]`` — would split mid-token and the
+        # solver silently mis-parses the column, returning a WRONG answer
+        # (verified: obj changes, primal unrecoverable).  We don't need real
+        # names in the file: the solution is mapped back by *index* below and
+        # the real names come from the in-memory Problem.  This makes the
+        # commercial path whitespace-agnostic, exactly like the in-process
+        # HiGHS path.
+        problem.write_mps(str(mps_path), release=True, emit_names=False)
+
+        # Merge baseline ``solver_config/<solver>.opt`` with the scenario
+        # options dict (raw entries win) and write the result to
+        # ``<solve>.opt`` for the per-solver CLI to ingest.  Returns
+        # ``None`` when both sources are empty — the per-solver script
+        # builders then skip the opt-file slot entirely.
+        opt_arg = _build_commercial_opt_file(
+            solver_name, options, opt_path,
+        )
+
+        argv, stdin_text = _SCRIPTS[solver_name](
+            binary, mps_path, sol_path, opt_arg,
+        )
+
+        if logger is not None:
+            logger.info(
+                "subprocess[%s]: spawning %s for %r",
+                solver_name, binary, solve_name,
+            )
+        try:
+            cp = subprocess.run(
+                argv,
+                input=stdin_text,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=time_limit,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise RuntimeError(
+                f"{solver_name!r} CLI exceeded time_limit={time_limit!r}s "
+                f"for solve {solve_name!r}; captured stderr: {exc.stderr!r}"
+            ) from exc
+
+        stdout = cp.stdout or ""
+        stderr = cp.stderr or ""
+
+        if cp.returncode != 0:
+            msg = (
+                f"{solver_name!r} CLI for solve {solve_name!r} exited with "
+                f"returncode={cp.returncode}.\n"
+                f"--- stdout ---\n{stdout}\n--- stderr ---\n{stderr}"
+            )
+            # MPS+sol preserved when work_folder was given; otherwise
+            # the finally-block has already cleaned them up.
+            if _looks_like_license_error(stdout, stderr):
+                raise RuntimeError(f"LICENSE: {msg}")
+            raise RuntimeError(msg)
+
+        status_str, objective, primal, dual = _PARSERS[solver_name](sol_path)
+        if status_str == "OTHER" and not primal:
+            if _looks_like_license_error(stdout, stderr):
+                raise RuntimeError(
+                    f"{solver_name!r} CLI for solve {solve_name!r} returned "
+                    f"no usable solution and its output mentions licensing.\n"
+                    f"--- stdout ---\n{stdout}\n--- stderr ---\n{stderr}"
+                )
+            raise RuntimeError(
+                f"{solver_name!r} CLI produced no solution file we could "
+                f"parse at {sol_path} for solve {solve_name!r}.\n"
+                f"--- stdout ---\n{stdout}\n--- stderr ---\n{stderr}"
+            )
+
+        optimal = status_str == "OPTIMAL"
+
+        # Real, ``col_id``-indexed column names come from the surviving
+        # ``_vars`` (never from the MPS — which now carries only generic
+        # names).  The ``.sol`` primal is keyed by those generic names, so
+        # we map each value back by *index*: ``C0000001`` → ``col_id`` 0.
+        # No real (possibly space-bearing) name is ever round-tripped
+        # through the whitespace-delimited MPS/.sol.
+        col_names = _col_names_from_vars(problem)
+        n_cols = len(col_names)
+        col_value = np.zeros(n_cols, dtype=np.float64)
+        primal_dict = primal or {}
+        mapped = 0
+        unrecognised = 0
+        for gname, val in primal_dict.items():
+            cid = _generic_col_id(gname)
+            if cid is None or not (0 <= cid < n_cols):
+                unrecognised += 1
+                continue
+            col_value[cid] = float(val)
+            mapped += 1
+        if unrecognised and logger is not None:
+            logger.warning(
+                "subprocess[%s]: %d/%d .sol entries had unrecognised "
+                "(non-generic) column names for solve %r — ignored",
+                solver_name, unrecognised, len(primal_dict), solve_name,
+            )
+        if mapped < n_cols and logger is not None:
+            logger.warning(
+                "subprocess[%s]: %d/%d columns absent from .sol for solve "
+                "%r (defaulted to 0.0)",
+                solver_name, n_cols - mapped, n_cols, solve_name,
+            )
+
+        # Duals: only the dual-capable parsers return a dict (Gurobi/COPT/
+        # Xpress carry none).  Their ``.sol`` keys duals by the generic row
+        # name (``R0000002`` → ``row_id`` 0); map onto the real constraint
+        # names captured before release so downstream name-based dual
+        # lookups keep working.
+        row_names = real_row_names
+        row_dual = np.zeros(len(row_names), dtype=np.float64)
+        if dual and row_names:
+            for gname, dv in dual.items():
+                rid = _generic_row_id(gname)
+                if rid is not None and 0 <= rid < len(row_names):
+                    row_dual[rid] = float(dv)
+        col_dual = np.zeros(n_cols, dtype=np.float64)
+
+        # Wrap the parsed arrays in the same duck-typed shim the HiGHS
+        # save-memory path uses.  Downstream writers consume
+        # ``allVariableNames()`` / ``getSolution()`` / ``getLp().row_names_``
+        # / ``passColName()`` identically to a live ``highspy.Highs`` — no
+        # 33 GB sidecar ``readModel``, no MPS text round-trip.
+        obj = objective if objective is not None else 0.0
+        h = _SolHighsShim(
+            col_names=col_names,
+            row_names=row_names,
+            col_value=col_value,
+            col_dual=col_dual,
+            row_dual=row_dual,
+            objective=obj,
+        )
+
+        return Solution(
+            optimal=optimal,
+            obj=obj,
+            col_value=col_value,
+            row_dual=row_dual,
+            col_dual=col_dual,
+            col_names=col_names,
+            row_names=row_names,
+            vars=dict(problem._vars),
+            highs=h,
+        )
+    finally:
+        if cleanup:
+            # out_dir is a dedicated per-solve tempdir; remove it wholesale
+            # so solver-written sidecars (Xpress' .slx/.prt, .hdr/.asc,
+            # per-solver logs) don't leak or block an rmdir.
+            shutil.rmtree(out_dir, ignore_errors=True)
+
+
+__all__ = ["solve_via_subprocess"]