dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/backends/dymola/persistent_backend.py

@@ -0,0 +1,949 @@
+"""Persistent-worker Dymola backend using the Python interface.
+
+Unlike the default batched backend (which launches Dymola per batch and drives
+it via generated `.mos` scripts), this backend keeps N long-lived
+`DymolaInterface` processes alive for the whole run. Each worker loads the
+library once and then pulls tests off a shared queue.
+
+Benefits:
+  - Library-load overhead paid once per worker, never again
+  - Per-test granularity: start/finish events fire as each test transitions,
+    no "batch jumps together" visibility gap
+  - Natural work-stealing: whichever worker finishes first grabs the next test
+  - Per-test timeout isolation: a hung test kills one worker (we restart it)
+    while the others keep running
+
+This is the default backend; pass `--batch` to opt out and use the `.mos`
+batched backend instead. There is no automatic fallback: if the Dymola
+Python interface can't be imported, `preflight` raises and the CLI aborts
+with a message naming both fixes (see `backends.select_backend`).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import shutil
+import threading
+import time
+from pathlib import Path
+
+from ...config import Config
+from ...discovery.library_state import (
+    LibraryChanges,
+    dependency_file,
+    dependency_root,
+    under,
+)
+from ...discovery.test_registry import TestModel
+from ..common.mat_reader import read_mat_time_extents
+from ..common.proc_kill import live_children
+from ..persistent import LibraryReloadError, PersistentBackendBase, Worker
+from ..types import Capability, TestRunResult
+from .backend import DymolaBackend, DymolaConfig
+from .interface_loader import load_dymola_interface
+from .log_parser import parse_test_logs
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Patches of Dymola's Python interface
+# ---------------------------------------------------------------------------
+
+_parallel_startup_patched = False
+
+
+def _patch_dymola_for_parallel_startup() -> None:
+    """Narrow Dymola's broad startup lock so workers can launch in parallel.
+
+    `dymola.dymola_interface_internal.dymola_lock` is held for the entire
+    `DymolaInterface.__init__`, which includes `_check_dymola` — an HTTP
+    ping retry loop that waits for the just-spawned Dymola to come up
+    (~7s per worker). With this lock in place, N workers all serialize on
+    startup, so 10 workers take 10×7 = 70s instead of ~7s.
+
+    The genuinely shared state is just port selection (otherwise two workers
+    could pick the same random port and collide). We narrow the critical
+    section to just `_find_available_port` and replace the broad lock with
+    a no-op so the slow per-worker waits overlap.
+    """
+    global _parallel_startup_patched
+    if _parallel_startup_patched:
+        return
+    try:
+        import dymola.dymola_interface_internal as _di  # type: ignore[import-not-found]
+    except ImportError:
+        return
+
+    _port_lock = threading.Lock()
+    _orig_find_port = _di.DymolaInterfaceInternal._find_available_port
+
+    def _safe_find_port(self):
+        with _port_lock:
+            return _orig_find_port(self)
+
+    _di.DymolaInterfaceInternal._find_available_port = _safe_find_port  # type: ignore[method-assign]
+
+    class _NoLock:
+        def acquire(self, blocking=True, timeout=-1):
+            return True
+
+        def release(self):
+            pass
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+    _di.dymola_lock = _NoLock()  # type: ignore[attr-defined]
+    _parallel_startup_patched = True
+
+
+#: The interface whose request the current thread is inside. Dymola's logger
+#: is static — a message does not say which Dymola it is about — so the
+#: request method notes it here for the logger's filter.
+_requesting = threading.local()
+_dymola_logger_patched = False
+
+
+def _install_dymola_log_filter() -> None:
+    """Monkey-patch Dymola's interface so the connection noise of a Dymola
+    THIS process closed is not printed.
+
+    The interface retries a request ten times, a second apart, and prints
+    every failed attempt. A thread still inside a call when its Dymola is
+    killed (a timeout, a cancel during translation, the pool closing over a
+    running test) prints "Remote end closed connection without response",
+    then a refused connection per second — and goes on to its next call,
+    which does the same. Measured on Dymola 2026x after a cancel during
+    translation: 10 lines, the thread retrying for 19.5 s after the close.
+
+    Muted by a window of seconds after a close, the first line (not among
+    the patterns) and every line past the window were printed, and for its
+    length the same lines of every OTHER worker's Dymola were not — where a
+    lost connection is a finding. So the mute is by interface and for good:
+    a worker's ``_quiet`` marks the one it is closing (:func:`_closing`),
+    ``_make_rpc_call`` notes whose request the thread is inside, and the
+    logger drops a connection error — an ``OSError``, as the request loop
+    logs it; nothing else — raised inside a marked one.
+
+    Dymola's ``DymolaLogger._PrintMessage`` uses ``print(msg)``, so the
+    lines go to stdout: patching the logger is cleaner than filtering a
+    stream.
+    """
+    global _dymola_logger_patched
+    if _dymola_logger_patched:
+        return
+    try:
+        import dymola.dymola_interface_internal as _di  # type: ignore[import-not-found]
+    except ImportError:
+        return  # interface not loaded yet; will be retried on next call
+    rpc = _di.DymolaInterfaceInternal._make_rpc_call
+    orig = _di.DymolaLogger._PrintMessage
+
+    def _noted_request(self, *args, **kwargs):
+        _requesting.interface = self
+        try:
+            return rpc(self, *args, **kwargs)
+        finally:
+            _requesting.interface = None
+
+    def _filtered_print(level, msg):
+        inside = getattr(_requesting, "interface", None)
+        if isinstance(msg, OSError) and getattr(inside, "_dstf_closing", False):
+            return
+        orig(level, msg)
+
+    _di.DymolaInterfaceInternal._make_rpc_call = _noted_request  # type: ignore[method-assign]
+    _di.DymolaLogger._PrintMessage = staticmethod(_filtered_print)  # type: ignore[method-assign]
+    _dymola_logger_patched = True
+
+
+@contextlib.contextmanager
+def _closing(interface):
+    """A worker's teardown of *interface*: from here on what it prints about
+    the connection it loses is this process's doing
+    (:func:`_install_dymola_log_filter`). The mark stays — a closed
+    interface is never used again, and the thread abandoned inside it may
+    retry for 20 s more. Nothing the teardown raises is caught here."""
+    _install_dymola_log_filter()
+    if interface is not None:
+        interface._dstf_closing = True
+    yield
+
+
+#: The simulation executable Dymola builds and runs for a test, by PROCESS
+#: NAME. Never matched as a substring of a command line: the compiler that
+#: builds it is handed a ``dymosim`` argument too.
+_DYMOSIM_NAMES = ("dymosim", "dymosim.exe")
+
+
+def _classify_translation_error(log_path: Path) -> str:
+    """Best-effort classification of a Dymola translation failure.
+
+    The full ``translation_log.txt`` is preserved as a per-test artifact;
+    this helper extracts the most actionable summary line for the
+    dashboard / per-test-report ``error_message`` field. Falls back to
+    the generic "Translation failed" for unrecognized patterns. Pattern
+    list grows organically — when a TRANSFORM run on a new platform
+    surfaces a recurring failure category, add a clause here so users
+    don't have to crack open the log file just to read the headline.
+    """
+    try:
+        text = log_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return "Translation failed"
+    if "model is too complex for the current license" in text:
+        return "Translation failed: license tier too small for this model"
+    lower = text.lower()
+    if "class not found" in lower or "could not find class" in lower:
+        return "Translation failed: missing class / undeclared dependency"
+    return "Translation failed"
+
+
+def _open_model_step(package_file: Path) -> str:
+    """The step a worker is in while Dymola opens *package_file*, as the
+    queue panel and a start's failure say it: the call with its path
+    QUOTED, as OpenModelica's ``loadFile("…")`` is — the one form the
+    panel cuts to the path's last part (``queue_rows.starting_text``).
+    Unquoted, the whole path stood in the panel's line."""
+    return f'openModel("{package_file.as_posix()}")'
+
+
+class DymolaWorker(Worker):
+    """One live Dymola process wrapped as a test worker."""
+
+    kill_name_hint = "dymola"
+    exec_thread_prefix = "dym"
+    # Give Dymola a real chance to flush its open dslog.txt handle before
+    # psutil escalates to SIGKILL — diagnostic loss on timeout was a real
+    # reported pain point on TRANSFORM/Linux.
+    timeout_kill_grace = 5.0
+
+    def __init__(
+        self,
+        worker_id: int,
+        config: Config,
+        dymola_config: DymolaConfig,
+        dymola_interface_cls,
+    ):
+        super().__init__(worker_id, config)
+        self.dymola_config = dymola_config
+        self._DI = dymola_interface_cls
+        self.dymola = None  # the DymolaInterface instance
+        self._n_tests_run = 0
+
+    def start(self) -> None:
+        """Launch Dymola and apply startup: settings + library loads.
+
+        Launches run fully in parallel — PID attribution is read directly
+        from DymolaInterface's internal subprocess handle, so we never need
+        to serialize around a process-set snapshot.
+        """
+        self._step = "its launch"
+        kwargs: dict = {"showwindow": bool(self.dymola_config.show_ide)}
+        if self.config.backend_path:
+            # DEBT: on Linux, backend_path must point at the wrapper script
+            # (e.g. /usr/local/bin/dymola), not the bare bin64/dymola binary.
+            # The wrapper exports LD_LIBRARY_PATH so Dymola finds its bundled
+            # libgit2/Qt6/Qtitan libs. Pointing at bin64/dymola directly fails
+            # with confusing "shared library not found" + "Mismatching Dymola
+            # version" errors — DymolaInterface only sees an unstartable child
+            # process. Surface this as a friendlier check at config-resolution
+            # time once we have a Linux-aware backend-path validator.
+            kwargs["dymolapath"] = str(self.config.backend_path)
+
+        self.dymola = self._launch(kwargs)
+
+        # Establish working directory
+        self.dymola.cd(str(self.config.work_dir))
+
+        # Load dependencies
+        for dep_path in self.config.dependencies or []:
+            dep_pkg = dependency_file(dep_path)
+            self._step = _open_model_step(dep_pkg)
+            ok = self.dymola.openModel(str(dep_pkg))
+            if not ok:
+                raise RuntimeError(
+                    f"Worker {self.worker_id}: failed to load dependency "
+                    f"{dep_pkg} — {self._last_error()}"
+                )
+
+        # Load main library
+        main_pkg = self.config.library_dir / "package.mo"
+        self._step = _open_model_step(main_pkg)
+        ok = self.dymola.openModel(str(main_pkg))
+        if not ok:
+            raise RuntimeError(
+                f"Worker {self.worker_id}: failed to load library {main_pkg} "
+                f"— {self._last_error()}"
+            )
+
+        # Framework settings (mirror startup.mos). ExecuteCommand returns the
+        # value of the command (e.g., `true` for an assignment), not a
+        # success/failure indicator — we only detect a real failure by the
+        # Dymola error log.
+        self._exec_setting("OutputCPUtime := true;")
+        self._exec_setting("Advanced.UI.TranslationInCommandLog := true;")
+
+        # User setup commands — warn on failure, don't abort
+        for cmd in self.dymola_config.backend_setup or []:
+            cmd = cmd.strip()
+            if not cmd.endswith(";"):
+                cmd += ";"
+            self._exec_setting(cmd)
+        self._step = ""
+
+    def _launch(self, kwargs: dict):
+        """Construct the DymolaInterface, tracking the Dymola it launches
+        from the moment the process exists.
+
+        The constructor launches Dymola and then waits for it to answer —
+        seconds. Read off the finished interface, the PID arrives after
+        that wait, and a start given up DURING it (the bound, the pool
+        closing) had nothing to kill: Dymola stayed up for minutes, holding
+        its licence seat. So the launch step itself — ``_start_dymola``,
+        which stores the ``subprocess.Popen`` as ``_dymola_process`` — is
+        wrapped on the instance before ``__init__`` runs.
+
+        Should that step ever move, the PID is still read once the
+        constructor returns, as it used to be: the kill is then late for a
+        start given up mid-launch, and best-effort without the attribute.
+        """
+        interface = self._DI.__new__(self._DI)
+
+        def _pid() -> int | None:
+            proc = getattr(interface, "_dymola_process", None)
+            return getattr(proc, "pid", None)
+
+        launch = getattr(interface, "_start_dymola", None)
+        if callable(launch):
+
+            def _tracked_launch(*args, **kw):
+                try:
+                    return launch(*args, **kw)
+                finally:
+                    self._track_launch(_pid())
+
+            interface._start_dymola = _tracked_launch
+        interface.__init__(**kwargs)
+        self._track_launch(_pid())
+        return interface
+
+    def process_detail(self) -> str:
+        proc = getattr(self.dymola, "_dymola_process", None)
+        if proc is None:
+            return f"Dymola had not come up ({self._step})" if self._step else ""
+        code = proc.poll()
+        state = (
+            "Dymola is still running"
+            if code is None
+            else f"Dymola exited (code {code})"
+        )
+        return f"{state} during {self._step}" if self._step else state
+
+    def cancel_running(self, test_key: str) -> bool:
+        """dymosim's own stop request: a file named ``stop`` in its working
+        directory. An integration that LOOKS at it ends there and
+        ``simulateModel`` returns with Dymola intact — measured 0.16 to
+        0.38 s on a CPU-bound model. One that does not look — a model
+        blocked in an external call (``Modelica.Utilities.System.command``)
+        never returns to the solver's loop — runs on: the file is written
+        at once, the watchdog's :attr:`cancel_grace` (10 s) runs out, and
+        the worker is killed and restarted, about 11.7 s after the request
+        (4 of 4). The request is ``True`` either way: it was made.
+
+        Only while a dymosim process runs under this Dymola. During
+        translation there is none, and nothing short of killing Dymola stops
+        the compile — ``False``, and the watchdog does that.
+        """
+        asked = False
+        for child in live_children(self.pids, name_hint=self.kill_name_hint):
+            try:
+                if child.name().lower() not in _DYMOSIM_NAMES:
+                    continue
+                (Path(child.cwd()) / "stop").write_text("", encoding="utf-8")
+                asked = True
+            except Exception:
+                continue  # gone, or not ours to look at
+        return asked
+
+    def run_test(
+        self,
+        test: TestModel,
+        test_key: str,
+        progress=None,
+    ) -> TestRunResult:
+        """Run one test in this worker. Returns the TestRunResult.
+
+        Splits translateModel + simulateModel into separate calls so we can
+        time them independently and emit per-phase progress events.
+        """
+        test_dir = self.config.work_dir / test_key
+        # Fresh dir each time — prevents stale dsres.mat / dslog.txt bleed-through.
+        # Defensive duplicate of cmd_run's central wipe (D91); kept here so a
+        # direct caller of run_tests outside cmd_run still gets clean state.
+        if test_dir.exists():
+            shutil.rmtree(test_dir)
+        test_dir.mkdir(parents=True, exist_ok=True)
+
+        # Bind the interface once. run_test executes on a thread the watchdog
+        # abandons on timeout (`t.join(0.5)`); the pool then restarts this
+        # worker and `self.dymola` becomes a *new* interface. An abandoned
+        # thread that later unblocks must keep talking to the dead interface —
+        # re-reading the attribute would let it issue RPCs against the fresh
+        # one concurrently with the next test, which is exactly the "Mismatch
+        # request/response ID" poisoning documented below.
+        dymola = self.dymola
+        start = time.monotonic()
+        translation_wall: float | None = None
+        sim_wall: float | None = None
+        try:
+            dymola.cd(str(test_dir))
+            dymola.clearlog()
+
+            # Phase 1: translate (may reuse cached translation — nearly free in that case)
+            if progress is not None:
+                progress.on_phase(test_key, "translating")
+            t_trans_start = time.monotonic()
+            self._step = f"translateModel({test.model_id})"
+            translation_ok = bool(dymola.translateModel(test.model_id))
+            translation_wall = time.monotonic() - t_trans_start
+
+            if not translation_ok:
+                # Save log, fail fast — skip the simulate call
+                try:
+                    dymola.savelog(str(test_dir / "translation_log.txt"))
+                except Exception:
+                    pass
+                elapsed = time.monotonic() - start
+                self._n_tests_run += 1
+
+                # Worker-health probe: a real translation failure always
+                # writes a non-trivial translation_log.txt (parse errors,
+                # license messages, etc. — typically hundreds of bytes).
+                # An empty / missing / very small log paired with a False
+                # return from translateModel is the signature of a
+                # broken-worker state we've seen on Dymola/Linux after a
+                # watchdog kill — the worker is alive enough to respond
+                # to RPCs but silently rejects every translateModel.
+                # Without this probe each broken-worker test wastes ~40s
+                # waiting for translateModel to time out internally, and
+                # the cascade silently fails every remaining test.
+                # Closing the worker here forces the dispatch loop's
+                # next iteration to call _try_restart, escalating to a
+                # real recovery attempt (or exhausting the budget if the
+                # broken state is permanent).
+                log_path = test_dir / "translation_log.txt"
+                if (not log_path.exists()) or log_path.stat().st_size < 50:
+                    # Close only OUR interface: if the watchdog abandoned
+                    # this thread and the pool already restarted the worker,
+                    # self.dymola is a fresh interface serving the next test
+                    # — closing it here would kill the new worker mid-test
+                    # (the cross-thread poisoning the pinned local exists
+                    # to prevent). self.close() reads self.*, so it is only
+                    # safe while self.dymola is still the pinned instance.
+                    if self.dymola is dymola:
+                        try:
+                            self.close(grace=1.0)
+                        except Exception:
+                            pass
+                    return TestRunResult(
+                        model_id=test.model_id,
+                        test_key=test_key,
+                        success=False,
+                        elapsed=elapsed,
+                        error_message=(
+                            "Worker broken: translateModel returned False with "
+                            "no diagnostic log (forcing restart)"
+                        ),
+                        translation_wall=translation_wall,
+                    )
+
+                return TestRunResult(
+                    model_id=test.model_id,
+                    test_key=test_key,
+                    success=False,
+                    elapsed=elapsed,
+                    error_message=_classify_translation_error(
+                        test_dir / "translation_log.txt"
+                    ),
+                    translation_wall=translation_wall,
+                )
+
+            # Phase 2: simulate (uses cached translation)
+            if progress is not None:
+                progress.on_phase(test_key, "simulating")
+            call_kwargs: dict = {
+                "method": test.method,
+                "tolerance": test.tolerance,
+                "resultFile": "dsres",
+            }
+            if test.stop_time != 1.0:
+                call_kwargs["stopTime"] = test.stop_time
+            if test.number_of_intervals is not None:
+                call_kwargs["numberOfIntervals"] = test.number_of_intervals
+            elif test.output_interval is not None:
+                call_kwargs["outputInterval"] = test.output_interval
+
+            t_sim_start = time.monotonic()
+            # simulateModel returns bool; actual success/failure determined
+            # by on-disk artifacts in _evaluate_from_disk
+            self._step = f"simulateModel({test.model_id})"
+            _ = dymola.simulateModel(test.model_id, **call_kwargs)
+            sim_wall = time.monotonic() - t_sim_start
+
+            # Phase 3: finalize (savelog)
+            if progress is not None:
+                progress.on_phase(test_key, "finalizing")
+            dymola.savelog(str(test_dir / "translation_log.txt"))
+        except Exception as exc:  # DymolaException or connection loss
+            elapsed = time.monotonic() - start
+            self._n_tests_run += 1
+            # Don't call savelog here — the JSON-RPC connection state is
+            # indeterminate after Dymola raises mid-call. An attempted
+            # savelog can complete partially, leaving the next test's RPC
+            # ID mismatched with the prior savelog's response, which
+            # poisons the worker for every subsequent test ("Mismatch
+            # request/response ID in JSON-RPC call" cascade observed on
+            # TRANSFORM/Linux). Translation-log preservation on this path
+            # would require either a connection-health probe before the
+            # savelog attempt or splitting the RPC client to discard
+            # in-flight state on exception — both bigger than this branch
+            # warrants. dslog.txt (written by Dymola itself during
+            # simulation) is still the available diagnostic.
+            msg = f"DymolaInterface error: {exc}"
+            return TestRunResult(
+                model_id=test.model_id,
+                test_key=test_key,
+                success=False,
+                elapsed=elapsed,
+                error_message=msg,
+                translation_wall=translation_wall,
+                sim_wall=sim_wall,
+            )
+
+        elapsed = time.monotonic() - start
+        self._n_tests_run += 1
+        result = self._evaluate_from_disk(test, test_key, elapsed)
+        # Attach phase timings to the result
+        result.translation_wall = translation_wall
+        result.sim_wall = sim_wall
+        return result
+
+    def export_fmu(self, test: TestModel, output_dir: Path) -> Path:
+        """Export ``test.model_id`` as an FMU into ``output_dir`` (4.B.2).
+
+        Uses Dymola's ``translateModelFMU`` API. Dymola produces the FMU in
+        the current working directory; we cd to ``output_dir`` so it lands
+        next to the chain's other artefacts, then return the resolved path.
+
+        Requires the FMI export option in the Dymola license; raises a clear
+        message on failure.
+        """
+        if self.dymola is None:
+            raise RuntimeError(
+                f"Worker {self.worker_id}: cannot export FMU before start()"
+            )
+        output_dir.mkdir(parents=True, exist_ok=True)
+        self.dymola.cd(str(output_dir))
+        # Dymola's translateModelFMU returns the FMU file path (without .fmu)
+        # on success, or an empty string on failure. fmiVersion="2" is the
+        # broadly compatible default; fmiType="all" gives both ME + CS.
+        try:
+            result = self.dymola.translateModelFMU(
+                test.model_id,
+                storeResult=False,
+                modelName="",
+                fmiVersion="2",
+                fmiType="all",
+                includeSource=False,
+                includeImage=0,
+            )
+        except Exception as exc:
+            raise RuntimeError(
+                f"DymolaInterface.translateModelFMU failed for {test.model_id}: {exc}"
+            ) from exc
+        if not result:
+            raise RuntimeError(
+                f"Dymola FMU export returned no path for {test.model_id} "
+                f"(check Dymola license includes FMI export, and the model "
+                f"translates successfully)"
+            )
+        # Dymola returns the basename without .fmu — append it.
+        fmu_path = output_dir / f"{result}.fmu"
+        if not fmu_path.exists():
+            # Fallback: scan for any .fmu Dymola may have produced.
+            candidates = list(output_dir.glob("*.fmu"))
+            if not candidates:
+                raise RuntimeError(
+                    f"Dymola FMU export claimed success but no .fmu found "
+                    f"in {output_dir} (returned: {result!r})"
+                )
+            fmu_path = candidates[0]
+        return fmu_path.resolve()
+
+    def _evaluate_from_disk(
+        self,
+        test: TestModel,
+        test_key: str,
+        elapsed: float,
+    ) -> TestRunResult:
+        """Inspect on-disk artifacts (dsres.mat + logs) and produce a
+        TestRunResult. Used both on the normal happy path and as a fallback
+        from `run_test_with_timeout` when the in-process flow couldn't
+        finish (timeout / worker exception) but the simulation may have
+        actually completed and written its mat file.
+        """
+        test_dir = self.config.work_dir / test_key
+        statistics = parse_test_logs(test_dir)
+
+        translation_failed = False
+        translation_log = test_dir / "translation_log.txt"
+        if translation_log.exists():
+            try:
+                tlog = translation_log.read_text(encoding="utf-8", errors="replace")
+                if "Translation aborted" in tlog or tlog.strip().endswith("= false"):
+                    translation_failed = True
+            except OSError:
+                pass
+
+        # A simulation truly completed only if BOTH:
+        #   1. dsfinal.txt exists (Dymola writes it at end of successful sim)
+        #   2. mat file's last time reaches the requested stop_time
+        # dsres.mat existence alone is insufficient — Dymola writes it
+        # incrementally, so a killed-mid-sim leaves a partial file.
+        mat_path = test_dir / "dsres.mat"
+        dsfinal_path = test_dir / "dsfinal.txt"
+        success = False
+        completion_msg: str | None = None
+        if not translation_failed and mat_path.exists() and dsfinal_path.exists():
+            extents = read_mat_time_extents(mat_path)
+            stop_time = float(test.stop_time)
+            if extents is not None:
+                last_time = extents[1]
+                # Allow a tiny tolerance — output_interval may not align perfectly
+                tol = max(1e-6, abs(stop_time) * 1e-6)
+                if last_time + tol >= stop_time:
+                    success = True
+                else:
+                    completion_msg = (
+                        f"Stopped early at T={last_time:.6g} of {stop_time:.6g}"
+                    )
+            else:
+                completion_msg = "dsres.mat unreadable"
+
+        if success:
+            return TestRunResult(
+                model_id=test.model_id,
+                test_key=test_key,
+                success=True,
+                elapsed=elapsed,
+                statistics=statistics,
+            )
+
+        # Build the most informative failure message we can
+        if translation_failed:
+            msg = "Translation failed"
+        elif not mat_path.exists():
+            msg = "No result file produced"
+        elif not dsfinal_path.exists():
+            msg = "Simulation aborted (no dsfinal.txt)"
+        else:
+            msg = completion_msg or "Simulation incomplete"
+
+        dslog_path = test_dir / "dslog.txt"
+        if dslog_path.exists():
+            try:
+                log_text = dslog_path.read_text(encoding="utf-8", errors="replace")
+                if "ERROR" in log_text or "error" in log_text:
+                    lines = log_text.strip().split("\n")
+                    msg = msg + " | " + " | ".join(lines[-3:])
+            except OSError:
+                pass
+
+        return TestRunResult(
+            model_id=test.model_id,
+            test_key=test_key,
+            success=False,
+            elapsed=elapsed,
+            error_message=msg,
+            statistics=statistics,
+        )
+
+    def _detach_interface(self) -> object | None:
+        d = self.dymola
+        self.dymola = None
+        return d
+
+    def _shutdown_interface(self, handle: object, grace: float) -> None:
+        handle.close()  # type: ignore[attr-defined]
+
+    def _quiet(self):
+        # The Dymola being torn down: the requests still in flight against
+        # it fail from here on, and that is not a finding.
+        return _closing(self.dymola)
+
+    def is_alive(self) -> bool:
+        return self.dymola is not None and not self.tool_gone()
+
+    # -----------------------------------------------------------------
+    def _exec_setting(self, cmd: str) -> None:
+        """Run a Modelica settings command. ExecuteCommand returns the value
+        of the command (e.g., `true` for an assignment), which we can't use
+        as a success indicator. Only log a warning if the Dymola error log
+        picks up an issue.
+        """
+        assert self.dymola is not None
+        try:
+            self.dymola.ExecuteCommand(cmd)
+        except Exception as exc:  # pragma: no cover — diagnostic path
+            logger.warning(
+                "Worker %s: setting '%s' raised: %s",
+                self.worker_id,
+                cmd,
+                exc,
+            )
+            return
+        err = self._last_error()
+        if err and ("Error" in err or "error:" in err.lower()):
+            logger.warning(
+                "Worker %s: setting '%s' reported: %s",
+                self.worker_id,
+                cmd,
+                err.strip()[:200],
+            )
+
+    def reload(self, changes: LibraryChanges | None) -> None:
+        """``openModel(package.mo)`` again, in the live Dymola: it then
+        discards the library it holds and reads each file as it is next
+        needed — a changed model, a base class or a component of it, an
+        added file, a removed one (its class is gone, and its test fails to
+        translate). The library always, whatever changed, and before it
+        each dependency that holds a changed file (all of them when nothing
+        is known of what changed). Opening one file of a library costs what
+        opening its ``package.mo`` does (0.01 to 0.05 s on a native file
+        system, 8 to 9.5 s on /mnt/d for a 3 270-file library), so nothing
+        is opened file by file.
+
+        ``changeDirectory=False``: a reopen must not leave Dymola's working
+        directory in the library. A file Dymola cannot parse is NOT an
+        error of this call (it returns true): its test fails to translate,
+        with the parser's message in the translation log."""
+        touched = (
+            None
+            if changes is None
+            else (*changes.changed, *changes.added, *changes.removed)
+        )
+        #: (what the message calls it, the file it is opened by)
+        opened: list[tuple[str, Path]] = []
+        for entry in self.config.dependencies or []:
+            # Which files are the dependency's is asked as the sweep
+            # spelled them; what is opened is what ``start`` opened.
+            root = dependency_root(entry)
+            if root is None:
+                continue
+            if touched is None or any(under(path, root) for path in touched):
+                opened.append((root.name, dependency_file(entry)))
+        library_dir = self.config.library_dir
+        opened.append((library_dir.name, library_dir / "package.mo"))
+        for name, main_pkg in opened:
+            self._step = _open_model_step(main_pkg)
+            if not self.dymola.openModel(str(main_pkg), changeDirectory=False):
+                raise LibraryReloadError(
+                    f"{name} does not load: {self._last_error().strip()[:400]}"
+                )
+
+    def _last_error(self) -> str:
+        try:
+            return str(self.dymola.getLastErrorLog()) if self.dymola else ""
+        except Exception:
+            return ""
+
+    def tool_version(self) -> str | None:
+        """Actual Dymola version via the built-in ``DymolaVersion()``.
+
+        ``ExecuteCommand`` returns the command's evaluated value (see
+        ``_exec_setting``), so calling it on a value-returning built-in yields
+        the version string (e.g. ``"Dymola 2026x Refresh 1"``). Best-effort:
+        returns ``None`` if the interface isn't up or the call yields no usable
+        string. This is what disambiguates a 2025x baseline from a 2026x
+        re-run when results drift.
+        """
+        if self.dymola is None:
+            return None
+        try:
+            val = self.dymola.ExecuteCommand("DymolaVersion()")
+        except Exception:
+            return None
+        if isinstance(val, str) and val.strip():
+            return val.strip()
+        return None
+
+    def library_versions(self) -> dict:
+        """Loaded Modelica Standard Library version.
+
+        Dymola exposes no scripting getter for a library's version, but it
+        bundles MSL on disk under ``$DYMOLA/Modelica/Library/Modelica X.Y.Z/``
+        and sets the ``DYMOLA`` env var (both platforms). We read that env var
+        via the interface, then glob the bundle dir for the version. Best-
+        effort → ``{}`` on any failure. The install path is local to the
+        machine running dstf, so the glob is a plain filesystem read.
+        """
+        if self.dymola is None:
+            return {}
+        try:
+            raw = self.dymola.ExecuteCommand(
+                'Modelica.Utilities.System.getEnvironmentVariable("DYMOLA")'
+            )
+        except Exception:
+            return {}
+        # getEnvironmentVariable returns [value, exists] over the interface.
+        root = raw[0] if isinstance(raw, (list, tuple)) and raw else raw
+        if not isinstance(root, str) or not root.strip():
+            return {}
+        import glob
+        import os
+        import re
+
+        vers = sorted(
+            {
+                m.group(1)
+                for p in glob.glob(
+                    os.path.join(root.strip(), "Modelica", "Library", "Modelica *")
+                )
+                if (m := re.search(r"Modelica ([\d][\d.]*)", os.path.basename(p)))
+            }
+        )
+        # If several MSL versions are bundled, report the newest (Dymola's
+        # default load) — max by dotted-int tuple, not string order.
+        if not vers:
+            return {}
+        best = max(vers, key=lambda v: tuple(int(x) for x in v.split(".")))
+        return {"Modelica": best}
+
+
+# ---------------------------------------------------------------------------
+
+
+class PersistentDymolaBackend(PersistentBackendBase, DymolaBackend):
+    """Dymola backend using persistent DymolaInterface workers + a queue.
+
+    Inherits the dispatch-loop machinery from :class:`PersistentBackendBase`
+    and the batched :class:`DymolaBackend` for ``read_result`` + config
+    extraction. Order matters — ``PersistentBackendBase`` first so its
+    ``run_tests`` template wins over the batch ``.mos`` backend's override.
+    """
+
+    worker_cls = DymolaWorker
+    backend_label = "Dymola"
+
+    #: FMU export lives HERE, not on the batch class: it needs a live
+    #: DymolaInterface (`translateModelFMU` over the running session).
+    #: Declared on the class the cross-backend chain actually holds an
+    #: instance of, so its `Capability.FMU_EXPORT` gate is truthful.
+    #: `_validate_capabilities` doesn't see this class (it isn't
+    #: `@register`-ed — it's reached via `DymolaBackend.persistent_backend_cls`),
+    #: so `tests/test_capability_gating.py` asserts the flag/override pairing.
+    #: Declared explicitly, not inherited-and-extended: this class does
+    #: persistent orchestration, so the batch class's BATCH_FALLBACK
+    #: would be a false claim here (B2 review finding 5).
+    #: CANCEL is the worker's: ``DymolaWorker.cancel_running`` (dymosim's
+    #: ``stop`` file) with the watchdog's kill behind it.
+    capabilities = frozenset(
+        {
+            Capability.PERSISTENT_WORKERS,
+            Capability.FMU_EXPORT,
+            Capability.LIVE_RESULTS,
+            Capability.CANCEL,
+        }
+    )
+
+    @classmethod
+    def preflight(cls, config) -> None:
+        # Probes the Dymola Python interface (the wheel/egg shipped under
+        # the Dymola install). Cheap — load_dymola_interface caches after
+        # the first call. RuntimeError carries an install hint that the
+        # CLI surfaces verbatim.
+        # Lazy import inside the method so tests can monkeypatch
+        # ``interface_loader.load_dymola_interface`` and have the patch
+        # take effect here.
+        from .interface_loader import load_dymola_interface as _load
+
+        _load(config.dymola_interface_path)
+
+    def setup_before_workers(self) -> None:
+        # Cache the DymolaInterface class for make_worker, then apply
+        # Dymola-specific runtime patches. These two patches must run
+        # before any worker spawns:
+        #   * _install_dymola_log_filter — keeps the connection errors of
+        #     a Dymola a worker closed out of the console.
+        #   * _patch_dymola_for_parallel_startup — narrows DymolaInterface's
+        #     module-level startup lock so workers can launch concurrently
+        #     (~7s × N serialized → all workers in ~7s wall).
+        self._di_cls = load_dymola_interface(self.config.dymola_interface_path)
+        _install_dymola_log_filter()
+        _patch_dymola_for_parallel_startup()
+
+    def make_worker(self, worker_id: int) -> DymolaWorker:
+        return DymolaWorker(
+            worker_id,
+            self.config,
+            self.dymola_config,
+            self._di_cls,
+        )
+
+    def _probe_worker_version(self, live_workers: list) -> str | None:
+        # Ask live workers in turn; the first to name a version wins. Called
+        # once at startup (before dispatch) so the interface is idle and
+        # cross-thread access to worker.dymola is safe.
+        for w in live_workers:
+            v = w.tool_version()
+            if v:
+                return v
+        return None
+
+    def _probe_library_versions(self, live_workers: list) -> dict | None:
+        for w in live_workers:
+            libs = w.library_versions()
+            if libs:
+                return libs
+        return None
+
+    def export_fmu(self, test: TestModel, output_dir: Path) -> Path:
+        """Spin up a one-shot worker to export a single FMU (4.B.2).
+
+        Heavier than reusing a worker from the pool, but keeps the export
+        path independent of the pool's lifecycle (so 4.B's cross-backend
+        chain can call this from arbitrary places). Optimization: have the
+        chain orchestration reuse an idle worker via a future helper.
+
+        VALIDATION CAVEAT: requires Windows + Dymola + the FMI export
+        license option. Cannot be exercised in CI on Linux WSL; tests use
+        a mock DymolaInterface.
+        """
+        di_cls = load_dymola_interface(self.config.dymola_interface_path)
+        _patch_dymola_for_parallel_startup()
+        worker = DymolaWorker(
+            worker_id=-1,
+            config=self.config,
+            dymola_config=self.dymola_config,
+            dymola_interface_cls=di_cls,
+        )
+        worker.start()
+        try:
+            return worker.export_fmu(test, output_dir)
+        finally:
+            # review 2026-07-06 (finding 76): use the worker's guarded close()
+            # (graceful close + psutil hard-kill of tracked PIDs), not
+            # dymola.close() — a hung or raising interface would otherwise
+            # leak the one-shot Dymola process and its license seat.
+            try:
+                worker.close()
+            except Exception:
+                pass
+
+    # run_tests is inherited from PersistentBackendBase.